Criar uma tradução
Send the file one of three ways: JSON with content (the file itself as UTF-8 text — text formats only, the simplest path for agents), JSON with file_url (HTTPS, fetched server-side, no redirects), or multipart/form-data with a file field (required for XLSX and ZIP). filename is optional: if omitted, a clean default name is generated and the format is inferred automatically from the content. Include instruction to get the full trust-gated plan back in the same response (takes some seconds); omit it to receive four grounded suggested_instructions and continue with the plan endpoint. Quality is chosen at approval, not here — the plan quotes both tiers. Per-format size limits are on /v1/account as entitlements.max_upload_bytes_by_format. The upload also appears in the web app.
POST/v1/batches
Requer batches:create. Criar uma tradução não custa nada: os créditos são reservados apenas quando você aprova um plano.
Como escolher a forma de envio do arquivo
Há três métodos de envio, e a escolha ideal depende do formato do arquivo, e não de preferência pessoal.
| Método | Recomendado para | Observações |
|---|---|---|
JSON com content | Qualquer formato de texto | O próprio arquivo como texto em UTF-8. É o caminho mais simples para um agente que já tem o conteúdo em memória. |
JSON com file_url | Arquivos já hospedados | Apenas HTTPS, obtido no lado do servidor. Redirecionamentos não são seguidos, portanto forneça a URL final. |
multipart/form-data | XLSX e ZIP | Obrigatório para formatos binários: eles não podem ser enviados como texto JSON. |
O parâmetro filename é opcional, mas recomendável. O formato é identificado por meio da extensão; portanto, nomes como strings.xml e export.csv acionam parsers diferentes para bytes idênticos.
Próximos passos
A resposta retorna um batch_id. A partir daí, a sequência é sempre a mesma:
POST /v1/batches/{batch_id}/plan: descreva o que deve ser traduzido, com suas próprias palavras.POST /v1/batches/{batch_id}/approve: use créditos e inicie o processo.GET /v1/batches/{batch_id}: consulte o status até a conclusão.GET /v1/batches/{batch_id}/result: obtenha o resultado. Retorna um link assinado, e não o arquivo diretamente.