HiAPI
De
Blog

Tutorial

So verwendest du grok-imagine Image-to-Image über die hiapi API: curl, Python und eine funktionierende Anfrage

Jul 11, 2026
So verwendest du grok-imagine Image-to-Image über die hiapi API: curl, Python und eine funktionierende Anfrage

grok-imagine/image-to-image nimmt ein oder mehrere Referenzbilder sowie einen Text-Prompt entgegen und liefert ein bearbeitetes Bild zurück – du kannst Produktfotos umstilisieren, den Hintergrund austauschen oder bis zu drei Referenzbilder zu einem Ergebnis verschmelzen. Auf hiapi läuft es über die einheitliche Task-API: Aufgabe erstellen, abfragen (oder Callback empfangen), Ergebnis herunterladen. Diese Anleitung führt dich durch die exakte Anfragestruktur und liefert direkt kopierbare, sofort lauffähige curl- und Python-Beispiele.

Was du baust + Voraussetzungen

Ziel: ein Referenzbild und einen Prompt übermitteln, die URL eines bearbeiteten Bildes zurückbekommen und es herunterladen – zuerst interaktiv per Polling, dann eine Produktionsversion mit Callback.

Du brauchst nur eines: einen hiapi API-Schlüssel. Hol ihn dir aus deinem Dashboard – er sieht aus wie sk-... und wird bei jedem Aufruf in den Authorization: Bearer-Header gesetzt.

Deine Referenzbilder müssen öffentlich zugängliche URLs sein (das Modell ruft sie serverseitig ab), hoste sie also zuerst auf deinem CDN oder Objektspeicher.

Minimales lauffähiges Beispiel (curl)

Aufgabe erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

Es gibt zwei Pflichtfelder – prompt und image_urls – und das ist bereits eine vollständige Anfrage. Die Antwort enthält die Task-ID unter data.taskId:

{
  "data": {
    "taskId": "<task-id>"
  }
}

Ergebnis abfragen:

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

Während die Aufgabe läuft, meldet data.status den Fortschritt. Wenn er success wird, steht die Bild-URL in data.output[0].url. Bei fail findest du Fehlercode und Meldung in data.error.

Ein wichtiges Detail: Ausgabe-URLs sind signiert und laufen ab (die Payload enthält expireAt). Lade die Datei sofort nach erfolgreichem Abschluss der Aufgabe herunter – speichere oder verlinke die rohe Ausgabe-URL niemals per Hotlink.

curl -o result.png "<data.output[0].url>"

Dasselbe Beispiel in Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

Das vollständige Eingabe-Schema

Feld Erforderlich Typ Beschreibung
prompt ✅ string Was geändert werden soll / gewünschtes Aussehen
image_urls ✅ URL-Array 1–3 Referenzbilder, müssen öffentlich zugänglich sein
aspect_ratio optional enum auto, 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2
resolution optional enum 1k oder 2k – Kleinbuchstaben
output_format optional enum jpeg, png oder webp

Das Schema ist strikt: Jedes Feld, das es nicht kennt, wird mit 400 abgelehnt. Es gibt kein size, kein seed, kein n – wenn du Modellcode portierst, der Pixelgrößen verwendet (z. B. size: "1024x1024"), verwende hier stattdessen aspect_ratio + resolution. Jede Aufgabe liefert ein Bild zurück; für Varianten reichst du mehrere Aufgaben ein.

Mehrere Referenzbilder: bis zu 3 Eingabebilder

image_urls akzeptiert bis zu drei Referenzbilder, die das Modell verschmilzt – zum Beispiel ein Produktbild plus eine Hintergrundvorlage plus ein Stilreferenzbild. Wenn du mehr als drei sendest, lehnt die API die Anfrage direkt ab:

invalid input: image_urls: maxItems: got 4, want 3

Setze das wichtigste Bild (normalerweise das Motiv) an die erste Stelle und erläutere im Prompt, welchen Beitrag jedes Referenzbild leistet.

Automatisches Seitenverhältnis

aspect_ratio: "auto" lässt das Modell das Ausgabeverhältnis aus deinem Referenzbild ableiten, statt ein festes Format zu erzwingen – für Produktfotos und Bearbeitungen, bei denen die Komposition erhalten bleiben soll, ist das der passende Standard. Setze ein explizites Verhältnis nur, wenn der Zielkontext es klar verlangt (z. B. 9:16 für Story-Platzierungen, 16:9 für Key-Visual-Banner).

Hinweise für den Produktivbetrieb

Callback statt Polling

Für Batch- oder Server-Workloads überspringe die Polling-Schleife – registriere beim Erstellen der Aufgabe einen Callback, und hiapi POSTet das Endergebnis an deinen Endpunkt:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when unterstützt nur "final" – du erhältst genau einen Aufruf, wenn die Aufgabe success oder fail erreicht, keine Zwischenfortschrittsereignisse.

Faustregel: Polling für interaktive Tools (ein Nutzer schaut zu; eine sleep-Schleife von 5 Sekunden ist in Ordnung), Callbacks für Pipelines (Dutzende Aufgaben laufen; du willst nicht für jede Aufgabe einen Poller). Dein Callback-Handler sollte die Ausgabe trotzdem sofort herunterladen – die URL, die er erhält, läuft genauso ab wie jede andere.

Idempotenz und Retries

Die Task-API trennt „Übermitteln" von „Ergebnis", was sichere Retries unkompliziert macht:

  • Persistiere die taskId in dem Moment, in dem create zurückkehrt. Wenn dein Prozess später abstürzt, stelle den Zustand durch Abfragen der gespeicherten ID wieder her – erstelle die Aufgabe nicht neu.
  • Wiederhole nur dann, wenn der create-Aufruf fehlgeschlagen ist und keine taskId zurückgegeben hat (Netzwerkfehler, 5xx). Eine erneut übermittelte Anfrage, die bereits eine ID zurückgegeben hat, erzeugt eine zweite, separat abgerechnete Aufgabe.
  • Behandle status: "fail" als terminal. Korrigiere die Eingabe (oder leite auf einen Fallback um) und reiche eine neue Aufgabe ein; eine fehlgeschlagene Aufgabe wird nicht neu gestartet.

Häufige Fehler

Was du siehst Bedeutung Behebung
401 – permission_denied Falscher Schlüssel oder Schlüssel hat keinen Zugriff auf dieses Modell Schlüssel im Dashboard prüfen
400 INVALID_REQUEST – missing required field "prompt" / "image_urls" Pflichteingabe fehlt Beide Felder sind Pflicht
400 INVALID_REQUEST – additional properties '...' not allowed Unbekanntes Feld (z. B. size, seed, n) Striktes Schema – nur Felder aus der Tabelle oben verwenden
400 INVALID_REQUEST – image_urls: maxItems Mehr als 3 Referenzbilder Auf 3 reduzieren
404 – task not found taskId beim GET falsch oder gehört zu einem anderen Konto Gespeicherte ID prüfen
status: "fail" beim Polling Akzeptiert, aber Generierung fehlgeschlagen data.error lesen, Eingabe anpassen, neu übermitteln

Beachte, dass ein Authentifizierungsfehler ein 401 mit "code": "permission_denied" im Fehler-Body ist – es lohnt sich, diesen explizit abzugleichen, da er auch den Fall abdeckt, dass der Schlüssel existiert, aber keinen Zugriff auf dieses Modell hat.

Nächste Schritte

Häufig gestellte Fragen

Wie viele Referenzbilder kann ich übergeben? Maximal 3 in image_urls. Die API lehnt mehr strikt ab (maxItems: got N, want 3).

Kann ich die Ausgabegröße in Pixeln festlegen? Nein. Es gibt kein size-Feld – du steuerst die Form mit aspect_ratio (14 Enum-Werte) und die Schärfe mit resolution (1k oder 2k, Kleinbuchstaben). Alles andere führt zu einem 400.

Was bewirkt aspect_ratio: "auto"? Es lässt das Modell dem Seitenverhältnis des Referenzbilds folgen, statt ein festes Format zu erzwingen – die übliche Wahl für Bearbeitungen, bei denen die Komposition erhalten bleiben soll.

Wie lange sind Ergebnis-URLs gültig? Sie sind signiert und haben eine Ablaufzeit (expireAt in der Ausgabe-Payload). Lade die Bytes so bald wie möglich nach erfolgreichem Abschluss der Aufgabe herunter; verlinke sie nicht per Hotlink.

Sollte ich pollen oder Callbacks verwenden? Für interaktive Nutzung reicht Polling etwa alle 5 Sekunden. Für Batch-Pipelines übergib callback: {"url": ..., "when": "final"} und verarbeite einen POST pro Aufgabe – "final" ist der einzige unterstützte Auslöser.

Kann ich mit einem Aufruf mehrere Varianten erhalten? Nein – es gibt keinen n-Parameter. Reiche für jede Variante eine Aufgabe ein; sie laufen ohnehin parallel.

Was ist der Unterschied zu grok-imagine-quality/image-to-image? Dieselbe Anfragestruktur, eine Renderstufe mit höherer Wiedergabetreue (und höheren Kosten). Prototypisiere in der Standardstufe und lasse die finalen Ergebnisse in der Qualitätsstufe erneut laufen; vergleiche die Kosten pro Bild auf der Preisseite.

TagsBild-APITutorial

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen