Translation Guide

Overview

The Translation API translates text between languages. The /v1/translate endpoint translates one or more texts into a single target language. Source language is auto-detected when not specified, or you can force it explicitly.

Translate

The /v1/translate endpoint translates a group 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": "zho_Hans",
    "target_language": "eng_Latn",
    "model_id": "vn-translate-basic"
  }'

Request Body

array

required

Texts to translate. Maximum 100 items or 50,000 characters total.

string

required

Target language code in <ISO 639-3>_<Script> format, e.g. eng_Latn, jpn_Jpan, zho_Hans. See Language Codes for accepted spellings, and Get Model Details for the languages each model supports.

string

required

Translation model ID, e.g. vn-translate-basic. Use the /v1/models?capability_type=translate endpoint to browse available translation models.

string

Source language code (same format as target_language). Omit it, or send an empty string or auto, for automatic detection; providing a language 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": "zho_Hans"
  },
  {
    "text": "Second sentence",
    "detected_source_language": "zho_Hans"
  }
]

string

Translated text.

string

Your source_language as sent, or the detected language code (e.g. zho_Hans) when source_language is omitted, empty or auto. See Responses.

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.

Language codes in these fields use the <ISO 639-3>_<Script> format, e.g. eng_Latn, zho_Hans.

curl "https://api.voxnexus.ai/v1/models/vn-translate-basic" \
  -H "X-Api-Key: YOUR_API_KEY"

Best Practices

Language Codes

Use codes in the <ISO 639-3>_<Script> format, such as eng_Latn or zho_Hans; see Language Codes for the rules, and Get Model Details for the languages each model supports. When the source language is known, specifying source_language avoids detection overhead and improves consistency.

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;
  }
}

Getting Started

REST API

WebSocket API

Translation Guide

Overview

Translate

Basic Usage

Request Body

Response

Response Headers

Discovering Translation Models

Best Practices

Language Codes

Error Handling

​Overview

​Translate

​Basic Usage

​Request Body

​Response

​Response Headers

​Discovering Translation Models

​Best Practices

​Language Codes

​Error Handling

Overview

Translate

Basic Usage

Request Body

Response

Response Headers

Discovering Translation Models

Best Practices

Language Codes

Error Handling