API-Beispiele

Version

API

Route

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

Parameter

Parameter	Erforderlich	Typ	Beschreibung
`image`	Ja	file[]	Eine oder mehrere Bilddateien oder ein ZIP-Archiv
`source_language`	Nein	string	Optional; beim Modell manga erforderlich (z. B. ja)
`target_language`	Ja	string	Zielsprachcode (z. B. en)
`model`	Nein	string	Erkennungsmodell; weglassen, um den API-Standard zu verwenden
`font`	Nein	string	Schriftstil; weglassen, um den API-Standard zu verwenden

Parameter	Erforderlich	Typ	Beschreibung
`Idempotency-Key`	Ja	HTTP header	Header der Vorbereitungsanfrage: stabiler Schlüssel für sichere Wiederholungen derselben Dateiliste innerhalb von 8 Stunden
`platform`	Nein	string \| null	Vorbereitungs- und Abschlussanfrage: optionale, selbst angegebene Plattformbezeichnung nur für die API-Aufrufprüfung
`files[]`	Ja	array<object>	Vorbereitungsanfrage: Dateimetadaten mit filename, content_type, size und content_sha256
`upload_id`	Ja	string	Abschlussanfrage: undurchsichtige Upload-Batch-ID aus der Vorbereitung
`files[].index files[].upload_intent`	Ja	integer string	Abschlussanfrage: index und undurchsichtiges upload_intent je Datei aus der Vorbereitung; erst nach jedem abgeschlossenen R2-Upload senden
`source_language`	Nein	string	Optional; beim Modell manga erforderlich (z. B. ja)
`target_language`	Ja	string	Zielsprachcode (z. B. en)
`model`	Nein	string	Erkennungsmodell; weglassen, um den API-Standard zu verwenden
`font`	Nein	string	Schriftstil; weglassen, um den API-Standard zu verwenden

Parameter	Erforderlich	Typ	Beschreibung
`batch_id`	Ja	string	Stapelkennung zur Abfrage des Aufgabenstatus

Parameter	Erforderlich	Typ	Beschreibung
Keine Parameter

Antwortparameter

Feld	Typ	Beschreibung
`task_id`	string	Aufgabenkennung
`batch_id`	string	Stapelkennung zur Abfrage des Aufgabenstatus

Feld	Typ	Beschreibung
`status`	integer	Anwendungsstatuscode; bei Erfolg 200
`cost_ms`	integer	Dauer der Verarbeitung dieser API-Anfrage in Millisekunden
`request_id`	string	Anfragekennung zur Nachverfolgung dieses API-Aufrufs
`data`	object	Nach Annahme der Anfrage zurückgegebene Übersetzungsaufgabenkennungen
`message`	string	Bei einer erfolgreichen API-Antwort immer success; dies bedeutet nicht, dass die Übersetzungsaufgabe abgeschlossen ist
`data.task_id`	string	Aufgabenkennung
`data.batch_id`	string	Stapelkennung zur Abfrage des Aufgabenstatus

