API de génération d’images par IA : exemple TypeScript

Une API de génération d’images par IA transforme un prompt en image au moyen d’une exécution programmée. Avec Pipe2, lancez Image Generator, interrogez l’identifiant renvoyé, puis lisez l’URL de l’image dans les ressources de l’exécution terminée. L’exemple TypeScript ci-dessous emploie la combinaison valide de modèle et de qualité la moins chère du catalogue actuel.

Générer une image avec le SDK TypeScript

Installez @pipe2-ai/sdk, placez un jeton d’accès personnel Pipe2 dans PIPE2_TOKEN, puis exécutez ce module avec Node. Le prompt définit un sujet, un décor et une lumière afin que le premier résultat soit simple à évaluer.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  model: 'gpt-image-2',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.',
  quality: 'fast',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Image generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

La requête de pipeline contenue dans ce programme est exactement la suivante :

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "gpt-image-2",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.",
    "quality": "fast"
  }
}

La documentation du SDK TypeScript détaille l’installation, l’authentification, les opérations de pipeline, l’envoi de ressources, les abonnements et les requêtes de crédits.

Comprendre le lancement, le suivi et la ressource

RunPipeline reçoit le slug du pipeline et un objet JSON d’entrée. La méthode renvoie les identifiants d’une exécution asynchrone au lieu de maintenir la connexion jusqu’à ce que l’image soit prête. Conservez run_pipeline.run_id : GetPipelineRun l’utilise pour récupérer le dernier état connu.

La boucle gère les deux états finaux. Une exécution completed peut contenir les ressources générées et l’exemple affiche l’URL de la première. Une exécution failed peut fournir error_message, à journaliser avec l’identifiant. En production, fixez aussi un délai maximal global et considérez une exécution introuvable comme une erreur. Pour recevoir les mises à jour en direct, le SDK propose également WatchPipelineRun sous forme d’itérable asynchrone.

Commencer par la requête valide la moins chère

L’exemple impose gpt-image-2 avec quality: 'fast'. Dans le catalogue actuel d’Image Generator, cette combinaison est la moins chère parmi les choix valides et correspond au niveau de faible qualité du modèle. Elle permet de vérifier l’authentification, la structure de la requête, le suivi et la gestion des ressources avant de consacrer davantage de crédits à une image finale.

Fast est un choix de coût, pas une garantie de finition. Avant de lancer un volume important, appelez EstimatePipelineCost avec les mêmes pipeline_slug et input. Refaites l’estimation dès que vous changez de modèle, de qualité ou de nombre d’images de référence : le catalogue actif fait foi pour la facturation.

Ne choisir que les paramètres utiles à l’image

Un prompt suffit. Image Generator peut également recevoir des images de référence, une vidéo de référence compatible, un format, une qualité, un modèle et une préférence d’amélioration du prompt. Les limites varient selon le modèle ; consultez donc le schéma du pipeline au lieu de supposer que tous les moteurs acceptent les mêmes médias.

Pour une génération uniquement textuelle, décrivez brièvement le sujet, la composition, la lumière et le style. Placez entre guillemets tout texte qui doit apparaître littéralement et relisez-le dans l’image. Avec des références, précisez le rôle de chaque fichier et les détails qui doivent rester constants. Les cinq formats communs sont 1:1, 16:9, 9:16, 4:3 et 3:4.

Le mode Auto laisse Pipe2 sélectionner un moteur compatible. N’imposez un modèle que si votre produit dépend d’une capacité documentée ou si vous réalisez une comparaison contrôlée. Le comparatif des générateurs d’images par IA explique comment conserver le même prompt, les mêmes références, le même cadrage et le même nombre d’essais.

Utiliser l’API de Nano Banana Pro avec Image Generator

Pour accéder à Nano Banana Pro par l’API de Pipe2, utilisez le même pipeline image-generator et définissez input.model sur gemini-3-pro-image. Nano Banana Pro est le nom du modèle dans le catalogue ; conservez l’identifiant Pipe2 dans la requête. Les méthodes du SDK, l’identifiant d’exécution, la boucle de suivi et l’image renvoyée suivent le fonctionnement présenté plus haut. Authentifiez-vous avec votre jeton Pipe2.

Pour comparer les résultats, gardez le prompt de l’exemple et changez uniquement le modèle. La requête existante avec GPT Image 2 en qualité fast permet de vérifier l’intégration à moindre coût. Estimez la requête modifiée avec EstimatePipelineCost avant de lancer Nano Banana Pro. Pour ce modèle, quality: 'fast' sélectionne une sortie 1K, tandis que auto ou hd sélectionnent une sortie 2K. Ces tailles partagent le même tarif : fast ne réduit donc pas le prix comme avec GPT Image 2. Ce pipeline ne propose pas de sortie 4K pour Nano Banana Pro.

Un prompt textuel suffit ; vous pouvez aussi fournir jusqu’à 14 reference_images. Expliquez le rôle de chaque référence dans le prompt. N’envoyez pas de reference_videos avec ce modèle : Nano Banana Pro n’accepte pas de vidéo en entrée dans Image Generator. Définissez enhance_prompt sur false pour conserver votre formulation dans une requête sans références. Pour une mise en page précise, décrivez la position de chaque élément, placez le texte exact entre guillemets et vérifiez l’image générée avant de l’utiliser.

Utiliser l’API de GPT Image 2 via Pipe2

L’exemple ci-dessus est déjà configuré pour accéder à GPT Image 2 par l’API de Pipe2 : envoyez pipeline_slug: 'image-generator' avec input.model: 'gpt-image-2' et un prompt textuel. Authentifiez-vous avec votre jeton Pipe2. Conservez l’identifiant renvoyé et interrogez l’exécution avec les mêmes méthodes du SDK pour récupérer l’image une fois l’exécution terminée ; le choix du modèle ne change pas ce fonctionnement.

Choisissez quality: 'fast' pour le niveau de qualité faible utilisé dans l’exemple d’intégration, auto pour le niveau moyen ou hd pour le niveau élevé. Ce sont les valeurs d’entrée de Pipe2 : transmettez-les telles quelles, sans les remplacer par les noms des niveaux. Estimez la requête modifiée avant d’augmenter la qualité. GPT Image 2 accepte jusqu’à cinq reference_images et ne prend pas en charge les reference_videos dans ce pipeline. Expliquez le rôle de chaque référence et vérifiez les modifications involontaires dans le résultat, notamment sur les textes et les détails du produit.

Protéger les jetons, les erreurs et les URL de sortie

Créez le client SDK avec un jeton Pipe2 fourni par l’environnement d’exécution. Ne l’inscrivez pas dans le code source, ne le validez pas dans le dépôt et ne l’exposez pas dans les journaux du navigateur. La requête nomme le pipeline Pipe2 ; le client n’envoie pas d’identifiant séparé au fournisseur du modèle.

Enregistrez l’identifiant avant de commencer le suivi afin qu’un processus redémarré puisse reprendre le même travail. Traitez l’URL de la ressource comme une donnée applicative : conservez-la si vous avez besoin d’une référence durable, vérifiez la présence d’une ressource avant d’accéder à l’index zéro et remontez l’erreur sans réessayer indéfiniment. Pour les prompts et médias des utilisateurs, appliquez aussi vos règles habituelles d’autorisation, de modération et de conservation.