batches

Create a translation

Create a translation using exactly one source: JSON content for verbatim UTF-8 text, JSON file_url for an HTTPS download without redirects, JSON upload_id for a completed temporary upload on this same credential, or multipart/form-data with a file field for local binary bytes. Omit filename with upload_id; the session already owns its name. Repeating an upload_id returns the existing batch without changing its instruction. Send an Idempotency-Key header (any 1 to 255 printable characters, a UUID is fine) on the other sources to make a retry after a lost response safe: a repeat returns the batch the first attempt created, without fetching or storing the file or planning again, and the same key with different content is refused with 409 idempotency_key_reused. Otherwise filename is optional and inferred if absent. Include instruction to receive the verified plan, measured counts, credit cost and extraction preview; omit it to receive suggested_instructions. Check plan.not_included before approval. Creating and planning cost no credits. Per-format limits are on GET /v1/account. The translation appears in the web app.

POST/v1/batches

Request

curl --request POST \
  --url 'https://api.ai-glot.com/v1/batches' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "upload_id": "550e8400-e29b-41d4-a716-446655440000",
  "instruction": "Translate all English text into French"
}'

import json
import requests

url = "https://api.ai-glot.com/v1/batches"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"upload_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"instruction\":\"Translate all English text into French\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.ai-glot.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "upload_id": "550e8400-e29b-41d4-a716-446655440000",
    "instruction": "Translate all English text into French"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.ai-glot.com/v1/batches");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"upload_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"instruction\":\"Translate all English text into French\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.ai-glot.com/v1/batches", bytes.NewBuffer([]byte("{\"upload_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"instruction\":\"Translate all English text into French\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.ai-glot.com/v1/batches"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"upload_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"instruction\":\"Translate all English text into French\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.ai-glot.com/v1/batches")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"upload_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"instruction\":\"Translate all English text into French\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": {
    "id": "<string>",
    "name": null,
    "file_name": null,
    "status": "analyzing",
    "quality_tier": null,
    "word_count": 123,
    "credit_cost": 123,
    "is_sample": true,
    "archived": true,
    "progress": {
      "phase": null,
      "percent": null,
      "updated_at": null,
      "estimated_seconds_remaining": 123
    },
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "created_at": null,
    "completed_at": null,
    "next_action": "provide_instruction",
    "plan": {
      "instruction": "<string>",
      "summary": null,
      "will_translate": null,
      "will_not_touch": null,
      "special_rules": [
        "<string>"
      ],
      "assumptions": [
        "<string>"
      ],
      "not_included": [
        "<string>"
      ],
      "languages": [
        {
          "source": {},
          "target": {},
          "segments": {},
          "words": {}
        }
      ],
      "totals": {
        "segments": 123,
        "words": 123,
        "files": {}
      },
      "credits": {
        "standard": 123,
        "lite": 123
      },
      "preview": [
        {
          "location": {},
          "source_text": {},
          "context": {},
          "languages": {},
          "source_lang": {},
          "target_lang": {}
        }
      ],
      "cached": true
    },
    "plan_revision": "<string>",
    "suggested_instructions": [
      "<string>"
    ]
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

Requires batches:create. Creating a translation costs nothing: credits are reserved only when you approve a plan.

Choosing how to send the file

Choose the transport that matches where the document lives and what your client can do.

Transport	Use it for	Notes
JSON with `upload_id`	A local file sent through a temporary upload session	Use the same credential that created the session. Omit `filename`. Repeating creation returns the existing translation without changing its instruction.
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`	Local binary files, including XLSX, DOCX, PPTX, PDF, IDML and ZIP	Send the original bytes in the `file` field. This is the CLI’s local-file transport.

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.

Retrying safely

Send an Idempotency-Key header (any 1 to 255 printable characters; a UUID is a good choice) so a retry after a lost response returns the translation the first attempt created, instead of a second one. A repeat is answered before the file is fetched or stored and does not plan again, so it costs nothing. The key is bound to what you sent: the same key with a different file, name or instruction is refused with idempotency_key_reused. Use a new key for new work. Where headers are not available (MCP tools, Code Mode) pass idempotency_key in the body. A creation with an instruction returns plan_revision with the plan: pass it as expected_plan_revision when you approve.

What happens next

The response gives you an id, used as batch_id in subsequent paths. 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.

Response

application/json

Create a translation from a file

dataobjectrequired

Show child attributes

idstringrequired

namestringnullrequired

file_namestringnullrequired

statusstringrequired

Where the translation is. All seven values: analyzing — the file's structure is being read, which takes seconds; poll. awaiting_instructions — the file is read, nobody has said what to translate; call plan. awaiting_approval — a plan is waiting for a yes; call approve, the only call that spends credits. translating — running; poll. completed — fetch the result. failed — the run could not finish; read error. cancelled — someone stopped it on purpose; also terminal, and not a failure. The last three are terminal: stop polling.

quality_tierstringnullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstringnullrequired

completed_atstringnullrequired

next_actionstring

The call to make next, so a client never has to map status itself. provide_instruction — call plan with an instruction. review_plan — the priced plan is embedded; check plan.not_included, then approve. wait — poll again; progress.estimated_seconds_remaining says how long is left. download — fetch the result. read_error — the run is over without a result; read error (and status says whether it broke or was cancelled). Absent only on a legacy pre-2026-08-31 CSV batch, which has no plan behind it; every translation created since then answers.

planobject | null

plan_revisionstring | null

suggested_instructionsstring[] | null

request_idstringrequired

Create a translation

Choosing how to send the file

Retrying safely

What happens next

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown