Recraft V4.1 API verwenden? In 5 Minuten Farbschema und Bildgenerierung zum Laufen bringen

TL;DR

• Die Recraft V4.1-Serie ist ein Paar von Text-zu-Bild-Modellen mit vollständig identischen Parametern: recraft-v4.1/text-to-image liefert detailreichere Endfassungen ($0.05/Bild), recraft-v4.1-flash/text-to-image schnelle Entwürfe ($0.01/Bild, vollständige Preise auf der Preisseite), der Unterschied ist nur das Feld model. Modellseite öffnen und ausprobieren, neue Nutzer erhalten bei der Registrierung 200 Credits.
• Das Besondere ist die Markenfarbpalette: colors übergibt eine Gruppe von RGB-Werten, das Bild fällt möglichst in diese Farben (im Playground derzeit nicht verfügbar, nur über die API).
• Aufruf über die HiAPI-/v1/tasks-Schnittstelle: Aufgabe absenden und taskId erhalten, dann Ergebnis abfragen, nach Erfolg von output[0].url herunterladen.

Was es kann

• Fotografie, Illustration und Poster: realistische Produktbilder, flache Vektorillustrationen, Poster mit Überschrift – eine Beschreibung genügt.
• Kontrollierbare Farben: colors legt die Palette fest, background_color die Hintergrundfarbe, damit Markenmaterialien dem VI treu bleiben.
• 6 Größen-Presets: square_hd (Standard), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, keine benutzerdefinierten Breiten/Höhen.
• Flash für Entwürfe + V4.1 für die Endfassung: gleiche Parameter, nur model tauschen, 10 Entwürfe plus 1 Endfassung für $0.15.

Hier ein echtes Ergebnis von V4.1:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(Auf Deutsch: minimalistisches Markenposter für eine Specialty-Kaffeemarke, riesige fette serifenlose Überschrift "NORTH BEAN", warme Terrakotta- und Cremefarbpalette, Illustration einer einzelnen Kaffeebohne, viel Negativraum, Schweizer Rasterlayout. Größe: portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, Beispielbild in diesem Artikel 896×1216, $0.05.

Mit diesem Prompt generieren →

Wie man die beiden Modelle wählt

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Pro Bild	$0.01	$0.05
Positionierung	Schnelle Entwürfe, Richtung auswählen	Detailreichere Endfassung
Parameter	Vollständig identisch (prompt / image_size / colors / background_color)	Wie links
Geeignet für	Massenexploration, Social-Media-Bilder, Entwurfsrunden	Abgabefassungen, Markenmaterialien

Beide Modelle laufen in derselben Pipeline: Flash liefert 10 Richtungen für $0.10, die ausgewählte wird durch Wechsel von model als V4.1-Endfassung für $0.05 neu erzeugt, ein Durchlauf kostet $0.15. Umgekehrt bei reinen Skizzen durchgehend Flash, 1.000 Bilder kosten nur $10.00. Prompts nach Szenario findest du im Prompt-Kompendium.

Zwei Einstiegswege

Browser in 3 Schritten: Modellseite öffnen → Prompt einfügen, Größe wählen → Generieren klicken, ein V4.1-Bild kostet $0.05. (colors und background_color erfordern die API.) Beim ersten Mal empfiehlt es sich, zuerst im Browser ein Bild zu erzeugen und den Stil zu bestätigen, bevor man Code schreibt.

API in 3 Schritten: POST /v1/tasks absenden → taskId erhalten → mit GET /v1/tasks/<taskId> auf success prüfen und herunterladen.

curl: das erste Bild (mit Markenfarben)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Dies verwendet die echten Parameter des Flash-Beispiels: eine dreifarbige Palette aus Dunkelblau, Orange und Weizen mit cremeweißem Hintergrund. Für die Endfassung model auf recraft-v4.1/text-to-image ändern, der Rest bleibt gleich.

Python: absenden, abfragen, herunterladen

import time, uuid, requests

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

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # temporäre Adresse, so schnell wie möglich herunterladen und speichern
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Parametertabelle (für beide Modelle identisch)

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	1–10000 Zeichen	Bildbeschreibung
image_size	Nein	square_hd (Standard) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 Presets, keine benutzerdefinierten Breiten/Höhen
colors	Nein	Array von RGB-Objekten, Kanäle je 0–255	Starke Palettensteuerung: Bild fällt möglichst in diese Farbgruppe; im Playground derzeit nicht verfügbar
background_color	Nein	Ein einzelnes RGB-Objekt	Hintergrundfarbe; im Playground derzeit nicht verfügbar

Jedes RGB-Objekt erfordert alle drei Schlüssel r/g/b, je 0–255, keine zusätzlichen Schlüssel. Felder außerhalb der Tabelle im Request-Body führen direkt zu 400.

Fehler, die dir begegnen (Originalwortlaut der Schnittstelle)

Was du getan hast	Rückgabe
prompt nicht übergeben	400 invalid input: prompt: missing required field "prompt"
image_size als Breiten-/Höhenobjekt übergeben	400 invalid input: image_size: got object, want string
colors-Kanal auf 256 gesetzt	400 invalid input: colors.0.r: maximum: got 256, want 255
colors fehlt der Schlüssel b	400 invalid input: colors.0.b: missing required field "b"
colors als String übergeben	400 invalid input: colors: got string, want array
RGB-Objekt mit einem zusätzlichen Schlüssel	400 invalid input: colors.0: additional properties 'a' not allowed
Unzureichendes Guthaben	402 insufficient account balance; top up and retry
Wiederholtes Absenden mit demselben Idempotency-Key gibt 409 oder 422 zurück, neuen Key verwenden und erneut versuchen.

Vor dem Go-Live beachten

• Callback: im Request-Body auf oberster Ebene "callback": {"url": "https://..."} übergeben, bei Endstatus wird automatisch benachrichtigt.
• Rechtzeitig sichern: output[0].url ist eine temporäre Adresse, sofort nach Erhalt herunterladen und im eigenen Speicher ablegen, nicht als永久-Link verwenden.
• Farben sind Steuerung, keine Sperre: Wenn der Prompt Farben enthält, die mit colors kollidieren, kann das Ergebnis beides mischen; für strenge Farbtreue keine anderen Farben im Prompt angeben.
• Flash→V4.1 nur model tauschen: Alle anderen Parameter bleiben unverändert, das Kompositionskonzept lässt sich direkt wiederverwenden.

Häufige Fragen

Sind die Parameter der beiden Modelle gleich?

Vollständig gleich. Nur das Feld model tauschen, null Codeänderung.

Wo setzt man den colors-Parameter?

Nur über die API. Der Playground bietet die Parameter colors und background_color derzeit nicht an.

Garantiert colors, dass nur die angegebenen Farben verwendet werden?

Nein. Es ist eine starke Steuerung, das Bild fällt möglichst in diese Farbgruppe, aber keine harte Sperre.

Wie viele Bilder pro Aufruf?

1 Bild pro Aufruf. Für mehrere Bilder mehrere Aufgaben absenden oder einreihen.

Wie viele Bilder für $10?

Flash kostet $0.01 pro Bild, $10 ergeben 1.000 Bilder. Fehlschläge werden nicht berechnet.

Nächster Schritt: Mit dem NORTH BEAN-Prompt auf der Modellseite ein Bild erzeugen, bei Markenfarben colors in den API-Request aufnehmen; Szenario-Vorlagen im Prompt-Kompendium.