API Documentation

Integrate powerful translation into your applications with our simple REST API.

Getting Started

The TranslateAPI provides a simple REST interface for translating text between 180+ languages. All API endpoints return JSON responses.

Base URL: https://api.translateapi.ai/api/v1/
Quick Start

Make your first translation request:

curl -X POST https://api.translateapi.ai/api/v1/translate/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "Hello, world!",
    "target_language": "es"
  }'
import requests

response = requests.post(
    "https://api.translateapi.ai/api/v1/translate/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "text": "Hello, world!",
        "target_language": "es"
    }
)

result = response.json()
print(result["translated_text"])  # "Hola, mundo!"
const response = await fetch("https://api.translateapi.ai/api/v1/translate/", {
    method: "POST",
    headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        text: "Hello, world!",
        target_language: "es"
    })
});

const result = await response.json();
console.log(result.translated_text);  // "Hola, mundo!"
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add(
            "Authorization", "Bearer YOUR_API_KEY"
        );

        var content = new StringContent(
            JsonConvert.SerializeObject(new {
                text = "Hello, world!",
                target_language = "es"
            }),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync(
            "https://api.translateapi.ai/api/v1/translate/",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        var data = JsonConvert.DeserializeObject<dynamic>(result);
        Console.WriteLine(data.translated_text);  // "Hola, mundo!"
    }
}

Authentication

Authenticate your requests using an API key. You can create API keys from your dashboard.

Header Authentication (Recommended)
Authorization: Bearer ta_your_api_key_here
Query Parameter
https://api.translateapi.ai/api/v1/translate/?api_key=ta_your_api_key_here
Keep your API keys secure! Do not expose them in client-side code or public repositories.

Translate Text

Translate text to a single target language.

POST https://api.translateapi.ai/api/v1/translate/
Request Body
Parameter Type Required Description
text string Yes Text to translate (max 50,000 characters)
target_language string Yes* Target language code (e.g., "es", "fr", "de")
source_language string No Source language code. Default: "auto" (auto-detect)

* Use target_language (string) for single language or target_languages (array) for multiple. See Multi-Target Translation.

Response
{
    "translated_text": "Hola, mundo!",
    "source_language": "en",
    "target_language": "es",
    "translations": {
        "es": "Hola, mundo!"
    },
    "character_count": 13,
    "translation_time": 0.45
}

Multi-Target Translation

Translate text to multiple languages in a single request. Uses the same endpoint as single translation.

Tip: You can translate to up to 50 languages in a single request.
POST https://api.translateapi.ai/api/v1/translate/
Request Body
{
    "text": "Hello, world!",
    "target_languages": ["es", "fr", "de", "ja"],
    "source_language": "en"
}

Use target_languages (array) instead of target_language (string) for multiple targets.

Response
{
    "source_language": "en",
    "translations": {
        "es": "Hola, mundo!",
        "fr": "Bonjour, monde!",
        "de": "Hallo, Welt!",
        "ja": "こんにちは、世界！"
    },
    "character_count": 52,
    "translation_time": 2.31
}

Batch Translation

Translate multiple texts at once with async processing. Submit a batch and poll for results.

Limits: max 100 texts per batch, max 300 total items (texts × target languages). Jobs time out 45 minutes after processing starts (queue wait time is not counted).
Processing time varies by language: common languages (Spanish, French, German, etc.) use fast models (~0.1s per text), while less common languages use our large multilingual model (~1-3s per text). A 100-text batch typically completes in 10-30 seconds for common languages, or 2-5 minutes for less common ones. For best results, send 1 target language per batch request and keep batch sizes under 50 texts.
POST https://api.translateapi.ai/api/v1/translate/batch/
Step 1: Submit Batch
curl -X POST https://api.translateapi.ai/api/v1/translate/batch/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Hello", "Goodbye", "Thank you"],
    "target_language": "es",
    "source_language": "en"
}'
Response (HTTP 202 Accepted)
{
    "job_id": "67535b2b-c9e3-4f82-9499-e237edbc1dd8",
    "status": "pending",
    "total_texts": 3,
    "queue_position": 1,
    "source_language": "en",
    "target_languages": ["es"],
    "character_count": 22,
    "credits_remaining": -1,
    "poll_url": "https://api.translateapi.ai/api/v1/jobs/67535b2b-c9e3-4f82-9499-e237edbc1dd8/"
}
Step 2: Poll for Results
GET https://api.translateapi.ai/api/v1/jobs/{job_id}/
Polling Example (Python)
import time, requests

