WaveSpeedAI

So verwenden Sie die Z-Image-Turbo-API auf WaveSpeed (Schritt-für-Schritt-Anleitung)

So verwenden Sie die Z-Image-Turbo-API auf WaveSpeed (Schritt-für-Schritt-Anleitung)

Ein kleines Ding hat mich hierher gebracht. Ich bin Dora. An jenem Tag brauchte ich einen sauberen Produktshot für eine Landing-Page-Variation, und meine üblichen Bild-Tools fühlten sich schwerer an als die Aufgabe. Ich hörte immer wieder von der Z-Image-Turbo​ ​​​API​. Nicht die lauten Erwähnungen, eher dass sie stillschweigend in Changelogs und Engineering-Notizen auftauchte. Also habe ich es versucht.

Ich habe es eine Woche lang Ende Januar 2026 verwendet, hauptsächlich um einfache Marketing-Visuals und ein paar Konzept-Texturen für einen Prototyp zu generieren. Nichts Besonderes. Ich wollte sehen, wo es passt, ohne meinen Tech-Stack umzugestalten. Hier ist, was geholfen hat, was nicht, und wie ich es angebunden habe, ohne ein Durcheinander zu schaffen.

Voraussetzungen

WaveSpeed-Konto erstellen

Ich begann mit der Erstellung eines WaveSpeed-Kontos. Der Ablauf war einfach: E-Mail, Passwort, Verifizierung. Keine Überraschungen. Mir gefällt, dass das Dashboard mich nicht versucht hat, etwas zu verkaufen, bevor ich testen konnte.

Holen Sie sich Ihren API-Schlüssel

Nach der Anmeldung ging ich zum Developer-Bereich und generierte einen Schlüssel. Ich beschriftete ihn für mein Test-Projekt und speicherte ihn in meiner lokalen .env-Datei. Eine kleine Anmerkung: Ich erstellte später einen zweiten Schlüssel für Staging. Schlüssel nach Umgebung zu trennen, sparte mir Vermutungen an, welche Aufrufe mein kostenpflichtiges Abonnement betrafen.

API-Grundlagen

Endpoint-URL-Struktur

Ich habe einen einzigen Generate-Endpoint für die meisten Fälle verwendet. Das Muster sah so aus:

  • Basis: api.wavespeed.ai
  • Versionierter Pfad: /v1
  • Produkt-Pfad: /z-image-turbo
  • Aktion: /generate

Also sah eine typische URL wie /v1/z-image-turbo/generate aus. Ich vermeide es, Versionen hartcodiert zu setzen, da sie sich ändern. Ich habe die Basis und Version in die Config gelegt, damit ich sie später aktualisieren kann, ohne Aufrufe umzuschreiben.

Authentifizierungs-Header-Setup

Auth war ein Standard-Bearer-Token. Was geholfen hat, war, das Header-Setup zentral zu halten:

  • Authorization: Bearer IHR_API_SCHLÜSSEL
  • Content-Type: application/json

Ich habe zuerst mit einem kleinen Timeout (10s) getestet und dann erhöht. Wenn der Service belastet ist, kann die Bildgenerierung länger dauern als ein typischer REST-Aufruf. Besser, es einzuplanen, als aggressiv erneut zu versuchen und Rate Limits zu treffen.

Wichtige Parameter erklärt

prompt, Effektive Prompts schreiben

Ich bin kein Prompt-Poet. Was hier geholfen hat, war einfache, wörtliche Sprache und ein klarer Style-Hinweis. Für Produktaufnahmen fand ich eine stabile Struktur:

  • Motiv: “ein matter schwarzer kabelloses Earbud auf weißem nahtlosem Hintergrund”
  • Winkel oder Objektiv: “45-Grad-Winkel, weiches Studio-Licht”
  • Kontext-Hinweise: “minimaler Schatten, keine Reflexionen”

Ich vermied es, Stile zu stapeln (“cinematisch, düster, redaktionell, glänzend”), weil die Bilder abdrifteten. Kurze, einfache Prompts gaben vorhersagbarere Ergebnisse.

Zwei Durchläufe halfen mir, zu iterieren:

  • Erster Durchlauf: breiter Prompt, um Komposition zu sehen.
  • Zweiter Durchlauf: Beschränkungen nur dort hinzufügen, wo nötig (Schattenlänge, Hintergrund-Textur).

size, Unterstützte Auflösungen (256-1536)

Ich verwendete meist quadratische und Hochformate. Die API akzeptierte gängige Werte von 256 bis 1536. Ich blieb bei 512 für schnelle Vorschau und 1024 für endgültige Assets. 1536 produzierte schöne Details, kostete aber mehr Zeit und Token. Wenn Sie viele Varianten generieren, beginnen Sie mit kleinen Größen und skalieren hoch, oder führen Sie ausgewählte Prompts mit höherer Größe erneut aus.

seed, Reproduzierbarkeits-Kontrolle

Seed war wichtiger als ich dachte. Wenn ich einen Look mochte, speicherte ich den Seed, damit ich nur eine Variable (wie Hintergrund-Dichte) anpassen konnte, ohne zu sehr abzudriften. Wenn ich den Prompt stark änderte, löschte ich den Seed, um nicht gegen die vorherige Verzerrung des Modells zu kämpfen. In der Praxis: Ich protokollierte Prompt, Größe und Seed pro Bild-ID. Es machte Re-Renders langweilig, auf gute Weise.

output_format, JPEG vs PNG vs WebP

  • JPEG: leicht und schnell. Gut für Vorschau und Web-Assets ohne Transparenz.
  • PNG: ​verlustfrei, größer. Ich verwendete es für UI-Overlays oder wenn ich eine saubere Kante brauchte.
  • WebP: ​ein solider Mittelweg. Kleiner als PNG, sauberer als aggressives JPEG.

Wenn ich batching durchführte, setzte ich Vorschau auf JPEG und Finales auf PNG oder WebP je nach Ziel. Format-Mischung in einem Durchlauf ist möglich, aber ich hielt es pro Job konsistent, um die Buchführung zu reduzieren.

Code-Beispiele

cURL Quick Start Hier ist der kürzeste Weg, den ich verwendet habe, um den Endpoint zu überprüfen. Ich mag es, mit cURL zu beginnen, weil es Fehlermeldungen offensichtlich macht.

Bash

curl -X POST https://api.wavespeed.ai/v1/z-image-turbo/generate \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a matte black wireless earbud on a white seamless background, soft studio lighting",
    "size": 1024,
    "seed": 12345,
    "output_format": "webp",
    "enable_sync_mode": true
  }' \
  --output preview.webp

Wenn Sync-Modus aktiviert und unterstützt für Ihre Anfrage ist, gibt die Antwort binäre Bilddaten oder ein base64-Feld zurück (hängt von Headers und Server-Einstellungen ab). Ich speicherte es während Tests direkt in einer Datei.

Python-Implementierung Ich hielt die Python-Version einfach. Requests, ein Timeout und grundlegende Fehlerprüfungen.

Python

import os
import requests
import base64

API_KEY = os.getenv("WAVESPEED_API_KEY")
URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate"

payload = {
    "prompt": "cozy reading nook by a window, soft morning light, minimalist",
    "size": 1024,
    "output_format": "png",
    "enable_sync_mode": True,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()

# Some deployments return JSON with base64. Others return binary directly.
content_type = resp.headers.get("Content-Type", "")
if "application/json" in content_type:
    data = resp.json()
    img_b64 = data.get("image_base64")
    if not img_b64:
        raise RuntimeError("No image in response")
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(img_b64))
else:
    with open("output.png", "wb") as f:
        f.write(resp.content)

print("Saved output.png")

JavaScript/Node.js Beispiel In Node bevorzuge ich fetch mit AbortController für Timeouts.

JavaScript

import fetch from 'node-fetch';
import { writeFileSync } from 'fs';

const API_KEY = process.env.WAVESPEED_API_KEY;
const URL = "https://api.wavespeed.ai/v1/z-image-turbo/generate";

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);

const payload = {
  prompt: "abstract paper texture, soft fibers, off-white, subtle grain",
  size: 512,
  output_format: "jpeg",
  enable_sync_mode: true,
};

try {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });

  if (!resp.ok) {
    throw new Error(`${resp.status} ${resp.statusText}`);
  }

  const buffer = Buffer.from(await resp.arrayBuffer());
  writeFileSync("out.jpg", buffer);
  console.log("Saved out.jpg");
} catch (err) {
  console.error("Request failed:", err.message);
} finally {
  clearTimeout(timeoutId);
}

Asynchron vs Synchron-Modus

enable_sync_mode erklärt

