Guia de acesso à API de tradução de documentos: use Python para traduzir em lote Word e PDF e use Webhook para receber os resultados

A API de tradução de documentos pode encadear upload, criação de tarefas, recebimento de retornos de chamada e download de traduções em um processo automatizado. Você pode concluir uma tradução completa em apenas quatro etapas.

Se o seu sistema processa contratos, instruções, documentos ou relatórios todos os dias, o upload, a espera e o download manuais rapidamente se tornarão um gargalo. Somente entregando essas etapas ao programa o processamento em lote poderá ser estável.

A API de tradução de documentos do OmniDoc (Zhiyi) reúne todo o processo: Carregar arquivos, criar tarefas, receber notificações de conclusão e baixar traduções. A tradução mantém o layout, tabelas, imagens e fórmulas do documento original, podendo gerar comparações bilíngues ou apenas a tradução.

Este artigo é adequado para desenvolvedores que precisam integrar a tradução de documentos em seus próprios sistemas. Após a leitura, você será capaz de dominar o processo completo de chamada, parâmetros comuns, métodos de repetição idempotentes, retornos de chamada do Webhook e regras de cobrança, e será capaz de executar uma tarefa completa usando Python.

Como acessar a API de tradução de documentos? Conclusão de uma frase

Você pode integrar a tradução de documentos em seu próprio sistema usando a API para carregar, criar tarefas, receber retornos de chamada e baixar traduções automaticamente em um processo de quatro etapas.

Tabela 0 Cenários de acesso e práticas recomendadas

Leia as informações básicas antes de acessar

As convenções básicas da API são as seguintes. Confirme este conteúdo antes de começar a escrever o código.

Tabela 1 Convenções básicas da API

Quais arquivos são suportados?

Suporta Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown com texto, legendas SRT/ASS, CSV, imagens PNG/JPG e documentos UniDoc (.udoc).

Exceto PPTX, todos os outros formatos suportam saída bilíngue. Quando o PPTX solicita o bilinguismo, apenas a tradução é devolvida. Para métodos de comparação específicos, consulte a comparação principal abaixo.

Conclua uma tradução em quatro etapas

1. Inscrever-se para upload: Chame POST /upload/presign, envie o nome e o tamanho do arquivo e obtenha o endereço de transferência direta, o cabeçalho de upload e o finalize_token.
2. Carregar e confirmar: Use o cabeçalho de upload retornado para colocar o arquivo e não traga a chave de API ao fazer o upload. Em seguida, chame POST /upload/finalize em troca de document.id.
3. Criar tarefa: Chame POST /jobs, envie document_id e target_lang, e é recomendado trazer Idempotency-Key ao mesmo tempo.
4. Recuperar resultados: pesquise GET /jobs/{id} ou inscreva-se no progresso do SSE ou configure o Webhook. Após a conclusão da tarefa, use GET /artifacts?job_id=... para obter o produto e baixá-lo.

Parâmetros comuns para criação de tarefas

Ao criar uma tarefa, os dois campos mais usados são document_id e target_lang. Outros campos são definidos conforme necessário.

Tabela 2 Campos de solicitação POST /jobs

Exemplo Python: Crie uma tarefa e aguarde a conclusão

O trecho abaixo depende apenas de solicitações. Para o processo completo de upload e download, consulte a página Python da documentação do desenvolvedor.

import time, uuid, requests

BASE = "https://omnidoc.top/api/v1"
HEADERS = {"X-API-Key": "sk_your_key"}

def create_job(document_id, target_lang="en", engine="xr-397b"):
    r = requests.post(f"{BASE}/jobs",
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={"document_id": document_id, "target_lang": target_lang, "engine": engine},
        timeout=30)
    r.raise_for_status()
    return r.json()

def wait_for_job(job_id):
    while True:
        job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=20).json()
        if job["status"] in ("completed", "failed"):
            return job
        time.sleep(5)

Lotes e novas tentativas: simultaneidade, filas e idempotência

Enfileiramento automático

Cada conta pode processar 5 arquivos simultaneamente. As tarefas que excedem o limite superior são criadas e enfileiradas normalmente, e stage_message indicará quantas tarefas existem pela frente.

Chaves idempotentes

Se a Chave de Idempotência for a mesma e o corpo da solicitação for o mesmo, a tarefa original será retornada e não será criada ou cobrada repetidamente. Ao encontrar um tempo limite de rede, verifique primeiro o status da tarefa e não reenvie com uma nova chave.

Código de erro

• 403: A configuração selecionada não é permitida para Key.
• 404: Documentação ou glossário não existe.
• 415: O formato não é suportado.
• 422: O arquivo está vazio ou os parâmetros são inválidos.

Webhook: Notifique seu servidor quando a tarefa terminar

Cada usuário pode configurar 3 webhooks. Crie com POST /webhooks, atualize ou desative com PATCH.

Quando uma tarefa de tradução de arquivo termina (independentemente do sucesso ou falha), o sistema envia o evento job.completed:

• data.status foi concluído ou falhou.
• data.char_count é o número de caracteres de tradução.

Preencha o segredo ao criar um Webhook e cada retorno de chamada subsequente trará X-Webhook-Signature. Use HMAC-SHA256 para assinar a solicitação original para confirmar a origem do retorno de chamada.

O URL de retorno de chamada deve estar acessível na rede pública e HTTPS é recomendado.

Como calcular a taxa?

Verificação de saldo antes de começar

• PDF: O saldo precisa ser superior a"número de páginas × 2 pontos".
• Outros formatos: cobrados com base na quantidade de palavras originais, no mínimo 2 pontos.
• Quando o saldo for insuficiente, a tarefa terminará com quota_exceeded e nenhuma taxa será deduzida.

Dedução com base no uso real

Após a conclusão da tarefa, as taxas serão deduzidas com base no uso real. Se a tarefa falhar ou for cancelada, nenhuma taxa será deduzida.

Consulta gratuita

Não serão deduzidos pontos para consulta de saldo, status de tarefas, utilização, vouchers e endereços de download.

Pacote de pontos

Os pacotes de pontos custam a partir de ¥ 9,9 por 3.000 pontos, e os pontos adquiridos são válidos por um longo período. Os pacotes em promoção podem ser consultados via GET /billing/credits/plans.

Próxima etapa

Exemplos completos de cURL, Python, Node.js podem ser visualizados na documentação do desenvolvedor: https://docs.omnidoc.top/guide/quickstart/.

Se não quiser escrever código por enquanto, você também pode se conectar ao assistente de IA do OmniDoc para traduzir diretamente os arquivos nativos. Para obter detalhes, consulte "Deixe a IA operar diretamente Word, Excel e PPT": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.

📊 Comparação principal

Diferentes formatos de arquivo possuem diferentes métodos de saída bilíngues. Você pode planejar com antecedência de acordo com seu tipo de arquivo.

🎯 Qual método é adequado para você?

Se você precisar processar contratos, especificações ou documentos em lote

Use API para se conectar ao sistema e fazer upload, criar tarefas e baixar traduções automaticamente de acordo com o processo de quatro etapas, eliminando operações manuais.

Se sua rede costuma ser instável

Traga a Chave de Idempotência ao criar a tarefa. Consulte o status primeiro após o tempo limite para evitar criações repetidas ou deduções repetidas.

Se você deseja processar a tarefa imediatamente após seu término

Configure o Webhook e preencha o segredo para verificação de assinatura. O sistema notificará proativamente o seu servidor quando a tarefa for concluída.

Se você tiver requisitos unificados para vocabulário profissional

Crie primeiro um glossário e depois passe glossary_id ao criar uma tarefa para unificar a tradução de nomes de marcas e palavras profissionais.

❓ Perguntas frequentes (FAQ)

1. Haverá deduções repetidas por enviar a mesma tarefa repetidamente?

Se a Chave de Idempotência for a mesma e o corpo da solicitação for o mesmo, a tarefa original será retornada sem criação ou dedução repetida.

2. Se a tarefa falhar ou for cancelada, os pontos serão deduzidos?

Nenhuma taxa será cobrada. Quando uma tarefa falha ou é cancelada, nenhuma dedução será feita.

3. O que acontece quando não há pontos suficientes?

A tarefa terminará com quota_exceeded e nenhuma taxa será deduzida. O limite de equilíbrio antes de iniciar é: o PDF requer um saldo superior a "número de páginas x 2 pontos" e outros formatos exigem um saldo de pelo menos 2 pontos com base na contagem de palavras.

4. Preciso trazer uma chave de API ao fazer upload de arquivos?

desnecessário. Ao usar o arquivo PUT do cabeçalho de upload, não traga a chave da API.

5. O que devo fazer se encontrar o limite de tráfego 429?

Tente novamente de acordo com o tempo Retry-After na resposta.

📝 Resumo

Ao agrupar uploads, criação de tarefas, retornos de chamada e downloads em um processo automatizado, a tradução de documentos pode ser integrada aos negócios diários. Comece executando uma tarefa com um exemplo Python e, em seguida, adicione um glossário, uma saída bilíngue e webhooks conforme necessário.

Experimente agora: carregue o documento para iniciar a tradução, mantendo o layout original