API per generare immagini con l’IA: esempio TypeScript

Un’API di generazione immagini IA trasforma un prompt in un’immagine attraverso un’esecuzione avviata dal codice. Con Pipe2, avvia Image Generator, interroga l’ID restituito e leggi l’URL dell’immagine nelle risorse dell’esecuzione completata. L’esempio TypeScript usa la combinazione valida di modello e qualità meno costosa del catalogo attuale.

Generare un’immagine con l’SDK TypeScript

Installa @pipe2-ai/sdk, inserisci un token di accesso personale Pipe2 in PIPE2_TOKEN ed esegui questo modulo con Node. Il prompt descrive un soggetto, un ambiente e una direzione della luce, così il primo risultato è facile da valutare.

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 richiesta alla pipeline contenuta nel programma è esattamente questa:

{
  "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 documentazione dell’SDK TypeScript descrive installazione, autenticazione, operazioni sulle pipeline, caricamento delle risorse, sottoscrizioni e interrogazioni dei crediti.

Capire il flusso di esecuzione, controllo e risorsa

RunPipeline riceve lo slug della pipeline e un oggetto JSON di input. Restituisce gli identificativi di un’esecuzione asincrona invece di tenere aperta la connessione fino a quando l’immagine è pronta. Conserva run_pipeline.run_id: GetPipelineRun lo usa per recuperare lo stato più recente.

Il ciclo gestisce entrambi gli stati finali. Un’esecuzione completed può includere le risorse generate e l’esempio stampa l’URL della prima. Un’esecuzione failed può contenere error_message, da registrare insieme all’ID. In produzione, imposta anche un tempo massimo complessivo e considera errore un’esecuzione assente. Per gli aggiornamenti in tempo reale, l’SDK offre inoltre WatchPipelineRun come iterabile asincrono.

Partire dalla richiesta valida meno costosa

L’esempio fissa gpt-image-2 con quality: 'fast'. Nel catalogo attuale di Image Generator è la combinazione valida con il costo più basso e corrisponde al livello di bassa qualità del modello. È adatta a verificare autenticazione, forma della richiesta, polling e gestione delle risorse prima di spendere più crediti per un’immagine finale.

Fast è una scelta di costo, non una promessa di qualità pronta per la pubblicazione. Prima di avviare un carico più ampio, usa EstimatePipelineCost con gli stessi pipeline_slug e input. Ripeti la stima quando cambi modello, qualità o numero di immagini di riferimento: per l’addebito fa fede il catalogo attivo.

Scegliere solo i controlli necessari

Un prompt è sufficiente. Image Generator può ricevere anche immagini di riferimento, un video di riferimento supportato, proporzioni, qualità, modello e preferenza per il miglioramento del prompt. I limiti dipendono dal modello scelto; leggi quindi lo schema della pipeline anziché dare per scontato che ogni motore accetti gli stessi media.

Per una generazione solo testuale, descrivi soggetto, composizione, luce e stile in una breve frase narrativa. Metti tra virgolette il testo che deve comparire letteralmente nell’immagine e rileggilo nel risultato. Con i riferimenti, indica il ruolo di ogni immagine e gli elementi da mantenere. Le cinque proporzioni comuni sono 1:1, 16:9, 9:16, 4:3 e 3:4.

Auto permette a Pipe2 di scegliere un motore compatibile. Fissa un modello soltanto se il prodotto dipende da una capacità documentata o se stai conducendo un confronto controllato. Il confronto tra generatori di immagini IA spiega come mantenere invariati prompt, riferimenti, inquadratura e numero di tentativi.

Gestire in sicurezza token, errori e URL

Crea il client SDK con un token Pipe2 fornito dall’ambiente di esecuzione. Non inserirlo nel sorgente, non salvarlo nel repository e non esporlo nei log del browser. La richiesta indica lo slug della pipeline Pipe2; il client non invia credenziali separate al fornitore del modello.

Salva l’ID prima di iniziare il polling, così un processo riavviato potrà riprendere lo stesso lavoro. Tratta l’URL della risorsa come dato applicativo: conservalo se serve un riferimento duraturo, verifica che esista una risorsa prima di accedere all’indice zero e mostra l’errore senza riprovare all’infinito. Applica inoltre le normali regole di autorizzazione, moderazione e conservazione dell’applicazione ai prompt e ai media degli utenti.