batches

Crea una traduzione

Invia il file in uno di questi tre modi: JSON con content (il file come testo UTF-8, solo per formati testuali, è il percorso più semplice per gli agenti), JSON con file_url (HTTPS, recuperato lato server, senza reindirizzamenti) o multipart/form-data con un campo file (obbligatorio per XLSX e ZIP). filename è opzionale: se omesso, viene generato un nome predefinito pulito e il formato è dedotto automaticamente dal contenuto. Includi instruction per ricevere il piano completo e protetto nella stessa risposta (richiede alcuni secondi); omettila per ricevere quattro suggested_instructions basate sul contesto e procedi con l'endpoint plan. La qualità viene scelta al momento dell'approvazione, non qui: il piano indica i costi per entrambi i tier. I limiti di dimensione per formato sono disponibili in /v1/account come entitlements.max_upload_bytes_by_format. Il caricamento appare anche nella 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 '{
  "file_url": "<string>",
  "content": "<string>",
  "filename": "<string>",
  "instruction": "<string>"
}'

import json
import requests

url = "https://api.ai-glot.com/v1/batches"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"file_url\":\"<string>\",\"content\":\"<string>\",\"filename\":\"<string>\",\"instruction\":\"<string>\"}")

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({
    "file_url": "<string>",
    "content": "<string>",
    "filename": "<string>",
    "instruction": "<string>"
  }),
});

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, "{\"file_url\":\"<string>\",\"content\":\"<string>\",\"filename\":\"<string>\",\"instruction\":\"<string>\"}");
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("{\"file_url\":\"<string>\",\"content\":\"<string>\",\"filename\":\"<string>\",\"instruction\":\"<string>\"}")))
  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("{\"file_url\":\"<string>\",\"content\":\"<string>\",\"filename\":\"<string>\",\"instruction\":\"<string>\"}"))
    .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 = "{\"file_url\":\"<string>\",\"content\":\"<string>\",\"filename\":\"<string>\",\"instruction\":\"<string>\"}"

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": "<string>",
    "file_name": "<string>",
    "status": "analyzing",
    "quality_tier": "<string>",
    "word_count": 123,
    "credit_cost": 123,
    "is_sample": true,
    "archived": true,
    "progress": {
      "phase": "<string>",
      "percent": 123.45,
      "updated_at": "<string>",
      "estimated_seconds_remaining": 123
    },
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "created_at": "<string>",
    "completed_at": "<string>",
    "next_action": "provide_instruction",
    "plan": {
      "instruction": "<string>",
      "summary": "<string>",
      "will_translate": "<string>",
      "will_not_touch": "<string>",
      "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": {},
          "source_lang": {},
          "target_lang": {}
        }
      ],
      "cached": true
    },
    "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

Sono disponibili tre metodi di invio, e la scelta corretta dipende dal formato e non dalle preferenze.

Metodo di invio	Utilizzo	Note
JSON con `content`	Qualsiasi formato di testo	Il file stesso come testo UTF-8. La soluzione più semplice per un agente che ha già il contenuto in memoria.
JSON con `file_url`	Un file già ospitato	Solo HTTPS, recuperato lato server. I reindirizzamenti non vengono seguiti, quindi fornisci l’URL finale.
`multipart/form-data`	XLSX e ZIP	Obbligatorio per i formati binari: non possono essere inviati come testo JSON.

filename è facoltativo ma consigliato. L’estensione determina l’identificazione del formato, quindi un nome come strings.xml e uno come export.csv faranno intervenire parser diversi su byte identici.

Cosa succede dopo

La risposta restituisce un batch_id. Da qui la sequenza è sempre la stessa:

POST /v1/batches/{batch_id}/plan: descrivi cosa tradurre, con parole tue.
POST /v1/batches/{batch_id}/approve: scala i crediti e avvia la traduzione.
GET /v1/batches/{batch_id}: effettua il polling fino al completamento.
GET /v1/batches/{batch_id}/result: recupera il risultato. Restituisce un link firmato, non il file vero e proprio.

Risposta

application/json

Crea una traduzione da un file

dataobjectrequired

Show child attributes

idstringrequired

namestring | nullrequired

file_namestring | nullrequired

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_tierstring | nullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstring | nullrequired

completed_atstring | nullrequired

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

suggested_instructionsstring[] | null

request_idstringrequired

Crea una traduzione

Scegliere come inviare il file

Cosa succede dopo

Risposta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown