자사의 업무 시스템이나 워크플로우에 문서, 음성/영상 파일 번역 처리를 통합하는 절차를 설명합니다.
cURL 또는 Python을 사용하여 파일의 비동기 업로드, 폴링(polling), 번역 결과 획득까지 신속하게 구현할 수 있습니다.
멱등성 키(Idempotency-Key)를 이용한 중복 실행 방지나 Retry-After에 따른 폴링, 장애 발생 시 재시도와 같은 안전 운영 포인트를 모두 다루고 있습니다.
Equalang API를 사용하면 텍스트의 즉시 번역 외에도 문서나 음성/영상 파일을 파일 단위로 처리할 수 있으며 (지원 형식에서는 원래 레이아웃이 유지됩니다).
본 기사에서는 cURL 및 Python(requests)을 이용한 파일 번역의 빠른 시작 방법과, 실제 운영에 필요한 오류 재시도 설계 방안을 설명합니다.
Equalang API의 기본 URL은 https://equalang.com/v1입니다.
모든 요청에는 Authorization HTTP 헤더에 API 키를 지정해야 합니다.
Authorization: Bearer el_your_api_key_here
API 키는 API 키 관리 화면에서 생성할 수 있으며, 목적에 따라 필요한 스코프(Scope)가 있습니다 (작업 처리에는 translations:document, 텍스트 번역은 translations:text, 파일 다운로드는 files:read).
성공 시 응답은 다음의 공통 JSON 구조를 따릅니다.
{
"code": "OK",
"message": "ok",
...
}
문서 번역은 ① 업로드 및 작업 시작, ② 상태 폴링(polling), ③ 완료 파일 다운로드라는 비동기 흐름으로 처리합니다. 검증용 샘플로 supply-confirmation.zh-CN.docx를 사용할 수 있습니다.
환경 변수에 API 키를 설정하여 실행합니다.
export EQUALANG_API_KEY="el_your_api_key_here"
1. 업로드 및 작업 시작
타임아웃으로 인한 중복 실행을 방지하기 위해 고유한 Idempotency-Key (UUID 등)를 부여합니다. 같은 전송을 재시도할 때는 이 키를 재사용하고, 새로운 작업을 할 때는 새로운 키를 생성해야 합니다.
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
-H "Authorization: Bearer $EQUALANG_API_KEY" \
-H "Idempotency-Key: a-unique-uuid-here" \
...
응답에서 data.job_id를 가져옵니다.
2. 상태 폴링(Polling)
응답 헤더의 Retry-After가 나타내는 초만큼 대기하면서, finished가 true가 될 때까지 진행 상황을 확인합니다.
curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
-H "Authorization: Bearer $EQUALANG_API_KEY"
3. 결과 다운로드
상태가 SUCCEEDED가 되면, 응답에 임시적인 download_url이 반환됩니다. 이 URL은 임시 서명(temporary signature)되어 있으므로, API의 Bearer 토큰을 첨부하지 않고 직접 다운로드합니다.
curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"
일련의 흐름을 자동화하는 Python 구현 예시입니다 (pip install requests가 필요합니다).
import os
import time
import requests
...
사전 견적(pre-estimate) 획득이나 복구 기능이 포함된 응용 구현에 대해서는 translate_file.py도 참조해 주세요.
안정적인 워크플로우 운영을 위해 다음 설계를 적용합니다.
재시도 판별: API 오류 응답에는 retryable 필드가 포함됩니다. true
의 경우에만 재시도(retry)를 실행하고, false로 처리합니다.
(예: 파라미터 오류 등)의 경우에는 즉시 중단합니다. -
작업 재실행 엔드포인트: 작업이 FAILED 상태이고 재시도가 가능하거나 CANCELLED인 경우, POST /v1/jobs/{job_id}/retry를 사용하여 재실행할 수 있습니다. 결과 전달에 실패한 케이스(RESULT_DELIVERY_FAILED)에서는 전달 처리만 재시도됩니다. -
작업 취소: 처리를 중단하려면 POST /v1/jobs/{job_id}/cancel을 호출합니다.
Equalang API에서 제공하는 주요 엔드포인트는 다음과 같습니다.
- 텍스트 동기 번역(
POST /v1/text/translate) : 경량 텍스트를 동기적으로 번역합니다. -
- 사전 견적(
POST /v1/files) : 번역 전에 소비 크레딧의 예상치(quote)와 file_id를 가져옵니다. -
- 문서 번역 작업 생성(
POST /v1/jobs/translate) : 멀티파트 파일 또는 업로드된 file_id를 지정하여 비동기 번역을 시작합니다. -
- 음성/영상 전사(Transcription) 작업 생성(
POST /v1/jobs/transcribe) : 미디어 파일에서 타임코드와 함께 자막(srt / txt 등)을 생성합니다. -
- 작업 상태 조회(
GET /v1/jobs/{job_id}) : 진행 상황과 완료 시 다운로드 링크를 가져옵니다. -
- 작업 목록 조회(
GET /v1/jobs) : 페이지네이션(cursor / limit)을 통해 과거 작업 기록을 확인할 수 있습니다. -
- 크레딧 잔액 확인(
GET /v1/credits/balance) : 사용 가능한 크레딧과 동결된 크레딧을 조회합니다.
언어 코드의 상세 사양은 Developers 가이드를 참조해 주십시오.
본 문서는 Equalang 팀에 의해 작성되었습니다. 신규 등록 시 200 크레딧이 부여되므로, 실제 API 요청에서 부담 없이 사용해 보시기 바랍니다.
