Cabeçalho da solicitação
Use X-API-Key: sk_… ou Authorization: Bearer sk_…, um dos dois por solicitação. Envie Content-Type: application/json com corpos JSON.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Autenticação por chave API · as traduções de arquivos são executadas como trabalhos assíncronos
Este site descreve a API da nuvem HTTP.
Confirme se sua chave e sua rede estão funcionando antes de enviar arquivos. A verificação de saldo não consome créditos nem gera nenhum trabalho de tradução.
Obtenha uma chave de API
Faça login no console da API API e crie uma chave que comece com sk_. Use uma chave separada para cada aplicação e defina um orçamento para ela.
Uma chave serve para a conta que a criou. Mantenha-a no servidor e leia-a de uma variável de ambiente; nunca a inclua no código-fonte da página web nem em um repositório público.
Verifique o saldo
Defina a variável de ambiente OMNIDOC_API_KEY e, em seguida, execute qualquer um dos exemplos abaixo. O sucesso retorna JSON; 401 indica que a chave apresenta um problema e precisa ser verificada. Nunca exiba a chave completa em tickets, capturas de tela ou logs.
export OMNIDOC_API_KEY="sk_your_key"curl --fail-with-body --silent --show-error \ 'https://omnidoc.top/api/v1/billing/credits/balance' \ -H "X-API-Key: $OMNIDOC_API_KEY"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());Um carregamento bem-sucedido apenas indica que o arquivo foi armazenado. Após criar um job, aguarde até que ele atinja um estado final e, em seguida, liste e baixe seus resultados.
| Etapa | Método e caminho | O que manter |
|---|---|---|
| Solicitar um envio | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Envie o arquivo | PUT para o upload_url retornado | Resposta de sucesso; esta solicitação não contém uma chave API |
| Confirme o carregamento | POST /upload/finalize | document.id |
| Crie uma tradução | POST /jobs | Trabalho id |
| Verifique o status | GET /jobs/{job_id} | completed ou failed |
| Liste os resultados | GET /artifacts?job_id={job_id} | IDs e formatos de artefatos |
| Baixar um resultado | GET /artifacts/{artifact_id}/download | Bytes do arquivo e o nome do arquivo de resposta |
Para o carregamento direto, envie o upload_headers do servidor exatamente como foi retornado e nunca envie X-API-Key para o endereço de armazenamento. Se o endereço de carregamento expirar ou a transferência falhar, solicite um novo. Detalhes: protocolo de carregamento , início rápido , ciclo de trabalho completo de Node.js e campos da solicitação de tradução .
Cada entrada lista os caminhos, campos de solicitação e exemplos. O status do serviço da sua conta e os limites da sua chave aplicam-se a todos eles.
Uma chave de API identifica uma conta. Não é uma senha pública para baixar um arquivo.
Cabeçalho da solicitação
Use X-API-Key: sk_… ou Authorization: Bearer sk_…, um dos dois por solicitação. Envie Content-Type: application/json com corpos JSON.
O que uma chave pode alcançar
Uma chave acessa apenas os recursos que sua conta pode utilizar; o status do serviço, o orçamento da chave e as configurações de tradução permitidas continuam a ser aplicados. Alterações na conta e a criação, rotação ou revogação de chaves são realizadas no console.
Veja autenticação, orçamentos e rotação e serviços e permissões .
Um timeout não significa que o trabalho não foi criado. Diferencie erros retentivos de solicitações que precisam ser corrigidas, para que nada seja enviado ou processado duas vezes.
Idempotency-Key para cada nova operação de criação; ao repetir a mesma operação, reutilize a chave original e o corpo da solicitação exatamente igual. Operações de documentos, trabalhos de mídia e criação de voz exigem a chave; para outros endpoints de criação, consulte suas páginas de referência.| Status | Verifique primeiro | O que fazer |
|---|---|---|
401 / 403 | Chave, permissões, propriedade de recursos | Corrija as credenciais ou permissões; não tente novamente sem verificar. |
402 | Créditos disponíveis | Recarregue e envie novamente |
409 | Chave e corpo da idempotência, estado do recurso | Consulte a operação original antes de iniciar uma nova |
422 | Erros de campo na resposta | Corrija os parâmetros ou o arquivo |
429 | Negócios code e Retry-After | Os limites de taxa e de fila podem ser aguardados; um orçamento de chaves esgotado deve ser aumentado primeiro. |
5xx | Erro temporário do serviço | Retrocesso exponencial limitado; mantenha a chave de idempotência para solicitações de criação |
Mantenha o cabeçalho de resposta X-Request-Id, o horário da requisição e o caminho para solução de problemas; nunca registre a chave completa. Todos os códigos de erro e exemplos de tentativa são encontrados na referência de erro . .
Sem créditos
O upload, a verificação de trabalhos, o download de resultados e a leitura do saldo e dos registros de liquidação não consomem créditos; o mesmo vale para glossários, projetos, tags, pesquisa e compartilhamento.
Cobrado por uso
A tradução de arquivos, as ferramentas de documentos, a tradução instantânea e os serviços de áudio e vídeo são cobrados com base no uso efetivo; a criação de uma tarefa não representa o custo final.
Antes do início de uma tarefa, apenas o limite de saldo é verificado; após sua conclusão, a utilização efetiva é cobrada. Caso o saldo seja insuficiente, a diferença é registrada como dívida, sendo quitada prioritariamente com créditos recebidos posteriormente. É possível conciliar cobranças e reembolsos por tarefa ou por operação de crédito. Quando o orçamento de uma chave é esgotado, ainda é possível consultar as tarefas, resultados e registros associados a essa chave.