Text-to-Text Translation

Translate plain text between supported languages. This endpoint does not accept audio — for speech-to-text or audio translation, use the Transcription API or Transcription → Translation.

Translate Text

Endpoint: POST /v1/translate

Description: Translate one or more text strings into a target language.

Authentication

All requests require a Bearer token in the Authorization header. See Authentication for details.

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token (`API Key` or access token)
`Content-Type`	Yes	`application/json`
`Accept`	No	`application/json` (recommended)

Rate limiting

30 requests per minute per user or IP address.

Word limit (v1)

On POST /v1/translate, each text item is limited to 20 words for individual accounts. Organization accounts are not subject to this limit.

If the limit is exceeded, the API returns HTTP 422:

{
  "status": "error",
  "message": "Text input exceeds the 20-word limit for API v1. Please reduce the text length.",
  "word_count": 25,
  "limit": 20,
  "code": 422
}

For longer text, split it into multiple requests or use POST /translate (non-v1) if available in your deployment.

Request body

{
  "text": "Hello",
  "source_language": "eng",
  "target_language": "amh"
}

Parameters

Parameter	Type	Required	Description
`text`	String or String[]	Yes	Source text to translate. If an array, send at most 4 strings (each is a separate translation).
`source_language`	String	No	Source language code. Omit for auto-detection.
`target_language`	String	Yes	Target language code.

Supported languages

Use language codes from the Supported Languages list, for example:

Language	Code
Amharic	`amh`
English	`eng`
Affan Oromo	`orm`
Tigrigna	`tig`

Batch requests

When text is an array of strings:

Send at most 4 strings per request.
Each string is translated independently and returned as a separate item in the response.
If some items succeed and others fail, the response uses status: "partial_success".

JSON array string (advanced)

If a single text string looks like a JSON array (starts with [ and ends with ]), it is parsed and each element is translated separately, then joined into one result.

Example input: '["Hello","world"]' → one translated string combining both parts.

Normal sentences with commas are not split this way.

Response

Single text string

HTTP 200:

{
  "status": "success",
  "message": "Success",
  "code": 200,
  "data": {
    "translation": {
      "id": 123,
      "success": true,
      "source_text": "Hello",
      "translated_text": "ሰላም",
      "source_language": "eng",
      "target_language": "amh",
      "character_count": 5,
      "created_at": "2026-06-03T12:00:00.000000Z"
    }
  }
}

source_language may reflect auto-detected language when you did not provide one.

Multiple text strings

HTTP 200:

{
  "status": "success",
  "message": "Success",
  "code": 200,
  "data": {
    "translations": [
      {
        "id": 123,
        "success": true,
        "source_text": "Hello",
        "translated_text": "ሰላም",
        "source_language": "eng",
        "target_language": "amh",
        "character_count": 5,
        "created_at": "2026-06-03T12:00:00.000000Z"
      }
    ],
    "total_count": 1
  }
}

Partial failure (batch)

When at least one item succeeds and at least one fails, status is partial_success with HTTP 200. Failed items include success: false.

Error responses

HTTP	When
422	Invalid request, word limit exceeded, or translation failed
503	Translation service temporarily unavailable

Translation history

Endpoint: GET /v1/translations

Description: Retrieve a paginated list of your past text translations.

See Transcription → Translation history for query parameters and response format.

Example request

curl -X POST "https://api.hasab.ai/api/v1/translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "text": "Hello",
    "source_language": "eng",
    "target_language": "amh"
  }'

Hasab