Skip to main content

​
Overview

The Translation API translates text between languages. It supports two modes:
  • Single target translation (/v1/translate): translate one or more texts into a single target language.
  • Batch translation (/v1/translate/batch): translate a group of texts into multiple target languages in one request.
Source language is auto-detected when not specified, or you can force it explicitly.

​
Translate

The /v1/translate endpoint translates a batch of texts into a single target language.

​
Basic Usage

curl -X POST "https://api.voxnexus.ai/v1/translate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["第一句", "第二句"],
    "source_language": "zh",
    "target_language": "en",
    "model_id": "vn-translate-basic"
  }'

​
Request Body

​
texts
array
required
Texts to translate. Maximum 100 items or 50,000 characters total.
​
target_language
string
required
Target language code (ISO 639-1), e.g. en, ja, fr.
​
model_id
string
required
Translation model ID, e.g. vn-translate-basic. Use the /v1/models?capability_type=translate endpoint to browse available translation models.
​
source_language
string
Source language code (ISO 639-1). Omit for automatic detection; providing this forces the source language.

​
Response

The response is an array of translated items, in the same order as the input texts. 
[
  {
    "text": "First sentence",
    "detected_source_language": "zh"
  },
  {
    "text": "Second sentence",
    "detected_source_language": "zh"
  }
]
​
text
string
Translated text.
​
detected_source_language
string
Detected or echoed source language (ISO 639-1).

​
Response Headers

  • X-Request-ID: Request identifier

​
Batch Translate

The /v1/translate/batch endpoint translates a group of texts into multiple target languages in a single request. Each target language returns a separate result set, in the same order as the input texts.
If translation to a particular target language fails, that language’s texts fall back to the original input and do not affect other languages.

​
Basic Usage

curl -X POST "https://api.voxnexus.ai/v1/translate/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["太冷了", "吃晚餐"],
    "source_language": "zh",
    "target_languages": ["en", "ja"],
    "model_id": "vn-translate-basic"
  }'

​
Request Body

​
texts
array
required
Texts to translate. Maximum 100 items or 50,000 characters total.
​
target_languages
array
required
Target language codes (ISO 639-1). 1–20 languages required.
​
model_id
string
required
Translation model ID, e.g. vn-translate-basic.
​
source_language
string
Source language code (ISO 639-1). Omit for automatic detection.

​
Response

The response is an array with one entry per target language. 
[
  {
    "target_language": "en",
    "detected_source_language": "zh",
    "texts": ["It's so cold", "Have dinner"]
  },
  {
    "target_language": "ja",
    "detected_source_language": "zh",
    "texts": ["寒すぎる", "夕食を食べる"]
  }
]
​
target_language
string
Target language code.
​
detected_source_language
string
Detected or echoed source language.
​
texts
array
Translated texts, in the same order as the request texts.

​
Response Headers

  • X-Request-ID: Request identifier

​
Discovering Translation Models

Translation models expose their routing capabilities through the /v1/models/{model_id} endpoint. The translate_capability object describes:
  • supports_auto_detect: whether source_language can be omitted.
  • target_languages: target languages reachable via auto-detection / wildcard routing.
  • source_routes: explicit per-source-language target routes, when configured.
curl "https://api.voxnexus.ai/v1/models/vn-translate-basic" \
  -H "X-Api-Key: YOUR_API_KEY"

​
Best Practices

​
Language Codes

Use ISO 639-1 language codes (e.g. en, zh, ja, fr). When the source language is known, specifying source_language avoids detection overhead and improves consistency.

​
Batching

Group multiple texts into a single request rather than sending them one at a time. Respect the limits of 100 items / 50,000 characters per request. For translating into many languages at once, prefer /v1/translate/batch.

​
Error Handling

Implement retry logic with exponential backoff for 429 responses. A 502 indicates a translation provider error, and 503 means no translation provider is currently available — both are typically transient and safe to retry. 
async function translateTexts(texts, targetLanguage) {
  try {
    const response = await fetch('https://api.voxnexus.ai/v1/translate', {
      method: 'POST',
      headers: {
        'X-Api-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        texts,
        target_language: targetLanguage,
        model_id: 'vn-translate-basic'
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `HTTP ${response.status}`);
    }

    const results = await response.json();
    return results.map(item => item.text);
  } catch (error) {
    console.error('Translation Error:', error);
    throw error;
  }
}