Equalang API-Referenz und Schnellstart

Equalang10. Oktober 2026

Kurz gesagt

Entwicklerleitfaden für die Equalang API: Texte sofort übersetzen, Dokumente und Medien asynchron verarbeiten, mit Beispielen für alle 10 Endpunkte.

Schlagwörter: API-Integration; Datei-Übersetzungs-API; automatische Übersetzung; Entwicklerleitfaden; API-Referenz

Wenn Sie Equalang in Ihr Verwaltungs-Backend oder Ihren Workflow einbinden, können Sie Texte sofort übersetzen oder ganze Dateien verarbeiten – etwa Dokumente, Audio und Video – und dabei das ursprüngliche Layout erhalten, wo es unterstützt wird.

Dieser Leitfaden enthält einen Schnellstart für den Dateiübersetzungs-Workflow mit cURL und Python, gefolgt von einer vollständigen Referenz aller 10 öffentlichen API-Endpunkte.

Authentifizierung und Standardantwort

Die Equalang API wird unter https://equalang.com/v1 bereitgestellt. Authentifizieren Sie jede Anfrage, indem Sie Ihren API-Schlüssel im HTTP-Header Authorization mitsenden:

Authorization: Bearer el_your_api_key_here

Ihr API-Schlüssel muss die passenden Berechtigungen haben (z. B. translations:document für Jobs, translations:text für Text, files:read für direkte Datei-Downloads).

Standardantwort-Umschlag: Alle erfolgreichen JSON-Antworten verwenden eine einheitliche Struktur auf der obersten Ebene. Aus Platzgründen lassen die Strukturbeispiele unten einige unwesentliche Felder weg, bleiben aber vollständig gültige JSON-Objekte. Die gezeigten IDs, URLs und Guthabenbeträge sind rein illustrativ – verwenden Sie in Ihrer Integration die tatsächlichen Werte aus Ihren eigenen Antworten.

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

Schnellstart: Asynchrone Dateiübersetzung

Die Verarbeitung eines ganzen Dokuments erfordert einen asynchronen Ablauf: Datei hochladen, um einen Job zu starten, den Status abfragen und das Ergebnis herunterladen. Sie können Ihre eigene Datei verwenden oder unsere Beispieldatei supply-confirmation.zh-CN.docx zum Testen herunterladen.

Methode 1: Mit cURL

Exportieren Sie zuerst Ihren API-Schlüssel (Sie können einen unter https://equalang.com/api-keys erstellen):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Datei hochladen und Job starten

Senden Sie die Datei direkt. Die API reserviert die nötigen Credits und gibt eine job_id zurück. Fügen Sie einen eindeutigen Idempotency-Key hinzu (etwa eine UUID), damit bei einem Timeout kein doppelter Job entsteht. Verwenden Sie denselben Schlüssel wieder, wenn Sie dieselbe Übermittlung erneut versuchen, und erzeugen Sie für neue Aufgaben einen neuen. (Stellen Sie sicher, dass vor dem Ausführen lokal eine Datei mit dem Namen report.docx liegt, oder ändern Sie den Namen im Code.)

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"

Entnehmen Sie die job_id dem data-Objekt der Antwort und verwenden Sie sie im nächsten Schritt. Übernehmen Sie keine historischen IDs aus Beispielen.

2. Job-Status abfragen

Verwenden Sie Ihre job_id, um den Fortschritt abzufragen. Warten Sie zwischen den Anfragen die vom Retry-After-Header empfohlene Zeitspanne. Beenden Sie das Abfragen, sobald finished auf true steht.

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

3. Ergebnis herunterladen

Sobald der Status SUCCEEDED lautet, enthält die Antwort eine temporäre download_url. Diese URL verwendet eine temporäre Signatur-Autorisierung, daher müssen (und sollten) Sie beim Herunterladen von dort Ihren Bearer-Token nicht mitsenden. Verwenden Sie ein Flag wie -f, damit HTTP-Fehler still fehlschlagen und Sie keine Fehlerseite als Datei abspeichern.

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

Methode 2: Mit Python (requests)

Hinweis: Erfordert die Bibliothek 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)

Für weitergehende Anwendungsfälle (etwa um zuerst die Kosten zu prüfen oder verlorene Abfragezustände wieder aufzunehmen) können Sie unser erweitertes Skript translate_file.py herunterladen.

Endpunkt-Referenz

Hier finden Sie die Details und Beispiele für die Payload-Struktur aller 10 öffentlichen Endpunkte.

Die genauen Sprachcodes (z. B. zh-CN, en) finden Sie in den Aufzählungen DocumentLanguage und TextLanguage im OpenAPI-Schema oder im Entwicklerleitfaden. Der Code auto ist ausschließlich für source_language vorgesehen.

1. Text übersetzen

POST /v1/text/translate

Übersetzt Zeichenketten synchron. Texte werden nur berechnet, wenn sie erfolgreich übersetzt wurden. detected_source_language ist null, wenn keine bestimmte Sprache automatisch erkannt wurde.

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. Datei für die Kostenabschätzung hochladen

POST /v1/files

Wenn Sie vor der Übersetzung die maximal möglichen Kosten anzeigen möchten, laden Sie die Datei hier hoch. Die Antwort enthält eine file_id und ein quote (erforderliche Credits).

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. Dokumentübersetzungs-Job erstellen

POST /v1/jobs/translate

Erstellt einen asynchronen Übersetzungs-Job. Akzeptiert file (multipart), file_url oder 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. Transkriptions-Job erstellen

POST /v1/jobs/transcribe

Extrahiert den gesprochenen Text aus einer Audio- oder Videodatei und gibt ihn als zeitgesteuerte Untertitel zurück, ohne ihn zu übersetzen.

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. Job-Status abfragen

GET /v1/jobs/{job_id}

Ruft Fortschritt und Download-Links eines laufenden oder abgeschlossenen Jobs ab. Ersetzen Sie {job_id} im Pfad durch Ihre tatsächliche 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. Datei-Bytes herunterladen

GET /v1/files/{file_id}

Anders als bei der temporären download_url (die keinen API-Schlüssel benötigt) können Sie mit diesem Endpunkt die Rohdaten jeder auf Ihrem Konto gespeicherten Quell- oder Zieldatei direkt über ihre file_id herunterladen. Er erfordert einen API-Schlüssel mit dem Recht files:read.

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

(Gibt Binärdaten direkt zurück, kein JSON-Umschlag)

7. Job abbrechen

POST /v1/jobs/{job_id}/cancel

Bricht einen Job ab. Ist der Job INIT oder QUEUED, wird er sofort zu CANCELLED. Ist er RUNNING, wechselt er in den Zustand CANCELLING, bis er vollständig gestoppt ist.

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 erneut ausführen

POST /v1/jobs/{job_id}/retry

Führt einen Job erneut aus. Sie können einen Job wiederholen, wenn er FAILED ist und error.retryable auf true steht, oder wenn er CANCELLED war. Beim erneuten Ausführen werden Credits erneut reserviert. Wenn die Ergebniszustellung fehlgeschlagen ist (RESULT_DELIVERY_FAILED), versucht ein erneuter Versuch die Zustellung noch einmal, berechnet Ihnen die Übersetzung aber kein zweites Mal.

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 auflisten

GET /v1/jobs

Gibt eine seitenweise Liste Ihrer Übersetzungs- und Transkriptions-Jobs zurück, beginnend mit dem neuesten. Übergeben Sie limit und cursor (oder offset) als Query-Parameter, um durch die Seiten zu blättern.

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. Credit-Guthaben prüfen

GET /v1/credits/balance

Gibt Ihre verfügbaren und eingefrorenen Konto-Credits zurück.

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

Fehlerbehandlung

Fehlgeschlagene API-Anfragen geben die üblichen HTTP-Fehlerstatus zurück, zusammen mit einer Fehler-Antwort, die den Grund nennt und angibt, ob der Vorgang retryable ist.

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