batches

Übersetzung erstellen

Erstelle eine Übersetzung mit genau einer Quelle: JSON-Inhalt für unveränderten UTF-8-Text, JSON file_url für einen HTTPS-Download ohne Weiterleitungen, JSON upload_id für einen abgeschlossenen temporären Upload mit denselben Zugangsdaten oder multipart/form-data mit einem file-Feld für lokale Binärdaten. Lass filename bei upload_id weg. Die Sitzung enthält den Dateinamen bereits. Bei einer Wiederholung mit derselben upload_id wird der vorhandene Batch zurückgegeben, ohne seine Anweisung zu ändern. Sende bei den anderen Quellen einen Idempotency-Key-Header (1 bis 255 druckbare Zeichen, eine UUID ist geeignet), damit ein erneuter Versuch nach einer verlorenen Antwort sicher ist: Bei einer Wiederholung wird der beim ersten Versuch erstellte Batch zurückgegeben, ohne die Datei erneut abzurufen oder zu speichern oder die Planung zu wiederholen. Derselbe Schlüssel mit anderem Inhalt wird mit 409 idempotency_key_reused abgelehnt. Andernfalls ist filename optional und wird, falls nicht angegeben, automatisch ermittelt. Gib instruction an, um den geprüften Plan, die ermittelten Mengen, die Credit-Kosten und eine Extraktionsvorschau zu erhalten. Wenn du instruction weglässt, erhältst du suggested_instructions. Prüfe vor der Freigabe plan.not_included. Erstellen und Planen kosten keine Credits. Die Limits pro Format findest du unter GET /v1/account. Die Übersetzung erscheint in der 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 '{
  "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>"
}

Erfordert batches:create. Das Erstellen einer Übersetzung ist kostenlos: Credits werden erst reserviert, wenn Sie einen Plan freigeben.

Übertragungsart auswählen

Wählen Sie die Übertragungsart passend dazu, wo sich das Dokument befindet und welche Möglichkeiten Ihr Client bietet.

Übertragungsart	Geeignet für	Hinweise
JSON mit `upload_id`	Eine lokale Datei, die über eine temporäre Upload-Sitzung gesendet wird	Verwenden Sie dieselben Zugangsdaten, mit denen die Sitzung erstellt wurde. Lassen Sie `filename` weg. Bei wiederholtem Aufruf wird die vorhandene Übersetzung zurückgegeben, ohne ihre Anweisung zu ändern.
JSON mit `content`	Text in beliebigem Format	Die Datei selbst als UTF-8-Text. Der einfachste Weg für einen Agenten, der den Inhalt bereits im Arbeitsspeicher hat.
JSON mit `file_url`	Eine bereits gehostete Datei	Nur HTTPS; der Abruf erfolgt serverseitig. Weiterleitungen werden nicht verfolgt. Geben Sie daher die endgültige URL an.
`multipart/form-data`	Lokale Binärdateien, darunter XLSX, DOCX, PPTX, PDF, IDML und ZIP	Senden Sie die Originalbytes im Feld `file`. Dies ist die Übertragungsart der CLI für lokale Dateien.

filename ist optional, aber empfehlenswert. Das Format wird anhand der Dateiendung erkannt. Daher führen Namen wie strings.xml und export.csv bei identischen Bytes zu unterschiedlichen Parsern.

Wiederholungsversuche sicher ausführen

Senden Sie einen Idempotency-Key-Header (beliebiger Wert aus 1 bis 255 druckbaren Zeichen; eine UUID ist eine gute Wahl). So wird bei einem erneuten Versuch nach einer verlorenen Antwort die Übersetzung zurückgegeben, die beim ersten Versuch erstellt wurde, statt eine zweite anzulegen. Eine Wiederholung wird beantwortet, bevor die Datei abgerufen oder gespeichert wird, und löst keine erneute Planung aus. Sie ist also kostenlos. Der Schlüssel ist an die übermittelten Daten gebunden: Wird derselbe Schlüssel mit einer anderen Datei, einem anderen Namen oder einer anderen Anweisung verwendet, wird die Anfrage mit idempotency_key_reused abgelehnt. Verwenden Sie für neue Aufträge einen neuen Schlüssel. Wenn keine Header verfügbar sind (MCP-Tools, Code Mode), übergeben Sie idempotency_key im Body. Bei einer Erstellung mit instruction wird plan_revision zusammen mit dem Plan zurückgegeben. Übergeben Sie diesen Wert als expected_plan_revision, wenn Sie den Plan freigeben.

Wie geht es weiter?

Die Antwort enthält eine id, die in den folgenden Pfaden als batch_id verwendet wird. Danach ist die Reihenfolge immer gleich:

POST /v1/batches/{batch_id}/plan: Beschreiben Sie in eigenen Worten, was übersetzt werden soll.
POST /v1/batches/{batch_id}/approve: Credits verwenden und den Vorgang starten.
GET /v1/batches/{batch_id}: Rufen Sie den Status ab, bis der Vorgang abgeschlossen ist.
GET /v1/batches/{batch_id}/result: Ergebnis abrufen. Zurückgegeben wird ein signierter Link, nicht die Datei selbst.

Antwort

application/json

Übersetzung aus einer Datei erstellen

dataobjectrequired

Show child attributes

idstringrequired

namestringnullrequired

file_namestringnullrequired

statusstringrequired

Der aktuelle Status der Übersetzung. Alle sieben Werte: analyzing - die Dateistruktur wird gelesen, was einige Sekunden dauert; Polling durchführen. awaiting_instructions - die Datei wurde gelesen, aber es wurde noch nicht festgelegt, was übersetzt werden soll; plan-Call ausführen. awaiting_approval - ein Plan wartet auf die Zustimmung; approve-Call ausführen, der einzige Aufruf, der Credits verbraucht. translating - läuft; Polling durchführen. completed - Ergebnis abrufen. failed - der Durchlauf konnte nicht abgeschlossen werden; error lesen. cancelled - jemand hat den Vorgang absichtlich gestoppt; ebenfalls ein Endzustand und kein Fehler. Die letzten drei sind Endzustände: Polling beenden.

quality_tierstringnullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstringnullrequired

completed_atstringnullrequired

next_actionstring

Der nächste auszuführen Call, sodass ein Client status nicht selbst zuordnen muss. provide_instruction - plan-Call mit einer Anweisung ausführen. review_plan - der bepreiste Plan ist eingebettet; plan.not_included prüfen, dann genehmigen. wait - erneut pollen; progress.estimated_seconds_remaining gibt die verbleibende Zeit an. download - Ergebnis abrufen. read_error - der Durchlauf ist ohne Ergebnis beendet; error lesen (und status gibt an, ob er abgebrochen wurde oder fehlgeschlagen ist). Fehlt nur bei einem veralteten CSV-Batch vor dem 2026-08-31, der keinen Plan besitzt; jede seitdem erstellte Übersetzung antwortet.

planobject | null

plan_revisionstring | null

suggested_instructionsstring[] | null

request_idstringrequired

Übersetzung erstellen

Übertragungsart auswählen

Wiederholungsversuche sicher ausführen

Wie geht es weiter?

Antwort

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown