API de tradução de documentos

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Uma cotação com cURL

Salve o JSON da cotação acima como payload.json e defina DOCUMENT_TRANSLATOR_API_KEY no seu shell. Este comando solicita apenas uma cotação. Para iniciar, envie o JSON de início com o ID da cotação retornado e o conteúdo idêntico para o endpoint de traduções.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

No PowerShell, use curl.exe e $env:DOCUMENT_TRANSLATOR_API_KEY; escreva o comando em uma única linha, em vez de usar a barra invertida para continuar a linha, como mostrado acima.

Créditos de tradução e chaves de API

Cada documento enviado pela API reserva um crédito da conta dentro dos limites. Tarefas estritas só são cobradas após validação e conclusão; tarefas com falha ou canceladas antes da conclusão liberam a reserva. Com o resultado de melhor esforço, pequenas lacunas podem consumir o crédito acordado, enquanto lacunas importantes ou erros críticos liberam a reserva. Consulte outcome.creditOutcome e outcome.completion em vez de presumir que todo resultado pronto foi cobrado.

Crie até cinco chaves de API ativas por conta. As chaves são exibidas uma única vez, armazenadas como hashes e podem ser revogadas em Conta. Uma chave ativa pode acessar as traduções pagas dessa conta, inclusive trabalhos criados com outra chave da mesma conta. As chaves não autorizam o início de sessão nem pagamentos.

Novas tentativas e solicitações interrompidas

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

Após uma solicitação de início cujo resultado seja incerto, reutilize o mesmo ID de orçamento, payload e chave de idempotência. Tentativas idênticas retornam o trabalho existente sem uma nova cobrança. Um payload alterado ou uma chave reutilizada para outro orçamento retorna 409. Os metadados do trabalho e da chave de idempotência são mantidos por sete dias após o encerramento.

Um trabalho com falha que possa ser retomado pode ser tentado novamente enquanto o texto de origem estiver disponível. A nova tentativa mantém o ID do trabalho e reutiliza os trechos concluídos. Os trabalhos permitem até três tentativas de processamento. Falhas no download podem ser tentadas novamente no endpoint do resultado, sem iniciar outra tradução.

Consultas periódicas e downloads

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

A consulta de status em lote aceita até 100 IDs e retorna { jobs: [...] }, contendo apenas trabalhos autorizados e não excluídos. Consulte a cada cinco segundos, aproximadamente, durante o processamento e a cada quinze segundos enquanto estiver na fila. Alterne os lotes de forma equilibrada ao recuperar mais de 100 trabalhos. Pause as consultas em abas ocultas e pare quando o trabalho chegar a um estado final ou ocorrer um erro permanente de autorização.

Quando o estado for ready, obtenha o resultado usando a mesma autorização da conta. Ele contém o mapeamento dos segmentos traduzidos para reconstrução local. Os resultados ficam acessíveis por 24 horas após a conclusão; entradas sem sucesso expiram uma hora após a criação. Resultados expirados retornam 410. Trabalhos excluídos ou inacessíveis retornam 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

Salve um arquivo concluído usando PUT com o corpo binário, Content-Length e Content-Type correspondente. As extensões compatíveis são docx, pptx, xlsx, pdf, txt e md, com um arquivo salvo por formato e um limite de saída de 50 MB. Repetir um salvamento bem-sucedido mantém o arquivo existente. GET baixa o arquivo salvo; savedFormats no status do trabalho lista os formatos disponíveis. O salvamento e o download usam as mesmas verificações de titularidade do trabalho, não consomem créditos adicionais e nunca prolongam o prazo de 24 horas.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE cancela trabalhos não concluídos ou remove textos disponíveis e arquivos salvos. Excluir um resultado concluído não gera reembolso nem prolonga o prazo para download. Esta versão não oferece webhooks de conclusão.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

Saldo e histórico da conta

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

O histórico é limitado ao proprietário atual e usa o cursor de paginação retornado. O endpoint de saldo usa a sessão da conta no navegador e retorna informações mínimas de login e saldo. Enquanto o Checkout estiver pendente, consulte-o a cada cinco segundos, por no máximo dez tentativas; pause quando a página estiver oculta e pare quando os créditos forem adicionados ou a conta encerrar a sessão.

n8n, Make e Zapier

Use uma etapa de solicitação HTTP com uma credencial Bearer secreta. Primeiro, extraia o texto; faça um POST do conteúdo JSON para o endpoint de cotação e, em seguida, um POST do ID da cotação, do conteúdo e de uma chave de idempotência estável de 16–80 caracteres para o endpoint de traduções. Adicione um intervalo e faça GET do status até o documento ficar pronto; obtenha o resultado e reconstrua ou salve o texto traduzido. Armazene o ID da cotação e a chave de repetição junto ao registro do fluxo de trabalho. Não é necessário um conector dedicado nem um envio multipart.

Limites e erros

• Até 50,000 palavras de origem, 400,000 caracteres extraídos e 12,000 segmentos de texto por documento. O navegador também limita os ficheiros originais a 25 MB, os PDFs a 300 páginas e os ficheiros PowerPoint a 300 diapositivos. Estes são limites de origem, verificados antes do início da tradução.
• Até 100 documentos na fila ou em processamento por conta. As chaves da API compartilham 120 cotações por minuto e cinco novos inícios ou tentativas a cada dez segundos por conta. Respeite Retry-After nas respostas 429 e use intervalos de espera progressivos limitados para falhas temporárias; aumentar a frequência das consultas não acelera o processamento.
• O modo de saída estrita rejeita segmentos traduzidos ausentes, duplicados ou malformados antes da cobrança. O modo de melhor esforço mantém as traduções validadas e pode conservar o texto original nas seções não resolvidas; outcome e issues descrevem o resultado. Nenhuma marca d'água ou atribuição ao serviço é adicionada ao conteúdo do documento.

Os erros incluem uma mensagem e um código. 400 indica entrada inválida; 401, autorização inválida; 402, créditos insuficientes; 404, trabalho indisponível; 409, cotação ou estado conflitante; 410, expiração; 429, limite de taxa ou capacidade; e 503, serviço indisponível.

Guardamos uma cópia privada do documento original até 24 horas após a conclusão da tradução, para que possa recuperar os downloads. Pode removê-la antes ao excluir a tradução. Apenas o texto extraído é enviado ao nosso fornecedor de tradução. Detalhes de privacidade