So verwendest du gpt-image-2 Image-to-Image über die hiapi API

Dieses Rezept zeigt Schritt für Schritt, wie du den Image-to-Image-Modus von gpt-image-2 über die einheitliche Task-API von hiapi aufrufst. Du erhältst ein direkt ausführbares curl-Beispiel, ein Python-Skript, das du direkt in dein Backend einbetten kannst, eine Node.js-Version für serverlose Szenarien sowie die Parameter, die wirklich zählen, und die Details, bei denen es in der Produktion leicht zu Fallstricken kommt.

Nach dem Lesen dieses Artikels hast du ein Skript, das eine Referenzbild-URL und einen Prompt entgegennimmt und eine generierte Bild-URL zurückgibt, die du direkt herunterladen oder an deine Speicherschicht übergeben kannst.

Vorbereitung

• Ein hiapi-Konto und ein API-Schlüssel. Erhältlich in der hiapi-Konsole.
• Ein Referenzbild, das unter einer öffentlichen HTTPS-URL gehostet wird (oder eine base64-Data-URL – beides ist möglich).
• Ein Text-Prompt, der beschreibt, was das Modell mit dem Referenzbild tun soll.

Das ist alles. Kein SDK erforderlich – hiapi ist einfach HTTP + JSON, jede Sprache, die POST-Anfragen senden kann, funktioniert.

Du möchtest zuerst die reine Text-zu-Bild-Generierung kennenlernen? Siehe Wie man Bilder mit der hiapi API generiert. Das unten beschriebene Muster ist derselbe asynchrone Task-Ablauf, nur mit einem zusätzlichen image-Feld.

Minimaler funktionsfähiger Aufruf

hiapi stellt alle Bildmodelle über dieselbe asynchrone Task-Schnittstelle bereit:

1. POST /v1/tasks – Task einreichen, gibt eine taskId zurück.
2. Entweder GET /v1/tasks/{taskId} abfragen, bis status === "success", oder eine callback.url angeben und das Endergebnis per Webhook empfangen.
3. Die Bild-URL aus data.output[0].url lesen und herunterladen oder speichern.

curl

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "input": {
      "prompt": "transform the subject into a watercolor painting, soft pastel palette",
      "image": "https://example.com/reference.jpg",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Die sofortige Antwort liefert dir die Task-ID:

{ "data": { "taskId": "task_01HXXXX..." } }

Dann fragst du das Ergebnis ab:

curl https://api.hiapi.ai/v1/tasks/task_01HXXXX... \
  -H "Authorization: Bearer sk-YOUR_KEY"

Sobald der Task fertig ist, sieht die Antwort so aus:

{
  "data": {
    "status": "success",
    "output": [{ "url": "https://cdn.hiapi.ai/...png", "expireAt": "..." }]
  }
}

output[0].url ist kurzlebig (beachte expireAt), also lade das Bild sofort herunter oder lade es erneut in deinen eigenen Speicher hoch – verlinke niemals direkt auf Endnutzer.

Die Parameter, die wirklich zählen

Feld	Typ	Beschreibung
model	string	Verwende die reine ID gpt-image-2/image-to-image. Kein models/-Präfix hinzufügen.
input.prompt	string	Die Transformation, die du auf das Referenzbild anwenden möchtest.
input.image	string	HTTPS-URL oder data:image/...;base64,...-URL.
input.aspect_ratio	string	Einer der Werte: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9 oder auto.
input.resolution	string	1K, 2K oder 4K. Standard ist 1K.

Zwei wichtige Verhaltensweisen:

• Einige hiapi-Modelle akzeptieren nur aspect_ratio (ohne resolution); andere Modelle benötigen Pixelabmessungen. gpt-image-2/image-to-image akzeptiert die oben gezeigte Kombination aus aspect_ratio + resolution – übergebe hier kein size: "1024x1024".
• Das image-Feld ist das Referenzbild. Wenn du eine base64-Data-URL übergibst, stelle sicher, dass die Payload unter dem Request-Body-Limit deiner Plattform liegt (einige MB sind in Ordnung; mehrere Megabyte große Bilder sollten zuerst hochgeladen und dann als URL übergeben werden).

Produktionsreifes Python-Skript

Diese Version führt das Polling mit Deadline-Handling durch und beendet sich bei Fehlern sauber:

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def submit(prompt: str, image_url: str, aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2/image-to-image",
        "input": {
            "prompt": prompt,
            "image": image_url,
            "aspect_ratio": aspect_ratio,
            "resolution": "1K",
        },
    }
    r = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id: str, timeout_s: int = 300, interval_s: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=20)
        r.raise_for_status()
        task = r.json()["data"]
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = submit(
        prompt="transform the subject into a watercolor painting, soft pastel palette",
        image_url="https://example.com/reference.jpg",
    )
    print("task:", task_id)
    print("url:", wait(task_id))

Ausführen mit HIAPI_API_KEY=sk-... python recipe.py.

Node.js (fetch, ohne Abhängigkeiten)

const API = "https://api.hiapi.ai/v1/tasks";
const TOKEN = process.env.HIAPI_API_KEY;
const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

async function submit(prompt, imageUrl, aspectRatio = "1:1") {
  const r = await fetch(API, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "gpt-image-2/image-to-image",
      input: { prompt, image: imageUrl, aspect_ratio: aspectRatio, resolution: "1K" },
    }),
  });
  const data = await r.json();
  if (!r.ok) throw new Error(JSON.stringify(data));
  return data.data.taskId;
}

