Equalang API-referens och snabbstart

När du integrerar Equalang i din administrativa backend eller i dina arbetsflöden kan du översätta text direkt eller bearbeta hela filer — dokument, ljud och video — och behålla den ursprungliga layouten där det stöds.

Den här guiden ger en snabbstart för arbetsflödet med filöversättning med cURL och Python, följt av en fullständig referens för alla 10 publika API-endpoints.

Autentisering och standardsvar

Equalang API finns på https://equalang.com/v1. Autentisera varje förfrågan genom att skicka din API-nyckel i HTTP-huvudet Authorization:

Authorization: Bearer el_your_api_key_here

Din API-nyckel måste ha rätt scopes (till exempel translations:document för jobb, translations:text för text, files:read för direkt nedladdning av filer).

Standardsvar: alla lyckade JSON-svar använder en standardstruktur på toppnivå. För att hålla det kort utelämnar strukturexemplen nedan några oviktiga fält, men de är fortsatt fullt giltiga JSON-objekt. ID:n, URL:er och saldobelopp som visas är rent illustrativa — använd de faktiska värdena som dina egna svar returnerar.

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

Snabbstart: asynkron filöversättning

Att bearbeta ett helt dokument kräver ett asynkront flöde: ladda upp filen för att starta ett jobb, fråga dess status och ladda ner resultatet. Du kan använda din egen fil eller ladda ner vår exempelfil supply-confirmation.zh-CN.docx för att testa.

Metod 1: med cURL

Exportera först din API-nyckel (du kan skapa en på https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Ladda upp filen och starta jobbet

Skicka filen direkt. API:et reserverar de krediter som behövs och returnerar ett job_id. Ta med en unik Idempotency-Key (till exempel ett UUID) så att inga dubbla jobb skapas om ett timeout inträffar. Återanvänd samma nyckel om du behöver skicka samma förfrågan igen, och skapa en ny för nya uppgifter. (Se till att du har en lokal fil som heter report.docx innan du kör, eller ändra namnet i koden.)

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"

Hämta job_id ur svarets data-objekt för att använda det i nästa steg. Kopiera inte gamla ID:n från exemplen.

2. Fråga jobbstatus

Använd ditt job_id för att följa framstegen. Vänta den tid som Retry-After-huvudet rekommenderar mellan förfrågningarna. Sluta fråga när finished är true.

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

3. Ladda ner resultatet

När statusen är SUCCEEDED innehåller svaret en tillfällig download_url. Den URL:en använder tillfällig signaturbehörighet, så du behöver inte (och bör inte) skicka din API-Bearer-token när du laddar ner från den. Använd en flagga som -f för att misslyckas tyst vid HTTP-fel, så att du inte sparar en felsida som din fil.

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

Metod 2: med Python (requests)

Observera: kräver biblioteket 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 mer avancerade fall (till exempel att först kontrollera prisuppgiften eller återställa förlorade avsökningslägen) kan du ladda ner vårt avancerade skript translate_file.py.

---

Referens för endpoints

Här finns detaljer och exempel på payload-struktur för alla 10 publika endpoints.

Se uppräkningarna DocumentLanguage och TextLanguage i OpenAPI-schemat eller utvecklarguiden för exakta koder för de språk som stöds (till exempel zh-CN, en). Koden auto gäller bara för source_language.

1. Översätt text

POST /v1/text/translate

Översätter textsträngar synkront. Texter debiteras bara om de översätts utan fel. detected_source_language är null om inget specifikt språk kunde identifieras automatiskt.

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. Ladda upp fil för prisuppgift

POST /v1/files

Om du behöver visa den högsta möjliga kostnaden före översättningen laddar du upp filen här. Den returnerar ett file_id och en quote (antal krediter som krävs).

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. Skapa dokumentöversättningsjobb

POST /v1/jobs/translate

Skapar ett asynkront översättningsjobb. Tar emot file (multipart), file_url eller 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. Skapa transkriberingsjobb

POST /v1/jobs/transcribe

Extraherar och returnerar det talade innehållet i en ljud- eller videofil som tidsatta undertexter, utan att översätta det.

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. Fråga jobbstatus

GET /v1/jobs/{job_id}

Hämtar framsteg och nedladdningslänkar för ett pågående eller avslutat jobb. Ersätt {job_id} i sökvägen med ditt faktiska 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. Ladda ner filens byte

GET /v1/files/{file_id}

Till skillnad från den tillfälliga download_url (som inte kräver någon API-nyckel) låter den här endpointen dig ladda ner råa byte från vilken källfil eller översatt fil som helst som finns lagrad på ditt konto, direkt med dess file_id. Den kräver en API-nyckel med scopet files:read.

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

(Returnerar binärdata direkt, utan JSON-kuvert)

7. Avbryt jobb

POST /v1/jobs/{job_id}/cancel

Avbryter ett jobb. Om jobbet har status INIT eller QUEUED blir det genast CANCELLED. Om det är RUNNING går det in i statusen CANCELLING tills det har stoppats helt.

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. Försök jobbet igen

POST /v1/jobs/{job_id}/retry

Försöker ett jobb igen. Du kan försöka igen om jobbet är FAILED och dess error.retryable är true, eller om det har varit CANCELLED. Ett nytt försök reserverar krediter igen. Observera att om leveransen av resultatet misslyckades (RESULT_DELIVERY_FAILED) försöker ett nytt försök leverera igen, men du debiteras inte en andra gång för översättningen.

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. Lista jobb

GET /v1/jobs

Returnerar en sidindelad lista över dina översättnings- och transkriberingsjobb, med de nyaste först. Skicka limit och cursor (eller offset) som frågeparametrar för att bläddra mellan sidor.

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. Kontrollera kreditsaldo

GET /v1/credits/balance

Returnerar dina tillgängliga och frysta krediter.

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

Felhantering

Misslyckade API-förfrågningar returnerar vanliga HTTP-felstatusar tillsammans med en felsvarspayload som anger orsaken och om åtgärden kan försökas igen (retryable).

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

Källor

• Fullständig dokumentation för Equalang API
• Equalangs OpenAPI-specifikation
• Equalang för utvecklare