Wie verwende ich die FLUX.3 Image API? In 5 Minuten zum ersten Bild

TL;DR

• FLUX.3 Image ist ein Bildmodell von Black Forest Labs, veröffentlicht im Oktober 2026, Modellname flux-3-image. Ein Modellname deckt sowohl Text-zu-Bild als auch Bildbearbeitung ab; bei der Bearbeitung können bis zu 10 Referenzbilder übergeben werden. Modellseite öffnen und direkt online testen.
• Abrechnung pro Bild: 1K (Standard) $0.048, 2K $0.10, 4K $0.607, bis 31. Oktober 20 % Rabatt auf alle Stufen. Jede Aufgabe erzeugt 1 Bild.
• Der schnellste Weg: POST /v1/tasks mit prompt senden, bis success pollen, output[0].url herunterladen. resolution immer explizit angeben, und sowohl fail als auch failed als Fehlerstatus prüfen.

Was ist FLUX.3 Image und was ist neu?

• Bildgenerierung und Bildbearbeitung mit einem Modellnamen. Ohne image_urls ist es Text-zu-Bild; mit 1–10 Referenzbildern wird rund um die Referenzbilder bearbeitet, wobei im Prompt klar angegeben wird, welche Rolle jedes Bild spielt.
• Fünf Auflösungsstufen: 768 ($0.041) bis 4K ($0.607); 15 Seitenverhältnisse von 21:9 bis 9:21, zusätzlich auto.
• Websuche ergänzt Details. grounding ist standardmäßig aktiviert und kann vor der Generierung Webseiten und Bilder durchsuchen, um Bildinformationen zu ergänzen.
• Platz 9 in der Text-zu-Bild-Rangliste von Artificial Analysis.

1.5K, 3:2 Innenraumaufnahme:

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

Mit diesem Prompt generieren → (1.5K, 3:2)

flux-3-image, 1.5K, 3:2, $0.07.

Zwei Einstiegswege

Online testen (ohne Code):

1. FLUX.3 Image Modellseite öffnen und anmelden (neue Nutzer erhalten bei Registrierung 200 Credits).
2. Prompt einfügen, Auflösung und Seitenverhältnis wählen, bei Bedarf Referenzbilder hochladen.
3. Auf Generieren klicken und das Ergebnis herunterladen.

API-Aufruf:

1. Im Konsolen-Dashboard einen API Key erstellen.
2. POST /v1/tasks mit "model": "flux-3-image".
3. GET /v1/tasks/{taskId} pollen oder Callback empfangen und output[0].url speichern.

curl: das erste Bild generieren

1K, 4:3, $0.048:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

Die Antwort enthält data.taskId. GET /v1/tasks/{taskId} pollen, sobald status zu success wird, output[0].url herunterladen.

Python: Senden, Pollen, Herunterladen

# pip install requests; export HIAPI_KEY=dein Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # Bei erneutem Senden derselben Anfrage denselben Idempotency-Key wiederverwenden, damit nur einmal abgerechnet wird
    r = requests.post(API, json={"model": "flux-3-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # nach dem zurückgegebenen Dateityp speichern
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

Bildbearbeitung mit Referenzbildern

image_urls übergeben (1–10 öffentliche Links) und im Prompt klar angeben, was jedes Bild liefert und was nicht übernommen werden soll. Das folgende Bild ist eine Komposition aus drei Bildern: Bild 1 liefert das Motiv, Bild 2 die Szene, Bild 3 nur die Farbpalette.

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # Bild 1: Motiv
        "https://your-cdn.example.com/cabin.jpg",    # Bild 2: Szene
        "https://your-cdn.example.com/street.jpg",   # Bild 3: nur Farbpalette
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, drei Referenzbilder, 3:2, $0.048. Referenzbilder kosten keinen Aufpreis.

Parameter-Kurzübersicht

Feld	Wert	Beschreibung
prompt	Zeichenkette, erforderlich, max. 5000 Zeichen	Bild beschreiben oder angeben, was geändert und was erhalten bleiben soll
image_urls	1–10 öffentliche Links, optional	Ohne Angabe Text-zu-Bild
resolution	768 / 1K / 1.5K / 2K / 4K, Standard 1K	Bestimmt den Preis; tatsächliche Breite und Höhe hängen vom Seitenverhältnis ab
aspect_ratio	21:9 2:1 16:9 3:2 7:5 4:3 5:4 1:1 4:5 3:4 5:7 2:3 9:16 1:2 9:21 auto, Standard auto	Für feste Platzierungen das Verhältnis explizit wählen
safety_tolerance	0–4, Standard 2	0 ist am strengsten
grounding	Boolesch, Standard true	Vor der Generierung Webseiten und Bilder durchsuchen

Hinweise vor dem Produktivbetrieb

• resolution immer angeben. Ein versehentliches 4K hebt den Preis pro Bild von $0.048 auf $0.607.
• Sowohl fail als auch failed prüfen. Die Dokumentation nennt failed, beide zu prüfen ist sicherer.
• Callback statt Polling verwenden: auf gleicher Ebene wie input "callback": {"url": "https://your-app.example.com/hiapi/callback"} hinzufügen und nach taskId deduplizieren.
• Ergebnisse sofort speichern. output[0].url ist zeitlich begrenzt gültig; rechtzeitig herunterladen oder beim Erstellen der Aufgabe dauerhafte Speicherung wählen.
• Den Idempotency-Key-Header mitsenden, damit bei Wiederholungen mit demselben Key nur eine Aufgabe erstellt wird.

Häufige Fragen

Wie viele Bilder pro Aufgabe?

1 Bild. Für mehrere Varianten separate Aufgaben senden.

Kann man PNG oder JPEG wählen?

Dieses Modell bietet keine Formatwahl. Wird ein bestimmtes Format benötigt, nach dem Herunterladen konvertieren.

Wann die Websuche deaktivieren?

Wenn eigene Referenzbilder vorliegen und die kreative Richtung feststeht. grounding: false setzen, der Preis bleibt gleich.

Wird bei fehlgeschlagener Generierung abgerechnet?

Nein. Es wird nur bei erfolgreicher Bilderzeugung abgerechnet.

Die Preise der einzelnen Stufen finden sich unter FLUX.3 Image API Preise, weitere Prompts unter FLUX.3 Image Prompt-Beispiele, ein Vergleich mit der Vorgängergeneration bei gleichem Prompt unter FLUX.3 Image vs FLUX.2. Alternativ direkt auf der Modellseite diese Zedernholzhütte generieren.