So verwenden Sie flux-2/image-to-image über die hiapi API: curl, Python und verfügbare Request-Beispiele

Kurz gesagt

• Was ist das:Eine einsatzbereite Lösung zum Aufrufen der flux-2/image-to-image API auf hiapi – Aufgabe erstellen, Status abfragen, Ergebnis herunterladen.
• Endpunkt:Verwenden Sie POST https://api.hiapi.ai/v1/tasks mit "model": "flux-2/image-to-image" und dann GET /v1/tasks/<taskId>, bis die Aufgabe einen Endzustand erreicht.
• Pflichtfelder der Eingabe (alle vier):prompt, image_urls (1–8 öffentliche URLs – das ist die Mehrfach-Referenzbild-Funktion), aspect_ratio und resolution (1K oder 2K).
• Das Schema ist strikt.Felder wie strength oder fidelity existieren nicht und werden mit 400 abgelehnt. Die Treue wird durch Ihre Referenzbilder, den Prompt und resolution gesteuert – nicht durch einen separaten Regler.

Was Sie bauen, und was Sie vorbereiten müssen

Ziel: Senden Sie ein oder mehrere Referenzbilder plus einen Text-Prompt an flux-2 und erhalten Sie ein herunterladbares bearbeitetes/neu gezeichnetes Bild zurück – mit curl oder Python, ohne SDK.

Voraussetzungen:

1. Ein hiapi API-Schlüssel – erstellen Sie ihn in der hiapi-Konsole. Der Schlüssel hat die Form sk-... und wird im Authorization: Bearer-Header übergeben.
2. Mindestens eine öffentlich zugängliche Bild-URL als Referenzbild. Die API ruft image_urls serverseitig ab, daher funktionieren localhost-Links oder URLs aus privaten Buckets nicht – verwenden Sie einen öffentlichen Bucket, ein CDN oder eine vorab signierte URL.
3. curl oder Python 3.8+ mit requests (pip install requests).

Request-Schema

flux-2/image-to-image läuft auf der einheitlichen Aufgaben-Schnittstelle von hiapi. Das input-Objekt akzeptiert genau die folgenden Felder:

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Was geändert oder erzeugt werden soll. Mindestens 3 Zeichen.
image_urls	string[]	Ja	1–8 öffentliche Bild-URLs. Mehr als eines = Mehrfach-Referenzbild: flux-2 kombiniert Identitäts-, Produkt- oder Stilmerkmale über alle Referenzbilder hinweg.
aspect_ratio	string	Ja	Eines von 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 oder auto (folgt dem Referenzbild).
resolution	string	Ja	1K oder 2K.

Jedes andere Feld wird abgelehnt. Wenn Sie beispielsweise ein strength- oder fidelity-Feld senden, wird Folgendes zurückgegeben:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

Das sollten Sie sich merken: Der Bild-zu-Bild-Modus von flux-2 hat keinen Denoising-Stärke-Regler. Wie treu die Ausgabe zum Referenzbild ist („hochtreue“ Bearbeitung vs. lockere Neuzeichnung) hängt davon ab, wie Sie den Prompt formulieren – z. B. „Behalte das Produkt sowie sein Etikett und seine Proportionen exakt wie im Referenzbild bei; ersetze nur den Hintergrund“ – plus resolution: "2K" für Arbeiten mit hohem Detailanspruch.

Minimales funktionierendes Beispiel: curl

Schritt 1 – Aufgabe erstellen:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Bei erfolgreicher Erstellung wird die Aufgaben-ID in data.taskId zurückgegeben.

Schritt 2 – abfragen, bis sie abgeschlossen ist:

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

Solange data.status kein Endzustand ist, fragen Sie im Abstand von einigen Sekunden weiter ab. Bei "status": "success" befindet sich die Bild-URL in data.output[0].url.

Schritt 3 – Ergebnis sofort herunterladen:

curl -s -o result.jpg "OUTPUT_URL"

Ausgabe-URLs tragen einen expireAt-Zeitstempel – sie sind temporär. Nach erfolgreicher Aufgabe sollten die Bytes sofort heruntergeladen (oder in Ihren eigenen Speicher kopiert) werden; verlinken Sie Aufgaben-Ausgaben im Produktivbetrieb nicht direkt per Hotlink.

Minimales funktionierendes Beispiel: Python

Ein vollständiges Skript – erstellen, abfragen, herunterladen – nur mit requests:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # temporäre URL – bitte sofort speichern
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

Beachten Sie, dass hier image_urls mit zwei Bildern verwendet wird – das ist die praktische Anwendung von Mehrfach-Referenzbildern. Es werden bis zu 8 Referenzbilder akzeptiert; das Modell kombiniert sie (Person + Kleidung, Produkt + Hintergrundstil, Figur + Posenreferenz usw.).

Hinweise für den Produktivbetrieb

