Crear un trabajo de traducción
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonSolicitud
Sección titulada «Solicitud»| Campo | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
document_id | cadena | ✅ | — | ID de un documento confirmado |
target_lang | cadena | ✅ | — | Código del idioma de destino |
source_lang | cadena | — | Detección automática | Código del idioma fuente |
engine | cadena | — | xr-397b | ID de configuración de traducción, véase configuraciones de traducción |
output_mode | cadena | — | bilingual | single o bilingual |
glossary_id | cadena | — | — | Un ID de glosario para esta cuenta. Los glosarios son para cuentas con pagos (al menos un pago exitoso); una cuenta sin pagar que envía uno recibe 403 |
include_images | booleano | — | false | Además, traduzca el texto en las imágenes del documento. |
context_translation | booleano | — | false | Activar la mejora del contexto |
style_preset | cadena | — | — | Preajuste de estilo |
Un trabajo creado ingresa a la cola. Cada cuenta procesa hasta 5 archivos simultáneamente; los trabajos adicionales siguen creándose y se colocan automáticamente en la cola, comenzando a medida que los anteriores finalizan. Mientras un trabajo está en espera, su stage_message indica cuántos trabajos hay por delante.
Antes de que comience un trabajo, el saldo se verifica frente a un umbral: un PDF requiere un saldo superior a “páginas × 2 créditos”; otros formatos se basan en la longitud del texto fuente, con un mínimo de 2 créditos. Si el saldo no permite iniciar un archivo, ese trabajo finaliza con status=failed y quota_exceeded=true, no se cobra nada y los demás trabajos no se ven afectados. Cuando un trabajo termina, se cobra el uso real; si el costo supera el saldo, este queda en negativo, los créditos que lleguen posteriormente saldan primero la deuda y, mientras el saldo esté negativo, no se pueden iniciar nuevos trabajos, por lo que es necesario recargar. Consulte créditos y uso .
Ejemplo
Sección titulada «Ejemplo»curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \ -H "X-API-Key: $OMNIDOC_API_KEY" \ -H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \ -H "Content-Type: application/json" \ -d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'Respuesta 201 (el stage_message del servidor está en chino):
{ "id": "q3f8s6c2a9m1k4tx", "document_id": "4q8mx2q9z1k7p6ra", "source_lang": null, "target_lang": "en", "engine": "xr-397b", "status": "pending", "stage": "queued", "stage_progress": 0, "stage_message": "排队中", "time_cost": 0, "error_msg": null, "quota_exceeded": false, "queue_position": null, "created_at": "2026-10-01T12:01:00Z", "updated_at": "2026-10-01T12:01:00Z"}Errores
Sección titulada «Errores»| Estado | Causa |
|---|---|
403 | La clave no permite la configuración seleccionada, o una cuenta sin pagar envió glossary_id |
404 | El documento o el glosario no existe, fue eliminado o pertenece a otra cuenta |
415 | El formato de archivo no se puede traducir |
422 | El archivo está vacío, no contiene texto traducible o algún parámetro es inválido. |
429 | Demasiadas solicitudes o la cola está llena; reintente después de Retry-After |
Idempotencia
Sección titulada «Idempotencia»Idempotency-Key es opcional pero se recomienda para cada envío. Una clave consta de 1 a 128 caracteres ASCII visibles y permanece válida indefinidamente para la misma credencial:
- Misma clave, mismo cuerpo: devuelve el trabajo original (incluido uno fallido); no se crea ni se cobra nada dos veces.
- Misma llave, diferente cuerpo:
409(idempotency_request_conflict). - El trabajo original fue eliminado:
410(idempotency_job_gone).
Utilice una nueva UUID para cada nuevo envío y reutilice la clave original solo al volver a intentar ese mismo envío.