เอกสารอ้างอิง API Equalang และคู่มือเริ่มต้นใช้งานอย่างรวดเร็ว

Equalang10 ตุลาคม 2569

โดยสังเขป

คู่มือสำหรับนักพัฒนาในการผสานรวม API Equalang: แปลข้อความหรือประมวลผลเอกสารและสื่อแบบอะซิงโครนัส พร้อมตัวอย่างสำหรับทั้ง 10 เอนด์พอยต์

คำสำคัญ: การผสานรวม API; API แปลไฟล์; การแปลอัตโนมัติ; คู่มือนักพัฒนา; เอกสารอ้างอิง API

เมื่อคุณผสานรวม Equalang เข้ากับแบ็กเอนด์สำหรับจัดการหรือเวิร์กโฟลว์ของคุณ คุณสามารถแปลข้อความได้ทันที หรือประมวลผลไฟล์ทั้งไฟล์ — เช่น เอกสาร เสียง และวิดีโอ — โดยคงรูปแบบต้นฉบับไว้ในส่วนที่รองรับ

คู่มือนี้ให้ขั้นตอนเริ่มต้นใช้งานอย่างรวดเร็วสำหรับเวิร์กโฟลว์การแปลไฟล์ด้วย cURL และ Python ตามด้วยเอกสารอ้างอิงฉบับสมบูรณ์สำหรับเอนด์พอยต์สาธารณะทั้ง 10 รายการ

การยืนยันตัวตนและรูปแบบการตอบกลับมาตรฐาน

Equalang API ให้บริการที่ https://equalang.com/v1 ยืนยันตัวตนทุกคำขอโดยระบุคีย์ API ของคุณในส่วนหัว HTTP Authorization:

Authorization: Bearer el_your_api_key_here

คีย์ API ของคุณต้องมีขอบเขต (scope) ที่ถูกต้อง (เช่น 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

ขั้นแรก ให้ export คีย์ API ของคุณ (คุณสามารถสร้างได้ที่ https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. อัปโหลดไฟล์และเริ่มงาน

ส่งไฟล์โดยตรง API จะสำรองเครดิตที่จำเป็นและส่งคืน job_id ให้ใส่ Idempotency-Key ที่ไม่ซ้ำกัน (เช่น UUID) เพื่อป้องกันงานที่ซ้ำซ้อนหากเกิด timeout ใช้คีย์เดิมซ้ำหากคุณต้องส่งคำขอเดิมอีกครั้ง และสร้างคีย์ใหม่สำหรับงานใหม่ (ตรวจสอบให้แน่ใจว่ามีไฟล์ชื่อ 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 นี้ใช้การอนุญาตด้วยลายเซ็นชั่วคราว ดังนั้นคุณไม่จำเป็นต้อง (และไม่ควร) ส่งโทเค็น Bearer ของ API เมื่อดาวน์โหลดจาก URL นั้น ใช้ flag เช่น -f เพื่อให้ล้มเหลวเงียบๆ เมื่อเกิดข้อผิดพลาด HTTP จะได้ไม่บันทึกหน้าข้อผิดพลาดเป็นไฟล์ของคุณ

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) ได้จากการแจกแจงค่า (enumeration) DocumentLanguage และ TextLanguage ในสคีมา OpenAPI หรือคู่มือนักพัฒนา โดยรหัส 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}

ต่างจาก download_url แบบชั่วคราว (ซึ่งไม่ต้องใช้คีย์ API) เอนด์พอยต์นี้ให้คุณดาวน์โหลดไบต์ดิบของไฟล์ต้นฉบับหรือไฟล์ที่แปลแล้วที่เก็บอยู่ในบัญชีของคุณโดยตรงด้วย file_id ของไฟล์นั้น ต้องใช้คีย์ 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

ลองทำงานใหม่ คุณสามารถลองใหม่ได้หากงานเป็น 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
}