Verwenden Sie Callbacks statt Polling.Für alles, was über ein Skript hinausgeht, registrieren Sie beim Erstellen der Aufgabe einen Callback, damit hiapi das Endergebnis an Ihren Dienst pusht:

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Mit "when": "final" erhalten Sie nur einen einzigen POST, wenn die Aufgabe einen Endzustand erreicht. Faustregel: Polling eignet sich für CLI, Batch-Verarbeitung und alle kurzlebigen Szenarien; Callbacks sind besser für benutzerorientierte Anwendungen, denn wenn für jedes Bild ein Worker eine Polling-Schleife offen hält, lässt sich das nicht skalieren. Wenn Sie keinen öffentlich erreichbaren Callback-Endpunkt bereitstellen können, dann pollen Sie – aber erhöhen Sie das Intervall auf mindestens 5 Sekunden.

Machen Sie Wiederholungen sicher.Behandeln Sie das Erstellen von Aufgaben als das, was es ist: eine Nebenwirkung. Speichern Sie die zurückgegebene taskId in Ihrem eigenen Job-Datensatz, bevor Sie aufgrund des Ergebnisses handeln; prüfen Sie bei Wiederholungen den Status der gespeicherten Aufgabe erneut, statt blind eine neue Aufgabe zu erstellen (jede erfolgreiche Erstellung wird separat abgerechnet). Wenn Ihr Job-Runner zweimal auslösen könnte, deduplizieren Sie zuerst anhand Ihrer eigenen Job-ID.

Behandeln Sie die Fehler, die tatsächlich auftreten:

• 401 permission_denied – falscher Schlüssel oder der Schlüssel ist nicht berechtigt, dieses Modell zu verwenden. Der Antworttext sieht so aus:

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Prüfen Sie den Schlüssel in der Konsole; unsere Checkliste für ungültige API-Schlüssel deckt die häufigsten Ursachen ab.

• 400 INVALID_REQUEST – Schema-Verstoß. Die message listet alle verstoßenden Felder auf einmal auf (fehlende Pflichtfelder, falsche Enum-Werte, unbekannte zusätzliche Felder). Lesen Sie sie daher vollständig, statt bei jeder Wiederholung nur ein Feld zu korrigieren.

• Aufgabe status: "fail" – die Aufgabe wurde angenommen, aber die Generierung ist fehlgeschlagen; der Fehler steht in data.error. Behandeln Sie ihn im Polling-/Callback-Pfad, nicht beim Erstellen.

• Ausgabe-URL abgelaufen – wenn ein Download einige Minuten nach dem Erfolg 4xx zurückgibt, haben Sie zu lange gewartet. Prüfen Sie expireAt erneut und laden Sie immer sofort herunter.

Weiterführende Literatur

• Modellseite flux-2/image-to-image – Parameter und aktuelle Preise
• Modellseite flux-2/text-to-image – dieselbe Serie, ohne Referenzbild
• flux-2 für E-Commerce-Produktbilder – End-to-End-Lösung auf Basis der Text-zu-Bild-Seite
• FLUX 1.1 Pro auf hiapi – Vergleich mit der Vorgängergeneration
• hiapi-Preise – Kosten pro Bild je Auflösung

Häufig gestellte Fragen

Wie viele Referenzbilder kann ich an flux-2 Bild-zu-Bild übergeben? 1 bis 8 Bilder, als öffentliche URLs in image_urls. Mehr als 8 führen zu einem Validierungsfehler (maxItems: got N, want 8).

Gibt es einen strength- oder fidelity-Parameter? Nein. Das Eingabe-Schema akzeptiert nur prompt, image_urls, aspect_ratio und resolution; unbekannte Felder werden mit 400 abgelehnt. Steuern Sie die Treue über die Formulierung des Prompts (geben Sie ausdrücklich an, was unverändert bleiben muss) und verwenden Sie 2K, wenn Details wichtig sind.

Welche Auflösungen und Seitenverhältnisse werden unterstützt? resolution ist 1K oder 2K. aspect_ratio ist eines von 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 oder auto – auto folgt Ihrem Referenzbild, was beim Bearbeiten in der Regel gewünscht ist.

Kann ich Base64-Bilder statt URLs senden? Nein – image_urls akzeptiert URLs, die öffentlich zugänglich sein müssen, damit die API sie abrufen kann. Laden Sie zuerst in einen Bucket oder ein CDN hoch und übergeben Sie dann die erzeugte URL (vorab signierte URLs funktionieren).

Was kostet flux-2 Bild-zu-Bild pro Bild? Der Preis variiert je nach Auflösung – sehen Sie auf der Modellseite flux-2/image-to-image und der Preisseite nach den aktuellen Tarifen pro Bild.

Wie lange sind generierte Bild-URLs gültig? Ausgabe-URLs sind temporär und enthalten ein expireAt-Feld. Nach erfolgreicher Aufgabe sollten die Bild-Bytes sofort heruntergeladen und selbst gespeichert werden.

Was ist der Unterschied zwischen flux-2/image-to-image und flux-2/text-to-image? Dieselbe Modellserie, unterschiedliche Modi: Text-zu-Bild generiert ausschließlich aus dem Prompt, während Bild-zu-Bild 1–8 Referenzbilder benötigt und darauf aufbauend bearbeitet oder kombiniert. Ihre Eingabe-Schemas unterscheiden sich, daher sind die Request-Bodies nicht austauschbar.