Referencia de la API de Equalang y guía de inicio rápido

Equalang10 de octubre de 2026

En breve

Guía de integración de la API de Equalang: traduce texto o procesa documentos y medios de forma asíncrona, con los 10 endpoints públicos como ejemplo.

Palabras clave: integración de API; API de traducción de archivos; traducción automática; guía para desarrolladores; referencia de API

Al integrar Equalang en tu backend de gestión o en tus flujos de trabajo, puedes traducir texto al instante o procesar archivos completos—documentos, audio y video—conservando su maquetación original cuando el formato lo permite.

Esta guía ofrece un inicio rápido del flujo de traducción de archivos con cURL y Python, seguido de la referencia completa de los 10 endpoints públicos de la API.

Autenticación y respuesta estándar

La API de Equalang se sirve en https://equalang.com/v1. Autentica cada petición enviando tu clave de API en la cabecera HTTP Authorization:

Authorization: Bearer el_your_api_key_here

Tu clave de API debe tener los permisos (scopes) adecuados (por ejemplo, translations:document para los trabajos, translations:text para el texto y files:read para las descargas directas de archivos).

Sobre de respuesta estándar: todas las respuestas JSON correctas usan la misma estructura de primer nivel. Por brevedad, los ejemplos estructurales de abajo omiten algunos campos no esenciales, pero siguen siendo objetos JSON válidos. Los ID, las URL y los saldos de créditos que aparecen son puramente ilustrativos: usa los valores reales que devuelvan tus propias respuestas.

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

Inicio rápido: traducción asíncrona de archivos

Procesar un documento completo requiere un flujo asíncrono: sube el archivo para iniciar un trabajo, consulta su estado y descarga el resultado. Puedes usar tu propio archivo o descargar nuestro archivo de ejemplo supply-confirmation.zh-CN.docx para probar.

Método 1: con cURL

Primero exporta tu clave de API (puedes crear una en https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Subir el archivo e iniciar el trabajo

Envía el archivo directamente. La API reserva los créditos necesarios y devuelve un job_id. Incluye un Idempotency-Key único (por ejemplo, un UUID) para que no se creen trabajos duplicados si se agota el tiempo de espera. Reutiliza esta clave si tienes que reintentar el mismo envío y genera una nueva para cada tarea nueva. (Asegúrate de tener un archivo local llamado report.docx antes de ejecutar, o cambia el nombre en el código.)

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"

Extrae el job_id del objeto data de la respuesta para usar en el paso siguiente. No copies ID históricos de los ejemplos.

2. Consultar el estado del trabajo

Usa tu job_id para consultar el progreso. Espera entre peticiones el tiempo recomendado por la cabecera Retry-After. Deja de consultar cuando finished sea true.

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

3. Descargar el resultado

Cuando el estado sea SUCCEEDED, la respuesta incluye una download_url temporal. Esta URL usa una autorización mediante firma temporal, así que no necesitas (ni debes) enviar tu token Bearer para descargar desde ella. Usa una opción como -f para que los errores HTTP fallen en silencio y no acabes guardando una página de error como si fuera tu archivo.

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

Método 2: con Python (requests)

Nota: requiere la biblioteca 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)

Para casos de uso avanzados (por ejemplo, comprobar antes el presupuesto o recuperar un estado de consulta perdido), puedes descargar nuestro script avanzado translate_file.py.

Referencia de endpoints

Aquí tienes los detalles y ejemplos de estructura de la carga útil de los 10 endpoints públicos.

Consulta las enumeraciones DocumentLanguage y TextLanguage del esquema OpenAPI o la guía para desarrolladores para ver los códigos exactos admitidos (por ejemplo, zh-CN, en). El código auto es exclusivo de source_language.

1. Traducir texto

POST /v1/text/translate

Traduce cadenas de texto de forma síncrona. El texto solo se cobra si se ha traducido correctamente. detected_source_language es null si no se detectó automáticamente un idioma concreto.

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. Subir archivo para presupuesto

POST /v1/files

Si necesitas mostrar el coste máximo posible antes de traducir, sube el archivo aquí. Devuelve un file_id y un quote (créditos necesarios).

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. Crear trabajo de traducción de documentos

POST /v1/jobs/translate

Crea un trabajo de traducción asíncrono. Acepta file (multipart), file_url o 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. Crear trabajo de transcripción

POST /v1/jobs/transcribe

Extrae el texto hablado de un archivo de audio o video y lo devuelve como subtítulos con marcas de tiempo, sin traducirlo.

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. Consultar estado del trabajo

GET /v1/jobs/{job_id}

Obtiene el progreso y los enlaces de descarga de un trabajo en curso o finalizado. Sustituye {job_id} en la ruta por tu UUID real.

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. Descargar los bytes del archivo

GET /v1/files/{file_id}

A diferencia de la download_url temporal (que no requiere clave de API), este endpoint te permite descargar directamente los bytes en crudo de cualquier archivo original o traducido guardado en tu cuenta, a partir de su file_id. Requiere una clave de API con el permiso files:read.

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

(Devuelve datos binarios directamente, sin envoltorio JSON)

7. Cancelar trabajo

POST /v1/jobs/{job_id}/cancel

Cancela un trabajo. Si está en INIT o QUEUED, pasa inmediatamente a CANCELLED. Si está en RUNNING, entra en el estado CANCELLING hasta que se detiene por completo.

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. Reintentar trabajo

POST /v1/jobs/{job_id}/retry

Reintenta un trabajo. Puedes reintentarlo si está en FAILED y su error.retryable es true, o si estaba en CANCELLED. Al reintentar se reservan créditos de nuevo. Ten en cuenta que, si la entrega del resultado falló (RESULT_DELIVERY_FAILED), el reintento volverá a intentar la entrega, pero no te cobrará la traducción por segunda vez.

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. Listar trabajos

GET /v1/jobs

Devuelve una lista paginada de tus trabajos de traducción y transcripción, empezando por el más reciente. Pasa limit y cursor (o offset) como parámetros de consulta para paginar.

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. Consultar saldo de créditos

GET /v1/credits/balance

Devuelve tus créditos disponibles y congelados.

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

Gestión de errores

Las peticiones fallidas devuelven códigos de error HTTP estándar junto con una carga de error que indica el motivo y si la operación es retryable.

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