MultiTEL
개발자

음성 텍스트 변환 및 번역 작업

인증, 작업 상태 조회, 결과가 불확실한 제출의 재시도, 결제 대기 결과의 정산, 사용량 확인, 오류 및 제한 처리를 안내합니다.

이 페이지의 내용
  1. 인증
  2. 완료될 때까지 주기적으로 조회하기
  3. 결과가 불확실한 요청을 안전하게 재시도하기
  4. 잔액을 충전한 뒤 결과 제공받기
  5. 사용량 확인하기
  6. 제한
  7. 요청 오류 처리하기

아래 예제의 SERVICE를 speech_to_text 또는 translate로, JOB_ID를 반환된 UUID로 바꾸세요. 모든 작업에는 인증에 설명된 계정 인증 정보가 필요하며, 해당 정보를 소유한 계정 범위에서만 수행됩니다. 작업은 어느 API 호스트에서든 조회할 수 있지만 호스트마다 응답의 외부 구조가 다르므로 일관되게 같은 호스트를 사용하세요.

호스트성공오류
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

호스트 api.multitel.net에서는 인증 실패(401)가 이 외부 구조를 적용하기 전에 반환되며 본문이 다를 수 있으므로, 응답을 파싱하기 전에 HTTP 상태를 확인하세요.

인증

모든 요청에는 계정 인증 정보가 포함되어야 합니다. 작업, 멱등성 키, 제한, 사용량, 요금은 인증 정보를 소유한 계정에 속합니다. 두 호스트에서 해당 계정의 모든 인증 정보가 이를 공유하며, 어떤 인증 정보로 요청을 보냈는지와 무관합니다.

  • HTTP Basic (Authorization: Basic 또는 curl --user). 비밀번호 유형의 API 계정, 하위 계정 또는 본인 계정의 로그인 정보를 사용할 수 있습니다. 전용 API 계정을 권장합니다. 사용자 이름에는 콜론을 넣을 수 없으며 사용자 이름과 비밀번호는 어느 쪽도 비워 둘 수 없습니다.
  • Bearer 토큰 (Authorization: Bearer YOUR_TOKEN). 토큰 유형의 API 계정에 사용할 수 있습니다. 토큰 API 계정에는 IP 제한이 필수이며, 요청은 허용된 주소에서 와야 합니다. 두 API 호스트 모두 계정에 설정된 IPv4 주소와 CIDR 범위를 허용합니다. 토큰을 Basic 비밀번호로 보낼 수는 없습니다. 사용하는 호스트에서 토큰이 작동하는지 확인하세요.
API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

API 계정에 IP 주소 제한이 있으면 허용된 주소에서 요청을 보내세요. 인증 정보가 없거나 유효하지 않으면 401을 반환합니다. 호스트 api.multitel.net에서는 토큰 계정의 인증 정보를 Basic으로 보내는 경우처럼, 인증 정보가 유효하더라도 이 서비스를 사용할 수 없으면 403과 unsupported_transcription_principal 또는 unsupported_translation_principal 오류 코드를 반환합니다. 호스트 api.multitel.net에 한 주소에서 인증 실패를 반복하면 해당 주소가 차단될 수 있으므로, 재시도하기 전에 인증 정보를 수정하세요.

완료될 때까지 주기적으로 조회하기

다음 요청을 보내세요: GET /v3/SERVICE/JOB_ID. 조회 주기는 3초에 한 번보다 짧지 않게 하는 것이 좋습니다. 외부 응답 구조는 요청을 설명합니다. 처리가 끝났는지는 내부 작업의 status를 확인하세요.

상태의미
queued접수되었으며 대기 중입니다. 한 계정의 작업은 다른 계정과 번갈아가며 한 번에 하나씩 처리됩니다.
running처리 중입니다. progress는 null일 수 있으며, null 값만으로 작업이 멈췄다는 뜻은 아닙니다.
completed결과를 사용할 수 있습니다. 보관하고 중요한 세부 사항을 원본과 비교하세요.
failed다음을 확인하세요: failureCode. 실패한 작업에는 요금이 부과되지 않습니다. 원인을 수정하고 새 키로 제출하세요. 같은 키로 다시 보내면 같은 실패한 작업이 반환됩니다.
awaiting_payment처리는 끝났지만 선불 잔액이 요금을 충당하지 못했습니다. 결과는 저장되며 작업을 정산할 때까지 제공되지 않습니다.
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

