API 문서화

요청 본문

* 사용 target_language (문자열) 단일 언어 또는 target_languages (배열) 다중에 대 한. 참조 다중 대상 번역.

응답

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

요청 본문

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

사용 target_languages (배열) 대신 target_language (문자열) 여러 대상에 대 한.

응답

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

1단계: 배치 제출

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

응답 (HTTP 202 허용)

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

2단계: 결과에 대한 투표

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

폴링 예제 (파이썬)

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)

응답(보류 중 — 대기 중, GPU를 기다리고 있음)

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

응답 (처리 중)

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

응답 (완료됨)

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

실시간 진행 추적

모든 설문조사 응답에는 실시간 진행 필드가 포함되어 있으므로 배치에서 정확히 무슨 일이 일어나는지 모니터링할 수 있습니다.

대규모 워크로드를 위한 모범 사례

• 배치 요청 당 1개의 대상 언어를 보냅니다. 이렇게 하면 각 배치가 빠르게 진행되고 진행 상황을 쉽게 추적할 수 있습니다.
• 50-100 텍스트에서 배치를 유지. 작은 배치는 빠르게 완료하고 더 자주 진행 상황 업데이트를 제공합니다.
• 최대 2개의 동시 배치 작업을 실행합니다. GPU는 2개의 배치를 병렬로 처리하므로 추가 작업은 대기열에 올라와 더 빨리 시작되지 않습니다.
• 시간이 초과되면 새 배치를 제출하는 대신 동일한 job_id를 다시 폴링합니다. 원래 작업이 GPU에서 여전히 처리되고 있을 수 있습니다.
• 3-5초마다 폴링합니다. 더 자주 폴링하면 처리 속도가 향상되지 않습니다.

다중 언어 배치

한 번에 여러 언어로 여러 텍스트를 번역:

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

완료된 결과 데이터

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

요청 매개 변수

* 둘 중 하나를 제공 target_language 또는 target_languages둘 다 아닙니다.

요청 (다중 부분/양식 데이터)

지원되는 파일 형식

예제 (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"

응답

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

상태 값

문서 번역의 상태를 확인하거나 다운로드 URL을 검색합니다.

응답

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

요청 본문

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

응답

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

그래, 그래 source_language 응답의 필드는 자동 감지가 사용될 때 감지된 언어를 보여줍니다.

응답

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