Tutorial

HiAPI Bild-Eingabefehler: Übergib eine öffentlich erreichbare URL, nicht Base64

Oct 22, 2026

Die Image-to-Image- und Referenzbild-Modelle auf HiAPI holen dein Quellbild von einer öffentlich erreichbaren HTTP(S)-URL – sie akzeptieren keine Base64-Byte-Strings und können auch keine privaten Adressen abrufen. Die häufigste Falle: Eine fehlerhafte Bild-Eingabe sieht aus, als wäre sie erfolgreich – POST /v1/tasks gibt 200 mit einer taskId zurück, und der eigentliche Fehler zeigt sich erst, wenn du den Task abfragst. Die zwei Fehler, die du tatsächlich zu sehen bekommst, sehen so aus:

{ "code": 200, "message": "success",
  "data": { "status": "fail", "model": "gpt-image-2/image-to-image", "storage": "temp", "taskId": "tk-...",
    "error": { "code": "INVALID_REQUEST",
      "message": "The image URL could not be downloaded. Please provide a reachable public HTTP(S) URL and try again." } } }

{ "code": 200, "message": "success",
  "data": { "status": "fail", "model": "gpt-image-2/image-to-image", "storage": "temp", "taskId": "tk-...",
    "error": { "code": "TASK_FAILED", "message": "task failed" } } }

Der erste Fall ist die Antwort bei einer nicht erreichbaren URL; der zweite ist das generische Ergebnis, wenn du eine Base64-Data-URI als Bild übergibst – ohne jeden Hinweis, nur ein task failed, und genau hier hängen die meisten fest. Beachte, dass das äußere "message": "success" nur bedeutet, dass die Polling-Anfrage selbst erfolgreich war; das eigentliche Ergebnis steht in data.status.

Häufige Ursachen (nach Trefferwahrscheinlichkeit absteigend)

Du hast Base64 in das Bildfeld eingefügt – eine Zeichenkette data:image/...;base64,.... Dieses Feld erwartet eine URL, die der Server abrufen kann, keine Inline-Bytes. Bei gpt-image-2/image-to-image wird eine Data-URI beim Absenden akzeptiert, danach endet der Task mit status: fail und dem Fehlercode TASK_FAILED / task failed.
Die URL ist nicht öffentlich erreichbar. http://localhost, 127.0.0.1, interne IPs, Dateien, die eine Anmeldung erfordern, sowie abgelaufene Pre-Signed-Links scheitern alle mit INVALID_REQUEST – "The image URL could not be downloaded…".
Falscher Feldname (unterschiedlich je nach Modell, siehe Tabelle unten). Das Feld für die Bild-Eingabe ist über die Modellfamilien hinweg nicht einheitlich. Ein falscher Name wird bereits beim Absenden mit HTTP 400 abgelehnt, z. B. wenn du bei gpt-image-2/image-to-image fälschlich image_url verwendest:
```
{ "code": 400, "data": null, "error_code": "INVALID_REQUEST",
  "message": "invalid input: input_urls: missing required field \"input_urls\"; <root>: additional properties 'image_url' not allowed" }
```
Du hast eine nackte Model-ID für die Bearbeitung verwendet. Eine nackte ID (z. B. gpt-image-2) ist reine Text-zu-Bild-Generierung und definiert gar kein Bildfeld, daher wird das Bildfeld abgelehnt: 400 invalid input: <root>: additional properties 'input_urls' not allowed. Für die Bearbeitung musst du die Image-to-Image-Routen-ID verwenden: gpt-image-2/image-to-image.

Fehlercodes lesen: „Eingabeproblem" oder „Upstream-Problem" lokalisieren

Betrachte die Antwort in zwei Teilen: Absende-Phase (die direkte Antwort auf POST /v1/tasks) und Endzustand (das data.status, das du beim Abfragen von GET /v1/tasks/<taskId> erhältst):

