Referensi API Equalang dan panduan mulai cepat

Equalang10 Oktober 2026

Secara singkat

Panduan developer untuk mengintegrasikan API Equalang: terjemahkan teks atau proses dokumen dan media secara asinkron, dengan contoh untuk ke-10 endpoint.

Kata kunci: integrasi API; API terjemahan file; terjemahan otomatis; panduan developer; referensi API

Saat mengintegrasikan Equalang ke backend manajemen atau alur kerja Anda, Anda dapat menerjemahkan teks secara instan atau memproses file utuh — seperti dokumen, audio, dan video — dengan mempertahankan tata letak aslinya jika formatnya didukung.

Panduan ini menyajikan mulai cepat untuk alur kerja penerjemahan file dengan cURL dan Python, diikuti referensi lengkap untuk ke-10 endpoint publik API.

Autentikasi dan respons standar

API Equalang dilayani di https://equalang.com/v1. Autentikasi setiap permintaan dengan menyertakan kunci API Anda di header HTTP Authorization:

Authorization: Bearer el_your_api_key_here

Kunci API Anda harus memiliki cakupan (scope) yang tepat (misalnya translations:document untuk pekerjaan, translations:text untuk teks, files:read untuk mengunduh file langsung).

Pembungkus respons standar: semua respons JSON yang berhasil menggunakan struktur tingkat atas standar. Demi keringkasan, contoh struktur di bawah menghilangkan beberapa kolom yang tidak penting, tetapi tetap berupa objek JSON yang sepenuhnya valid. ID, URL, dan angka saldo yang ditampilkan semata-mata ilustrasi — gunakan nilai nyata yang dikembalikan oleh respons Anda.

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

Mulai cepat: penerjemahan file asinkron

Memproses satu dokumen utuh memerlukan alur kerja asinkron: unggah file untuk memulai pekerjaan, periksa statusnya, lalu unduh hasilnya. Anda dapat menggunakan file sendiri, atau mengunduh file contoh supply-confirmation.zh-CN.docx dari kami untuk mencobanya.

Metode 1: menggunakan cURL

Pertama, ekspor kunci API Anda (Anda dapat membuatnya di https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Unggah file dan mulai pekerjaan

Kirim file secara langsung. API menyisihkan kredit yang diperlukan dan mengembalikan job_id. Sertakan Idempotency-Key yang unik (misalnya UUID) untuk mencegah pekerjaan ganda jika terjadi timeout. Gunakan kembali kunci ini jika Anda perlu mengulang pengiriman yang sama, dan buat kunci baru untuk tugas baru. (Pastikan Anda punya file lokal bernama report.docx sebelum menjalankan, atau ubah namanya di dalam kode.)

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"

Ekstrak job_id dari objek data pada respons untuk digunakan pada langkah berikutnya. Jangan menyalin ID lama dari contoh.

2. Periksa status pekerjaan

Gunakan job_id Anda untuk memantau kemajuan. Tunggu durasi yang disarankan oleh header Retry-After di antara permintaan. Berhenti memeriksa saat finished bernilai true.

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

3. Unduh hasilnya

Setelah statusnya SUCCEEDED, respons menyertakan download_url sementara. URL ini menggunakan otorisasi tanda tangan sementara, jadi Anda tidak perlu (dan sebaiknya tidak) mengirim token Bearer API saat mengunduh darinya. Gunakan flag seperti -f agar berhenti dengan tenang saat terjadi error HTTP, sehingga Anda tidak menyimpan halaman error HTML sebagai file Anda.

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

Metode 2: menggunakan Python (requests)

Catatan: memerlukan pustaka 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)

Untuk kasus lanjutan (misalnya memeriksa perkiraan biaya terlebih dahulu atau memulihkan status pemeriksaan yang hilang), Anda dapat mengunduh skrip lanjutan translate_file.py kami.

Referensi endpoint

Berikut detail dan contoh struktur payload untuk ke-10 endpoint publik.

Lihat enumerasi DocumentLanguage dan TextLanguage dalam skema OpenAPI atau panduan developer untuk kode bahasa yang didukung (misalnya zh-CN, en). Kode auto hanya untuk source_language.

1. Terjemahkan teks

POST /v1/text/translate

Menerjemahkan string teks secara sinkron. Teks hanya ditagih jika berhasil diterjemahkan. detected_source_language bernilai null jika bahasa tertentu tidak terdeteksi secara otomatis.

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. Unggah file untuk penawaran harga

POST /v1/files

Jika Anda perlu menampilkan biaya maksimum yang mungkin terjadi sebelum menerjemahkan, unggah file di sini. Endpoint ini mengembalikan file_id dan quote (kredit yang dibutuhkan).

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. Buat pekerjaan penerjemahan dokumen

POST /v1/jobs/translate

Membuat pekerjaan penerjemahan asinkron. Menerima file (multipart), file_url, atau 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. Buat pekerjaan transkripsi

POST /v1/jobs/transcribe

Mengekstrak dan mengembalikan ucapan dari file audio atau video sebagai takarir (subtitle) berpenanda waktu, tanpa menerjemahkannya.

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. Periksa status pekerjaan

GET /v1/jobs/{job_id}

Mengambil kemajuan dan tautan unduhan untuk pekerjaan yang aktif atau sudah selesai. Ganti {job_id} di path dengan UUID Anda yang sebenarnya.

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. Unduh byte file

GET /v1/files/{file_id}

Berbeda dengan download_url sementara (yang tidak memerlukan kunci API), endpoint ini memungkinkan Anda mengunduh byte mentah dari file sumber maupun file hasil terjemahan yang tersimpan di akun Anda secara langsung, dengan file_id-nya. Endpoint ini memerlukan kunci API dengan cakupan files:read.

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

(Mengembalikan data biner secara langsung, tanpa pembungkus JSON)

7. Batalkan pekerjaan

POST /v1/jobs/{job_id}/cancel

Membatalkan pekerjaan. Jika pekerjaan berstatus INIT atau QUEUED, statusnya langsung menjadi CANCELLED. Jika berstatus RUNNING, ia masuk ke status CANCELLING hingga benar-benar berhenti.

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. Coba ulang pekerjaan

POST /v1/jobs/{job_id}/retry

Mengulang pekerjaan. Anda dapat mengulang jika pekerjaan berstatus FAILED dan error.retryable-nya bernilai true, atau jika pekerjaan itu pernah berstatus CANCELLED. Mengulang akan menyisihkan kredit lagi. Perhatikan bahwa jika pengiriman hasil gagal (RESULT_DELIVERY_FAILED), pengulangan akan mencoba mengirim ulang, tetapi Anda tidak akan ditagih untuk penerjemahan yang kedua kali.

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. Daftar pekerjaan

GET /v1/jobs

Mengembalikan daftar pekerjaan penerjemahan dan transkripsi Anda yang dibagi per halaman, dimulai dari yang terbaru. Kirim limit dan cursor (atau offset) sebagai parameter kueri untuk menelusuri halaman.

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. Periksa saldo kredit

GET /v1/credits/balance

Mengembalikan kredit yang tersedia dan kredit yang dibekukan pada akun Anda.

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

Penanganan error

Permintaan API yang gagal mengembalikan status error HTTP standar beserta payload respons error yang menunjukkan alasannya dan apakah operasi tersebut dapat diulang (retryable).

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