So verwendest du flux-2-klein-4b/image-to-image über die hiapi API

FLUX.2 [klein] 4B ist ein kompaktes, schnelles Bildbearbeitungsmodell von Black Forest Labs: Gib ihm ein Referenzbild und eine Anweisung in natürlicher Sprache, und es liefert ein bearbeitetes Bild mit bis zu 4 MP zurück. Bei hiapi läuft es wie alle anderen Modelle über dieselbe Unified Async API – erstelle eine Aufgabe mit POST /v1/tasks und rufe das Ergebnis dann per Polling oder Callback ab. Diese Anleitung beschreibt die genaue Request-Struktur, funktionierende curl/Python-Beispiele und die Integration in eine Produktionsumgebung.

Was du vorbereiten musst

• Einen hiapi API-Schlüssel. Erhältlich im Dashboard – der Schlüssel hat die Form sk-... und wird im Header Authorization: Bearer übergeben.
• Eine öffentlich erreichbare URL eines Referenzbilds (jpeg, png oder webp – svg wird nicht unterstützt). Bilder mit mehr als 4 MP werden automatisch auf 4 MP verkleinert.
• Die aktuelle Preisgestaltung für flux-2-klein-4b/image-to-image ist nach Auflösung gestaffelt (0,25 MP bis 4 MP) – sieh dir die Live-Preise unter hiapi pricing an, statt sie hier fest zu kodieren.

Minimal funktionierendes Beispiel

Die Modell-ID ist flux-2-klein-4b/image-to-image – verwende sie genau in dieser Schreibweise (einschließlich des Schrägstrichs) als Wert von model (nicht im URL-Pfad). Alle hiapi-Modelle teilen denselben Endpunkt; nur die Felder des input-Objekts unterscheiden sich je nach Modell.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

Diese Anfrage gibt sofort eine taskId zurück – die Generierung erfolgt asynchron:

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Ergebnis per Polling abrufen:

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

Wenn status zu "success" wird, befindet sich das bearbeitete Bild unter data.output[0].url. Diese URL ist temporär (mit expireAt), daher solltest du die Datei sofort herunterladen oder erneut hosten – speichere diesen Hotlink nicht direkt.

Derselbe Ablauf in Python:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Anfrageparameter

flux-2-klein-4b/image-to-image akzeptiert ein striktes Eingabe-Schema – zusätzliche Felder, die hier nicht aufgeführt sind, werden mit 400 abgelehnt:

Feld	Erforderlich	Beschreibung
prompt	Ja	Natürlichsprachliche Beschreibung der anzuwendenden Bearbeitung.
image_urls	Ja	Array mit genau einer Referenzbild-URL. Bei mehreren Einträgen wird maxItems: got N, want 1 zurückgegeben.
resolution	Nein	Einer der Werte: 0.25 MP, 0.5 MP, 1 MP (Standard), 2 MP, 4 MP. Verwende 0.25/0.5 MP für kostengünstige Entwürfe und 2/4 MP für das finale Ergebnis.
aspect_ratio	Nein	Einer der Werte: match_input_image (Standard), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	Nein	Ganzzahl, um reproduzierbare Ergebnisse zwischen ansonsten identischen Anfragen zu erzielen.
output_format	Nein	jpg (Standard), png oder webp.
output_quality	Nein	Ganzzahl, Kompressionsqualität für jpg/webp (Standard 95).

Dieses Modell hat kein size- oder n-Feld – das sind Konventionen anderer Anbieter, die dieses Schema nicht kennt. Jedes hiapi-Modell hat seine eigene Feldmenge; sieh dir daher die Modellreferenzseite an, bevor du Anfragen übernimmst, die für andere Modelle erstellt wurden.

Hinweise für den Produktionseinsatz

Bevorzuge Callbacks gegenüber Polling. Füge ein Objekt callback auf oberster Ebene hinzu, und hiapi benachrichtigt deinen Dienst, statt dass du in einer Schleife pollen musst:

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when akzeptiert nur "final" – es wird eine Benachrichtigung gesendet, wenn die Aufgabe einen Endzustand (success oder fail) erreicht, kein Fortschrittsstream. Behandle den Callback als Wecksignal: Nach dem Empfang solltest du dennoch GET /v1/tasks/<taskId> aufrufen, um den maßgeblichen Status zu lesen, und deinen Handler in Bezug auf taskId idempotent halten, um doppelte Zustellungen abzufangen.

Idempotenz. Speichere die taskId dauerhaft, sobald create_task zurückkehrt, und beginne erst dann mit dem Polling oder dem Warten auf den Callback. Wenn der Prozess während des Wartens abstürzt, sollte er nach dem Neustart mit GET /v1/tasks/<taskId> fortfahren, statt die Aufgabe neu zu erstellen – das Erstellen einer Aufgabe ist ein abrechenbares Ereignis, GET kann kostenlos wiederholt werden.

Fehlerbehandlung. Ungültige oder nicht autorisierte Schlüssel geben HTTP 401 mit einem strukturierten Antwortkörper zurück:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Protokolliere die request_id – das Support-Team kann damit den genauen Aufruf nachverfolgen. Ein fehlerhaftes input (fehlender prompt/image_urls, nicht unterstützter aspect_ratio-Wert oder nicht erkannte zusätzliche Felder) gibt 400 mit error_code: "INVALID_REQUEST" zurück und benennt das problematische Feld in der Meldung; korrigiere den Request-Body, statt ihn unverändert erneut zu senden.

Weiterführende Literatur

• FLUX.2 [klein] 4B Image-to-Image-Modellreferenz – vollständige Parameterdokumentation und Beispiel-Request-Bodys.
• FLUX.2 [klein] 4B Text-to-Image-Modellreferenz – die entsprechende Text-to-Image-Variante ohne Referenzbild.
• hiapi pricing – aktuelle Kosten pro Bild, gestaffelt nach Auflösung.
• Unified Async API – Übersicht – der plattformweit von jedem Modell geteilte Vertrag POST /v1/tasks / GET /v1/tasks/:id.

Häufig gestellte Fragen

Welche Bildformate akzeptiert image_urls? jpeg, png oder webp. svg wird nicht unterstützt. Bilder mit mehr als 4 MP werden vor der Bearbeitung automatisch auf 4 MP verkleinert.

Kann ich mehrere Referenzbilder übergeben? Nein – image_urls ist bei diesem Modell auf genau ein Element begrenzt. Mehr Einträge führen zu 400 (maxItems: got N, want 1).

Warum wird meine Anfrage mit "additional properties ... not allowed" abgelehnt? Das Schema ist strikt: Jedes Feld, das nicht in der obigen Parametertabelle enthalten ist (z. B. Konventionen anderer Anbieter wie size, n oder strength), löst einen 400-Fehler aus. Sieh dir die Modellreferenz an, um die exakt akzeptierte Feldmenge zu erfahren.

Wie behalte ich das Seitenverhältnis des Originalbilds bei? Setze aspect_ratio auf match_input_image – das ist auch der Standardwert, wenn du das Feld ganz weglässt.

Was ist der Unterschied zwischen flux-2-klein-4b/image-to-image und der 9B-Variante? Beide teilen dasselbe Anfrage-Schema (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). Der 9B-Weg opfert etwas Geschwindigkeit und Kosten für stärkeren Realismus, Textwiedergabe und Details – verwende 4B, wenn du schnell und kostengünstig iterierst, und 9B, wenn die Bearbeitung bei feinen Details überzeugen muss.

Brauche ich eine Callback-URL, oder reicht Polling? Polling mit GET /v1/tasks/:id ist für die lokale Entwicklung, Aufgaben mit geringem Volumen oder als Fallback geeignet, wenn eine Callback-Zustellung ausbleibt. Für Produktionsverkehr vermeiden Callbacks den Aufwand einer Polling-Schleife bei jeder Anfrage.