Equalang API-referentie en snelstartgids

Wanneer je Equalang integreert in je beheer-backend of workflow, kun je tekst direct vertalen of complete bestanden verwerken — zoals documenten, audio en video — waarbij de oorspronkelijke lay-out behouden blijft waar die ondersteund wordt.

Deze gids geeft een snelstart voor de workflow van bestandsvertaling met cURL en Python, gevolgd door een volledige referentie van alle 10 openbare API-endpoints.

Authenticatie en standaardantwoord

De Equalang API wordt aangeboden op https://equalang.com/v1. Verifieer elk verzoek door je API-sleutel mee te geven in de HTTP-header Authorization:

Authorization: Bearer el_your_api_key_here

Je API-sleutel moet de juiste scopes hebben (bijvoorbeeld translations:document voor jobs, translations:text voor tekst, files:read voor het direct downloaden van bestanden).

Standaard antwoordenvelop: alle geslaagde JSON-antwoorden gebruiken een standaard structuur op het hoogste niveau. Voor de beknoptheid laten de onderstaande structuurvoorbeelden enkele niet-essentiële velden weg, maar ze blijven volledig geldige JSON-objecten. De getoonde id's, URL's en saldi zijn louter illustratief: gebruik de werkelijke waarden uit je eigen antwoorden.

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

Snelstart: asynchrone bestandsvertaling

Het verwerken van een heel document vraagt een asynchrone workflow: upload het bestand om een job te starten, poll de status en download het resultaat. Je kunt je eigen bestand gebruiken, of ons voorbeeldbestand supply-confirmation.zh-CN.docx downloaden om mee te testen.

Methode 1: met cURL

Exporteer eerst je API-sleutel (je kunt er een aanmaken op https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Upload en start de job

Verstuur het bestand rechtstreeks. De API reserveert de benodigde credits en geeft een job_id terug. Voeg een unieke Idempotency-Key toe (zoals een UUID) om dubbele jobs bij een timeout te voorkomen. Hergebruik deze sleutel als je dezelfde inzending opnieuw moet proberen, en maak een nieuwe aan voor nieuwe taken. (Zorg dat je een lokaal bestand met de naam report.docx hebt voordat je dit uitvoert, of pas de naam in de code aan.)

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"

Haal de job_id uit het data-object van het antwoord om hem in de volgende stap te gebruiken. Kopieer geen historische id's uit voorbeelden.

2. Poll de jobstatus

Gebruik je job_id om de voortgang te volgen. Wacht tussen verzoeken de duur die de header Retry-After aanraadt. Stop met pollen zodra finished true is.

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

3. Download het resultaat

Zodra de status SUCCEEDED is, bevat het antwoord een tijdelijke download_url. Deze URL gebruikt een tijdelijke handtekeningautorisatie, dus je hoeft (en moet) je API-Bearer-token niet meesturen bij het downloaden. Gebruik een vlag zoals -f om bij HTTP-fouten stil te falen, zodat je geen fout-HTML als je bestand opslaat.

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

Methode 2: met Python (requests)

Let op: vereist de requests-bibliotheek (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)

Voor geavanceerd gebruik (zoals eerst de prijsopgave controleren of verloren pollingstatussen herstellen) kun je ons geavanceerde script translate_file.py downloaden.

---

Endpoint-referentie

Hieronder staan de details en voorbeelden van de payload-structuur voor alle 10 openbare endpoints.

Raadpleeg de opsommingen DocumentLanguage en TextLanguage in het OpenAPI-schema of de gids voor ontwikkelaars voor de exacte codes van de ondersteunde talen (bijvoorbeeld zh-CN, en). De code auto is uitsluitend bedoeld voor source_language.

1. Tekst vertalen

POST /v1/text/translate

Vertaal tekstreeksen synchroon. Teksten worden alleen in rekening gebracht als ze met succes zijn vertaald. detected_source_language is null als er niet automatisch een specifieke taal is herkend.

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. Bestand uploaden voor prijsopgave

POST /v1/files

Wil je vóór het vertalen de maximaal mogelijke kosten tonen, upload het bestand dan hier. Het antwoord geeft een file_id en een quote (de benodigde credits) terug.

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. Documentvertaaljob aanmaken

POST /v1/jobs/translate

Maakt een asynchrone vertaaljob aan. Accepteert file (multipart), file_url of 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. Transcriptiejob aanmaken

POST /v1/jobs/transcribe

Haalt de gesproken tekst uit een audio- of videobestand en geeft die terug als ondertiteling met tijdscodes, zonder ze te vertalen.

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. Jobstatus opvragen

GET /v1/jobs/{job_id}

Geeft de voortgang en de downloadlinks van een actieve of voltooide job. Vervang {job_id} in het pad door je werkelijke 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. Bestandsbytes downloaden

GET /v1/files/{file_id}

In tegenstelling tot de tijdelijke download_url (waarvoor geen API-sleutel nodig is), kun je met dit endpoint de onbewerkte bytes van elk bron- of vertaald bestand op je account downloaden, rechtstreeks via de bijbehorende file_id. Er is een API-sleutel met de scope files:read voor nodig.

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

(Geeft direct binaire data terug, geen JSON-envelop)

7. Job annuleren

POST /v1/jobs/{job_id}/cancel

Annuleert een job. Is de job INIT of QUEUED, dan wordt hij direct CANCELLED. Is hij RUNNING, dan gaat hij naar de status CANCELLING tot hij volledig gestopt is.

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. Job opnieuw proberen

POST /v1/jobs/{job_id}/retry

Probeert een job opnieuw. Je kunt opnieuw proberen als een job FAILED is en error.retryable true is, of als hij CANCELLED was. Opnieuw proberen reserveert de credits opnieuw. Let op: als de levering van het resultaat is mislukt (RESULT_DELIVERY_FAILED), probeert een nieuwe poging de levering opnieuw, maar wordt de vertaling niet een tweede keer in rekening gebracht.

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. Jobs weergeven

GET /v1/jobs

Geeft een gepagineerde lijst van je vertaal- en transcriptiejobs, te beginnen met de nieuwste. Geef limit en cursor (of offset) mee als queryparameters om te pagineren.

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. Creditsaldo controleren

GET /v1/credits/balance

Geeft de beschikbare en de bevroren credits van je account terug.

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

Fouten afhandelen

Mislukte API-verzoeken geven standaard HTTP-foutstatussen terug, samen met een foutpayload die de reden aangeeft en of de bewerking retryable is.

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

Bronnen

• Volledige API-documentatie van Equalang
• OpenAPI-specificatie van Equalang
• Equalang voor ontwikkelaars