Equalang API Reference & Quickstart
EqualangIn brief
Developer guide to integrating Equalang API. Translate text or process documents and media asynchronously. Includes 10 endpoint examples.
Keywords: API integration; file translation API; automated translation; developer guide; API reference
When integrating Equalang into your management backend or workflow, you can translate text instantly or process entire files—such as documents, audio, and video—while keeping their original layout where supported.
This guide provides a quickstart for the file translation workflow using cURL and Python, followed by a complete reference for all 10 public API endpoints.
Authentication & Standard Response
The Equalang API is served at https://equalang.com/v1. Authenticate every request by providing your API key in the Authorization HTTP header:
Authorization: Bearer el_your_api_key_here
Your API key must have the correct scopes (e.g., translations:document for jobs, translations:text for text, files:read for direct file downloads).
Standard Response Envelope: All successful JSON responses use a standard top-level structure. For brevity, the structural examples below omit some non-essential fields but remain fully valid JSON objects. The IDs, URLs, and balance numbers shown are purely illustrative—ensure you use the actual values returned in your own responses.
{
"code": "OK",
"message": "ok",
"data": {},
"request_id": "req_example_id"
}
Quickstart: Asynchronous File Translation
Processing a whole document requires an asynchronous workflow: upload the file to start a job, poll its status, and download the result. You can use your own file, or download our sample file supply-confirmation.zh-CN.docx for testing.
Method 1: Using cURL
First, export your API key (you can create one at https://equalang.com/api-keys):
export EQUALANG_API_KEY="el_your_api_key_here"
1. Upload and Start Job
Submit the file directly. The API reserves the necessary credits and returns a job_id. Include a unique Idempotency-Key (such as a UUID) to prevent duplicate jobs if a timeout occurs. Reuse this key if you need to retry the same submission, and generate a new one for new tasks. (Make sure you have a local file named report.docx before running, or change the name in the code).
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"
Extract the job_id from the response data object to use in the next step. Do not copy historical IDs from examples.
2. Poll Job Status
Use your job_id to poll progress. Wait for the duration recommended by the Retry-After header between requests. Stop polling when finished is true.
curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \ -H "Authorization: Bearer $EQUALANG_API_KEY"
3. Download the Result
Once the status is SUCCEEDED, the response includes a temporary download_url. This URL uses a temporary signature authorization, so you do not need to (and should not) send your API Bearer token when downloading from it. Use a flag like -f to fail silently on HTTP errors so you don't save error HTML as your file.
curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"
Method 2: Using Python (requests)
Note: Requires the requests library (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)
For advanced use cases (like checking quotes first or recovering lost polling states), you can download our advanced script translate_file.py.
Endpoint Reference
Here are the details and payload structure examples for all 10 public endpoints.
Please note that document and text endpoints support different languages. Refer to the DocumentLanguage and TextLanguage enumerations in the OpenAPI schema or the Developers guide for the exact codes (e.g., zh-CN, en). The auto code is exclusively for source_language.
1. Translate Text
POST /v1/text/translate
Translate text strings synchronously. Texts are billed only if successfully translated. detected_source_language is null if a specific language wasn't automatically detected.
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. Upload File for Quotation
POST /v1/files
If you need to display the maximum potential cost before translating, upload the file here. It returns a file_id and a quote (credits required).
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. Create Document Translation Job
POST /v1/jobs/translate
Creates an asynchronous translation job. Accepts file (multipart), file_url, or 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. Create Transcription Job
POST /v1/jobs/transcribe
Extracts and returns the spoken text from an audio or video file as timed subtitles, without translating it.
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. Query Job Status
GET /v1/jobs/{job_id}
Retrieves the progress and download links for an active or completed job. Replace {job_id} in the path with your actual 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. Download File Bytes
GET /v1/files/{file_id}
Unlike the temporary download_url (which requires no API key), this endpoint allows you to download the raw bytes of any source or translated file stored on your account directly using its file_id. It requires an API key with the files:read scope.
curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \ -H "Authorization: Bearer $EQUALANG_API_KEY" \ -o translated_result.docx
(Returns binary data directly, no JSON envelope)
7. Cancel Job
POST /v1/jobs/{job_id}/cancel
Cancels a job. If the job is INIT or QUEUED, it immediately becomes CANCELLED. If it is RUNNING, it enters a CANCELLING state until fully stopped.
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. Retry Job
POST /v1/jobs/{job_id}/retry
Retries a job. You can retry if a job is FAILED and its error.retryable is true, or if it was CANCELLED. Retrying will reserve credits again. Note that if result delivery failed (RESULT_DELIVERY_FAILED), retrying will attempt delivery again but will not charge you for translation a second time.
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. List Jobs
GET /v1/jobs
Returns a paginated list of your translation and transcription jobs, starting with the newest. Pass limit and cursor (or offset) as query parameters to paginate.
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. Check Credit Balance
GET /v1/credits/balance
Returns your available and frozen account credits.
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"
}
Handling Errors
Failed API requests return standard HTTP error statuses accompanied by an error response payload indicating the reason and whether the operation is retryable.
{
"code": "INVALID_JOB_ID",
"message": "Invalid job id",
"data": null,
"request_id": "9e97df047da640f7b60e10cfbc571711",
"retryable": false
}