Equalang API 레퍼런스와 퀵스타트
Equalang핵심 요약
Equalang API 연동 가이드. 텍스트 즉시 번역과 문서·오디오·비디오의 비동기 처리, 공개 API 10개의 예시를 담았습니다.
키워드: API 연동; 파일 번역 API; 자동 번역; 개발자 가이드; API 레퍼런스
관리 백엔드나 워크플로에 Equalang을 연동하면 텍스트를 즉시 번역할 수 있을 뿐 아니라, 문서와 오디오·비디오를 파일 단위로 처리할 수 있습니다. 지원되는 형식에서는 원본 레이아웃도 유지됩니다.
이 가이드에서는 cURL과 Python으로 파일 번역 워크플로를 시작하는 방법을 먼저 소개하고, 공개된 API 엔드포인트 10개 전체를 참조 문서로 정리합니다.
인증과 표준 응답
Equalang API는 https://equalang.com/v1에서 제공됩니다. 모든 요청은 Authorization HTTP 헤더에 API 키를 넣어 인증합니다.
Authorization: Bearer el_your_api_key_here
API 키에는 필요한 스코프가 부여되어 있어야 합니다(예: 작업은 translations:document, 텍스트는 translations:text, 파일 직접 다운로드는 files:read).
표준 응답 구조: 성공한 JSON 응답은 모두 동일한 최상위 구조를 사용합니다. 아래에서는 간결하게 보여주려고 필수적이지 않은 일부 필드를 생략했지만, 여전히 완전히 유효한 JSON 객체입니다. 예시에 나오는 ID·URL·잔액은 순전히 예시 값이며, 실제 응답에서 반환된 값을 사용해야 합니다.
{
"code": "OK",
"message": "ok",
"data": {},
"request_id": "req_example_id"
}
퀵스타트: 파일 비동기 번역
문서 한 건을 처리하려면 파일을 업로드해 작업을 시작하고, 상태를 폴링한 뒤 결과를 다운로드하는 비동기 흐름을 거칩니다. 직접 가진 파일을 써도 되고, 테스트용 샘플 supply-confirmation.zh-CN.docx을 내려받아도 됩니다.
방법 1: cURL 사용
먼저 API 키를 환경 변수로 내보냅니다(키 생성: https://equalang.com/api-keys).
export EQUALANG_API_KEY="el_your_api_key_here"
1. 업로드 및 작업 시작
파일을 직접 전송합니다. API가 필요한 크레딧을 확보하고 job_id를 반환합니다. 타임아웃이 발생해도 작업이 중복 생성되지 않도록 고유한 Idempotency-Key(UUID 등)를 함께 보내세요. 같은 요청을 재시도할 때는 이 키를 다시 사용하고, 새 작업에는 새 키를 만듭니다. (실행 전에 로컬에 report.docx 파일이 있어야 하며, 없다면 코드의 파일명을 바꾸세요.)
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" \ -F "file=@report.docx" \ -F "target_language=en"
다음 단계에 쓸 job_id는 응답의 data 객체에서 추출하세요. 예시에 있는 과거 ID를 그대로 복사해 쓰지 마세요.
2. 작업 상태 폴링
job_id로 진행 상황을 폴링합니다. 요청 사이에는 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은 임시 서명으로 인증되므로, 다운로드할 때 API의 Bearer 토큰을 보낼 필요가 없고 보내지도 마세요. HTTP 오류가 났을 때 오류 HTML을 파일로 저장하지 않도록 -f처럼 실패를 감지하는 옵션을 사용하세요.
curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"
방법 2: Python(requests) 사용
참고: requests 라이브러리가 필요합니다(pip install requests).
import os
import time
import requests
API_KEY = os.environ.get("EQUALANG_API_KEY")
# Provide a stable key for the same request, change it for new tasks
IDEMPOTENCY_KEY = os.environ.get("IDEMPOTENCY_KEY", "your-unique-uuid-here")
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Idempotency-Key": IDEMPOTENCY_KEY
}
BASE_URL = "https://equalang.com/v1"
# 1. Create Job
# Ensure you have a local file named report.docx before running
with open("report.docx", "rb") as f:
files = {"file": f}
data = {"target_language": "en"}
response = requests.post(
f"{BASE_URL}/jobs/translate",
headers=HEADERS,
files=files,
data=data,
timeout=30
)
response.raise_for_status()
job_id = response.json()["data"]["job_id"]
print(f"Job created: {job_id}")
# 2. Poll Job
while True:
res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
res.raise_for_status()
job_data = res.json()["data"]
if job_data["finished"]:
if job_data["status"] == "SUCCEEDED":
download_url = job_data["download_url"]
print(f"Success! Downloading result...")
# 3. Download Result (No API key needed for the temporary URL)
dl_res = requests.get(download_url, timeout=30)
dl_res.raise_for_status()
with open("report_translated.docx", "wb") as out:
out.write(dl_res.content)
print("Download complete.")
else:
print(f"Job ended with status: {job_data['status']}")
break
retry_after = int(res.headers.get("Retry-After", 5))
time.sleep(retry_after)
견적을 먼저 확인하거나 폴링 상태를 잃어버린 경우를 복구하는 등 고급 사용 사례에는 응용 스크립트 translate_file.py를 내려받아 사용하세요.
엔드포인트 레퍼런스
공개된 엔드포인트 10개의 세부 사항과 요청·응답 구조 예시를 소개합니다.
지원 언어의 정확한 코드(예: zh-CN, en)는 OpenAPI 스키마의 DocumentLanguage와 TextLanguage 열거형 또는 Developers 가이드를 참조하세요. auto 코드는 source_language 전용입니다.
1. 텍스트 번역
POST /v1/text/translate
텍스트 문자열을 동기적으로 번역합니다. 비용은 번역이 성공한 텍스트에 대해서만 청구됩니다. 언어가 자동으로 감지되지 않았다면 detected_source_language는 null입니다.
curl --fail-with-body -X POST "https://equalang.com/v1/text/translate" \
-H "Authorization: Bearer $EQUALANG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"texts": ["您的订单已发货。"], "target_language": "en"}'
{
"code": "OK",
"message": "ok",
"data": {
"translations": [
{
"translated_text": "Your order has been shipped.",
"detected_source_language": null,
"error": null
}
],
"usage": {
"credits_charged": 0.07
}
},
"request_id": "dd0b35ce1b52474faad670a33a9fc62d"
}
2. 견적용 파일 업로드
POST /v1/files
번역 전에 최대 비용을 표시해야 한다면 이곳에 파일을 업로드하세요. file_id와 필요한 크레딧을 나타내는 quote가 반환됩니다.
curl --fail-with-body -X POST "https://equalang.com/v1/files" \ -H "Authorization: Bearer $EQUALANG_API_KEY" \ -F "file=@report.docx"
{
"code": "OK",
"message": "ok",
"data": {
"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6",
"quote": {
"translate": 0.59,
"transcribe": null
}
},
"request_id": "e81b9f386ace4a82b63dc292c9cff669"
}
3. 문서 번역 작업 생성
POST /v1/jobs/translate
비동기 번역 작업을 생성합니다. file(multipart), file_url, file_id 중 하나를 받습니다.
# Using a previously uploaded file_id
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
-H "Authorization: Bearer $EQUALANG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6", "target_language": "en"}'
{
"code": "OK",
"message": "ok",
"data": {
"job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
"status": "INIT",
"credits_reserved": 0.59
},
"request_id": "36c7dc43855b4e9eae553e7fd656788c"
}
4. 전사 작업 생성
POST /v1/jobs/transcribe
오디오나 비디오 파일에서 음성을 추출해 시간 정보가 있는 자막으로 반환하며, 번역은 하지 않습니다.
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/transcribe" \
-H "Authorization: Bearer $EQUALANG_API_KEY" \
-F "file=@interview.mp3" \
-F 'options={"output_formats": ["srt", "txt"]}'
{
"code": "OK",
"message": "ok",
"data": {
"job_id": "b1a23c45-1234-5678-90ab-cdef12345678",
"status": "INIT",
"credits_reserved": 1.848
},
"request_id": "req_12345"
}
5. 작업 상태 조회
GET /v1/jobs/{job_id}
진행 중이거나 완료된 작업의 진행 상황과 다운로드 링크를 가져옵니다. 경로의 {job_id}는 실제 UUID로 바꿔 넣으세요.
curl --fail-with-body "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
{
"code": "OK",
"message": "ok",
"data": {
"job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
"status": "SUCCEEDED",
"finished": true,
"progress_percent": 100,
"download_url": "https://example.com/download/download_url",
"outputs": [
{
"kind": "translation",
"format": "docx",
"filename": "supply-terms.zh-cn-equalang-en.docx",
"download_url": "https://example.com/download/download_url"
}
]
},
"request_id": "7c7621312ab04f3da3492db98945e597"
}
6. 파일 바이트 다운로드
GET /v1/files/{file_id}
API 키가 필요 없는 임시 download_url과 달리, 이 엔드포인트는 계정에 저장된 원본 또는 번역된 파일의 원시 바이트를 file_id로 직접 내려받습니다. files:read 스코프를 가진 API 키가 필요합니다.
curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \ -H "Authorization: Bearer $EQUALANG_API_KEY" \ -o translated_result.docx
(JSON 봉투 없이 바이너리 데이터를 직접 반환합니다)
7. 작업 취소
POST /v1/jobs/{job_id}/cancel
작업을 취소합니다. 작업이 INIT 또는 QUEUED 상태이면 즉시 CANCELLED가 됩니다. RUNNING 상태라면 완전히 중단될 때까지 CANCELLING 상태로 남습니다.
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/cancel" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
{
"code": "OK",
"message": "ok",
"data": {
"job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
"status": "CANCELLED",
"finished": true,
"usage": {
"credits_reserved": 0,
"credits_charged": 0
}
},
"request_id": "502c12dff71149f588620e96b07769fb"
}
8. 작업 재시도
POST /v1/jobs/{job_id}/retry
작업을 재시도합니다. 재시도할 수 있는 경우는 작업이 FAILED이면서 error.retryable이 true인 경우, 또는 CANCELLED인 경우입니다. 재시도하면 크레딧이 다시 확보됩니다. 단 결과 전달이 실패한 경우(RESULT_DELIVERY_FAILED)에는 재시도에서 전달만 다시 시도하며 번역 비용을 두 번 청구하지 않습니다.
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/retry" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
{
"code": "OK",
"message": "ok",
"data": {
"job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
"status": "INIT",
"finished": false,
"usage": {
"credits_reserved": 0.59,
"credits_charged": 0
}
},
"request_id": "497c3794b0a4497e890f64cc8b7d6d27"
}
9. 작업 목록
GET /v1/jobs
번역·전사 작업 목록을 최신순으로 페이지 단위로 반환합니다. 페이지 이동에는 쿼리 파라미터 limit와 cursor(또는 offset)를 전달합니다.
curl --fail-with-body "https://equalang.com/v1/jobs?limit=10" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
{
"code": "OK",
"message": "ok",
"data": {
"items": [
{
"job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
"status": "SUCCEEDED",
"task": "translate"
}
],
"limit": 10,
"offset": 0,
"total": 39,
"next_cursor": "MjAyNi0xMC0wOVQxOD..."
},
"request_id": "e79cd556afe94424a558e12ca7c2aed8"
}
10. 크레딧 잔액 확인
GET /v1/credits/balance
계정의 사용 가능 크레딧과 동결된 크레딧을 반환합니다.
curl --fail-with-body "https://equalang.com/v1/credits/balance" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
{
"code": "OK",
"message": "ok",
"data": {
"total_credits": 125.50,
"frozen_credits": 1.50,
"available_credits": 124.00
},
"request_id": "req_bal_123"
}
오류 처리
실패한 API 요청은 표준 HTTP 오류 상태와 함께, 실패 이유와 재시도 가능 여부(retryable)를 담은 오류 응답을 반환합니다.
{
"code": "INVALID_JOB_ID",
"message": "Invalid job id",
"data": null,
"request_id": "9e97df047da640f7b60e10cfbc571711",
"retryable": false
}