job_id = response.json()["job_id"]
total = response.json()["total_texts"]
headers = {"Authorization": "Bearer YOUR_API_KEY"}

print(f"Batch submitted: {total} texts (job {job_id})")

while True:
    result = requests.get(f"https://api.translateapi.ai/api/v1/jobs/{job_id}/", headers=headers).json()
    status = result["status"]
    processed = result.get("processed_texts", 0)
    progress = result.get("progress_percentage", 0)

    if status == "completed":
        print(f"Completed: {processed}/{total} texts in {result.get('processing_time', 0):.1f}s")
        translations = result["result_data"]["translations"]
        break
    elif status == "failed":
        print(f"Failed at {processed}/{total}: {result.get('error_message', 'unknown')}")
        raise Exception(result.get("error_message", "Translation failed"))
    elif status == "pending":
        queue_pos = result.get("queue_position", "?")
        print(f"Queued (position {queue_pos}) — waiting for GPU worker...")
    else:
        print(f"[{status}] {processed}/{total} ({progress:.0f}%)")

    time.sleep(3)
Response (pending — queued, waiting for GPU)
{
    "job_id": "67535b2b-...",
    "status": "pending",
    "processed_texts": 0,
    "total_texts": 3,
    "progress_percentage": 0.0,
    "queue_position": 3
}
Response (while processing)
{
    "job_id": "67535b2b-...",
    "status": "processing",
    "processed_texts": 1,
    "total_texts": 3,
    "progress_percentage": 33.33,
    "queue_position": null
}
Response (completed)
{
    "job_id": "67535b2b-...",
    "status": "completed",
    "processed_texts": 3,
    "total_texts": 3,
    "progress_percentage": 100.0,
    "processing_time": 10.65,
    "result_data": {
        "translations": ["Hola", "Adiós", "Gracias"],
        "source_language": "en",
        "target_language": "es",
        "character_count": 22,
        "processing_time": 10.65
    }
}
Real-time progress tracking

Every poll response includes real-time progress fields so you can monitor exactly what is happening with your batch:

