Crie um trabalho de tradução
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonSolicitação
Seção intitulada “Solicitação”| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
document_id | string | ✅ | — | ID de um documento confirmado |
target_lang | string | ✅ | — | Código do idioma de destino |
source_lang | string | — | Detecção automática | Código do idioma de origem |
engine | string | — | xr-397b | ID de configuração de tradução, consulte configurações de tradução |
output_mode | string | — | bilingual | single ou bilingual |
glossary_id | string | — | — | 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_images | booleano | — | false | Além disso, traduza o texto nas imagens do documento. |
context_translation | booleano | — | false | Ativar aprimoramento de contexto |
style_preset | string | — | — | 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 .
Exemplo
Seção intitulada “Exemplo”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"}| Status | Causa |
|---|---|
403 | A chave não permite a configuração selecionada, ou uma conta não paga enviou glossary_id |
404 | O documento ou glossário não existe, foi excluído ou pertence a outra conta |
415 | O formato do arquivo não pode ser traduzido |
422 | O arquivo está vazio, não contém texto traduzível ou um parâmetro é inválido |
429 | Número excessivo de solicitações ou fila cheia; tente novamente após Retry-After |
Idempotência
Seção intitulada “Idempotência”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.