Generare immagini via API, direttamente nel tuo IDE

L’immagine arriva dove serve

Alla tua pagina manca una copertina. Invece di spostare download tra strumenti, fai salvare il risultato direttamente nel progetto. Il nostro metodo separa il brief creativo, lo script che chiama il servizio e le istruzioni per l’assistente. Ogni parte può evolvere senza rifare l’intero processo.

1. Preparare l’accesso

Questo esempio didattico usa lo SDK Python e l’API Images di OpenAI: generazione da un prompt e decodifica del risultato Base64. Installa lo SDK con python -m pip install --upgrade openai. Imposta OPENAI_API_KEY nell’ambiente del terminale dell’IDE e IMAGE_MODEL con un modello GPT Image accessibile al tuo account, per esempio gpt-image-2 se disponibile. Non inserire mai la chiave nel codice, nel browser o in Git.

2. Scrivere un brief utile

Crea brief.txt nella radice del progetto. Descrivi soggetto, materiali, luce, palette e inquadratura. Esempio: «Copertina per un blog, studio di sviluppo futuristico, metallo spazzolato, luce blu ardesia, composizione orizzontale, soggetto centrale, senza testo». Mantieni la stessa struttura per tutte le copertine e cambia il soggetto. Le dimensioni esatte richiedono parametri supportati dal modello: il solo prompt non le garantisce.

3. Salvare l’immagine nel progetto

Salva questo codice in scripts/generate_image.py ed esegui python scripts/generate_image.py dalla radice. Il nome univoco conserva i risultati precedenti. L’esempio si aspetta una risposta GPT Image in Base64; non gestisce servizi che restituiscono un URL o un identificativo di attività da interrogare. Il codice è stato controllato senza effettuare chiamate API reali per questo tutorial.

import base64
import os
from pathlib import Path
from uuid import uuid4
from openai import OpenAI

client = OpenAI(timeout=180.0, max_retries=0)
prompt = Path("brief.txt").read_text(encoding="utf-8")
result = client.images.generate(
    model=os.environ["IMAGE_MODEL"],
    prompt=prompt,
    n=1,
    output_format="png",
)
if not result.data or not result.data[0].b64_json:
    raise RuntimeError("No image returned")
image = base64.b64decode(result.data[0].b64_json, validate=True)
folder = Path("assets/generated")
folder.mkdir(parents=True, exist_ok=True)
target = folder / f"image-{uuid4().hex[:12]}.png"
target.write_bytes(image)
print(target)

4. Aggiungere una competenza a VS Code

Con un assistente compatibile con Agent Skills, come GitHub Copilot in modalità agente in VS Code, crea .github/skills/image-assets/SKILL.md. La competenza descrive una procedura: non fornisce chiavi né accesso ai modelli. Lo script rimane in scripts/generate_image.py. Questa base in inglese può essere condivisa in un team multilingue e adattata al progetto.

---
name: image-assets
description: Generate an original image asset from a brief using the project's image API script.
---
Use for an explicit request to create an image for this project.
1. Read the design guidelines. Define subject, palette, crop and intended use.
2. Write the agreed visual brief to brief.txt in the project root.
3. Check that OPENAI_API_KEY and IMAGE_MODEL are set without printing them.
4. Run python scripts/generate_image.py from the project root once.
5. If generation fails or times out, report it; do not retry automatically.
6. Open the saved image if an image-viewing tool is available. Otherwise
   state that visual inspection remains outstanding.
7. Keep the original. Create a web-optimized copy and use it in the page.
8. Check the path, layout, crop and alternative text. Report the saved file.
Never expose API keys, overwrite an existing image or invent a successful result.

5. Chiedere un risultato concreto

Nella chat dell’IDE: «Usa image-assets per creare una copertina per questo articolo, rispetta i colori del sito e integra una versione ottimizzata senza sovrascrivere le immagini esistenti». L’assistente deve accedere al terminale e, per il controllo visivo, a uno strumento di lettura delle immagini. Restano valide le autorizzazioni dell’IDE. Un’altra idea utile è creare le illustrazioni di un tutorial partendo da una cartella di brief, una alla volta.

Dal file generato alla pagina pronta

Conserva il PNG originale, crea una copia WebP e controlla il ritaglio su mobile. Riserva lo spazio dell’immagine per evitare spostamenti del layout. Scrivi un testo alternativo se l’immagine comunica informazioni; per una decorazione puoi usare alt vuoto. Non ripetere automaticamente la richiesta dopo un timeout: potrebbe essere stata elaborata anche senza risposta.

E con CONSTELLO?

Consulta il catalogo e la documentazione del tuo account per conoscere le funzioni disponibili. La compatibilità con una API di chat non garantisce un endpoint per generare immagini. Prima di adattare lo script a CONSTELLO o ad altri servizi, verifica URL, modello e formato della risposta. Il tutorial non afferma di aver convalidato un’integrazione immagini CONSTELLO. L’obiettivo è mantenere la creazione degli asset vicina al codice.