Field Description
status Current job state: pending (queued, waiting for a GPU worker), processing (actively translating), completed, failed
processed_texts Number of individual translations completed so far. Updates in real time as each text is translated.
total_texts The number of translations in this batch (texts × target languages).
progress_percentage Completion percentage (0-100). Calculated from processed_texts / total_texts.
queue_position Your position in the queue when status is "pending" (1 = next up). Null when processing or completed. Use this to estimate wait time and show queue status to your users.
processing_time Total processing time in seconds (available when completed).
Type: When status is "pending"Check queue_position to see how many jobs are ahead of yours (1 = you're next).
Best Practices for Large Workloads
  • Send 1 target language per batch request. This keeps each batch fast and makes progress easy to track.
  • Keep batches at 50-100 texts. Smaller batches complete faster and give you more frequent progress updates.
  • Run at most 2 concurrent batch jobs. The GPU processes 2 batches in parallel — additional jobs queue and won't start faster.
  • On timeout, re-poll the same job_id instead of submitting a new batch. The original job may still be processing on the GPU.
  • Poll every 3-5 seconds. More frequent polling does not speed up processing.
Multi-Language Batch

Translate multiple texts to multiple languages at once:

{
    "texts": ["Hello", "Goodbye"],
    "target_languages": ["es", "fr"],
    "source_language": "en"
}
Completed result_data
{
    "translations": [
        {"es": "Hola", "fr": "Bonjour"},
        {"es": "Adiós", "fr": "Au revoir"}
    ],
    "source_language": "en",
    "target_languages": ["es", "fr"],
    "character_count": 24,
    "processing_time": 2.45
}
Request Parameters
Parameter Type Required Description
texts array Yes Array of strings to translate
target_language string Yes* Target language code for single language
target_languages array Yes* Array of target language codes for multiple languages
source_language string No Source language code. Default: "auto"

* Provide either target_language or target_languages, not both.

Async Processing: Batch requests return immediately with a job_id. Poll GET /api/v1/jobs/{job_id}/ until status is "completed", then read result_data for translations. Use progress_percentage to track progress.

Document Translation

Translate entire documents while preserving formatting. Supports multiple file formats.

POST https://api.translateapi.ai/api/v1/translate/document/
Request (multipart/form-data)
Parameter Type Required Description
file file Yes The document to translate (max 10MB)
target_language string Yes Target language code (e.g., "es", "fr", "de")
source_language string No Source language code. Default: "auto" (auto-detect)
Supported File Types
  • .txt - Plain text files
  • .docx - Word documents
  • .pdf - PDF documents (including scanned)
  • .json - JSON files (translates string values)
  • .xml - XML files
  • .srt - Subtitle files
  • .po / .pot - Gettext translation files
  • .jpg / .jpeg - JPEG images (OCR)
  • .png - PNG images (OCR)
  • .tiff / .tif - TIFF images (OCR)
  • .bmp - BMP images (OCR)
  • .webp - WebP images (OCR)
OCR Support: Image files and scanned PDFs are processed with optical character recognition (OCR) to extract text before translation. For best results, use clear, high-resolution images.
Example (cURL)
# Translate a Word document
curl -X POST https://api.translateapi.ai/api/v1/translate/document/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.docx" \
  -F "target_language=es" \
  -F "source_language=en"

# Translate text from an image (OCR)
curl -X POST https://api.translateapi.ai/api/v1/translate/document/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@scanned_page.jpg" \
  -F "target_language=es" \
  -F "source_language=en"
Image files are processed with OCR to extract text before translation. The translated output is returned as a .txt file.
Response
{
    "id": 123,
    "original_filename": "document.docx",
    "file_type": "docx",
    "source_language": "en",
    "target_language": "es",
    "status": "completed",
    "character_count": 5420,
    "translated_file_url": "/media/translated/document_es.docx",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:05Z"
}
Status Values
pending File uploaded, waiting to be processed
processing Translation in progress
completed Translation complete, download available
failed Translation failed (check error_message)
GET https://api.translateapi.ai/api/v1/translate/document/{id}/

Check the status of a document translation or retrieve the download URL.

Response
{
    "id": 123,
    "original_filename": "document.docx",
    "status": "completed",
    "translated_file_url": "/media/translated/document_es.docx",
    "character_count": 5420
}

Language Detection

Language detection is built into every translation request. Set source_language to "auto" (or omit it) and the detected language is returned in the response.

POST https://api.translateapi.ai/api/v1/translate/
Request Body
{
    "text": "Bonjour, comment allez-vous?",
    "target_language": "en"
}
Response
{
    "translated_text": "Hello, how are you?",
    "source_language": "fr",
    "target_language": "en",
    "translations": {
        "en": "Hello, how are you?"
    },
    "character_count": 28,
    "translation_time": 0.52
}

The source_language field in the response shows the detected language when auto-detection is used.

Supported Languages

Get the list of all supported languages.

GET https://api.translateapi.ai/api/v1/translate/languages/
Response
{
    "count": 186,
    "results": [
        {"iso": "en", "name": "English", "en_label": "English"},
        {"iso": "es", "name": "Español", "en_label": "Spanish"},
        {"iso": "fr", "name": "Français", "en_label": "French"},
        ...
    ]
}

Translation Models

We use state-of-the-art open source translation models running on our own GPU infrastructure. All models are commercially licensed (Apache 2.0).

Model Languages Best For
Helsinki-NLP/opus-mt 50+ language pairs Common languages (EN, ES, FR, DE, IT, PT, RU, ZH, JA, etc.)
Google MADLAD-400 400+ languages Rare languages, comprehensive coverage

The API automatically selects the best model for your language pair. You can optionally specify an engine parameter:

Engine Description
"auto" Default. Tries HuggingFace first, falls back to MADLAD-400
"huggingface" Force HuggingFace/MarianMT (fastest, 50+ languages)
"madlad" Force MADLAD-400 (400+ languages)

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
402 Payment Required - Daily character quota exceeded
429 Too Many Requests - Rate limit exceeded
503 Service Unavailable - Translation engine temporarily down
Error Response Format
{
    "error": "daily_limit_exceeded",
    "credits_remaining": 0,
    "daily_limit": 100000
}

Rate Limits

Limits vary by plan. See pricing for full details:

Plan Characters/Month Price
Free 250,000 $0 Sign Up Free
Starter 2,500,000 $9/mo Subscribe
Pro 10,000,000 $29/mo Subscribe
Business 40,000,000 $79/mo Subscribe
Scale 125,000,000 $199/mo Subscribe

When you exceed your limit, you'll receive a 429 Too Many Requests response until the next month or you upgrade.

Auto-Scaling Cloud Infrastructure

TranslateAPI runs on dedicated NVIDIA A100 GPU instances with automatic horizontal scaling. When demand increases, additional GPU instances are launched within minutes to maintain fast response times. This means our API can handle virtually unlimited concurrent requests without degradation — from a single request to thousands per minute.

Rate this page
Thank you for your rating!
/5 based on ratings