Dokumentacja API Equalang i szybki start

Integrując Equalang ze swoim backendem zarządzającym albo z własnym procesem pracy, możesz tłumaczyć tekst natychmiast albo przetwarzać całe pliki — dokumenty, audio i wideo — zachowując ich oryginalny układ tam, gdzie jest to obsługiwane.

Ten przewodnik daje szybki start z procesem tłumaczenia plików przy użyciu cURL i Pythona, a potem pełną dokumentację wszystkich 10 publicznych endpointów API.

Uwierzytelnianie i standardowa odpowiedź

API Equalang działa pod adresem https://equalang.com/v1. Uwierzytelniaj każde żądanie, podając swój klucz API w nagłówku HTTP Authorization:

Authorization: Bearer el_your_api_key_here

Twój klucz API musi mieć odpowiednie zakresy (scope), na przykład translations:document dla zadań, translations:text dla tekstu, files:read do bezpośredniego pobierania plików.

Standardowa koperta odpowiedzi: wszystkie udane odpowiedzi JSON mają standardową strukturę najwyższego poziomu. Dla zwięzłości przykłady struktury poniżej pomijają niektóre nieistotne pola, ale pozostają w pełni poprawnymi obiektami JSON. Pokazane identyfikatory, adresy URL i liczby salda mają charakter wyłącznie ilustracyjny — używaj wartości rzeczywiście zwracanych w twoich odpowiedziach.

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

Szybki start: asynchroniczne tłumaczenie plików

Przetworzenie całego dokumentu wymaga procesu asynchronicznego: prześlij plik, aby uruchomić zadanie, sprawdzaj jego stan, a potem pobierz wynik. Możesz użyć własnego pliku albo pobrać nasz przykładowy plik supply-confirmation.zh-CN.docx do testów.

Metoda 1: z użyciem cURL

Najpierw wyeksportuj swój klucz API (możesz go utworzyć na https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Prześlij plik i uruchom zadanie

Wyślij plik bezpośrednio. API rezerwuje potrzebne kredyty i zwraca job_id. Dołącz unikalny Idempotency-Key (na przykład UUID), aby zapobiec powieleniu zadania, gdy wystąpi timeout. Użyj tego samego klucza, jeśli musisz powtórzyć to samo wysłanie, i wygeneruj nowy dla nowych zadań. (Upewnij się, że masz lokalnie plik o nazwie report.docx, albo zmień nazwę w kodzie.)

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"

Wyciągnij job_id z obiektu data odpowiedzi, aby użyć go w następnym kroku. Nie kopiuj identyfikatorów z przykładów.

2. Sprawdzaj stan zadania

Użyj swojego job_id, aby śledzić postęp. Między żądaniami odczekaj czas zalecany przez nagłówek Retry-After. Przestań sprawdzać, gdy finished będzie mieć wartość true.

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

3. Pobierz wynik

Gdy stan to SUCCEEDED, odpowiedź zawiera tymczasowy download_url. Ten adres korzysta z tymczasowej autoryzacji podpisem, więc nie musisz (i nie powinieneś) przesyłać swojego tokenu Bearer API przy pobieraniu z niego. Użyj flagi takiej jak -f, aby przy błędach HTTP kończyć bez zbędnych komunikatów, dzięki czemu nie zapiszesz strony błędu zamiast swojego pliku.

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

Metoda 2: z użyciem Pythona (requests)

Uwaga: wymaga biblioteki 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)

W bardziej zaawansowanych przypadkach (na przykład gdy chcesz najpierw sprawdzić wycenę albo odzyskać utracone stany odpytywania) możesz pobrać nasz zaawansowany skrypt translate_file.py.

---

Dokumentacja endpointów

Poniżej znajdziesz szczegóły i przykłady struktury payloadu dla wszystkich 10 publicznych endpointów.

Dokładne kody obsługiwanych języków (na przykład zh-CN, en) znajdziesz w wyliczeniach DocumentLanguage i TextLanguage w schemacie OpenAPI albo w przewodniku dla deweloperów. Kod auto jest zarezerwowany wyłącznie dla source_language.

1. Tłumaczenie tekstu

POST /v1/text/translate

Tłumaczy ciągi tekstowe synchronicznie. Opłata jest pobierana tylko za teksty przetłumaczone pomyślnie. detected_source_language ma wartość null, jeśli nie wykryto automatycznie konkretnego języka.

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. Przesyłanie pliku w celu wyceny

POST /v1/files

Jeśli przed tłumaczeniem musisz pokazać maksymalny możliwy koszt, prześlij plik tutaj. Endpoint zwraca file_id oraz quote (wymagane kredyty).

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. Tworzenie zadania tłumaczenia dokumentu

POST /v1/jobs/translate

Tworzy asynchroniczne zadanie tłumaczenia. Przyjmuje file (multipart), file_url albo 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. Tworzenie zadania transkrypcji

POST /v1/jobs/transcribe

Wyodrębnia i zwraca wypowiedziany tekst z pliku audio lub wideo w postaci napisów z znacznikami czasu, bez tłumaczenia go.

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. Sprawdzanie stanu zadania

GET /v1/jobs/{job_id}

Zwraca postęp i linki do pobrania dla aktywnego lub zakończonego zadania. Zastąp {job_id} w ścieżce swoim rzeczywistym 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. Pobieranie bajtów pliku

GET /v1/files/{file_id}

W przeciwieństwie do tymczasowego download_url (który nie wymaga klucza API) ten endpoint pozwala pobrać surowe bajty dowolnego pliku źródłowego lub przetłumaczonego, zapisanego na twoim koncie, bezpośrednio po jego file_id. Wymaga klucza API z zakresem files:read.

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

(Zwraca dane binarne bezpośrednio, bez koperty JSON)

7. Anulowanie zadania

POST /v1/jobs/{job_id}/cancel

Anuluje zadanie. Jeśli zadanie ma stan INIT lub QUEUED, od razu staje się CANCELLED. Jeśli jest w stanie RUNNING, przechodzi w stan CANCELLING, aż całkowicie się zatrzyma.

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. Ponawianie zadania

POST /v1/jobs/{job_id}/retry

Ponawia zadanie. Możesz je ponowić, jeśli zadanie ma stan FAILED, a jego error.retryable ma wartość true, albo jeśli zostało wcześniej CANCELLED. Ponowienie rezerwuje kredyty ponownie. Zwróć uwagę: jeśli nie udało się dostarczenie wyniku (RESULT_DELIVERY_FAILED), ponowienie znów spróbuje go dostarczyć, ale nie zostaniesz obciążony za tłumaczenie drugi raz.

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 zadań

GET /v1/jobs

Zwraca podzieloną na strony listę twoich zadań tłumaczenia i transkrypcji, zaczynając od najnowszych. Przekaż limit oraz cursor (albo offset) jako parametry zapytania, aby przechodzić między stronami.

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. Sprawdzanie salda kredytów

GET /v1/credits/balance

Zwraca dostępne i zamrożone kredyty twojego konta.

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

Obsługa błędów

Nieudane żądania API zwracają standardowe statusy błędów HTTP wraz z treścią odpowiedzi błędu, która wskazuje przyczynę oraz to, czy operację można ponowić (retryable).

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

Źródła

• Pełna dokumentacja API Equalang
• Specyfikacja OpenAPI Equalang
• Equalang dla deweloperów