batches

Créer une traduction

Créez une traduction en utilisant exactement une seule source : le contenu JSON pour du texte UTF-8 à traduire tel quel, file_url en JSON pour un téléchargement HTTPS sans redirection, upload_id en JSON pour un téléversement temporaire terminé avec ces mêmes identifiants, ou multipart/form-data avec un champ file pour des données binaires locales. N’indiquez pas filename avec upload_id : la session a déjà enregistré le nom du fichier. Si vous réutilisez un upload_id, le lot existant est renvoyé sans que son instruction soit modifiée. Pour les autres sources, envoyez un en-tête Idempotency-Key (de 1 à 255 caractères imprimables, un UUID convient) afin de pouvoir réessayer sans risque si la réponse est perdue : le premier lot créé est renvoyé, sans récupérer ni stocker le fichier ni relancer la planification. Si vous réutilisez la même clé avec un contenu différent, la requête est refusée avec le code 409 idempotency_key_reused. Sinon, filename est facultatif et son nom est déduit s’il n’est pas fourni. Incluez instruction pour recevoir le plan vérifié, les quantités mesurées, le coût en crédits et l’aperçu de l’extraction. Omettez-le pour recevoir suggested_instructions. Vérifiez plan.not_included avant d’approuver. La création et la planification ne coûtent aucun crédit. Les limites par format sont indiquées sur GET /v1/account. La traduction apparaît dans l’application web.

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>"
}

Nécessite batches:create. La création d’une traduction est gratuite : les crédits sont réservés uniquement lorsque vous approuvez un plan.

Choisir comment envoyer le fichier

Choisissez le mode de transfert adapté à l’emplacement du document et aux capacités de votre client.

Mode de transfert	Utilisation	Remarques
JSON avec `upload_id`	Fichier local envoyé via une session de téléversement temporaire	Utilisez les mêmes identifiants que ceux ayant servi à créer la session. Omettez `filename`. Une nouvelle requête de création renvoie la traduction existante sans modifier ses consignes.
JSON avec `content`	Tout format texte	Le contenu du fichier sous forme de texte UTF-8. C’est la méthode la plus simple pour un agent qui a déjà le contenu en mémoire.
JSON avec `file_url`	Fichier déjà hébergé	HTTPS uniquement, avec récupération côté serveur. Les redirections ne sont pas suivies : indiquez l’URL finale.
`multipart/form-data`	Fichiers binaires locaux, notamment XLSX, DOCX, PPTX, PDF, IDML et ZIP	Envoyez les octets d’origine dans le champ `file`. C’est le mode de transfert des fichiers locaux de la CLI.

filename est facultatif, mais il est préférable de le renseigner. L’extension permet d’identifier le format : avec les mêmes octets, un nom comme strings.xml et un nom comme export.csv feront appel à des analyseurs différents.

Réessayer sans risque

Envoyez un en-tête Idempotency-Key (de 1 à 255 caractères imprimables ; un UUID convient) afin qu’une nouvelle tentative après la perte d’une réponse renvoie la traduction créée lors de la première tentative, au lieu d’en créer une deuxième. Une requête répétée reçoit une réponse avant la récupération ou le stockage du fichier et ne déclenche pas de nouvelle planification : elle est donc gratuite. La clé est liée aux données envoyées : si vous réutilisez la même clé avec un fichier, un nom ou des consignes différents, la requête est refusée avec idempotency_key_reused. Utilisez une nouvelle clé pour tout nouveau travail. Lorsque les en-têtes ne sont pas disponibles (outils MCP, Code Mode), transmettez idempotency_key dans le corps de la requête. Si la création inclut une instruction, la réponse renvoie plan_revision avec le plan : transmettez cette valeur dans expected_plan_revision lorsque vous approuvez le plan.

Étapes suivantes

La réponse fournit un id, utilisé comme batch_id dans les chemins suivants. La séquence est toujours la même :

POST /v1/batches/{batch_id}/plan : indiquez avec vos propres mots ce qu’il faut traduire.
POST /v1/batches/{batch_id}/approve : dépensez des crédits et lancez le traitement.
GET /v1/batches/{batch_id} : interrogez le statut jusqu’à la fin du traitement.
GET /v1/batches/{batch_id}/result : récupérez le résultat. La réponse contient un lien signé, et non le fichier lui-même.

Réponse

application/json

Créer une traduction à partir d'un fichier

dataobjectrequired

Show child attributes

idstringrequired

namestringnullrequired

file_namestringnullrequired

statusstringrequired

État de la traduction. Les sept valeurs possibles: analyzing: la structure du fichier est lue, cela prend quelques secondes: effectuez un poll. awaiting_instructions: le fichier est lu, mais personne n'a indiqué quoi traduire: appelez plan. awaiting_approval: un plan attend une validation: appelez approve, le seul appel qui consomme des crédits. translating: exécution en cours: effectuez un poll. completed: récupérez le résultat. failed: l'exécution n'a pas pu se terminer: lisez error. cancelled: quelqu'un l'a arrêtée volontairement: état également terminal, et non un échec. Les trois derniers sont terminaux: arrêtez le polling.

quality_tierstringnullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstringnullrequired

completed_atstringnullrequired

next_actionstring

L'appel à effectuer ensuite, pour qu'un client n'ait jamais à mapper status lui-même. provide_instruction: appelez plan avec une instruction. review_plan: le plan chiffré est intégré: vérifiez plan.not_included, puis approuvez. wait: effectuez un nouveau poll: progress.estimated_seconds_remaining indique le temps restant. download: récupérez le résultat. read_error: l'exécution est terminée sans résultat: lisez error (et status indique s'il y a eu une erreur ou une annulation). Absent uniquement pour un lot CSV hérité antérieur au 2026-08-31, qui ne possède pas de plan: toute traduction créée depuis lors répond.

planobject | null

plan_revisionstring | null

suggested_instructionsstring[] | null

request_idstringrequired

Créer une traduction

Choisir comment envoyer le fichier

Réessayer sans risque

Étapes suivantes

Réponse

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown