Referência da API da Equalang e guia de início rápido

Equalang10 de outubro de 2026

Em resumo

Guia de integração da API da Equalang: traduza texto ou processe documentos e mídias de forma assíncrona, com os 10 endpoints públicos como exemplo.

Palavras-chave: integração de API; API de tradução de arquivos; tradução automática; guia para desenvolvedores; referência de API

Ao integrar a Equalang ao seu back-office de gestão ou aos seus fluxos de trabalho, você pode traduzir texto na hora ou processar arquivos inteiros — documentos, áudio e vídeo — mantendo a formatação original onde o formato permite.

Este guia traz um início rápido do fluxo de tradução de arquivos com cURL e Python, seguido da referência completa dos 10 endpoints públicos da API.

Autenticação e resposta padrão

A API da Equalang é servida em https://equalang.com/v1. Autentique cada requisição enviando a sua chave de API no cabeçalho HTTP Authorization:

Authorization: Bearer el_your_api_key_here

A sua chave de API precisa ter as permissões (scopes) corretas (por exemplo, translations:document para os trabalhos, translations:text para texto e files:read para downloads diretos de arquivos).

Envelope de resposta padrão: todas as respostas JSON bem-sucedidas usam a mesma estrutura de primeiro nível. Por concisão, os exemplos estruturais abaixo omitem alguns campos não essenciais, mas continuam sendo objetos JSON válidos. Os IDs, as URLs e os saldos de créditos exibidos são puramente ilustrativos: use os valores reais retornados nas suas próprias respostas.

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

Início rápido: tradução assíncrona de arquivos

Processar um documento inteiro exige um fluxo assíncrono: envie o arquivo para iniciar um trabalho, consulte o status e baixe o resultado. Você pode usar o seu próprio arquivo ou baixar o nosso arquivo de exemplo supply-confirmation.zh-CN.docx para testar.

Método 1: com cURL

Primeiro exporte a sua chave de API (você pode criar uma em https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Enviar o arquivo e iniciar o trabalho

Envie o arquivo diretamente. A API reserva os créditos necessários e retorna um job_id. Inclua um Idempotency-Key único (por exemplo, um UUID) para evitar trabalhos duplicados se houver timeout. Reutilize essa chave se precisar repetir o mesmo envio e gere uma nova para cada nova tarefa. (Certifique-se de ter um arquivo local chamado report.docx antes de executar, ou altere o nome no 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"

Extraia o job_id do objeto data da resposta para usar na próxima etapa. Não copie IDs históricos dos exemplos.

2. Consultar o status do trabalho

Use o seu job_id para acompanhar o progresso. Aguarde entre as requisições o tempo recomendado pelo cabeçalho Retry-After. Pare de consultar quando finished for true.

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

3. Baixar o resultado

Quando o status for SUCCEEDED, a resposta traz uma download_url temporária. Essa URL usa autorização por assinatura temporária, então você não precisa (e não deve) enviar o seu token Bearer para baixar a partir dela. Use uma opção como -f para que erros HTTP falhem silenciosamente e você não acabe salvando uma página de erro no lugar do seu arquivo.

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

Método 2: com Python (requests)

Observação: requer a 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 avançados (por exemplo, verificar a cotação antes ou recuperar um estado de consulta perdido), você pode baixar o nosso script avançado translate_file.py.

Referência de endpoints

Aqui estão os detalhes e exemplos de estrutura do payload dos 10 endpoints públicos.

Consulte as enumerações DocumentLanguage e TextLanguage no esquema OpenAPI ou no guia para desenvolvedores para ver os códigos exatos dos idiomas suportados (por exemplo, zh-CN, en). O código auto vale exclusivamente para source_language.

1. Traduzir texto

POST /v1/text/translate

Traduz textos de forma síncrona. Os textos só são cobrados se forem traduzidos com sucesso. detected_source_language é null se nenhum idioma específico tiver sido detectado automaticamente.

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. Enviar arquivo para cotação

POST /v1/files

Se você precisa exibir o custo máximo possível antes de traduzir, envie o arquivo aqui. A resposta retorna um file_id e uma quote (créditos necessários).

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. Criar trabalho de tradução de documento

POST /v1/jobs/translate

Cria um trabalho de tradução assíncrono. Aceita 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. Criar trabalho de transcrição

POST /v1/jobs/transcribe

Extrai o texto falado de um arquivo de áudio ou vídeo e o retorna como legendas com marcações de tempo, sem traduzi-lo.

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 status do trabalho

GET /v1/jobs/{job_id}

Recupera o progresso e os links de download de um trabalho em andamento ou concluído. Substitua {job_id} no caminho pelo seu 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. Baixar os bytes do arquivo

GET /v1/files/{file_id}

Ao contrário da download_url temporária (que não exige chave de API), este endpoint permite baixar diretamente os bytes brutos de qualquer arquivo de origem ou traduzido guardado na sua conta, a partir do seu file_id. Ele requer uma chave de API com a permissão files:read.

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

(Retorna dados binários diretamente, sem envelope JSON)

7. Cancelar trabalho

POST /v1/jobs/{job_id}/cancel

Cancela um trabalho. Se ele estiver em INIT ou QUEUED, passa imediatamente para CANCELLED. Se estiver em RUNNING, entra no estado CANCELLING até ser totalmente interrompido.

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. Repetir trabalho

POST /v1/jobs/{job_id}/retry

Repete um trabalho. Você pode repeti-lo se ele estiver em FAILED e o error.retryable for true, ou se estava em CANCELLED. Ao repetir, os créditos são reservados novamente. Se a entrega do resultado tiver falhado (RESULT_DELIVERY_FAILED), a repetição tentará a entrega de novo, mas não cobrará a tradução uma 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 trabalhos

GET /v1/jobs

Retorna uma lista paginada dos seus trabalhos de tradução e transcrição, começando pelo mais recente. Passe limit e cursor (ou 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

Retorna os seus créditos disponíveis e 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"
}

Tratamento de erros

Requisições que falham retornam status de erro HTTP padrão, acompanhados de um payload de erro que indica o motivo e se a operação é retryable.

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