Equalang
Ghi chú Equalang

Tài liệu API Equalang và hướng dẫn bắt đầu nhanh

Equalang

Tóm tắt

Hướng dẫn dành cho nhà phát triển về tích hợp API Equalang: dịch văn bản hoặc xử lý tài liệu và media theo cách bất đồng bộ, kèm ví dụ cho cả 10 endpoint.

Từ khóa: tích hợp API; API dịch file; dịch tự động; hướng dẫn nhà phát triển; tài liệu API

Khi tích hợp Equalang vào backend quản lý hoặc quy trình làm việc của mình, bạn có thể dịch văn bản ngay lập tức hoặc xử lý toàn bộ file — như tài liệu, âm thanh và video — trong khi vẫn giữ nguyên bố cục gốc ở những định dạng được hỗ trợ.

Hướng dẫn này cung cấp phần bắt đầu nhanh cho quy trình dịch file bằng cURL và Python, tiếp theo là tài liệu đầy đủ cho cả 10 endpoint công khai của API.

Xác thực và phản hồi chuẩn

API Equalang được phục vụ tại https://equalang.com/v1. Xác thực mọi yêu cầu bằng cách cung cấp khóa API của bạn trong header HTTP Authorization:

Authorization: Bearer el_your_api_key_here

Khóa API của bạn phải có các phạm vi (scope) phù hợp (ví dụ: translations:document cho tác vụ, translations:text cho văn bản, files:read để tải file trực tiếp).

Cấu trúc phản hồi chuẩn: mọi phản hồi JSON thành công đều dùng một cấu trúc cấp cao nhất tiêu chuẩn. Để ngắn gọn, các ví dụ cấu trúc bên dưới lược bỏ một số trường không thiết yếu nhưng vẫn là những đối tượng JSON hoàn toàn hợp lệ. Các ID, URL và số dư hiển thị chỉ mang tính minh họa — hãy dùng giá trị thực tế mà phản hồi của bạn trả về.

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

Bắt đầu nhanh: dịch file bất đồng bộ

Xử lý một tài liệu trọn vẹn đòi hỏi quy trình bất đồng bộ: tải file lên để bắt đầu tác vụ, truy vấn trạng thái của nó và tải kết quả xuống. Bạn có thể dùng file của mình, hoặc tải file mẫu supply-confirmation.zh-CN.docx của chúng tôi để thử.

Cách 1: dùng cURL

Trước tiên, xuất khóa API của bạn (bạn có thể tạo khóa tại https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Tải file lên và bắt đầu tác vụ

Gửi file trực tiếp. API dự trữ các tín dụng cần thiết và trả về job_id. Hãy kèm một Idempotency-Key duy nhất (chẳng hạn một UUID) để tránh các tác vụ trùng lặp nếu xảy ra timeout. Dùng lại khóa này nếu bạn cần thử lại cùng một lần gửi, và tạo khóa mới cho tác vụ mới. (Hãy đảm bảo bạn có sẵn một file cục bộ tên là report.docx trước khi chạy, hoặc đổi tên trong đoạn mã.)

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"

Trích xuất job_id từ đối tượng data của phản hồi để dùng ở bước tiếp theo. Đừng sao chép các ID cũ từ những ví dụ.

2. Truy vấn trạng thái tác vụ

Dùng job_id của bạn để theo dõi tiến độ. Chờ khoảng thời gian được header Retry-After khuyến nghị giữa các yêu cầu. Dừng truy vấn khi finished là true.

curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. Tải kết quả

Sau khi trạng thái là SUCCEEDED, phản hồi sẽ bao gồm một download_url tạm thời. URL này dùng cơ chế ủy quyền bằng chữ ký tạm thời, vì vậy bạn không cần (và không nên) gửi token Bearer của API khi tải từ đó. Hãy dùng cờ như -f để thoát im lặng khi gặp lỗi HTTP, để bạn không lưu nhầm trang lỗi HTML thành file của mình.

curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"

Cách 2: dùng Python (requests)

Lưu ý: cần thư viện 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)

Với các trường hợp nâng cao (như kiểm tra báo giá trước hoặc khôi phục trạng thái truy vấn bị mất), bạn có thể tải script nâng cao translate_file.py của chúng tôi.

Tài liệu tham khảo endpoint

Dưới đây là chi tiết và ví dụ về cấu trúc payload cho cả 10 endpoint công khai.

Hãy tham khảo các kiểu liệt kê DocumentLanguage và TextLanguage trong lược đồ OpenAPI hoặc hướng dẫn dành cho nhà phát triển để biết mã chính xác của các ngôn ngữ được hỗ trợ (ví dụ: zh-CN, en). Mã auto chỉ dành riêng cho source_language.

1. Dịch văn bản

POST /v1/text/translate

Dịch các chuỗi văn bản theo cách đồng bộ. Văn bản chỉ bị tính phí nếu được dịch thành công. detected_source_language là null nếu không tự động phát hiện được một ngôn ngữ cụ thể.

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. Tải file lên để nhận báo giá

POST /v1/files

Nếu bạn cần hiển thị chi phí tối đa có thể trước khi dịch, hãy tải file lên đây. Nó trả về file_id và quote (số tín dụng cần thiết).

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. Tạo tác vụ dịch tài liệu

POST /v1/jobs/translate

Tạo một tác vụ dịch bất đồng bộ. Chấp nhận file (multipart), file_url hoặc 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. Tạo tác vụ phiên âm

POST /v1/jobs/transcribe

Trích xuất và trả về lời nói trong file âm thanh hoặc video dưới dạng phụ đề có mốc thời gian, chứ không dịch nội dung đó.

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. Truy vấn trạng thái tác vụ

GET /v1/jobs/{job_id}

Truy xuất tiến độ và liên kết tải xuống của một tác vụ đang chạy hoặc đã hoàn tất. Thay {job_id} trong đường dẫn bằng UUID thực tế của bạn.

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. Tải byte của file

GET /v1/files/{file_id}

Khác với download_url tạm thời (không cần khóa API), endpoint này cho phép bạn tải trực tiếp các byte thô của bất kỳ file nguồn hay file đã dịch nào đang được lưu trong tài khoản của mình, bằng file_id của nó. Nó cần một khóa API có phạm vi files:read.

curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -o translated_result.docx

(Trả về dữ liệu nhị phân trực tiếp, không có bao JSON)

7. Hủy tác vụ

POST /v1/jobs/{job_id}/cancel

Hủy một tác vụ. Nếu tác vụ đang ở trạng thái INIT hoặc QUEUED, nó sẽ lập tức chuyển thành CANCELLED. Nếu đang là RUNNING, nó sẽ vào trạng thái CANCELLING cho đến khi dừng hẳn.

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. Thử lại tác vụ

POST /v1/jobs/{job_id}/retry

Thử lại một tác vụ. Bạn có thể thử lại nếu tác vụ ở trạng thái FAILED và error.retryable của nó là true, hoặc nếu nó đã bị CANCELLED. Việc thử lại sẽ dự trữ tín dụng một lần nữa. Lưu ý rằng nếu việc giao kết quả thất bại (RESULT_DELIVERY_FAILED), thử lại sẽ cố giao lại nhưng sẽ không tính phí dịch lần thứ hai.

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. Liệt kê tác vụ

GET /v1/jobs

Trả về danh sách được phân trang các tác vụ dịch và phiên âm của bạn, bắt đầu từ tác vụ mới nhất. Truyền limit và cursor (hoặc offset) dưới dạng tham số truy vấn để phân trang.

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. Kiểm tra số dư tín dụng

GET /v1/credits/balance

Trả về tín dụng khả dụng và tín dụng bị đóng băng của tài khoản bạn.

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"
}

Xử lý lỗi

Các yêu cầu API thất bại sẽ trả về mã trạng thái lỗi HTTP chuẩn, kèm theo payload phản hồi lỗi cho biết lý do và liệu thao tác có thể thử lại (retryable) hay không.

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

Nguồn