Create a translation
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
Requires batches:create. Creating a translation costs nothing: credits are reserved only when you approve a plan.
Choosing how to send the file
Three transports, and the right one depends on the format rather than on preference.
| Transport | Use it for | Notes |
|---|---|---|
JSON with content | Any text format | The file itself as UTF-8 text. The simplest path for an agent that already holds the content in memory. |
JSON with file_url | A file already hosted | HTTPS only, fetched server-side. Redirects are not followed, so give the final URL. |
multipart/form-data | XLSX and ZIP | Required for binary formats: they cannot survive being sent as JSON text. |
filename is optional but worth sending. The extension is how the format is identified, so a name like strings.xml and a name like export.csv lead to different parsers on identical bytes.
What happens next
The response gives you a batch_id. From there the sequence is always the same:
POST /v1/batches/{batch_id}/plan: describe what to translate, in your own words.POST /v1/batches/{batch_id}/approve: spend credits and start.GET /v1/batches/{batch_id}: poll until it finishes.GET /v1/batches/{batch_id}/result: collect the result. It returns a signed link, not the file itself.