Absende-Phase HTTP 400, flacher Envelope {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."} → deine Anfrage-Struktur/dein Feld ist fehlerhaft (Eingabeproblem). Der Task wurde noch nicht angelegt, es wird nicht abgerechnet. Korrigiere den Feldnamen oder die Model-ID.
Absende-Phase HTTP 401, verschachtelter Envelope {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} → das ist ein Authentifizierungsproblem (falscher Key oder fehlende Berechtigung), kein Eingabeproblem.
Absende-Phase HTTP 200 + taskId, aber beim Polling data.status: "fail": sieh dir data.error.code an –
- INVALID_REQUEST und message "could not be downloaded" → die Bild-URL ist nicht abrufbar (weiterhin dein Eingabeproblem: ersetze das Bild durch eine öffentlich erreichbare URL).
- TASK_FAILED und message "task failed" → generischer Fehler, ohne Hinweis. Schließe zuerst Base64 / fehlerhafte Eingaben aus; schlägt es danach weiterhin fehl, behandle es als Problem der „Upstream-Generierung".

Mit einem Satz: Ein 4xx in der Absende-Phase ist ein Problem auf Anfrage-/Authentifizierungsebene; erst ein fail im Endzustand kann Download oder Upstream-Generierung betreffen; und in jedem Fall lass dich nicht vom äußeren "message":"success" täuschen – maßgeblich ist immer data.status.

Der Feldname für die Bild-Eingabe variiert je nach Modell

Die folgende Tabelle wurde anhand des aktuellen input-Schemas der jeweiligen Modelle überprüft (halte dich trotzdem stets an die Modellseite, die Felder unterscheiden sich je nach Familie):

Model-ID (Image-to-Image-Route)	Bild-Eingabefeld	Typ
`gpt-image-2/image-to-image`	`input_urls`	String-Array
`seedream-5.0-pro/image-to-image`	`image_urls`	String-Array
`nano-banana-pro`	`image_input`	String-Array

Das Feld gehört in das input-Objekt; die meisten Referenzbild-Modelle erwarten ein Array (auch wenn es nur ein Bild ist).

Schritte zur Behebung

Hoste das Bild auf einer öffentlich erreichbaren HTTP(S)-URL. Lade es in einen beliebigen Objektspeicher / CDN hoch (Cloudflare R2, S3, GCS usw.) und setze das Objekt auf öffentlich lesbar, oder verwende eine noch gültige Pre-Signed-URL.
Stelle sicher, dass es ohne Authentifizierung erreichbar ist. Führe in einer sauberen Sitzung (oder auf einem anderen Rechner als deinem lokalen) curl -sI "<deineURL>" aus; es sollte 200 zurückgeben mit content-type image/*. Wenn Cookies, Header oder VPN erforderlich sind, kann der Server es nicht abrufen.
Verwende die Image-to-Image-Model-ID, nicht die nackte ID. Für die Bearbeitung rufst du gpt-image-2/image-to-image auf (oder die entsprechende i2i-Route deines Modells), nicht gpt-image-2.
Verwende den Feldnamen aus der Dokumentation des jeweiligen Modells (input_urls / image_urls / image_input) und lege ihn in input ab.
Übergib niemals Base64. Wenn du nur Bytes hast, lade sie zuerst hoch und übergib dann die erhaltene URL.
Erst absenden, dann pollen. GET /v1/tasks/<taskId>, bis data.status gleich success oder fail ist. Lies bei einem Fehler data.error.message – erscheint "could not be downloaded", liegt das Problem an der URL, nicht an deinem Prompt.

Minimales Verifikationsbeispiel

Mach zuerst einen kostenlosen Konnektivitätstest: Das Auflisten der Modelle legt keinen Task an und kostet nichts.

curl -s https://api.hiapi.ai/v1/models \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Eine 200-Antwort mit einem data-Array bedeutet, dass dein Key funktioniert. Ein ungültiger Key liefert 401 + {"error":{"code":"permission_denied", ... ,"type":"hiapi_error"}} – das ist ein Authentifizierungsproblem, kein Eingabeproblem. Sende anschließend eine korrekte Image-to-Image-Anfrage: Setze im Modellfeld eine öffentlich erreichbare URL.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "input": {
      "prompt": "Ersetze den Hintergrund durch ein sauberes Studioweiß",
      "input_urls": ["https://your-public-host.example.com/source.png"]
    }
  }'

Ersetze input_urls durch die URL deines eigenen erreichbaren Bildes. Bei erfolgreichem Absenden wird data.taskId zurückgegeben; poll dann GET https://api.hiapi.ai/v1/tasks/<taskId>, bis data.status gleich success ist, und hole das Ergebnis aus data.output[0].url (diese URL hat eine Gültigkeitsdauer; lade sie schnell herunter oder speichere sie um, verwende keinen Hotlink).

Häufig gestellte Fragen

Kann ich Base64 an die Image-to-Image-Modelle von HiAPI übergeben? Nein. Das Bildfeld erwartet eine öffentliche HTTP(S)-URL, die der Server herunterladen kann. Eine Zeichenkette data:image/...;base64,... wird bei manchen Modellen beim Absenden akzeptiert, doch der Task endet anschließend mit status: fail und dem Fehlercode TASK_FAILED / task failed. Lade die Bytes an einen öffentlichen Ort hoch und übergib die URL.

Mein POST /v1/tasks gab 200 zurück, aber der Task ist fehlgeschlagen – warum? Das 200 beim Absenden bedeutet nur, dass die Anfrage angenommen wurde. Der Bild-Download und die Generierung erfolgen erst danach. Poll GET /v1/tasks/<taskId>; eine fehlerhafte Bild-Eingabe zeigt sich dort als data.status: fail mit error.code gleich INVALID_REQUEST ("The image URL could not be downloaded…") oder TASK_FAILED.

In welches Feld gehört die Bild-URL nun eigentlich? Das hängt vom Modell ab. gpt-image-2/image-to-image verwendet input_urls, seedream-5.0-pro/image-to-image verwendet image_urls, nano-banana-pro verwendet image_input (alle als Array). Prüfe vor dem Senden der Anfrage das aktuelle Schema auf der Modellseite.

Gehen localhost oder private URLs? Nein. HiAPI ruft das Bild von seinen eigenen Servern ab, daher scheitern localhost, 127.0.0.1, interne Adressen, Links, die erst nach Anmeldung sichtbar sind, und abgelaufene Pre-Signed-URLs alle mit "The image URL could not be downloaded.". Verwende eine öffentlich auflösbare URL ohne Authentifizierung.

Was bedeutet der Fehler additional properties 'input_urls' not allowed? Du hast das Bildfeld an ein Modell übergeben, das es nicht definiert – meistens, weil du die nackte Text-zu-Bild-ID (gpt-image-2) statt der Image-to-Image-Route (gpt-image-2/image-to-image) verwendet hast oder den Feldnamen eines anderen Modells genutzt hast. Das ist ein 400 beim Absenden; siehe den obigen 400-Bad-Request-Leitfaden.

Werden fehlgeschlagene Bild-Tasks abgerechnet? Anfragen, die bereits beim Absenden mit 400 abgelehnt werden, werden nicht abgerechnet; sobald ein Task jedoch angenommen wurde (200 + taskId) und erst danach fehlschlägt, kann er abgerechnet werden – siehe oben „Werden fehlgeschlagene Anfragen abgerechnet?". Korrigiere daher die URL, bevor du es erneut versuchst.