意扣
Equalang 笔记

Equalang API 接入参考与 10 个公开接口结构示例

意扣

导读

面向开发者的 Equalang API 接入指南。学习如何即时翻译文本，或通过异步任务自动处理文档和音视频文件，附 10 个公开接口结构示例。

关键词：API接入；文件翻译API；自动化翻译；开发者指南；接口参考

当业务系统（如管理后台或收件目录）需要将文件或文本转化为目标语言时，团队希望机器能直接返回在支持的格式中尽力保留排版的译文，而不是手动去网页端上传。Equalang 提供了完整的 API 体系，既能同步返回短文本翻译，又能异步处理文档、表格、幻灯片甚至音视频录音。

本文将演示最常用的文件翻译跑通流程，并为您提供全套 10 个公开接口的完整参考与轻量级结构示例。

认证与通用响应结构

Equalang API 的正式请求地址为 https://equalang.com/v1。请在每次受保护的请求头中，通过 Authorization HTTP 头携带您的 API 密钥：

Authorization: Bearer el_您的_api_密钥

请确保您的 API 密钥具备需要的权限（如翻译任务对应 translations:document，下载自身文件对应 files:read）。

通用响应体： 所有成功的 JSON 响应都包含一致的顶层结构 { "code", "message", "data", "request_id" }。为了突出重点，下文的 JSON 结构示例适度省略了次要字段，但保留了合法的 JSON 对象结构。请注意示例中的 ID、URL 与余额仅为示意，完整代码运行时请使用您自身实际返回的数据。

{
  "code": "OK",
  "message": "ok",
  "data": {},
  "request_id": "req_example_id"
}

快速上手：异步文件翻译

完整处理一份文件需要时间。API 采用异步模式：上传文件创建任务、轮询进度、完成后下载。您可以使用自己的文件，或下载样本文件 supply-terms-clean.en.docx 进行测试。

方式 1：使用 cURL

首先，配置你的 API 密钥（可在 https://equalang.com/api-keys 创建）：

export EQUALANG_API_KEY="el_您的_api_密钥"

1. 上传并创建任务

最直接的方式是同时提交文件和目标语言。系统会预留相应的积分，并返回 job_id。为了防止网络超时导致的重复创建与扣费，请务必在请求头加上 Idempotency-Key（如 UUID）。同一任务重试时保留该 key，新任务请更换 key。（请确保本地存在 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=zh-CN"

从返回结果的 data 对象中提取您自己的 job_id，以供下一步使用，不要盲目复制文档中的历史 ID。

2. 轮询任务状态

拿着真实的 job_id 定期查询进度。您可以参考响应头中的 Retry-After 来决定下一次请求的间隔。当返回的 finished 为 true 时即可停止轮询。

curl --fail-with-body "https://equalang.com/v1/jobs/您的实际_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. 下载翻译结果

一旦状态变为 SUCCEEDED，响应的 data 会提供一个 download_url。这是一个临时签名授权的链接，因此无需也不应该携带 API Bearer 头进行下载。建议使用 -f 等参数，以便 HTTP 报错时停止下载，避免将错误 HTML 存为文件。

curl -f -o report_translated.docx "https://example.com/download/您的临时签名链接"

方式 2：使用 Python (requests)

注：需先安装依赖 pip install requests。

import os
import time
import requests

API_KEY = os.environ.get("EQUALANG_API_KEY")
# 同一任务重试时保留该 key，新任务请更换 key
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. 创建任务
# 请确保本地存在 report.docx 文件再运行
with open("report.docx", "rb") as f:
    files = {"file": f}
    data = {"target_language": "zh-CN"}
    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_id}")

# 2. 轮询任务
while True:
    # 轮询时不要发送 Idempotency-Key，只需认证
    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"成功！正在下载结果...")

            # 3. 下载结果 (无需且不能带 API 密钥)
            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("下载完成。")
        else:
            print(f"任务结束，状态为: {job_data['status']}")
        break

    retry_after = int(res.headers.get("Retry-After", 5))
    time.sleep(retry_after)

另外，如果您的业务更倾向于“先确认报价，再决定是否翻译”或需要异常状态恢复，我们提供了一份标准的 Python 进阶示例代码，您可以直接下载 translate_file.py 运行测试。

接口参考字典

以下是目前对外公开的 10 个端点的用途与简明结构示例。

请注意：文档翻译与文本翻译支持的语言列表不同，请参阅 OpenAPI 规范中的 DocumentLanguage / TextLanguage 枚举，或 开发者指南 确认确切的代码（如 zh-CN, en）。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": ["Your order has been shipped."], "target_language": "zh-CN"}'
{
  "code": "OK",
  "message": "ok",
  "data": {
    "translations": [
      {
        "translated_text": "您的订单已发货。",
        "detected_source_language": null,
        "error": null
      }
    ],
    "usage": {
      "credits_charged": 0.06
    }
  },
  "request_id": "3e409e57f5f44f949a18897072ff976a"
}

(注：示例中的价格、ID 均为示意数据，实际消耗取决于内容长度。)

2. 独立上传文件并估价

POST /v1/files

如果业务需要事先向用户展示可能消耗的最高额度，可先调用此接口上传。它会返回文件的 quote（最高花费）与 file_id。

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_id 或公网 file_url。系统将预留对应的 credits_reserved 积分。

# 这里演示用此前获得的 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": "zh-CN"}'
{
  "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

处理录音或视频。此接口不翻译，而是输出原本的语音文字（可指定生成 srt 或 txt 等）。

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}

在 URL 路径中带上任务真实的 UUID (job_id)，查询任意翻译或转录任务的进度与最终下载链接。

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/...",
    "outputs": [
      {
        "kind": "translation",
        "format": "docx",
        "filename": "supply-terms-clean.en-equalang-zh-cn.docx",
        "download_url": "https://example.com/download/..."
      }
    ]
  },
  "request_id": "7c7621312ab04f3da3492db98945e597"
}

6. 通过 API 下载文件字节

GET /v1/files/{file_id}

不同于临时签名授权的 download_url，您可以通过本接口直接下载名下的原始文件或结果文件，此接口受权限保护，客户端需携带您的 API 密钥，且具备 files:read 权限。

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

重试接口。对于因异常终止且 error.retryable 为 true 的 FAILED 任务，或已 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

分页查看账号下的所有历史任务。可以通过 query 参数 limit 控制条数，并带上上一页的 cursor。返回的核心数据在 data.items 数组中。

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 错误码以及特定的错误 JSON，指示其原因和是否支持直接重试 (retryable)。

{
  "code": "INVALID_JOB_ID",
  "message": "Invalid job id",
  "data": null,
  "request_id": "9e97df047da640f7b60e10cfbc571711",
  "retryable": false
}

参考资料 / Sources