Usare GPT Image 2 in Codex, Claude Code e altri agenti di programmazione

Un agente di programmazione come Codex o Claude Code può generare immagini con GPT Image 2 chiamando direttamente l'API. Metti la tua chiave API in una variabile d'ambiente, dai all'agente il prompt qui sotto e lui costruirà la richiesta, te la mostrerà, la invierà dopo la tua approvazione, interrogherà l'attività e salverà le immagini nel tuo progetto. Non serve alcun plugin: un agente che può eseguire un comando di shell o un breve script può chiamare l'API.

SeedRouter non fornisce un server MCP né una skill già pronta. Il prompt di questa guida è l'intera integrazione. Puoi salvarlo come istruzione riutilizzabile in qualunque agente usi.

Cosa serve all'agente prima di iniziare?

Tre cose:

1. Una chiave API nell'ambiente. Creane una nella pagina chiavi API ed esportala nella shell in cui gira l'agente. L'agente la legge da lì; non dovrebbe mai chiederti di incollarla.
2. Accesso alla rete. L'agente chiama https://api.seedrouter.ai, quindi la sua sandbox deve consentire richieste in uscita per questa attività.
3. Crediti. Le richieste vengono pagate con il tuo saldo, quindi ricarica prima della prima esecuzione.

export SEEDROUTER_API_KEY="your-key"

Quale prompt dare all'agente?

Incolla questo all'inizio dell'attività, poi compila l'obiettivo tra parentesi quadre. Elenca i campi esatti che l'API accetta, così l'agente non inventa parametri, e lo obbliga a fermarsi per la tua approvazione prima che venga addebitato qualsiasi importo:

Use the SeedRouter API to generate a gpt-image-2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never expose it in code, prompts, logs, or output.

Goal:
- Use case: [product / social / concept art / UI mockup]
- Subject and style: [subject, composition, lighting, style]
- Size: [auto | 1024x1024 | 1536x1024 | 1024x1536 | WIDTHxHEIGHT]
- Quality: [auto | low | medium | high]
- Number of images: [1-10]
- Acceptance criteria: [e.g. no text in the image, consistent product, clean background]

Request fields this endpoint accepts, and nothing else:
  model (required, "gpt-image-2"), prompt (required, up to 32000 chars),
  n (1-10, default 1), size (default auto; a custom WIDTHxHEIGHT must have
  both sides divisible by 16, neither edge over 3840, total pixels between
  655360 and 8294400, and keep a ratio between
  1:3 and 3:1), quality (auto|low|medium|high, default auto),
  background (auto|opaque|transparent, default auto; transparent requires
  output_format png), output_format (png|jpeg, default png),
  output_compression (0-100, default 100, jpeg only),
  moderation (auto|low, default auto), user (your own identifier).
For editing use /v1/images/generations with images: [{image_url: "https://..."}]
(up to 16) and optional mask: {image_url: "https://..."}. Mask requires images.
Inputs must be URLs, not base64 or multipart files. stream and partial_images
are not supported because delivery is asynchronous.

Before any paid request, show me the model id, the exact request body and the
estimated cost, then wait for my explicit approval.

After approval:
1. POST https://api.seedrouter.ai/v1/images/generations with the body above and
   an Authorization: Bearer $SEEDROUTER_API_KEY header.
2. Save the task id from the response "id" field. The response is
   {"id": "...", "status": "processing"} — the image is not in it.
3. Poll https://api.seedrouter.ai/v1/tasks/{task_id} with the same header every
   5-10 seconds until status is "completed" or "failed". Do not retry forever;
   if you stop waiting, preserve the task id and report that it is still pending.
   A polling timeout is not a failed task. Never submit a duplicate just to check status.
4. On success, download every URL in output.data[].url, return the local paths,
   the task id, and the parameters used. The response carries no cost field.
5. On failure, keep the task id, explain the reason and what to change, and do
   not retry without my approval. A task that ends failed is not charged.

Il passaggio di approvazione è il più importante. Un agente che riprova di sua iniziativa può inviare più volte la stessa richiesta a pagamento. Mantieni quell'istruzione anche quando ti fidi della configurazione.

Come si usa in Codex?

Apri Codex nel tuo progetto e incolla il prompt con il tuo obiettivo compilato. Per riutilizzarlo, aggiungi il prompt al file AGENTS.md del progetto, il file di istruzioni che Codex legge per il repository, sotto un titolo come "Generating images". A quel punto basta una richiesta come "crea un'immagine hero per la pagina dei prezzi"; Codex segue i passaggi salvati.

Se Codex gira in una sandbox senza accesso alla rete, non può raggiungere l'API. Consenti l'accesso alla rete per quella sessione prima di chiedergli di generare.

Come si usa in Claude Code?

Lo stesso prompt funziona in Claude Code. Per riutilizzarlo, salvalo nel file CLAUDE.md del progetto, oppure come skill: una cartella con un file SKILL.md le cui istruzioni contengono il prompt. Claude Code lo carica quando chiedi un'immagine. Assicurati che SEEDROUTER_API_KEY sia esportata nel terminale da cui avvii Claude Code.

Com'è fatta una buona esecuzione dell'agente?

1. Descrivi l'immagine e dove deve andare.
2. L'agente mostra l'ID modello, il corpo esatto della richiesta e un costo stimato, e attende.
3. Approvi. L'agente invia una sola volta e riporta l'ID attività.
4. Interroga l'attività finché non è completata, scarica le immagini nel progetto e ti indica i percorsi dei file.

Se un'esecuzione si interrompe a metà, l'ID attività resta valido. Chiedi all'agente di riprendere il polling di quell'ID invece di generare di nuovo; un secondo invio è un secondo addebito. Un'attività che termina con errore non viene addebitata.

Domande frequenti

SeedRouter offre un server MCP o una skill per GPT Image 2?

No. L'API stessa è l'integrazione, e il prompt qui sopra dà a un agente tutto ciò che gli serve per chiamarla. Salva il prompt come skill o file di istruzioni nel tuo agente se vuoi riutilizzarlo.

L'agente può modificare immagini già presenti nel mio progetto?

Sì, se le immagini sono raggiungibili tramite URL HTTPS pubblici. L'API riceve immagini di riferimento e maschere come URL, non come file locali, quindi caricale prima o indica all'agente dove sono ospitate.

Quale modello deve usare l'agente?

gpt-image-2 per un prezzo fisso per immagine consegnata, oppure gpt-image-2-official per pagare in base ai token che ogni generazione riporta. Sostituisci il modello nel prompt per cambiare. I prezzi correnti sono nella pagina del modello.

Mantieni una persona nel ciclo

Dai all'agente la chiave tramite l'ambiente, i campi tramite il prompt e l'ultima parola tramite il passaggio di approvazione. Questa combinazione permette a Codex o Claude Code di produrre immagini dentro il tuo progetto senza addebiti a sorpresa. La documentazione dell'API GPT Image 2 contiene tutti i campi se vuoi estendere il prompt.