Tài liệu API

Cơ thể yêu cầu

* Dùng target_language (string) cho ngôn ngữ đơn hoặc target_languages (array) cho nhiều. Xem Dịch đa mục tiêu.

Phản hồi

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

Cơ thể yêu cầu

{
    "text": "Hello, world!",
    "target_languages": ["es", "fr", "de", "ja"],
    "source_language": "en"
}

Dùng target_languages (ma trận) thay vì target_language (string) cho nhiều mục tiêu.

Phản hồi

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

Bước 1: Gửi gói

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"
}'

Phản hồi (HTTP 202 Chấp nhận)

{
    "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/"
}

Bước 2: Đánh giá kết quả

GET https://api.translateapi.ai/api/v1/jobs/{job_id}/

Ví dụ thăm dò (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)

Phản hồi (đợi — xếp hàng, đợi GPU)

{
    "job_id": "67535b2b-...",
    "status": "pending",
    "processed_texts": 0,
    "total_texts": 3,
    "progress_percentage": 0.0,
    "queue_position": 3
}

Phản hồi (trong khi xử lý)

{
    "job_id": "67535b2b-...",
    "status": "processing",
    "processed_texts": 1,
    "total_texts": 3,
    "progress_percentage": 33.33,
    "queue_position": null
}

Trả lời (đã hoàn thành)

{
    "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
    }
}

Điều khiển tiến độ thời gian thực

Mỗi câu trả lời của cuộc thăm dò bao gồm các trường tiến trình thời gian thực để bạn có thể theo dõi chính xác những gì đang xảy ra với gói của bạn:

Thực hành tốt nhất cho các tải công việc lớn

• Gửi 1 ngôn ngữ mục tiêu mỗi yêu cầu gói. Điều này giữ mỗi gói nhanh và làm cho tiến trình dễ theo dõi.
• Giữ các gói ở 50- 100 văn bản. Những gói nhỏ hơn hoàn thành nhanh hơn và cho bạn cập nhật tiến độ thường xuyên hơn.
• Chạy tối đa 2 công việc đồng thời. GPU xử lý 2 công việc song song — các công việc bổ sung sẽ xếp hàng và không bắt đầu nhanh hơn.
• Khi hết thời gian, thăm dò lại cùng một job_ id thay vì gửi một gói mới. Công việc ban đầu có thể vẫn đang xử lý trên GPU.
• Tìm kiếm mỗi 3- 5 giây. Tìm kiếm thường xuyên hơn không làm tăng tốc xử lý.

Bộ đa ngôn ngữ

Dịch nhiều văn bản sang nhiều ngôn ngữ cùng một lúc:

{
    "texts": ["Hello", "Goodbye"],
    "target_languages": ["es", "fr"],
    "source_language": "en"
}

Dữ liệu kết quả hoàn thành

{
    "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
}

Yêu cầu tham số

* Cho hoặc target_language hoặc target_languages, không phải cả hai.

Yêu cầu (dữ liệu nhiều phần/biểu mẫu)

Kiểu tập tin được hỗ trợ

Ví dụ (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"

Phản hồi

{
    "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"
}

Giá trị trạng thái

Kiểm tra trạng thái của bản dịch tài liệu hoặc lấy URL tải về.

Phản hồi

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

Cơ thể yêu cầu

{
    "text": "Bonjour, comment allez-vous?",
    "target_language": "en"
}

Phản hồi

{
    "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 trường trong câu trả lời cho thấy ngôn ngữ được phát hiện khi sử dụng tự động phát hiện.

Phản hồi

{
    "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"},
        ...
    ]
}