호스트 api.multitel.net에서는 HOST를 https://api.multitel.net 주소로 설정하고 .response.id를 .data.id 대신 읽으세요.

결과가 불확실한 요청을 안전하게 재시도하기

제출 시간이 초과되거나 429 또는 5xx 상태가 반환되면 같은 입력을 같은 멱등성 키로 다시 보내세요. 어느 호스트에서든 작업이 접수된 후 응답이 유실되거나 오류로 대체될 수 있습니다. 같은 키로 다시 보내면 작업이 존재할 경우 해당 작업이 반환됩니다. 키를 다른 입력에 재사용하면 409와 idempotency_conflict를 반환합니다. 유료 서비스가 비활성화된 동안의 503이나 읽을 수 없는 오디오 파일에 대한 500처럼 매번 반복되는 오류도 있으므로 몇 차례 시도한 뒤에는 중단하세요.

키를 바꿀 때의 동작은 서비스마다 다릅니다.

  • 음성 텍스트 변환에서는 새 키가 새 작업을 만들며 처리가 성공적으로 끝나면 별도 요금이 부과됩니다. 원래 키는 처리 방식이 업데이트된 후에도 원래 작업을 계속 반환합니다.
  • 번역에서는 동일한 내용으로 새 키를 보내면 대기 중, 처리 중, 완료 또는 결제 대기 상태의 일치하는 작업을 추가 요금 없이 반환합니다. 이전 작업이 실패했거나 처리 버전이 바뀌면 새 작업을 만듭니다. 처리 버전이 바뀐 뒤 원래 키로 번역을 재시도하면 409를 반환하므로, 원래 작업 ID를 보관하고 작업을 직접 조회하세요.

잔액을 충전한 뒤 결과 제공받기

작업 상태가 awaiting_payment이면 잔액이 해당 작업의 costUsd를 다음 $0.00001 단위로 올림한 금액 이상이 되도록 충전한 후 다음 요청을 보내세요: POST /v3/SERVICE/JOB_ID/settle. 차감은 $0.00001 단위로 이루어지고 같은 서비스의 이전 작업에서 이월된 잔여분을 포함하므로, 차감액은 costUsd보다 $0.00001 미만의 차이로 클 수 있습니다. 호스트 api.multi.tel에서는 JSON {} 또는 빈 본문을 보내세요. 본문에 속성이 하나라도 있으면 400으로 거부됩니다. 호스트 api.multitel.net에서는 본문을 무시합니다. 정산은 저장된 결과를 제공하며 음성 텍스트 변환이나 번역을 다시 실행하지 않습니다. 응답에 작업이 포함되므로 상태가 completed인지 확인하세요. 잔액이 여전히 부족하면 작업은 awaiting_payment 상태로 유지되며 응답도 여전히 HTTP 200입니다.

음성 텍스트 변환에서는 이미 완료된 작업을 정산하면 duplicate: true와 함께 작업이 반환되며, 대기 중, 처리 중 또는 실패한 작업을 정산하면 409와 transcription_not_awaiting_payment를 반환합니다. 번역에서는 다른 상태의 작업을 정산하면 작업을 변경하지 않고 반환합니다. 정산은 유료 처리가 활성화된 동안에만 가능합니다(그렇지 않으면 503). 결제 대기 작업은 예약된 비용으로 계산되므로, 선불 계정에서는 해당 작업을 정산할 때까지 새 유료 작업 제출이 402로 차단될 수 있습니다.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

사용량 확인하기

다음을 사용하세요: GET /v3/SERVICE/usage. 선택적 매개변수 from 및 to는 YYYY-MM-DD 형식의 UTC 날짜이며 시작일과 종료일을 모두 포함합니다. 생략하면 from의 기본값은 오늘의 30일 전이며 to의 기본값은 오늘(UTC)입니다. to는 from보다 이전일 수 없고 두 날짜의 간격은 최대 366일입니다(최대 367개의 날짜). 잘못된 달력 날짜, 역순이거나 너무 긴 범위는 400을 반환합니다. 호스트 api.multi.tel에서는 다른 쿼리 매개변수도 같은 오류를 반환합니다.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

응답에는 mode, currency (USD), from, to 및 days가 포함됩니다. 마지막 항목은 최신순으로 정렬된 목록입니다.

  • 음성 텍스트 변환 항목은 날짜와 출처별로 묶입니다. 포함되는 필드는 date, source (api 또는 Hosted PBX 녹음의 경우 hpbx), files, audioSeconds, billedSeconds, accruedUsd 및 debitedUsd입니다.
  • 번역 항목은 날짜, 출처, 엔진별로 묶입니다. 포함되는 필드는 date, source, engine, jobs, sourceCharacters, accruedUsd 및 debitedUsd입니다.

accruedUsd는 소수점 아래 아홉 자리의 정확한 비용이며 debitedUsd는 소수점 아래 다섯 자리의 차감액입니다. 사용량은 각 작업의 요금이 정산된 UTC 날짜에 기록되므로, 대기 중, 처리 중, 실패 또는 결제 대기 작업은 표시되지 않습니다.

제한

각 계정은 음성 텍스트 변환과 번역을 합쳐 최대 50개의 미완료 작업을 가질 수 있습니다. 대기 중, 처리 중 또는 결제 대기 상태이며 Hosted PBX 녹음 처리도 포함됩니다. 이 한도나 서비스 전체 용량에 도달하면 제출 시 429와 transcription_queue_full 또는 translation_queue_full 오류 코드를 반환합니다. 호스트 api.multi.tel에서는 해당 호스트에 대한 모든 요청을 합산하여 클라이언트 IP 주소별로 분당 300개 요청 제한도 적용합니다. 이 제한에 걸리면 JSON 오류용 외부 구조 대신 요청 빈도 제한 헤더와 일반 텍스트 본문을 포함한 429를 반환합니다.

요청 오류 처리하기

기본 호스트에서는 실패 시 HTTP 오류 상태와 status: "error", code, message, requestId가 포함된 JSON을 반환합니다. 모든 응답에는 X-Request-ID 헤더도 포함됩니다. 직접 값을 지정할 수 있으며 128자보다 긴 값은 잘립니다. 호환 호스트는 response.code에 오류 코드만 반환합니다. 가능한 경우 요청 ID와 오류 코드를 기록하고 오디오, 텍스트, 인증 정보는 로그에 남기지 마세요.

일반적인 상태:

상태의미
400잘못된 입력입니다.
401인증 정보가 없거나 유효하지 않습니다.
402선불 잔액이 부족합니다.
403호환 호스트에서 이 서비스를 사용할 수 없는 인증 정보입니다.
404알 수 없는 작업 또는 경로입니다.
405지원하지 않는 메서드 또는 서비스 내의 알 수 없는 경로입니다.
409충돌하는 입력, 같은 언어로의 번역 또는 결제 대기가 아닌 음성 작업의 정산입니다.
413본문 또는 파일이 너무 큽니다.
422지원하지 않는 오디오 또는 사용할 수 없는 표준 번역 언어 쌍입니다.
429대기열, 유효성 검사 또는 요청 빈도 제한입니다.
500읽을 수 없는 오디오 파일을 포함한 예기치 않은 서버 오류입니다.
503비활성화되었거나 일시적으로 사용할 수 없는 서비스 또는 현재 확인할 수 없는 인증 정보입니다.

모든 유효성 검사 실패가 같은 상태를 반환한다고 가정하지 말고 반환된 오류 코드를 따르세요.

429 또는 503이면 기다린 뒤 대기 시간을 늘려 가며 같은 제출 키로 재시도하세요. Retry-After 헤더가 있으면 따르세요. 입력이나 인증 정보가 잘못되었으면 먼저 원인을 수정하세요. 이전 작업이 아직 대기열에 있는 동안 새 키를 반복해서 제출하지 마세요.