Comment utiliser le SDK JavaScript WaveSpeedAI

Le SDK JavaScript de WaveSpeedAI fournit un moyen simple d’intégrer la génération d’images et vidéos IA dans vos applications Node.js et TypeScript. Ce guide couvre tout ce que vous devez savoir pour commencer.

Prérequis

Avant de commencer, assurez-vous d’avoir :

Node.js 18+ installé sur votre machine
Une clé API WaveSpeedAI depuis wavespeed.ai/settings/api-keys

Installation

Installez le SDK en utilisant npm :

npm install wavespeed

Ou avec yarn :

yarn add wavespeed

Configuration de l’authentification

Le SDK a besoin de votre clé API pour authentifier les requêtes. Vous avez deux options :

Option 1 : Variable d’environnement (Recommandé)

Définissez la variable d’environnement WAVESPEED_API_KEY :

export WAVESPEED_API_KEY="your-api-key-here"

Utilisez ensuite le SDK directement :

import wavespeed from "wavespeed";

const output = await wavespeed.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" });

Option 2 : Passer la clé API directement

Importez la classe Client et passez votre clé API au constructeur :

import { Client } from "wavespeed";

const client = new Client("your-api-key-here");

Générer votre première image

Voici un exemple complet qui génère une image en utilisant Z-Image Turbo :

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A serene mountain landscape at sunset with golden light" }
);

console.log(output["outputs"][0]); // URL to the generated image

La méthode run() gère l’ensemble du processus : soumettre la requête, interroger l’achèvement et retourner le résultat.

Télécharger des fichiers

Pour les workflows qui nécessitent des images d’entrée (comme image-vers-vidéo), utilisez la méthode upload() pour obtenir une URL accessible à WaveSpeedAI :

import wavespeed from "wavespeed";

// Upload a local image file
const imageUrl = await wavespeed.upload("./my-image.png");

// Use the uploaded image for video generation
const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/image-to-video",
  {
    image: imageUrl,
    prompt: "Camera slowly zooms in while clouds move in the background"
  }
);

console.log(video["outputs"][0]); // URL to the generated video

Options de configuration

Options du client

Configurez le comportement des tentatives lors de l’initialisation du client :

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,           // Max retries for failed requests
  maxConnectionRetries: 5, // Max retries for connection errors
  retryInterval: 1.0       // Seconds between retries
});

Options d’exécution

Configurez les appels run() individuels :

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A cute orange cat wearing a tiny hat" },
  {
    timeout: 60,        // Max seconds to wait for completion
    pollInterval: 0.5,  // Seconds between status checks
    enableSyncMode: true // Use synchronous mode if available
  }
);

Travailler avec différents modèles

Text-to-Image

Générez des images à partir de descriptions textuelles :

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  {
    prompt: "A futuristic cityscape with flying cars and neon lights",
    size: "1024x1024"
  }
);

Image-to-Video

Transformez les images statiques en vidéos :

import wavespeed from "wavespeed";

const imageUrl = await wavespeed.upload("./landscape.jpg");

const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/image-to-video",
  {
    image: imageUrl,
    prompt: "Gentle wind blowing through the trees"
  }
);

Text-to-Video

Générez des vidéos directement à partir du texte :

import wavespeed from "wavespeed";

const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/t2v-480p",
  {
    prompt: "A golden retriever running through a field of flowers"
  }
);

Utilisation avec TypeScript

Le SDK inclut les définitions TypeScript. Voici un exemple type-safe :

import wavespeed from "wavespeed";

interface GenerationOutput {
  outputs: string[];
  timings?: Record<string, number>;
}

const output: GenerationOutput = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "An astronaut riding a horse on Mars" }
);

const imageUrl: string = output.outputs[0];
console.log(imageUrl);

Gestion des erreurs

Pour les applications de production, configurez les tentatives et gérez les erreurs gracieusement :

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,
  maxConnectionRetries: 5,
  retryInterval: 1.0
});

try {
  const output = await client.run(
    "wavespeed-ai/z-image/turbo",
    { prompt: "A beautiful sunset over the ocean" },
    { timeout: 120 }
  );
  console.log("Generated:", output.outputs[0]);
} catch (error) {
  console.error("Generation failed:", error.message);
}