async function wait(taskId, timeoutMs = 300000, intervalMs = 5000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const r = await fetch(`${API}/${taskId}`, { headers });
    const task = (await r.json()).data;
    if (task.status === "success") return task.output[0].url;
    if (task.status === "fail") throw new Error(JSON.stringify(task.error));
    await new Promise((res) => setTimeout(res, intervalMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

(async () => {
  const id = await submit(
    "transform the subject into a watercolor painting, soft pastel palette",
    "https://example.com/reference.jpg",
  );
  console.log("task:", id, "\nurl:", await wait(id));
})();

Polling vs. Callback

Alle 5 Sekunden abzufragen ist für ein einmaliges Skript in Ordnung, aber es blockiert einen Worker für die gesamte Dauer des Tasks. In einem echten Backend möchtest du normalerweise einen Webhook:

{
  "model": "gpt-image-2/image-to-image",
  "input": { "prompt": "...", "image": "https://example.com/reference.jpg" },
  "callback": { "url": "https://your-app.example.com/api/hiapi-callback", "when": "final" }
}

Wenn der Task abgeschlossen ist (erfolgreich oder fehlgeschlagen), sendet hiapi ein POST an diese URL mit derselben Payload, die du von GET /v1/tasks/{id} bekommen würdest. Behandle diesen Handler als idempotent – Wiederholungen sind möglich – und verifiziere die Anfrage, bevor du ihr vertraust (eigenes Signatur-Token in der URL, Prüfung des Authorization-Headers usw.).

Ein sauberes Muster ist: Task einreichen, taskId unter deiner eigenen Job-ID persistent speichern, dem Aufrufer 202 Accepted zurückgeben und den Webhook die Speicherung + Benachrichtigung erledigen lassen.

Fehlerbehandlung

In der Praxis wirst du auf drei Fehlermuster stoßen:

1. 401 permission_denied mit "This API key cannot use the selected model." – Der Schlüssel ist nicht für die Verwendung von gpt-image-2/image-to-image autorisiert. Prüfe dies in der hiapi-Konsole und bestätige auf der Preisseite, dass das Modell in deinem Tarif enthalten ist.
2. 400 mit additional properties not allowed – Du hast ein Feld gesendet, das das jeweilige Modell nicht akzeptiert (z. B. size statt aspect_ratio). Die Fehlermeldung nennt den beanstandeten Schlüssel; entferne ihn und versuche es erneut.
3. status: "fail" beim Polling mit einem data.error-Objekt – das Modell selbst hat die Eingabe abgelehnt (unsichere Inhalte, nicht erreichbare Referenz-URL usw.). Protokolliere error.code und error.message, aber wiederhole nicht blind automatisch.

Setze für POST /v1/tasks-Aufrufe immer ein Request-Timeout (30 Sekunden reichen – die taskId wird schnell zurückgegeben) und für die Polling-Schleife oder den Webhook-Empfangspfad ein separates, längeres Timeout.

Verwandte Links

• gpt-image-2-Modellseite – Fähigkeitsmatrix und Preisstufen.
• Alle hiapi-Modelle – der vollständige Katalog, falls du andere Bild- oder Videomodelle benötigst.
• API-Dokumentation – die vollständige Referenz zu /v1/tasks und der gesamten Schnittstelle.
• Wie man Bilder mit der hiapi API generiert – das Text-zu-Bild-Schwesterstück dieses Rezepts.

Häufige Fragen

F: Unterstützt gpt-image-2/image-to-image mehrere Referenzbilder? A: Der minimale Vertrag verwendet ein einzelnes image-Feld. Wenn du für deinen Anwendungsfall mehrere Referenzbilder benötigst (z. B. ein Motivbild + ein Stilbild), fasse sie zuerst zu einem zusammen oder sieh auf der Modellseite nach, welche Felder aktuell unterstützt werden.

F: Kann ich eine lokale Datei statt einer URL übergeben? A: Ja – kodiere sie als data:image/png;base64,...-URL und übergebe sie als input.image. Bei Dateien über etwa 3 MB lade sie zuerst in deinen eigenen Speicher hoch und übergib eine öffentliche URL; das ist schneller und umgeht Request-Body-Limits.

F: Wie lange dauert ein Task? A: Die meisten gpt-image-2-Image-to-Image-Tasks sind bei 1K-Auflösung in 10–30 Sekunden abgeschlossen. Höhere Auflösungen und komplexe Prompts können länger dauern – setze das Polling-Timeout zur Sicherheit auf 5 Minuten.

F: Wie steuere ich, wie stark das Ergebnis vom Referenzbild abweicht? A: Drücke es im Prompt explizit aus. "Keep the subject's pose and composition, only restyle to watercolor" erzeugt eine engere Übereinstimmung als "make this a watercolor". Der Image-to-Image-Modus von gpt-image-2 ist prompt-gesteuert – es gibt keinen separaten "strength"-Schieberegler im Request-Envelope.

F: Ist output[0].url dauerhaft? A: Nein. Sie trägt einen expireAt-Zeitstempel (normalerweise einige Stunden). Lade die Bytes nach erfolgreichem Task so bald wie möglich herunter und lade sie in deinen eigenen Speicher hoch (R2, S3 usw.).

F: Was kostet ein Bild? A: Das hängt von deinem Tarif und der Auflösung ab. Die aktuellen Kosten pro Aufruf findest du auf der Preisseite.