batches

Crear una traducción

Crea una traducción usando exactamente una fuente: contenido JSON para texto UTF-8 literal, JSON file_url para una descarga HTTPS sin redirecciones, JSON upload_id para una carga temporal completada con estas mismas credenciales, o multipart/form-data con un campo file para bytes binarios locales. Omite filename con upload_id: la sesión ya tiene asignado el nombre. Si repites un upload_id, se devuelve el lote existente sin cambiar sus instrucciones. Envía una cabecera Idempotency-Key (de 1 a 255 caracteres imprimibles; puede ser un UUID) con las demás fuentes para que sea seguro reintentar si se pierde la respuesta: al repetir la solicitud, se devuelve el lote creado en el primer intento, sin volver a descargar ni almacenar el archivo ni planificarlo de nuevo. Si la misma clave se usa con contenido distinto, se rechaza con 409 idempotency_key_reused. En los demás casos, filename es opcional y se deduce si se omite. Incluye instruction para recibir el plan verificado, el recuento medido, el coste en créditos y una vista previa de la extracción. Si lo omites, recibirás suggested_instructions. Comprueba plan.not_included antes de aprobar. Crear y planificar no cuesta créditos. Consulta los límites por formato en GET /v1/account. La traducción aparece en la aplicación 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>"
}

Requiere batches:create. Crear una traducción no cuesta nada: los créditos solo se reservan al aprobar un plan.

Cómo enviar el archivo

Elige el método de envío que mejor se adapte a dónde está el documento y a las capacidades de tu cliente.

Método	Cuándo usarlo	Notas
JSON con `upload_id`	Para un archivo local enviado mediante una sesión de carga temporal	Usa las mismas credenciales con las que creaste la sesión. Omite `filename`. Si repites la solicitud, se devuelve la traducción existente sin cambiar sus instrucciones.
JSON con `content`	Para cualquier formato de texto	El archivo como texto UTF-8. Es la opción más sencilla para un agente que ya tiene el contenido en memoria.
JSON con `file_url`	Para un archivo alojado	Solo HTTPS; se obtiene desde el servidor. No se siguen las redirecciones, así que proporciona la URL final.
`multipart/form-data`	Para archivos binarios locales, incluidos XLSX, DOCX, PPTX, PDF, IDML y ZIP	Envía los bytes originales en el campo `file`. Es el método que usa la CLI para enviar archivos locales.

filename es opcional, pero conviene incluirlo. La extensión permite identificar el formato, así que strings.xml y export.csv se procesan con analizadores distintos aunque contengan los mismos bytes.

Cómo repetir una solicitud de forma segura

Envía una cabecera Idempotency-Key (de 1 a 255 caracteres imprimibles; un UUID es una buena opción) para que, si repites la solicitud tras perderse la respuesta, se devuelva la traducción creada en el primer intento en vez de crear otra. La solicitud repetida se responde antes de obtener o almacenar el archivo y no vuelve a generar un plan, por lo que no cuesta nada. La clave queda asociada a lo que enviaste: si usas la misma clave con otro archivo, nombre o instrucción, la solicitud se rechaza con idempotency_key_reused. Usa una clave nueva para cada nuevo trabajo. Si no puedes enviar cabeceras (herramientas MCP, Code Mode), incluye idempotency_key en el cuerpo. Si creas la traducción con una instruction, la respuesta incluye plan_revision junto con el plan. Envíalo como expected_plan_revision al aprobarlo.

Qué ocurre a continuación

La respuesta incluye un id, que se utiliza como batch_id en las rutas posteriores. A partir de ahí, la secuencia es siempre la misma:

POST /v1/batches/{batch_id}/plan: describe con tus propias palabras qué quieres traducir.
POST /v1/batches/{batch_id}/approve: consume créditos e inicia el proceso.
GET /v1/batches/{batch_id}: consulta el estado hasta que termine.
GET /v1/batches/{batch_id}/result: descarga el resultado. Devuelve un enlace firmado, no el archivo.

Respuesta

application/json

Crear una traducción a partir de un archivo

dataobjectrequired

Show child attributes

idstringrequired

namestringnullrequired

file_namestringnullrequired

statusstringrequired

Ubicación de la traducción. Los siete valores posibles: analyzing: se está leyendo la estructura del archivo, lo que tarda segundos; haga polling. awaiting_instructions: el archivo ha sido leído, pero nadie ha indicado qué traducir; llame a plan. awaiting_approval: un plan espera confirmación; llame a approve, la única llamada que consume créditos. translating: en ejecución; haga polling. completed: recupere el resultado. failed: la ejecución no pudo finalizar; lea error. cancelled: alguien la detuvo deliberadamente; también es un estado terminal y no es un fallo. Los tres últimos son terminales: deje de hacer polling.

quality_tierstringnullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstringnullrequired

completed_atstringnullrequired

next_actionstring

La siguiente llamada a realizar, para que el cliente no tenga que mapear el status por sí mismo. provide_instruction: llame a plan con una instrucción. review_plan: el plan con precio está embebido; revise plan.not_included y luego apruebe. wait: haga polling de nuevo; progress.estimated_seconds_remaining indica el tiempo restante. download: recupere el resultado. read_error: la ejecución terminó sin resultado; lea error (y status indica si falló o fue cancelada). Solo ausente en lotes CSV antiguos anteriores al 2026-08-31 que no tienen un plan asociado; todas las traducciones creadas desde entonces responden.

planobject | null

plan_revisionstring | null

suggested_instructionsstring[] | null

request_idstringrequired

Crear una traducción

Cómo enviar el archivo

Cómo repetir una solicitud de forma segura

Qué ocurre a continuación

Respuesta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown