WAN 2.5 API Quickstart auf WaveSpeed: Authentifizierung, Parameter und Beispielanfragen

Hallo, ich bin Dora. Eigentlich hatte ich nicht geplant, diese Woche die WAN 2.5 API auf WaveSpeed auszuprobieren. Ein kleines Ärgernis trieb mich dazu: Ich brauchte ein paar konsistente Bildvariationen für einen Entwurf, und meine üblichen Tools waren entweder zu klickintensiv oder zu clever für ihren eigenen Nutzen. Ich wollte etwas Langweiliges und Zuverlässiges, etwas Skriptbares, Versioniertes, leicht Rückgängig Zu Machendes.

Also öffnete ich die Dokumentation, brühte mir Tee und schrieb ein winziges Skript zusammen. Das ist, was ich dabei notierte, getestet im Januar 2026, ohne Glanz. Es geht weniger um “Features” und mehr um die Teile, die die Arbeit leichter machten, sobald sie an ihrem Platz waren.

API-Übersicht

Wenn Sie jemals eine moderne KI-API berührt haben, wird WaveSpeed’s Herangehensweise an WAN 2.5 vertraut vorkommen. HTTP rein, JSON raus. Sie senden einen Prompt (und manchmal ein Bild), es gibt Ihnen entweder ein fertiges Artefakt oder eine Job-ID zurück, die Sie abfragen können.

Ein paar Basis-Details, auf die ich vor dem Schreiben von Code achtete:

Versionierung: WAN 2.5 wird als eine unterschiedliche Version bereitgestellt, was für Reproduzierbarkeit wichtig ist. Ich hielt mich an den expliziten Versionspfad in URLs statt zu einem “latest”-Alias. Diese kleine Entscheidung spart zukünftige mich vor lautlosen Verhaltensänderungen.
Modi: Einige Arbeitslasten sind synchron (klein, schnell), andere starten als Jobs. Wenn Sie höherauflösende Generierungen oder Batch-Arbeiten durchführen, erwarten Sie einen asynchronen Fluss mit einem Status-Endpoint oder Webhooks.
Formate: JSON-Antworten enthalten normalerweise einen Status, eine Asset-URL oder Base64-Payload und einige Metadaten (Seed, Schritte, Timing). Ich behalte die Metadaten, praktisch, wenn Sie später einen Look reproduzieren möchten.
Limits: Bildgröße, Schrittanzahl und Concurrency sind begrenzt. Die Standardwerte reichten für Entwürfe, aber ich stieß an eine Grenze, als ich versuchte, die Auflösung zu erhöhen. Mehr zu Rate Limits unten.

Die Kurzfassung: Es ist ein gerader Weg, wenn Sie sich mit REST auskennen. Der Trick besteht darin, die wenigen langweiligen Bits (Keys, Parameter, Wiederholungen) richtig zu machen, damit Sie sie vergessen können.

Diese Einfachheit ist ein Teil davon, warum wir WaveSpeed so gebaut haben. Ich wollte, dass WAN 2.5 (und andere Modelle) sich skriptbar, versioniert und langweilig im besten Sinne anfühlen. Wenn Sie das selbst verdrahten, können Sie es hier erkunden.

Auth & Key

Ich habe einen WaveSpeed API-Schlüssel im Dashboard generiert und ihn in eine Umgebungsvariable eingefügt. Nichts Ausgefallenes, aber es sparte mir davor, Geheimnisse über Dateien zu jagen.

Besorgen Sie sich einen Schlüssel in Ihren Kontoeinstellungen auf WaveSpeed. Er ist an Ihre Organisation/Ihr Projekt gebunden.
Speichern Sie ihn lokal als Umgebungsvariable: WAVESPEED_API_KEY. Ich verwendete eine .env-Datei für die Entwicklung und den geheimen Speicher meiner CI für Durchläufe.
Verwenden Sie Bearer-Auth im Header: Authorization: Bearer $WAVESPEED_API_KEY.
Wenn Sie Schlüssel rotieren, tun Sie dies während der Schwachlastzeiten. Ich habe das auf stille Weise gelernt, als eine zeitgesteuerte Rotation einen langen Job unterbrach.

Wenn Ihr Team begrenzte Schlüssel benötigt, überprüfen Sie die Dashboard-Einstellungen. Ich bevorzuge den Least-Privilege-Weg für alles, das an eine Automatisierung gebunden ist. Ein kleines Friktionsproblem: Wenn Sie von mehreren Maschinen aus arbeiten, beschriften Sie Schlüssel deutlich nach Host oder Service, hilft beim späteren Audit der Nutzung.

Erforderliche Parameter

Exakte Namen können je nach Endpoint unterscheiden, aber hier ist die minimale Form, die ich für Wan 2.5 auf WaveSpeed verwendete. Behandeln Sie diese als Skelett, bestätigen Sie die Feldnamen in der offiziellen Dokumentation für Ihr Konto.

model: Ich setze das explizit auf wan-2.5 (oder den nächsten exakten String in Ihrem Plan). Es hält das Verhalten über Updates stabil.
input: Eine Prompt-Zeichenkette. Ich hielt sie kurz und konkret. WAN antwortet tendenziell besser auf klare, einfache Formulierungen als auf Adjektiv-Suppe.
mode oder task: Bildgenerierung versus Variation/Hochskalierung. Wenn Sie ein Quellbild übergeben, ist dies wichtig.
output: Ich forderte standardmäßig eine Bild-URL an. Base64 ist vorhanden, aber URLs sind speicherfreundlicher.

Wenn ich vergaß, das Modell explizit zu setzen, erhielt ich einen sinnvollen Standard, aber meine Ergebnisse verschoben sich subtil über Durchläufe. Nicht falsch, nur nicht reproduzierbar. Das Sperren der Version entfernte dieses Wackeln.

Optionale Parameter

Hier sitzt die echte Kontrolle. Ich berührte am ersten Tag nur eine Handvoll.

seed: Ich schalte dies ein, sobald mir ein Look gefällt. Es stabilisiert die Atmosphäre für Variationen.
steps: Höhere Schritte können Detail auf Kosten von Zeit und Credits vorantreiben. Ich erhöhte in kleinen Inkrementen (z. B. 24 → 32) und beobachtete Rückgaben.
guidance oder cfg_scale: Strafft die Einhaltung des Prompts. Zu hoch und es wird spröde.
size oder resolution: Hier springen die Kosten. Ich entwerfe klein, dann mache Finales in Zielgrößen erneut.
image: Für Variationen eine Quellbild-URL übergeben oder hochladen. Koppeln Sie mit einem Strength-Parameter, falls unterstützt.
safety oder moderation flags: Lassen Sie sie an, es sei denn, Ihr Workflow benötigt wirklich eine benutzerdefinierte Handhabung.
user oder metadata: Ich füge eine Request-ID oder Projekt-Tag hinzu, um Durchläufe später in Protokollen nachzuverfolgen.

Kleine Beobachtung: Das Ändern von zwei Knöpfen gleichzeitig machte es schwer zu sagen, was half. Ich änderte eine Sache pro Durchlauf und hielt Notizen in Kommentaren. Altmodisch, aber es funktionierte.

Beispiel-Request-Muster

Ich versuchte drei einfache Formen: einen schnellen Curl, ein winziges Python-Skript und einen Background-Job für Async.

Synchroner Entwurf (curl)

Das reichte aus, um meinen Schlüssel und Prompt vor dem Verdrahten von etwas anderem zu überprüfen.

Beispiel-Endpoint, bestätigen Sie den exakten Pfad in der Dokumentation für Ihr Konto und Ihre Region:

POST https://api.wavespeed.ai/wan/v2.5/generations

Headers:

Authorization: Bearer $WAVESPEED_API_KEY
Content-Type: application/json

Body (minimal):

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

Worauf ich achtete:

200 mit Ergebnis und Metadaten → Sie sind in Ordnung.
202 mit einer Job-ID → Schalten Sie auf asynchronen Fluss um.
4xx → Etwas in der Payload oder Auth ist falsch.

Kleiner Python-Helfer

Ich schrieb eine winzige Funktion, um Header, Timeouts und JSON zu handhaben. Sie gab entweder eine URL zurück oder warf eine saubere Ausnahme. Nichts Magisches, nur die Art von Wrapper, über die man nicht zweimal nachdenkt.

Praktische Bits:

Setzen Sie einen kurzen Connect-Timeout und einen etwas längeren Read-Timeout.
Handhabe 429 mit Wiederholung und Jitter.
Protokollieren Sie den Seed, die Schritte und die Größe für jeden Durchlauf.

Asynchroner Fluss (Jobs)

Für größere Bilder oder Batches erhielt ich eine 202 und eine Job-ID. Die Schleife war einfach:

POST-Job,

Fragen Sie GET /jobs/{id} alle paar Sekunden ab,
Stoppen Sie bei Endzustand (erfolgreich/fehlgeschlagen),
Rufen Sie Asset-URL ab.

Wenn Ihr Stack Webhooks mag, WaveSpeed exponiert auch Callbacks. Ich blieb zuerst beim Abfragen, es ist ein weniger beweglicher Teil während des Setups.

Fehlercodes

Ich hielt neben meinem Editor eine kleine Karte. Es zahlte sich schneller aus als erwartet.

400 Bad Request: Normalerweise ein Feldname oder Typ-Mismatch. Ich habe einmal die Größe als Zeichenkette, nicht als Objekt gesendet. Die Behebung war offensichtlich, sobald ich langsamer wurde und die Nachricht las.
401 Unauthorized: Schlüssel fehlt oder ist fehlgebildet. Überprüfen Sie Ihren Bearer-Header und nachfolgende Leerzeichen.
403 Forbidden: Schlüssel existiert, aber hat keinen Umfang für den Endpoint oder Modell-Tier.
404 Not Found: Falscher Endpoint-Pfad oder eine Job-ID, die abgelaufen ist.
409 Conflict: Sie sehen dies manchmal, wenn Sie einen Job aktualisieren, der bereits beigelegt hat. Fragen Sie erneut ab, hören Sie nicht auf zu drücken.
429 Too Many Requests: Sie sind über ein Pro-Minute oder Pro-Org Limit hinaus. Weichen Sie mit exponentiellen Wiederholungen aus.
500/503 Server Errors: Selten in meinen Tests, aber planen Sie für sie ein. Eine kurze Wiederholungsschleife hielt meine Skripte ruhig.

Kleine Gewohnheit, die half: Ich habe den Fehlercode und die Request-ID (falls vorhanden) in meine Protokolle eingebracht. Wenn etwas Seltsames auftritt, kann der Support diese ID verwenden, um sie nachzuverfolgen.

Rate Limits

Ich stieß auf Rate Limits, als ich mit Concurrency faul wurde. Leicht zu tun, leichter zu vermeiden.

Was funktionierte:

Respektieren Sie die Headers: Viele Endpoints geben Rate-Header zurück (z. B. verbleibend, Reset-Zeit). Headernamen können variieren, überprüfen Sie die Dokumentation, aber sie sind es wert, gelesen zu werden.
Verwenden Sie einen Token-Bucket oder einfache Warteschlange. Ich beschränkte meine Skripte auf einen kleinen, stetigen Tropfen statt Bursts. Das System atmete leichter, und ich auch.
Trennen Sie Entwürfe von Finales. Entwürfe können klein und schnell laufen: Finales können einzeln im Hintergrund laufen.
Cache-Wiederholungen. Wenn Sie Prompts testen, behalten Sie frühere Ergebnisse für ein paar Minuten, damit Sie nicht denselben Anruf verbrennen.

Ich baute auch einen sehr schlichten Backoff: Basis-Verzögerung von 1s, Verdoppelung bei jedem 429, mit einer Obergrenze von 30s und maximal 4 Wiederholungen. Es fühlte sich unhurried an und vermied Dogpiling des Service.

Kostengarantien

Das war meine Hauptsorge. Bildarbeit kann Credits im Hintergrund knabbern, während Sie Tee trinken.

Ein paar Schutzmaßnahmen, die ich am ersten Tag setzte:

Budget-Caps im Dashboard: Ich setzte eine monatliche Obergrenze und Email-Benachrichtigungen ein Stück darunter. Wenn Ihr Team einen Schlüssel teilt, helfen Benachrichtigungen, Schleifen früh zu fangen.
Pro-Request-Obergrenzen: Ich zwang Größe und Schritte, unter einem Max zu leben, es sei denn, ich übergab ein Override-Flag. Es sparte mich vor “Oops, 4K alles.”
Draft-First-Workflow: Ich führe kleine Vorschauversionen aus (niedrigere Auflösung, weniger Schritte) und nur das Hochskalieren der Keeper. Dies schnitt meine Ausgaben am ersten Nachmittag um mehr als die Hälfte.
Seed-Disziplin: Sobald ich eine Richtung gefunden hatte, die mir gefiel, fixierte ich den Seed und änderte einen Parameter nach dem anderen. Weniger blinde Durchläufe: mehr absichtliche.
Protokolle mit Kosten: Wenn die Antwort ein Kredit- oder Nutzungsfeld enthält (einige Endpoints tun dies), speichern Sie es. Wenn nicht, schätzen Sie basierend auf Auflösung und Schritte und notieren Sie, dass es eine Schätzung ist.

Ich habe auch einen Soft-Kill-Switch in meine Skripte eingefügt: Wenn die Tagesnutzung eine Schwelle überschreitet, neue Jobs pausiert und eine Nachricht auf Slack gesendet. Es ist nicht elegant, aber es ist ehrlich über Einschränkungen.

Dies sparte zuerst nicht die Zeit. Es sparte Aufmerksamkeit. Nach ein paar Durchläufen verblassten die Schutzvorrichtungen in den Hintergrund, und ich konnte wieder über die Arbeit nachdenken statt über den Zähler.