batches

Prepara o perfeziona il piano

Interazione in linguaggio naturale. Invia instruction per (ri)pianificare da zero, oppure refinement per regolare il piano corrente ("in realtà, solo le righe vuote"). La risposta include il piano ricostruito con i conteggi misurati e un'anteprima di 10 estratti reali. Nulla viene addebitato fino all'approvazione; controlla plan.not_included: una lista non vuota significa che parte dell'istruzione NON verrà eseguita.

POST/v1/batches/{batch_id}/plan

Request

curl --request POST \
  --url 'https://api.ai-glot.com/v1/batches/<batch_id>/plan' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "instruction": "<string>",
  "refinement": "<string>"
}'

import json
import requests

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

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

const response = await fetch("https://api.ai-glot.com/v1/batches/<batch_id>/plan", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "instruction": "<string>",
    "refinement": "<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/<batch_id>/plan");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"instruction\":\"<string>\",\"refinement\":\"<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/<batch_id>/plan", bytes.NewBuffer([]byte("{\"instruction\":\"<string>\",\"refinement\":\"<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/<batch_id>/plan"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"instruction\":\"<string>\",\"refinement\":\"<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/<batch_id>/plan")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"instruction\":\"<string>\",\"refinement\":\"<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. La pianificazione è gratuita e ripetibile: non viene addebitato nulla finché non effettui l’approvazione.

Istruzione o perfezionamento

Invia l’uno o l’altro, non entrambi.

Campo	Significato
`instruction`	Pianifica da zero. Sostituisce completamente qualsiasi piano precedente.
`refinement`	Modifica il piano già esistente: “in realtà, solo le righe vuote”, “non toccare gli URL”.

La distinzione è importante quando un piano è quasi corretto: refinement mantiene tutto ciò che hai già approvato, mentre instruction ricomincia da capo e potrebbe reinterpretare parti che andavano già bene.

Controlla il piano prima di approvare

La risposta include il piano rigenerato con i conteggi effettivi (il numero reale di elementi e parole individuati nel file, non una stima basata sulle dimensioni), oltre a un’anteprima di dieci estrazioni reali.

Questi dieci elementi rappresentano la verifica più economica a disposizione. Mostrano le stringhe esatte che verranno inviate per la traduzione, così un’istruzione che ha accidentalmente selezionato il campo sbagliato risulterà visibile prima di comportare qualsiasi costo.

Risposta

application/json

Prepara o perfeziona il piano di traduzione

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

Prepara o perfeziona il piano

Istruzione o perfezionamento

Controlla il piano prima di approvare

Risposta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown