---
title: "Create a translation"
description: "Upload a file over the API and get a translation ready to plan, using JSON text, an HTTPS URL or multipart form data for binary formats."
canonical: "https://ai-glot.com/docs/api/translations/create"
updated: "2026-08-31"
---

# Create a translation

Requires `batches:create`. Creating a translation costs nothing: credits are reserved only when you [approve a plan](/docs/api/translations/approve).

## 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:

1. [`POST /v1/batches/{batch_id}/plan`](/docs/api/translations/plan): describe what to translate, in your own words.
2. [`POST /v1/batches/{batch_id}/approve`](/docs/api/translations/approve): spend credits and start.
3. [`GET /v1/batches/{batch_id}`](/docs/api/translations/retrieve): poll until it finishes.
4. [`GET /v1/batches/{batch_id}/result`](/docs/api/translations/download): collect the result. It returns a signed link, not the file itself.

> **Info: Size limits are per format**
>
> Each format family has its own ceiling, from 4 MB to 60 MB. See [Files and formats](/docs/platform/files-and-formats) for the full table. A file over its limit is refused with `file_too_large` before any bytes are stored.