API de traducción de documentos

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Una consulta de precio con cURL

Guarda el JSON de consulta de precio anterior como payload.json y configura DOCUMENT_TRANSLATOR_API_KEY en tu shell. Este comando solo solicita una consulta de precio. Para iniciar, envía el JSON de inicio con el ID de consulta devuelto y la misma carga útil al endpoint de traducciones.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

En PowerShell, usa curl.exe y $env:DOCUMENT_TRANSLATOR_API_KEY; escribe el comando en una sola línea en vez de usar la continuación con barra invertida que se muestra arriba.

Créditos de traducción y claves de API

Cada documento enviado a la API reserva un crédito de la cuenta, dentro de los límites. Los trabajos estrictos solo cobran cuando se validan y están listos; las tareas fallidas o canceladas antes de terminar liberan la reserva. Con el resultado de mejor esfuerzo, las omisiones pequeñas pueden consumir el crédito acordado, mientras que las omisiones importantes o los errores críticos lo liberan. Consulta outcome.creditOutcome y outcome.completion en lugar de asumir que se cobró por cada resultado listo.

Crea hasta cinco claves de API activas por cuenta. Las claves se muestran una sola vez, se guardan como hashes y se pueden revocar en la sección Cuenta. Una clave activa puede acceder a las traducciones de pago de esa cuenta, incluidos los trabajos creados con otra clave de la misma cuenta. Las claves no autorizan el inicio de sesión ni los pagos.

Reintentos y solicitudes interrumpidas

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

Si no está seguro de que la solicitud de inicio se haya completado, vuelva a utilizar el mismo ID de cotización, la misma carga útil y la misma clave de idempotencia. Los reintentos idénticos devuelven el trabajo existente sin realizar otro cargo. Si cambia la carga útil o reutiliza una clave para otra cotización, se devuelve 409. Los metadatos del trabajo y de idempotencia se conservan durante siete días tras la finalización.

Un trabajo fallido que se pueda reanudar puede volver a intentarse mientras el texto de origen siga disponible. El reintento conserva el ID del trabajo y reutiliza los fragmentos completados. Cada trabajo permite un máximo de tres intentos de procesamiento. Si falla la descarga, puedes volver a intentar acceder al resultado sin iniciar otra traducción.

Consultas periódicas y descargas

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

La consulta del estado por lotes acepta un máximo de 100 ID y devuelve { jobs: [...] }, que contiene solo trabajos autorizados y no eliminados. Consulta aproximadamente cada cinco segundos mientras se procesan y cada quince segundos mientras están en cola. Alterna los lotes de forma equitativa si estás recuperando más de 100 trabajos. Pausa las consultas en las pestañas ocultas y detente cuando el trabajo llegue a un estado final o se produzca un error de autorización permanente.

Cuando el estado sea «ready», obtén el resultado con la misma autorización de cuenta. Contiene la correspondencia de segmentos traducidos para reconstruir el documento localmente. Los resultados están disponibles durante 24 horas después de completarse; las entradas no válidas caducan una hora después de su creación. Los resultados caducados devuelven 410. Los trabajos eliminados o inaccesibles devuelven 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

Guarda un archivo terminado mediante PUT, con su cuerpo binario, Content-Length y el Content-Type correspondiente. Se admiten las extensiones docx, pptx, xlsx, pdf, txt y md, con un archivo guardado por formato y un límite de salida de 50 MB. Si se repite una operación de guardado correcta, se conserva el archivo existente. GET descarga el archivo guardado; savedFormats en el estado del trabajo enumera los formatos disponibles. Guardar y descargar utilizan las mismas comprobaciones de propiedad del trabajo, no cuestan créditos adicionales y nunca amplían el plazo de 24 horas.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE cancela el trabajo sin terminar o elimina el texto disponible y los archivos guardados. Eliminar un resultado completado no lo reembolsa ni amplía su plazo de descarga. Esta versión no incluye webhooks de finalización.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

Saldo e historial de la cuenta

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

El historial está limitado al propietario actual y utiliza el cursor de paginación devuelto. El endpoint de saldo utiliza la sesión de la cuenta del navegador y devuelve información mínima de inicio de sesión y saldo. Mientras el Checkout esté pendiente, consulte el endpoint cada cinco segundos, hasta diez veces; pause las consultas cuando la página esté oculta y deténgalas cuando se acrediten los créditos o se cierre la sesión de la cuenta.

n8n, Make y Zapier

Usa un paso de solicitud HTTP con una credencial Bearer secreta. Extrae primero el texto, envía la carga útil JSON mediante POST al endpoint de consulta de precio y luego envía el ID de consulta, la carga útil y una clave de idempotencia estable de 16–80 caracteres al endpoint de traducciones mediante POST. Añade una espera y consulta el estado mediante GET hasta que esté listo; luego obtén el resultado y reconstruye o guarda el texto traducido. Guarda el ID de consulta y la clave de reintento con el registro de tu flujo de trabajo. No se necesita un conector específico ni una carga multipart.

Límites y errores

• Hasta 50,000 palabras de origen, 400,000 caracteres extraídos y 12,000 segmentos de texto por documento. El navegador también limita los archivos originales a 25 MB, los PDF a 300 páginas y los archivos de PowerPoint a 300 diapositivas. Estos son límites de origen que se comprueban antes de iniciar la traducción.
• Hasta 100 documentos en cola o en procesamiento por cuenta. Las claves de API comparten un límite de 120 consultas por minuto y cinco nuevos inicios o reintentos cada diez segundos por cuenta. Respeta Retry-After en las respuestas 429 y aplica esperas progresivas limitadas ante fallos temporales; aumentar la frecuencia de las consultas de estado no acelera el procesamiento.
• El resultado estricto rechaza los segmentos traducidos ausentes, duplicados o mal formados antes de cobrar. El resultado de mejor esfuerzo conserva las traducciones validadas y puede mantener el texto original en las secciones sin resolver; outcome e issues describen el resultado. No se añade ninguna marca de agua ni atribución al servicio al contenido del documento.

Los errores incluyen un mensaje y un código. 400 indica datos no válidos, 401 autorización no válida, 402 créditos insuficientes, 404 trabajo no disponible, 409 presupuesto o estado en conflicto, 410 caducidad, 429 límite de solicitudes o capacidad y 503 servicio no disponible.

Guardamos una copia privada de tu documento original hasta 24 horas después de finalizar la traducción para que puedas recuperar tus descargas. Puedes eliminarla antes borrando la traducción. Solo se envía el texto extraído a nuestro proveedor de traducción. Detalles de privacidad