batches

Crea una traduzione

Crea una traduzione usando una sola fonte: contenuto JSON per testo UTF-8 da mantenere invariato, JSON file_url per un download HTTPS senza reindirizzamenti, JSON upload_id per un caricamento temporaneo completato con queste stesse credenziali oppure multipart/form-data con un campo file per i byte binari locali. Se usi upload_id, ometti filename: il nome è già associato alla sessione. Se ripeti un upload_id, viene restituito il batch esistente senza modificarne l’istruzione. Per le altre fonti, invia un header Idempotency-Key (da 1 a 255 caratteri stampabili, va bene un UUID) per poter ripetere la richiesta in sicurezza se la risposta va persa: la richiesta ripetuta restituisce il batch creato al primo tentativo, senza recuperare o archiviare di nuovo il file né ripetere la pianificazione. Se la stessa chiave viene usata con contenuti diversi, la richiesta viene rifiutata con 409 idempotency_key_reused. Negli altri casi, filename è facoltativo e, se non specificato, viene dedotto. Includi instruction per ricevere il piano verificato, i conteggi misurati, il costo in crediti e un’anteprima dell’estrazione; omettilo per ricevere suggested_instructions. Controlla plan.not_included prima di approvare. La creazione e la pianificazione non costano crediti. I limiti per formato sono indicati in GET /v1/account. La traduzione appare nell’app 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>"
}

Richiede batches:create. Creare una traduzione non costa nulla: i crediti vengono riservati solo quando approvi un piano.

Scegliere come inviare il file

Scegli il metodo di trasferimento più adatto alla posizione del documento e alle funzionalità del client.

Metodo di trasferimento	Da usare per	Note
JSON con `upload_id`	Un file locale inviato tramite una sessione di caricamento temporaneo	Usa le stesse credenziali con cui hai creato la sessione. Ometti `filename`. Se ripeti la richiesta, viene restituita la traduzione esistente senza modificarne le istruzioni.
JSON con `content`	Qualsiasi formato di testo	Il file stesso come testo UTF-8. È il metodo più semplice per un agente che ha già il contenuto in memoria.
JSON con `file_url`	Un file già ospitato online	Solo HTTPS, recuperato dal server. I reindirizzamenti non vengono seguiti, quindi fornisci l’URL finale.
`multipart/form-data`	File binari locali, inclusi XLSX, DOCX, PPTX, PDF, IDML e ZIP	Invia i byte originali nel campo `file`. È il metodo di trasferimento per file locali della CLI.

filename è facoltativo, ma è consigliabile specificarlo. Il formato viene identificato in base all’estensione, quindi nomi come strings.xml ed export.csv attivano parser diversi anche se i byte sono identici.

Ripetere la richiesta in sicurezza

Invia un’intestazione Idempotency-Key (da 1 a 255 caratteri stampabili; un UUID è una buona scelta), così un nuovo tentativo dopo una risposta persa restituisce la traduzione creata dal primo tentativo, invece di crearne una seconda. La richiesta ripetuta riceve risposta prima che il file venga recuperato o archiviato e non avvia di nuovo la pianificazione, quindi non costa nulla. La chiave è associata ai dati inviati: se riutilizzi la stessa chiave con un file, un nome o un’istruzione diversi, la richiesta viene rifiutata con idempotency_key_reused. Usa una nuova chiave per una nuova attività. Se non puoi usare intestazioni (strumenti MCP, Code Mode), passa idempotency_key nel corpo della richiesta. Se la creazione include un’instruction, la risposta restituisce plan_revision insieme al piano: passalo come expected_plan_revision quando approvi.

Passaggi successivi

La risposta fornisce un id, da usare come batch_id nei percorsi successivi. La sequenza è sempre la stessa:

POST /v1/batches/{batch_id}/plan: descrivi cosa tradurre, con parole tue.
POST /v1/batches/{batch_id}/approve: usa i crediti e avvia la traduzione.
GET /v1/batches/{batch_id}: controlla lo stato finché l’elaborazione non è terminata.
GET /v1/batches/{batch_id}/result: recupera il risultato. Restituisce un link firmato, non il file stesso.

Risposta

application/json

Crea una traduzione da un file

dataobjectrequired

Show child attributes

idstringrequired

namestringnullrequired

file_namestringnullrequired

statusstringrequired

Stato della traduzione. I sette valori possibili: analyzing: la struttura del file è in fase di lettura, operazione che richiede pochi secondi; effettua il polling. awaiting_instructions: il file è stato letto, ma non è stato specificato cosa tradurre; chiama l'endpoint plan. awaiting_approval: un piano è in attesa di conferma; chiama approve, l'unica operazione che consuma crediti. translating: in corso; effettua il polling. completed: recupera il risultato. failed: l'esecuzione non è stata completata; leggi error. cancelled: l'esecuzione è stata interrotta deliberatamente; è uno stato terminale e non rappresenta un errore. Gli ultimi tre sono stati terminali: interrompi il polling.

quality_tierstringnullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstringnullrequired

completed_atstringnullrequired

next_actionstring

La chiamata successiva da effettuare, così che il client non debba mappare autonomamente lo status. provide_instruction: chiama plan con un'istruzione. review_plan: il piano con i relativi costi è incorporato; controlla plan.not_included, poi approva. wait: effettua nuovamente il polling; progress.estimated_seconds_remaining indica il tempo rimanente. download: recupera il risultato. read_error: l'esecuzione è terminata senza un risultato; leggi error (e status indica se è avvenuto un errore o se è stata cancellata). Assente solo nei batch CSV legacy precedenti al 2026-08-31, che non hanno un piano associato; ogni traduzione creata da tale data risponde.

planobject | null

plan_revisionstring | null

suggested_instructionsstring[] | null

request_idstringrequired

Crea una traduzione

Scegliere come inviare il file

Ripetere la richiesta in sicurezza

Passaggi successivi

Risposta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown