텍스트 번역 API

이 API는 텍스트를 대기열 작업으로 번역하며, 작업마다 하나의 대상 언어를 사용합니다. 텍스트를 제출한 뒤 반환된 작업 ID를 보관하고 처리가 끝날 때까지 작업을 조회하세요. 모든 요청은 HTTPS로 전송하고 계정의 인증 정보를 사용하세요. 예제에 나온 HTTP Basic 인증 정보 또는 API 토큰을 사용할 수 있으며, 자세한 내용은 인증을 참조하세요. 인증 정보는 서버에 보관하세요.

엔드포인트

두 API 호스트인 https://api.multi.tel 및 호환 호스트 https://api.multitel.net은 계정 범위의 작업, 멱등성 키, 제한, 과금을 공유합니다. 응답 봉투 형식이 다르므로 해당 형식에 맞는 파서와 함께 한 호스트를 일관되게 사용하세요.

작업	메서드 및 경로
서비스 정보	`GET /v3/translate`
작업 제출	`POST /v3/translate`
작업을 만들지 않고 견적 확인	`POST /v3/translate/estimate`
작업 조회	`GET /v3/translate/JOB_ID`
결제 대기 작업 정산	`POST /v3/translate/JOB_ID/settle`
사용량	`GET /v3/translate/usage`

호스트가 api.multi.tel인 경우 모든 경로에 접두사 /v1/translate를 /v3/translate 대신 사용할 수도 있습니다. 호스트가 api.multitel.net인 경우 /v3/translate 경로를 사용하세요.

서비스 정보 응답에는 enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages 및 ratesNanosPerCharacter가 포함됩니다. cpuLanguages는 표준 번역에서 허용하는 기본 언어 코드 목록입니다. ratesNanosPerCharacter는 각 엔진에 설정된 원문 코드 포인트당 가격을 십억분의 일 미국 달러 단위로 나타냅니다. 값이 5000이면 백만 코드 포인트당 $5입니다. 이 응답은 향상된 번역의 현재 이용 가능 여부를 알려 주지 않습니다. 이용할 수 없을 때 향상된 견적은 503을 반환합니다. 조회는 무료입니다.

텍스트 번역

JSON을 Content-Type: application/json 헤더와 함께 POST https://api.multi.tel/v3/translate로 보내세요. 작업마다 대상 언어는 하나이므로 대상 언어별로 별도 작업을 제출하세요.

필드	의미
`text`	필수. 공백과 줄바꿈을 포함해 1~20,000 Unicode 코드 포인트인 원문이며, 공백으로만 이루어져서는 안 됩니다. 일부 이모지와 결합 부호로 표현한 악센트 문자는 여러 코드 포인트를 포함합니다. 바이트 길이로 측정하지 않으며, 세기 전에 텍스트를 정규화하지도 않습니다. 이 호스트는 더 긴 텍스트를 400으로 거부합니다.
`source_language`	원문 로캘 코드입니다. `cpu`에는 필수이며, 없으면 요청은 422 `translation_language_pair_unavailable`를 반환합니다. `enhanced`에서는 선택 사항입니다. 생략하면 작업과 결과의 `sourceLocale`은 비어 있고 아래의 동일 언어 검사를 적용하지 않습니다. 지정을 권장합니다. 생략하려면 필드 자체를 보내지 마세요. 이 호스트는 빈 문자열을 거부합니다.
`target_language`	필수 대상 로캘 코드입니다. 예: `es` 또는 `fr-CA`.
`engine`	필수: `cpu`는 표준 번역, `enhanced`는 향상된 번역입니다.

로캘 코드는 BCP 47 태그로, 문자, 숫자, 하이픈으로 구성되며 길이는 2~63자입니다. 정규 형식으로 변환되므로 en-us는 en-US로 기록됩니다. 유효하지 않은 태그 및 und, mul 또는 zxx는 400 invalid_translation_language를 반환합니다. 표준 번역 지원 여부는 기본 언어로 검사하며 nb 및 nn는 no로 간주합니다. fr-CA와 같은 지역 대상 태그도 허용하고 기록하지만 표준 출력은 기본 언어를 따르며 지역 표현은 보장하지 않습니다.

이 호스트에서는 요청 본문을 128 KiB 이내로 유지하세요. 텍스트는 UTF-8로 보내세요. 모든 비 ASCII 문자를 \u 시퀀스로 이스케이프하면 20,000자 요청이 제한을 넘을 수 있습니다.

본문은 이 네 필드만 받습니다. 그 밖의 속성은 모두 400 invalid_translation_request로 거부되며, idempotency_key, 소유자 ID, 무료 처리 플래그, 구간 배열도 포함됩니다.

멱등성과 재사용

각 제출에는 Idempotency-Key 헤더가 필요하며 길이는 1~190자여야 합니다. ASCII 영문자, 숫자, -, _, . 및 :을 사용하고 앞뒤 공백은 넣지 마세요. 키가 없거나 191자 이상이면 400으로 거부됩니다. 키는 양쪽 호스트와 계정의 모든 인증 정보에 걸쳐 해당 계정의 번역에 적용됩니다.

같은 키로 같은 텍스트, 정규화된 언어, 같은 엔진을 보내면 기존 작업과 HTTP 200, duplicate: true가 반환되며 추가 요금은 없습니다.
같은 키로 다른 텍스트, 언어 또는 엔진을 보내면 409 idempotency_conflict를 반환합니다. 작업 생성 후 처리 버전이 바뀐 경우에도 같은 키는 409를 반환합니다. 이때는 재제출하지 말고 원래 작업을 ID로 조회하세요.
새 키로 같은 텍스트, 정규화된 언어, 같은 엔진을 보내면, 그 내용과 현재 처리 버전을 사용하는 작업이 대기 중, 실행 중, 완료 또는 결제 대기 상태인 경우 기존 작업과 HTTP 200, duplicate: true가 반환되고 새 처리 요금은 없습니다. 재사용된 작업이 결제 대기 중이면 여전히 정산이 필요합니다. 실패한 작업은 재사용하지 않으며, 새 작업을 만들어 완료 시 과금합니다.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

새 작업은 HTTP 202를 반환합니다. 예제 텍스트는 57 코드 포인트이므로 백만 코드 포인트당 $5 요금에서는 $0.000285입니다. 축약한 응답은 다음과 같습니다(식별자는 예시입니다).

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

제출 시 선불 잔액으로 해당 작업과 다른 미정산 작업의 비용을 충당할 수 없으면 402 insufficient_balance, 계정 또는 서비스의 미완료 작업이 너무 많으면 429 translation_queue_full도 반환할 수 있습니다. 다음 경우에는 503을 반환합니다.

paid_translation_not_enabled: 유료 번역이 비활성화된 경우.
translation_unavailable: 향상된 요청을 보냈지만 향상된 번역을 이용할 수 없는 경우.
translation_pricing_unavailable: 선택한 엔진에 요금이 설정되지 않은 경우.

429 및 503 응답은 나중에 같은 키로 재시도하세요.

품질 선택

긴 텍스트는 작은 조각으로 처리한 후 다시 연결합니다. 줄바꿈과 공백이 바뀔 수 있고, 처리 경계에 걸친 문장은 문맥을 잃을 수 있습니다. 원문을 보관하고 연결된 결과를 검토하세요. 표준 번역은 지역 태그의 기본 언어를 사용합니다. 태그를 허용하고 기록해도 지역 표현은 보장되지 않습니다.

표준 번역은 CPU 워커에서 실행됩니다. 향상된 번역은 설정된 외부 AI 서비스에 텍스트를 보냅니다. 출력은 여전히 검토해야 합니다. 서비스는 모든 언어 쌍이나 텍스트 유형에서 한 엔진이 더 정확하다고 보장하지 않습니다.

표준 번역은 초안이며 품질과 처리 시간은 언어 쌍에 따라 다릅니다. 향상된 번역은 문맥이 중요한 텍스트를 위한 것이지만, 중요한 이름, 숫자, 부정 표현, 약속 내용은 여전히 검토해야 합니다. 어느 옵션도 원본 전사문에 이미 있는 오류를 수정하지 않으므로 비교할 수 있도록 원문을 보관하세요.

다음 작업으로 같은 API 호스트에서 현재 지원 여부, 표준 번역 지원 언어, 설정 요금을 확인하세요: GET /v3/translate. 표준 요청의 원문 또는 대상 기본 언어가 cpuLanguages에 없으면 422 translation_language_pair_unavailable를 반환합니다. source_language가 지정되었고 대상과 기본 언어가 같으면 작업을 만드는 대신 409 translation_same_language를 반환합니다. 향상된 번역은 별도로 활성화합니다. 이용할 수 없을 때 향상된 제출과 견적은 503을 반환합니다.

먼저 견적 확인

호스트가 api.multi.tel인 경우 같은 JSON 본문을 POST /v3/translate/estimate로 보내세요. 멱등성 키는 필요하지 않습니다. 견적도 422 및 409 검사를 포함해 같은 검증을 수행하지만 작업 생성, 번역, 자금 예약, 잔액 확인, 과금은 하지 않습니다. HTTP 200을 반환하며 estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd 및 costUsd가 data 아래에 포함됩니다. 위 예에서 costUsd는 0.000285000입니다(표준 요금). 향상된 번역을 이용할 수 없을 때 향상된 견적은 503 service_unavailable를 반환합니다. 견적에는 현재 설정 요금을 사용합니다. 작업의 요금 단가는 생성 시 고정되며 해당 단가로 과금됩니다.

번역 결과 가져오기

새 제출은 HTTP 202, 기존 또는 재사용 작업은 HTTP 200을 반환합니다. data.id를 보관하고 공통 작업 흐름을 사용하세요. 작업 객체에는 다음 필드가 포함됩니다.

id, status, engine, sourceLocale 및 targetLocale.
sourceCharacters, costUsd, costIsEstimate 및 pricePerMillionCharactersUsd.
progress 및 createdAt.
modelVersion: 내부 구조를 해석하지 않고 다루는 처리 버전 문자열입니다.
duplicate: 재사용 응답에 포함됩니다.
failureCode: 실패한 작업의 경우 translation_failed, translation_timeout, input_failed 또는 worker_lease_lost.

실패한 작업의 costUsd는 영입니다.

완료된 작업에는 data.result가 있으며 그 안에 sourceLocale (원문 언어를 지정하지 않으면 비어 있음), targetLocale, 번역된 text (구간 텍스트를 줄바꿈으로 연결한 것), segments가 들어 있습니다. 이 API로 제출한 텍스트에서 segments에는 번역된 text와 대상 language를 가진 항목 하나가 포함됩니다. 결제 대기 작업의 결과는 정산할 때까지 제공되지 않습니다.

api.multitel.net 사용

호환 엔드포인트 POST https://api.multitel.net/v3/translate는 같은 JSON 필드와 같은 Idempotency-Key 헤더를 받습니다. 헤더가 없으면 JSON 본문의 idempotency_key 문자열도 받습니다. 다른 추가 필드는 모두 400 unsupported_translation_option으로 거부됩니다. 이 호스트의 원시 본문은 최대 256,000바이트이며, 20,000 코드 포인트를 초과하는 텍스트는 413 translation_too_large를 반환합니다(400이 아님). 빈 source_language는 생략으로 처리합니다. 429 응답에는 Retry-After: 15가 포함됩니다. 이 호스트는 다음 오류도 반환합니다.

400 json_body_required: 본문이 없거나, JSON이 유효하지 않거나, JSON 스칼라인 경우. JSON 객체를 보내세요.
400 invalid_translation_options: text, target_language 또는 engine이 없거나 비어 있거나 문자열이 아닌 경우, 또는 source_language가 문자열이 아닌 경우.
400 invalid_translation_text: 공백만 있는 텍스트인 경우.
400 invalid_translation_engine: 알 수 없는 엔진인 경우.
400 idempotency_key_required: 키가 없거나 비어 있거나 너무 긴 경우, 또는 idempotency_key가 문자열이 아닌 경우.
400 invalid_job: 작업 ID 형식이 잘못된 경우.

이 호스트의 번역 서비스 응답은 봉투 형식 {"status":{"code":HTTP_STATUS},"response":{...}}을 사용하며, status는 객체입니다. 작업 ID는 response.id에서, 완료된 결과는 response.result에서 읽으세요. 오류 시 코드는 response.code에 들어 있으며 메시지나 요청 ID는 없습니다. 인증 실패(401)는 호스트 공통 로그인 검사에서 반환되며 본문이 다를 수 있으므로 파싱 전에 HTTP 상태를 확인하세요. 작업은 기본 호스트와 공유하지만 파서가 봉투 형식에 맞도록 폴링, 정산, 사용량 조회에는 같은 호스트를 사용하세요. 이 호스트도 /v3/translate/estimate에서 같은 JSON 필드를 받으며 멱등성 키는 필요하지 않습니다. 견적은 response 아래에 있습니다.