API Grok Imagine: genera un’immagine con l’SDK Pipe2

Per accedere all’API Grok Imagine tramite Pipe2, esegui Image Generator con model: 'grok-imagine-image'. Invia un prompt testuale, consulta lo stato tramite l’ID di esecuzione ricevuto e recupera l’immagine generata. Questa guida usa l’API e l’autenticazione di Pipe2; non mostra una richiesta diretta all’API xAI.

Seleziona Grok in modo esplicito

Lo slug della pipeline è image-generator; l’identificatore del modello va dentro input. Usa grok-imagine-image per il modello standard o grok-imagine-image-quality per Grok Imagine Quality. Auto può scegliere un altro motore: specifica il modello se devi usare Grok.

L’esempio usa il modello standard, senza immagini di riferimento, con quality: 'fast': una configurazione Grok valida al costo minimo per questo flusso. Fast seleziona un output 1K; auto e hd selezionano 2K. Attualmente, Grok standard ha lo stesso prezzo base per immagine nelle due dimensioni; fast non offre un ulteriore sconto. Le immagini di riferimento aggiungono un costo. Prima di avviare una serie di generazioni, usa EstimatePipelineCost con lo stesso slug e gli stessi dati di input.

Esegui l’esempio dell’SDK

Installa il pacchetto con npm install @pipe2-ai/sdk. Salva il codice seguente come grok-image.mjs, imposta PIPE2_TOKEN nell’ambiente con un token di accesso personale Pipe2, poi esegui node grok-image.mjs. L’account deve avere crediti sufficienti. Conserva il token sul server.

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}`);

La richiesta corrispondente alla 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
  }
}

Consulta la documentazione dell’SDK TypeScript per il client usato da questo modulo JavaScript e il riferimento API per l’API pubblica.

Conserva l’ID finché l’immagine non è pronta

RunPipeline restituisce un ID di esecuzione, non l’immagine finita. GetPipelineRun recupera lo stato e i file di output. L’esempio si interrompe in caso di errore o annullamento, verifica che un’esecuzione completata contenga un file e stampa l’URL della prima immagine. Limita il controllo a 60 verifiche con attese di tre secondi: è una scelta dell’applicazione, non una garanzia sui tempi di generazione.

Se il controllo va in timeout, riprendi a consultare lo stesso ID invece di inviare una generazione duplicata. Salva l’ID appena l’avvio riesce. In produzione, gestisci anche gli errori di rete e conserva il riferimento al file restituito dove serve all’applicazione.

Aggiungi riferimenti solo quando servono

Un prompt testuale è sufficiente. Entrambi i modelli di immagine Grok supportano fino a tre reference_images in JPEG o PNG, con un massimo di 20 MB per immagine. Non accettano reference_videos in questa pipeline. I rapporti d’aspetto disponibili sono 1:1, 16:9, 9:16, 4:3 e 3:4; l’esempio usa il formato quadrato predefinito.

enhance_prompt: false impedisce che il prompt venga riscritto prima della generazione quando la richiesta contiene solo testo. Descrivi soggetto, ambiente, inquadratura e luce, poi verifica il risultato prima di usarlo. Per definire meglio la composizione, consulta la guida ai prompt Grok Imagine. Quando aggiungi riferimenti, spiega il contributo di ciascuno e stima nuovamente il costo della richiesta modificata.