Pular para o conteúdo

Crie um trabalho de tradução

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
CampoTipoObrigatórioPadrãoDescrição
document_idstring✅—ID de um documento confirmado
target_langstring✅—Código do idioma de destino
source_langstring—Detecção automáticaCódigo do idioma de origem
enginestring—xr-397bID de configuração de tradução, consulte configurações de tradução
output_modestring—bilingualsingle ou bilingual
glossary_idstring——Um ID de glossário desta conta. Glossários são para contas pagantes (pelo menos um pagamento bem-sucedido); uma conta não paga que envia um pagamento recebe 403
include_imagesbooleano—falseAlém disso, traduza o texto nas imagens do documento.
context_translationbooleano—falseAtivar aprimoramento de contexto
style_presetstring——Predefinição de estilo

Um trabalho criado entra na fila. Cada conta processa até 5 arquivos simultaneamente; trabalhos adicionais continuam a ser criados e a fila avança automaticamente à medida que os anteriores são concluídos. Enquanto um trabalho aguarda, seu stage_message indica quantos trabalhos estão à frente.

Antes de iniciar um trabalho, o saldo é verificado em relação a um limite: um PDF exige um saldo superior a “páginas × 2 créditos”; outros formatos baseiam-se no comprimento do texto de origem, com no mínimo 2 créditos. Se o saldo não for suficiente para iniciar um arquivo, esse trabalho termina com status=failed e quota_exceeded=true, nada é cobrado e os demais trabalhos não são afetados. Ao finalizar um trabalho, é cobrado o consumo efetivo; se o custo ultrapassar o saldo, este fica negativo, sendo que os créditos recebidos posteriormente quitam primeiro a dívida, e novos trabalhos não podem ser iniciados enquanto o saldo estiver negativo, portanto, faça uma recarga. Consulte créditos e consumo .

Terminal window
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"}'

Resposta 201 (o stage_message do servidor está em chinês):

{
"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"
}
StatusCausa
403A chave não permite a configuração selecionada, ou uma conta não paga enviou glossary_id
404O documento ou glossário não existe, foi excluído ou pertence a outra conta
415O formato do arquivo não pode ser traduzido
422O arquivo está vazio, não contém texto traduzível ou um parâmetro é inválido
429Número excessivo de solicitações ou fila cheia; tente novamente após Retry-After

Idempotency-Key é opcional, mas recomendado para todas as submissões. Uma chave consiste em 1 a 128 caracteres ASCII visíveis e permanece válida indefinidamente para a mesma credencial:

  • Mesma chave, mesmo corpo: retorna o trabalho original (incluindo um que tenha falhado); nada é criado ou cobrado duas vezes.
  • Mesma chave, corpo diferente: 409 (idempotency_request_conflict).
  • O trabalho original foi excluído: 410 (idempotency_job_gone).

Use uma nova UUID para cada novo envio e reutilize a chave original apenas ao tentar novamente o mesmo envio.