Feld	Typ	Beschreibung
`status_code`	integer	Bei einer erfolgreichen Task-Status-Antwort immer 200
`request_id`	string	Anfragekennung zur Nachverfolgung dieses API-Aufrufs
`auth_type`	string	Bei einer PAT-authentifizierten Task-Status-Anfrage immer account
`task_reference`	string	Die batch_id aus dem Anfragepfad, unverändert zurückgegeben
`data`	object	Datenobjekt für Ergebnisse pro Bild und den Gesamtstatus der Aufgabe
`data.items`	array<object>	Array mit Aufgabenergebnissen pro Bild
`data.items[].image_id`	string	Stabile Kennung des Bildergebnisses
`data.items[].index`	integer	Nullbasierte Position des Bildes im Stapel
`data.items[].filename`	string	Ursprünglicher Bilddateiname
`data.items[].status`	string	Status des Bildergebnisses (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	URL des Quellbildes; sie ist für aktuell über die API erstellte Aufgaben verfügbar.
`data.items[].translated_url`	string	URL des übersetzten Bildes; bis ein Ergebnis verfügbar ist, ist sie eine leere Zeichenfolge, auch bei ausstehenden, laufenden oder fehlgeschlagenen Bildern.
`data.items[].is_translated`	boolean	Nur true, wenn eine abgeschlossene übersetzte Bild-URL verfügbar ist
`data.items[].output_file_path`	string	Kompatibilitätsalias für translated_url; eine leere Zeichenfolge, wenn kein übersetztes Bild verfügbar ist.
`data.items[].message`	string \| null	Optionale Infomeldung
`data.items[].error`	string \| null	Fehlerdetails bei fehlgeschlagener Bildaufgabe; andernfalls null
`data.items[].inpaint_image_url`	string \| null	URL des Bildes mit entferntem Text oder null, wenn das gewählte Modell bzw. der Ausführungspfad keines erzeugt.
`data.items[].block_json`	array<object>	In V1 beibehaltene strukturierte Textblöcke; kann leer sein, wenn das Modell oder der Ausführungspfad keine Blockmetadaten liefert.
`data.task_status`	string	Gesamtstatus der Aufgabe (pending \| processing \| completed \| failed \| canceled)

Feld	Typ	Beschreibung
`status`	integer	Anwendungsstatuscode; bei Erfolg 200
`cost_ms`	integer	Laufzeit der Aufgabe in Millisekunden; 0, wenn gültige Aufgabenzeitstempel fehlen
`request_id`	string	Anfragekennung zur Nachverfolgung dieses API-Aufrufs
`data`	array<object>	Array kompakter Ergebnisse pro Bild
`message`	string	Bei einer erfolgreichen API-Antwort immer success; dies bedeutet nicht, dass die Übersetzungsaufgabe abgeschlossen ist
`data[].image_id`	string	Stabile Kennung des Bildergebnisses
`data[].filename`	string	Ursprünglicher Bilddateiname
`data[].status`	string	Status des Bildergebnisses (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	URL des Quellbildes; sie ist für aktuell über die API erstellte Aufgaben verfügbar.
`data[].translated_url`	string	URL des übersetzten Bildes; bis ein Ergebnis verfügbar ist, ist sie eine leere Zeichenfolge, auch bei ausstehenden, laufenden oder fehlgeschlagenen Bildern.
`data[].erased_url`	string	URL des Bildes mit entferntem Text; kann eine leere Zeichenfolge sein. Modelle oder Ausführungspfade, die nur ein fertiges Bild zurückgeben, etwa Manga mit dem Auto-Fertigbildpfad, erzeugen sie nicht.
`data[].blocks`	array<object>	Strukturierte übersetzte Textblöcke; kann leer sein, wenn das Modell oder der Ausführungspfad keine Blockmetadaten liefert, etwa Manga mit dem Auto-Fertigbildpfad.
`data[].blocks[].angle`	number	Drehwinkel des Textblocks
`data[].blocks[].color`	string	Hexadezimalfarbe des übersetzten Textes
`data[].blocks[].handwritten`	boolean	Ob der Ausgangstext als handschriftlich erkannt wurde
`data[].blocks[].location`	object	Begrenzung des Textblocks durch vier Eckpunkte
`data[].blocks[].location.left_bottom`	array<number>	Koordinatenpaar der bezeichneten Ecke
`data[].blocks[].location.right_bottom`	array<number>	Koordinatenpaar der bezeichneten Ecke
`data[].blocks[].location.left_top`	array<number>	Koordinatenpaar der bezeichneten Ecke
`data[].blocks[].location.right_top`	array<number>	Koordinatenpaar der bezeichneten Ecke
`data[].blocks[].text`	string	Für den Block gerenderter Übersetzungstext
`data[].blocks[].direction`	string	Schreibrichtung des übersetzten Textes

Feld	Typ	Beschreibung
`subscription_credits`	integer	Guthaben der bezeichneten Kategorie
`subscription_credits_expires_at`	string \| null	Ablaufzeit des Abonnementguthabens im ISO-8601-Format oder null
`one_time_credits`	integer	Guthaben der bezeichneten Kategorie
`one_time_credits_expires_at`	string \| null	Ablaufzeit des Einmalguthabens im ISO-8601-Format oder null
`free_credits`	integer	Guthaben der bezeichneten Kategorie
`total_credits`	integer	Summe aller verfügbaren Guthaben
`is_temporary`	boolean	Ob das Guthaben zu einem temporären Konto gehört

Feld	Typ	Beschreibung
`status`	integer	Anwendungsstatuscode; bei Erfolg 200
`cost_ms`	integer	Dauer der Verarbeitung dieser API-Anfrage in Millisekunden
`request_id`	string	Anfragekennung zur Nachverfolgung dieses API-Aufrufs
`data`	object	Container für die aktuellen Guthabenstände
`message`	string	Bei einer erfolgreichen API-Antwort immer success; dies bedeutet nicht, dass die Übersetzungsaufgabe abgeschlossen ist
`data.total_credits`	integer	Summe aller verfügbaren Guthaben
`data.is_temporary`	boolean	Ob das Guthaben zu einem temporären Konto gehört
`data.detail`	object	Aufschlüsselung der verfügbaren Guthaben nach Kategorie
`data.detail.subscription`	object	Guthaben und Ablaufzeit der jeweiligen Kategorie
`data.detail.subscription.credits`	integer	Guthaben der bezeichneten Kategorie
`data.detail.subscription.expires_at`	string \| null	Ablaufzeit des Guthabens im ISO-8601-Format oder null
`data.detail.one_time`	object	Guthaben und Ablaufzeit der jeweiligen Kategorie
`data.detail.one_time.credits`	integer	Guthaben der bezeichneten Kategorie
`data.detail.one_time.expires_at`	string \| null	Ablaufzeit des Guthabens im ISO-8601-Format oder null
`data.detail.free`	object	Guthaben und Ablaufzeit der jeweiligen Kategorie
`data.detail.free.credits`	integer	Guthaben der bezeichneten Kategorie
`data.detail.free.expires_at`	null	Immer null, da dieser aggregierte Endpunkt keine einheitliche Ablaufzeit für kostenloses Guthaben liefert

Beispielantwort (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

Beispielantwort (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

Beispielantwort (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

Beispielantwort (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

Beispielantwort (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

Beispielantwort (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

Parameter der Fehlerantwort

Bei V2-Fehlern bleibt der HTTP-Status erhalten und derselbe Umschlag mit fünf Feldern wird zurückgegeben.

Feld	Typ	Beschreibung
`status`	integer	Tatsächlicher HTTP-Fehlerstatuscode
`cost_ms`	integer	Dauer der Verarbeitung dieser API-Anfrage in Millisekunden
`request_id`	string	Anfragekennung zur Nachverfolgung dieses API-Aufrufs
`data`	object	Leerer Fehlerdatencontainer, der nur den stabilen maschinenlesbaren Code enthält
`message`	string	Öffentliche Fehlermeldung; interne Diagnosedetails werden nicht offengelegt
`data.code`	string	Stabiler maschinenlesbarer Fehlercode

Beispiel für eine Fehlerantwort (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

Beispieleingaben

API-Schlüssel

Quellsprache

Zielsprache

Modell

Schrift

API-Beispiele

Route

Parameter

Antwortparameter

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Parameter der Fehlerantwort

Beispiel für eine Fehlerantwort (JSON)

Beispieleingaben

Python3-Beispiel

cURL-Beispiele

Python3-Beispiel

cURL

Python3-Beispiel

cURL

Route

Parameter

Antwortparameter

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Beispielantwort (JSON)

Parameter der Fehlerantwort

Beispiel für eine Fehlerantwort (JSON)

Beispieleingaben

Python3-Beispiel

cURL-Beispiele

Python3-Beispiel

cURL

Python3-Beispiel

cURL

Cookie-Einstellungen