API Grok Imagine : générer une image avec le SDK Pipe2

Pour accéder à l’API Grok Imagine via Pipe2, lancez Image Generator avec model: 'grok-imagine-image'. Envoyez un prompt textuel, interrogez l’identifiant d’exécution reçu et récupérez l’image générée. Ce guide utilise l’API et l’authentification de Pipe2 ; il ne présente pas d’appel direct à l’API xAI.

Sélectionner Grok explicitement

Le slug du pipeline est image-generator ; l’identifiant du modèle se place dans input. Utilisez grok-imagine-image pour le modèle standard ou grok-imagine-image-quality pour Grok Imagine Quality. Auto peut choisir un autre moteur : fixez le modèle si vous devez utiliser Grok.

L’exemple emploie le modèle standard, sans image de référence, avec quality: 'fast' : une configuration Grok valide au coût minimal pour ce parcours. Fast sélectionne une sortie 1K ; auto et hd sélectionnent 2K. Pour Grok standard, le prix de base par image est actuellement identique dans les deux tailles ; fast n’apporte donc pas de réduction supplémentaire. Les références ajoutent un coût. Avant de lancer un ensemble de générations, appelez EstimatePipelineCost avec le même slug et les mêmes données d’entrée.

Exécuter l’exemple du SDK

Installez le paquet avec npm install @pipe2-ai/sdk. Enregistrez le code suivant dans grok-image.mjs, définissez PIPE2_TOKEN dans votre environnement avec un jeton d’accès personnel Pipe2, puis lancez node grok-image.mjs. Votre compte doit disposer de suffisamment de crédits. Conservez le jeton côté serveur.

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

const token = process.env.PIPE2_TOKEN;
if (!token) throw new Error('Set PIPE2_TOKEN');
const client = createClient(token);
const input = {
  model: 'grok-imagine-image',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.',
  quality: 'fast',
  enhance_prompt: false,
};
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

for (let attempt = 0; attempt < 60; attempt++) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (!run) throw new Error('Run not found');
  if (run.status === 'failed' || run.status === 'cancelled') {
    throw new Error(run.error_message ?? run.status);
  }
  if (run.status === 'completed') {
    const url = run.assets?.[0]?.url;
    if (!url) throw new Error('Completed run has no image asset');
    console.log(url);
    process.exit(0);
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Polling timed out; resume with run ID ${run_pipeline.run_id}`);

Voici la requête correspondante pour le pipeline :

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

La documentation du SDK TypeScript décrit le client utilisé par ce module JavaScript ; la référence de l’API présente l’API publique.

Conserver l’identifiant jusqu’à la fin de la génération

RunPipeline renvoie un identifiant d’exécution, pas l’image terminée. GetPipelineRun récupère son état et ses fichiers de sortie. L’exemple s’arrête en cas d’échec ou d’annulation, vérifie qu’une exécution terminée contient un fichier et affiche l’URL de la première image. Il limite le suivi à 60 vérifications espacées de trois secondes : ce choix de l’application ne garantit pas une durée de génération.

Si le délai de suivi est dépassé, reprenez la consultation du même identifiant au lieu de soumettre une génération en double. Enregistrez cet identifiant dès que le lancement réussit. En production, gérez aussi les erreurs réseau et conservez la référence du fichier là où votre application en a besoin.

Ajouter des références seulement si elles sont utiles

Un prompt textuel suffit. Les deux modèles d’image Grok acceptent jusqu’à trois reference_images au format JPEG ou PNG, avec un maximum de 20 MB par image. Ils n’acceptent pas reference_videos dans ce pipeline. Les formats disponibles sont 1:1, 16:9, 9:16, 4:3 et 3:4 ; l’exemple utilise le carré par défaut.

enhance_prompt: false évite la réécriture du prompt avant génération pour une requête contenant uniquement du texte. Décrivez le sujet, le décor, le cadrage et la lumière, puis vérifiez le résultat avant de l’utiliser. Pour mieux maîtriser la composition, consultez le guide des prompts Grok Imagine. Si vous ajoutez des références, expliquez le rôle de chacune et estimez à nouveau le coût de la requête modifiée.