Wenn enable_sync_mode wahr war, kamen kleine Bilder (512–1024) oft in einem Durchgang an. Das war schön für Vorschau und Einzelaufträge. Aber Sync-Modus zeitgesteuert unter schwerer Last oder größeren Größen. Wenn ich auf diese Grenze traf, gab die API stattdessen eine Job-ID zurück.

Abfragen nach Ergebnissen

Async brauchte eine Sekunde zum Anverbinden, dann war es ok. Der Ablauf:

  • POST eine Generate-Anfrage mit enable_sync_mode auf false gesetzt (oder einfach weglassen).
  • Erhalten Sie eine job_id im JSON.
  • Fragen Sie einen Status-Endpoint alle 1–2 Sekunden mit exponentiellem Backoff ab.
  • Wenn Status erledigt ist, laden Sie das Bild von der bereitgestellten URL herunter.

Ich begrenzte Polling auf ~30 Sekunden, bevor ich anmutig fehlschlug. In der Produktion würde ich auf einen Webhook wechseln, wenn der Service ihn anbietet. Polling funktioniert, aber es ist nicht romantisch.

Fehlerbehandlung

Häufige Fehler-Codes

Was ich während Tests sah:

  • 400: ein schlechtes Feld (Größe außer Bereich, unbekanntes Format). Korrigieren Sie Ihre Last.
  • 401: fehlender oder ungültiger Bearer-Token. Überprüfen Sie den Header und die Schlüsselreichweite.
  • 404: falscher Endpoint-Pfad oder Job nicht gefunden (normalerweise ein Tippfehler).
  • 429: Rate Limit. Sichern Sie ab und versuchen Sie es später erneut.
  • 500/503: vorübergehendes Service-Problem. Erneut versuchen mit Jitter.

Ich protokollierte Response-Körper, weil sie oft einen Hinweis in einfacher Sprache trugen, hilfreich, wenn Größe oder Seed abgelehnt wurden.

Best Practices für Rate Limiting

Ich verwendete einen Token Bucket auf dem Client, mit einer kurzen Warteschlange. Wenn die API 429 zurückgab, sicherte ich exponentiell ab und addierte zufälligen Jitter (50–200ms), um dröhnende Herden zu vermeiden. Auch Bündeln von Anfragen (siehe unten) reduzierte Spitzenlastausbrüche.

Produktions-Tipps

Batch-Verarbeitungsmuster

Das Generieren eines Bildes pro Anfrage fühlte sich einfach an, aber es verschwendete Overhead. Ich zog zu einer kleinen Batch-Größe (3–5 Prompts pro Stück) und bekam stabileren Durchsatz. Ich schrieb Ergebnisse in einen datierten Ordner mit einer manifest.json-Datei, die Prompt, Größe, Seed und Ausgabepfad speicherte. Dieses Manifest erwies sich als praktisch, wenn ein Stakeholder sagte: “Können wir das Gleiche machen, aber mit etwas wärmerer Beleuchtung?” Ich erhöhte einfach den Seed oder tweakte den Prompt und führte erneut aus.

Kostenoptimierung

Drei Dinge spielten eine Rolle:

  • Größe-Disziplin: Vorschau bei 512, Finalisierung bei 1024 nur bei Bedarf. 1536 nur für Zuschnitt-intensive Verwendung.
  • Format-Eignung: JPEG für Vorschau: WebP für die meisten Web-Builds: PNG, wenn Transparenz nicht verhandelbar ist.
  • Frühes Stoppen: Wenn die ersten Frames falsch aussahen, stoppte ich den Job, anstatt zu warten. Es sparte Pfennige, die sich aufsummieren.

Ein weiterer praktischer Hinweis: Ich setzte eine tägliche Ausgabenlimit in meinen Skripten. Nicht glamourös, aber es schützte mich vor einer auslaufenden Schleife.

Ein paar abschließende Beobachtungen. Die Z-Image-Turbo API fühlte sich nicht magisch an. Das ist wahrscheinlich der Grund, warum ich sie mochte. Sie war stabil, sobald ich die Schutzvorrichtungen setzte: feste Seeds für Reproduzierbarkeit, kleine Batches, konservative Timeouts. Sync-Modus war nett für Vorschau: Async ergab für alles andere Sinn. Wenn Sie bereits in AI-Tools schwimmen, wird dieses eine nicht um Aufmerksamkeit schreien. Es sitzt stillschweigend in der Pipeline und macht seinen Job.

Ich bin immer noch neugierig, wie es laute Prompts bei höheren Auflösungen behandelt. Das ist ein Test für einen anderen Tag.