Référence de l'API Equalang et guide de démarrage rapide

Equalang10 octobre 2026

En bref

Guide d'intégration de l'API Equalang : traduisez du texte ou traitez documents et médias en asynchrone, avec les exemples des 10 endpoints publics.

Mots-clés: intégration API; API de traduction de fichiers; traduction automatique; guide du développeur; référence API

En intégrant Equalang à votre back-office ou à vos workflows, vous pouvez traduire du texte instantanément ou traiter des fichiers entiers — documents, audio et vidéo — tout en conservant leur mise en page d'origine lorsque le format le permet.

Ce guide propose un démarrage rapide du workflow de traduction de fichiers avec cURL et Python, suivi d'une référence complète des 10 endpoints publics de l'API.

Authentification et réponse standard

L'API Equalang est servie sur https://equalang.com/v1. Authentifiez chaque requête en transmettant votre clé API dans l'en-tête HTTP Authorization :

Authorization: Bearer el_your_api_key_here

Votre clé API doit disposer des autorisations (scopes) appropriées (par exemple translations:document pour les jobs, translations:text pour le texte, files:read pour les téléchargements directs de fichiers).

Enveloppe de réponse standard : toutes les réponses JSON réussies utilisent une structure de premier niveau identique. Par souci de concision, les exemples structurels ci-dessous omettent certains champs non essentiels, mais restent des objets JSON parfaitement valides. Les identifiants, URL et soldes de crédits affichés sont purement illustratifs : utilisez les valeurs réelles renvoyées par vos propres réponses.

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

Démarrage rapide : traduction asynchrone de fichiers

Le traitement d'un document entier suit un déroulement asynchrone : téléversez le fichier pour lancer un job, interrogez son statut, puis téléchargez le résultat. Vous pouvez utiliser votre propre fichier ou télécharger notre fichier d'exemple supply-confirmation.zh-CN.docx pour vos tests.

Méthode 1 : avec cURL

Exportez d'abord votre clé API (vous pouvez en créer une sur https://equalang.com/api-keys) :

export EQUALANG_API_KEY="el_your_api_key_here"

1. Téléverser le fichier et lancer le job

Envoyez le fichier directement. L'API réserve les crédits nécessaires et renvoie un job_id. Ajoutez un Idempotency-Key unique (par exemple un UUID) afin d'éviter les doublons si un délai d'attente est dépassé. Réutilisez cette clé si vous devez relancer la même soumission, et générez-en une nouvelle pour chaque nouvelle tâche. (Assurez-vous qu'un fichier local nommé report.docx existe avant l'exécution, ou modifiez le nom dans le 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"

Récupérez le job_id dans l'objet data de la réponse pour l'étape suivante. Ne recopiez pas les identifiants historiques des exemples.

2. Interroger le statut du job

Utilisez votre job_id pour suivre la progression. Respectez entre deux requêtes la durée recommandée par l'en-tête Retry-After. Arrêtez l'interrogation lorsque finished vaut true.

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

3. Télécharger le résultat

Une fois le statut SUCCEEDED, la réponse contient une download_url temporaire. Cette URL repose sur une autorisation par signature temporaire : vous n'avez donc pas besoin (et ne devez pas) envoyer votre jeton Bearer pour télécharger depuis celle-ci. Utilisez une option comme -f pour échouer silencieusement en cas d'erreur HTTP, afin de ne pas enregistrer une page d'erreur à la place de votre fichier.

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

Méthode 2 : avec Python (requests)

Remarque : nécessite la bibliothèque 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)

Pour des cas d'usage avancés (vérifier d'abord le devis, ou retrouver un état d'interrogation perdu), vous pouvez télécharger notre script avancé translate_file.py.

Référence des endpoints

Voici le détail et des exemples de structure de charge utile pour les 10 endpoints publics.

Reportez-vous aux énumérations DocumentLanguage et TextLanguage du schéma OpenAPI ou au guide Développeurs pour les codes exacts des langues prises en charge (par exemple zh-CN, en). Le code auto est réservé à source_language.

1. Traduire du texte

POST /v1/text/translate

Traduit des chaînes de texte de façon synchrone. Les textes ne sont facturés que s'ils ont été traduits avec succès. detected_source_language vaut null si aucune langue précise n'a été détectée automatiquement.

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. Téléverser un fichier pour obtenir un devis

POST /v1/files

Si vous devez afficher le coût maximal potentiel avant de traduire, téléversez le fichier ici. La réponse renvoie un file_id et un quote (crédits requis).

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. Créer un job de traduction de document

POST /v1/jobs/translate

Crée un job de traduction asynchrone. Accepte file (multipart), file_url ou 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. Créer un job de transcription

POST /v1/jobs/transcribe

Extrait le texte parlé d'un fichier audio ou vidéo et le renvoie sous forme de sous-titres synchronisés, sans le traduire.

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. Consulter le statut d'un job

GET /v1/jobs/{job_id}

Récupère la progression et les liens de téléchargement d'un job en cours ou terminé. Remplacez {job_id} dans le chemin par votre UUID réel.

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. Télécharger les octets d'un fichier

GET /v1/files/{file_id}

Contrairement à la download_url temporaire (qui ne demande aucune clé API), cet endpoint vous permet de télécharger directement les octets bruts de n'importe quel fichier source ou traduit stocké sur votre compte, à partir de son file_id. Il requiert une clé API disposant du droit files:read.

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

(Renvoie directement des données binaires, sans enveloppe JSON)

7. Annuler un job

POST /v1/jobs/{job_id}/cancel

Annule un job. Si le job est INIT ou QUEUED, il passe immédiatement à CANCELLED. S'il est RUNNING, il entre dans l'état CANCELLING jusqu'à son arrêt complet.

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. Relancer un job

POST /v1/jobs/{job_id}/retry

Relance un job. Vous pouvez relancer un job s'il est FAILED et que son error.retryable vaut true, ou s'il a été CANCELLED. La relance réserve à nouveau des crédits. Si la livraison du résultat a échoué (RESULT_DELIVERY_FAILED), une relance retente la livraison, sans vous facturer une seconde fois la traduction.

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. Lister les jobs

GET /v1/jobs

Renvoie une liste paginée de vos jobs de traduction et de transcription, du plus récent au plus ancien. Transmettez limit et cursor (ou offset) en paramètres de requête pour parcourir les pages.

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. Vérifier le solde de crédits

GET /v1/credits/balance

Renvoie vos crédits disponibles et gelés.

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

Gestion des erreurs

Les requêtes API échouées renvoient des statuts d'erreur HTTP standard, accompagnés d'une charge utile d'erreur qui indique la raison et si l'opération est retryable.

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