Guide de démarrage rapide de l'API WAN 2.5 sur WaveSpeed : Authentification, paramètres et exemples de requêtes

Bonjour, je suis Dora. À l’origine, je n’avais pas prévu d’essayer l’API WAN 2.5 sur WaveSpeed cette semaine. Un petit tracas m’a poussée à le faire : j’avais besoin de quelques variations d’image cohérentes pour un brouillon, et mes outils habituels étaient soit trop manuels, soit trop intelligents pour leur propre bien. Je voulais quelque chose de simple et fiable, scriptable, versionné, facile à revenir en arrière.

J’ai donc ouvert la documentation, je me suis préparé un thé, et j’ai câblé un petit script. Voici ce que j’ai noté en chemin, testé en janvier 2026, sans fioriture. C’est moins sur les « fonctionnalités » et plus sur les parties qui ont rendu le travail plus léger une fois qu’elles étaient en place.

Aperçu de l’API

Si vous avez touché n’importe quelle API d’IA moderne, la vision de WaveSpeed sur WAN 2.5 vous semblera familière. De l’HTTP en entrée, du JSON en sortie. Vous envoyez un prompt (et parfois une image), et elle retourne soit un artefact terminé, soit un ID de job que vous pouvez interroger.

Quelques détails de base que j’ai surveillés avant d’écrire du code :

Versioning : WAN 2.5 est exposé en tant que version distincte, ce qui compte pour la reproductibilité. J’ai collé au chemin de version explicite dans les URLs plutôt qu’à un alias « latest ». Ce petit choix me sauve de changements de comportement silencieux à l’avenir.
Modes : Certaines charges de travail sont synchrones (petites, rapides), d’autres s’échelonnent en tant que jobs. Si vous faites des générations en haute résolution ou du travail par lot, attendez-vous à un flux asynchrone avec un endpoint de statut ou des webhooks.
Formats : Les réponses JSON incluent généralement un statut, une URL d’actif ou une charge utile base64, et quelques métadonnées (seed, étapes, timing). Je conserve les métadonnées, utiles quand vous voulez reproduire un look plus tard.
Limites : La taille de l’image, le nombre d’étapes et la concurrence sont plafonnés. Les valeurs par défaut suffisaient pour les brouillons, mais j’ai atteint une limite une fois que j’ai essayé de monter la résolution. Plus sur les limites de débit ci-dessous.

La version courte : c’est un chemin simple si vous êtes à l’aise avec REST. L’astuce est d’obtenir les petits trucs ennuyeux (clés, paramètres, retry) corrects pour pouvoir les oublier.

Cette simplicité est en partie la raison pour laquelle nous avons construit WaveSpeed comme nous l’avons fait. Je voulais que WAN 2.5 (et d’autres modèles) se sente scriptable, versionné et ennuyeux de la meilleure façon. Si vous câblez cela vous-même, vous pouvez l’explorer ici.

Authentification & clé

J’ai généré une clé API WaveSpeed dans le tableau de bord et l’ai mise dans une variable d’environnement. Rien de fancy, mais ça m’a épargné de traquer les secrets à travers les fichiers.

Obtenez une clé à partir de vos paramètres de compte sur WaveSpeed. Elle est liée à votre org/projet.
Stockez-la localement en tant que var env : WAVESPEED_API_KEY. J’ai utilisé un fichier .env pour le dev et le magasin des secrets de mon CI pour les runs.
Utilisez l’authentification Bearer dans l’en-tête : Authorization: Bearer $WAVESPEED_API_KEY.
Si vous faites pivoter les clés, faites-le pendant les heures creuses. J’ai appris cela discrètement quand une rotation programmée a interrompu un long job.

Si votre équipe a besoin de clés délimitées, vérifiez les paramètres du tableau de bord. Je préfère la route du moins de privilèges pour tout ce qui est lié à une automatisation. Une petite friction mineure : si vous lancez depuis plusieurs machines, étiquetez les clés clairement par hôte ou service, cela aide quand vous auditez l’utilisation plus tard.

Paramètres requis

Les noms exacts peuvent différer selon l’endpoint, mais voici la forme minimale que j’ai utilisée pour Wan 2.5 sur WaveSpeed. Traitez ceci comme un squelette, confirmez les noms de champs dans la documentation officielle pour votre compte.

model : Je l’ai défini explicitement à wan-2.5 (ou la chaîne exacte la plus proche de votre plan). Cela maintient le comportement stable à travers les mises à jour.
input : Une chaîne de prompt. Je l’ai gardée courte et concrète. WAN a tendance à mieux réagir aux formulations claires et simples qu’à la soupe d’adjectifs.
mode ou task : Génération d’image par rapport à variation/upscale. Si vous transmettez une image source, cela compte.
output : J’ai demandé une URL d’image par défaut. Base64 est là, mais les URLs sont plus douces pour la mémoire.

Quand j’ai oublié de définir le modèle explicitement, j’ai obtenu une valeur par défaut sensée, mais mes résultats ont changé subtilement à travers les runs. Pas mal, juste pas reproductible. Verrouiller la version a supprimé ce tremblement.

Paramètres optionnels

C’est là que se trouve le vrai contrôle. Je n’ai touché que quelques-uns le premier jour.

seed : Je l’active une fois que j’aime un look. Cela stabilise la vibe pour les variations.
steps : Les étapes plus élevées peuvent affiner les détails au détriment du temps et des crédits. J’ai augmenté par petits incréments (par ex., 24 → 32) et j’ai regardé les retours.
guidance ou cfg_scale : Resserre l’adhérence au prompt. Trop haut et ça devient fragile.
size ou resolution : C’est là que les coûts montent. Je brouille petit, puis je re-lance les finales à la taille cible.
image : Pour les variations, transmettez une URL d’image source ou téléchargez. Associez avec un paramètre de force si supporté.
safety ou moderation flags : Laissez-les activés sauf si votre workflow a réellement besoin d’une gestion personnalisée.
user ou metadata : J’ajoute un ID de demande ou une étiquette de projet pour tracer les runs dans les journaux plus tard.

Petite observation : changer deux boutons à la fois rendait difficile à dire ce qui aidait. J’ai changé une chose par run et j’ai gardé des notes dans les commentaires. À l’ancienne, mais ça a marché.

Exemples de modèles de demandes

J’ai essayé trois formes simples : un curl rapide, un petit script Python, et un job en arrière-plan pour l’asynchrone.

Brouillon synchrone (curl)

C’était suffisant pour faire une vérification de santé mentale de ma clé et de mon prompt avant de câbler autre chose.

Endpoint d’exemple, confirmez le chemin exact dans la documentation de votre compte et région :

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

En-têtes :

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

Corps (minimal) :

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

Ce que j’ai surveillé :

200 avec un résultat et des métadonnées → vous êtes bon.
202 avec un id de job → basculez vers le flux asynchrone.
4xx → quelque chose dans la charge utile ou l’authentification est mal.

Petit assistant Python

J’ai écrit une minuscule fonction pour gérer les en-têtes, les timeouts et le json. Elle a retourné soit une URL, soit a levé une exception propre. Rien de magique, juste le genre d’enveloppe sur laquelle vous ne pensez pas deux fois.

Bits pratiques :

Définissez un court timeout de connexion et un timeout de lecture légèrement plus long.
Gérez 429 avec une retry et du jitter.
Enregistrez le seed, les étapes et la taille pour chaque run.

Flux asynchrone (jobs)

Pour les images plus grandes ou les lots, j’ai obtenu un 202 et un id de job. La boucle était simple :

POST job,

Poll GET /jobs/{id} toutes les quelques secondes,
Arrêtez sur un état terminal (succès/échec),
Récupérez l’URL de l’actif.

Si votre pile aime les webhooks, WaveSpeed expose également des rappels. J’ai collé au polling au début, c’est une pièce mobile de moins pendant la configuration.

Codes d’erreur

J’ai gardé une petite carte à côté de mon éditeur. Ça a payé plus vite que je ne l’aurais prévu.

400 Bad Request : Généralement une incompatibilité de nom ou de type de champ. J’ai une fois envoyé size comme une chaîne, pas un objet. La correction était évidente une fois que j’ai ralenti et que j’ai lu le message.
401 Unauthorized : Clé manquante ou malformée. Vérifiez votre en-tête Bearer et les espaces de fin.
403 Forbidden : La clé existe mais manque de portée pour l’endpoint ou le niveau de modèle.
404 Not Found : Mauvais chemin d’endpoint ou un id de job qui a expiré.
409 Conflict : Vous verrez parfois ceci lors de la mise à jour d’un job qui s’est déjà réglé. Interrogez à nouveau, ne continuez pas à pousser.
429 Too Many Requests : Vous êtes au-delà d’une limite par minute ou par org. Reculez avec des retry exponentiels.
500/503 Server Errors : Rare dans mes tests, mais prévoyez-les. Une courte boucle de retry a gardé mes scripts calmes.

Petite habitude qui a aidé : j’ai fait remonter le code d’erreur et l’id de demande (s’il est présent) dans mes journaux. Quand quelque chose se gâte, le support peut utiliser cet id pour le tracer.

Limites de débit

J’ai heurté les limites de débit une fois que je suis devenu paresseux avec la concurrence. Facile à faire, plus facile à éviter.

Ce qui a marché :

Respectez les en-têtes : De nombreux endpoints retournent des en-têtes de débit (par ex., restant, heure de réinitialisation). Les noms d’en-têtes peuvent varier, vérifiez la documentation, mais ils valent la peine d’être lus.
Utilisez un token bucket ou une file d’attente simple. J’ai limité mes scripts à un petit goutte-à-goutte régulier au lieu de rafales. Le système respirait mieux, et moi aussi.
Séparez les brouillons des finales. Les brouillons peuvent s’exécuter petit et rapide : les finales peuvent s’exécuter l’un après l’autre en arrière-plan.
Mettez en cache les répétitions. Si vous testez des prompts, gardez les résultats précédents quelques minutes pour ne pas graver le même appel.

J’ai aussi construit un backoff très simple : délai de base de 1s, doublant à chaque 429, avec un plafond de 30s et un maximum de 4 retry. Cela semblait tranquille et évitait de faire la queue sur le service.

Garde-fous de coûts

C’était ma préoccupation principale. Le travail d’image peut ronger les crédits en arrière-plan pendant que vous préparez du thé.

Quelques protections que j’ai mises en place le premier jour :

Plafonds budgétaires dans le tableau de bord : J’ai défini un plafond mensuel et des alertes email un cran en dessous. Si votre équipe partage une clé, les alertes vous aident à attraper les boucles tôt.
Plafonds par demande : J’ai forcé la taille et les étapes à vivre sous un max sauf si j’ai passé un drapeau de remplacement. Ça m’a sauvé du « oups, 4K tout. »
Flux brouillon en premier : J’exécute de petits aperçus (résolution inférieure, moins d’étapes) et je montais seulement les gardiens. Cela a coupé ma dépense de plus de la moitié dans le premier après-midi.
Discipline de seed : Une fois que j’ai trouvé une direction que j’aimais, j’ai fixé le seed et changé un paramètre à la fois. Moins d’exécutions aveugles : plus intentionnelles.
Journaux avec coûts : Si la réponse inclut un champ de crédit ou d’utilisation (certains endpoints le font), stockez-le. Quand ce n’est pas le cas, estimez sur la base de la résolution et des étapes et notez que c’est une estimation.

J’ai aussi mis un interrupteur de fermeture logiciel dans mes scripts : si l’utilisation du jour franchissait un seuil, les nouveaux jobs s’arrêtaient et postaient un message sur Slack. Ce n’est pas élégant, mais c’est honnête à propos des contraintes.

Cela n’a pas sauvé du temps au début. Ça a sauvé de l’attention. Après quelques runs, les garde-fous se sont estompés en arrière-plan, et j’ai pu repenser au travail à la place du mètre.