Saltearse al contenido

Crear un trabajo de traducción

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
CampoTipoObligatorioPredeterminadoDescripción
document_idcadena✅—ID de un documento confirmado
target_langcadena✅—Código del idioma de destino
source_langcadena—Detección automáticaCódigo del idioma fuente
enginecadena—xr-397bID de configuración de traducción, véase configuraciones de traducción
output_modecadena—bilingualsingle o bilingual
glossary_idcadena——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_imagesbooleano—falseAdemás, traduzca el texto en las imágenes del documento.
context_translationbooleano—falseActivar la mejora del contexto
style_presetcadena——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 .

Ventana de terminal
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"
}
EstadoCausa
403La clave no permite la configuración seleccionada, o una cuenta sin pagar envió glossary_id
404El documento o el glosario no existe, fue eliminado o pertenece a otra cuenta
415El formato de archivo no se puede traducir
422El archivo está vacío, no contiene texto traducible o algún parámetro es inválido.
429Demasiadas solicitudes o la cola está llena; reintente después de Retry-After

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.