Wie verwendet man die FLUX.2 Text-to-Image API? Parameter, Code und ein echtes generiertes Bild

TL;DR

• Der Modellname von FLUX.2 Pro Text-to-Image bei HiAPI ist flux-2/text-to-image, von Black Forest Labs. Stärken sind Prompt-Treue und Text im Bild. Öffne die Modellseite, um es direkt online auszuprobieren.
• Abrechnung nach Auflösungsstufe: 0,5 MP $0,0375, 1 MP (Standard) $0,05, 2 MP $0,075, 4 MP $0,125. Das Seitenverhältnis beeinflusst den Preis nicht.
• Der schnellste Weg: POST /v1/tasks mit prompt senden, bis success pollen, dann output[0].url herunterladen. Der Wert von resolution enthält ein Leerzeichen und muss als "1 MP" geschrieben werden.

Zuerst ein echtes generiertes Bild

Das folgende Bild wurde mit der Anfrage aus diesem Artikel generiert, 2 MP, 16:9:

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

Mit diesem Prompt generieren → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0,075. Das „API ready“ auf dem Notizbuch ist korrekt geschrieben, im Bild gibt es keinen überflüssigen Text.

Parameter auf einen Blick

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	String	Wichtige Elemente an den Satzanfang stellen, 30–80 englische Wörter liefern die besten Ergebnisse
aspect_ratio	Nein	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, Standard 1:1	Bei custom zusammen mit width / height verwenden
resolution	Nein	0.5 MP / 1 MP / 2 MP / 4 MP, Standard 1 MP	Bestimmt den Preis; bei custom ignoriert
width / height	Nur bei custom	256–2048	Wird automatisch auf ein Vielfaches von 16 gerundet
output_format	Nein	webp (Standard) / jpg / png
output_quality	Nein	0–100, Standard 80	Wirkt nur bei webp, jpg
seed	Nein	Ganzzahl	Nach Fixierung lässt sich dasselbe Ergebnis reproduzieren
safety_tolerance	Nein	1–5, Standard 2	1 ist am strengsten

Die Parameter werden strikt validiert: Wird ein zusätzliches Feld übergeben, das nicht in der Dokumentation steht, wird direkt HTTP 400 zurückgegeben (additional properties ... not allowed). Dieser Endpunkt nimmt nur Text entgegen; um mit Referenzbildern Bilder zu bearbeiten, verwende flux-2/image-to-image.

curl: Das erste Bild erfolgreich generieren

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

Die Antwort enthält nur data.taskId, das Bild ist noch nicht generiert. Frage GET /v1/tasks/{taskId} ab; sobald status zu success wird, lade das Bild von output[0].url herunter.

Python: Senden, Pollen, Herunterladen

# pip install requests; export HIAPI_KEY=你的 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):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "flux-2/text-to-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 wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

Was kostet es

Auflösung	Pro Bild	100 Bilder
0.5 MP	$0,0375	$3,75
1 MP (Standard)	$0,05	$5,00
2 MP	$0,075	$7,50
4 MP	$0,125	$12,50

Aktueller HiAPI-Preis, geprüft am 18. Oktober 2026.

Seitenverhältnis, seed und Ausgabeformat beeinflussen den Preis nicht, es zählt nur die Auflösungsstufe. Fehlschläge werden nicht berechnet. Günstiger geht es mit FLUX.2 [klein] 4B: 1 MP kostet $0,00143 pro Bild, den Vergleich aller Stufen findest du unter FLUX.2 API-Preise.

Vor dem Produktivbetrieb beachten

• resolution enthält ein Leerzeichen: Schreibe "1 MP", nicht "1MP" oder "1K"; bei einem Fehler wird 400 zurückgegeben und die möglichen Werte werden aufgelistet.
• Bei custom-Größen wird resolution ignoriert: Wenn aspect_ratio auf custom gesetzt ist, wird nach width × height generiert.
• Für Reproduzierbarkeit seed fixieren: Gleicher Prompt, gleicher seed ergeben weitgehend identische Ergebnisse, praktisch für den Vergleich beim Feinjustieren der Formulierung.
• Ergebnisse sofort speichern: output[0].url hat eine Gültigkeitsdauer; nach dem Herunterladen im eigenen Speicher ablegen.
• Callback statt Polling verwenden: Auf derselben Ebene wie input "callback": {"url": "https://your-app.example.com/hiapi/callback"} hinzufügen und nach taskId deduplizieren.

Häufige Fragen

Muss resolution angegeben werden?

Nein, Standard ist 1 MP. Es wird jedoch empfohlen, es jedes Mal anzugeben, um Verwechslungen mit 4 MP zu vermeiden.

Kann man Referenzbilder übergeben?

Über diesen Endpunkt nicht. Für Bildbearbeitung mit Referenzbildern und die Kombination mehrerer Bilder verwende flux-2/image-to-image, bis zu 8 Referenzbilder; fertige Prompts findest du unter FLUX.2 Bearbeitungs-Prompts.

Warum wird „additional properties not allowed“ zurückgegeben?

Es wurde ein Feld übergeben, das dieses Modell nicht kennt, etwa strength oder prompt_upsampling. Verwende nur die Felder aus der obigen Parametertabelle.

Wie wählt man zwischen FLUX.3 Image und FLUX.2 Pro?

FLUX.3 Image generiert und bearbeitet Bilder mit einem einzigen Modellnamen, kann 4K ausgeben und bis zu 10 Referenzbilder verarbeiten; FLUX.2 Pro bietet seed und benutzerdefinierte Breite/Höhe, 4 MP kosten nur $0,125. Den Vergleich mit demselben Prompt findest du unter FLUX.3 Image vs FLUX.2.

Kopiere den obigen Schreibtisch-Prompt und generiere dein erstes Bild auf der Modellseite.