Equalang API リファレンスとクイックスタート
Equalangこの記事の要点
Equalang API の統合ガイド。テキストの即時翻訳と、ドキュメント・音声・動画の非同期処理、公開 API 10 件の実例をまとめています。
キーワード: API 連携; ファイル翻訳 API; 自動翻訳; 開発者ガイド; API リファレンス
業務システムやワークフローに Equalang を組み込めば、テキストを即時に翻訳できるだけでなく、ドキュメントや音声・動画をファイル単位で処理できます。対応する形式では元のレイアウトも保たれます。
本ガイドでは、cURL と Python によるファイル翻訳のクイックスタートを紹介したうえで、公開されている全 10 件の API エンドポイントをまとめて解説します。
認証と共通レスポンス
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"
}
クイックスタート: ファイルの非同期翻訳
ドキュメント 1 件を処理するには、アップロードしてジョブを開始し、ステータスをポーリングして結果をダウンロードする、という非同期の流れになります。手持ちのファイルを使うほか、検証用のサンプル 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"
}
エラー処理
失敗したリクエストは標準的な HTTP エラーステータスを返し、理由と retryable（再試行可能かどうか）を示すエラーペイロードが付属します。
{
"code": "INVALID_JOB_ID",
"message": "Invalid job id",
"data": null,
"request_id": "9e97df047da640f7b60e10cfbc571711",
"retryable": false
}