Il modo più semplice per automatizzare la generazione di immagini su larga scala senza dover gestire diverse API è separare il workflow dal provider del modello. Inserisci ogni richiesta di immagine in una coda, instrada ogni job a un ID di modello attuale e invia le richieste compatibili tramite un’unica chiave CometAPI e la base URL compatibile con OpenAI https://api.cometapi.com/v1.
Questo tutorial costruisce quella pipeline in Python. Accetta job di prodotto, pubblicità e contenuti da una coda in JSON Lines; sceglie un modello; limita la concorrenza; ritenta i guasti transitori; salva risultati basati su URL o base64; e registra l’uso per job e il costo stimato. L’esempio mantiene questi elementi essenziali di produzione in un blocco compatto così puoi testare il workflow senza trasformare l’articolo in un riferimento di codice.
Come un’API di immagini unificata semplifica la generazione in batch
Alla fine, il workflow avrà questo aspetto:
jobs.jsonl → bounded worker pool → CometAPI /v1/images/generations → object storage → manifest.jsonl
La coda e il livello di storage restano tuoi. Cambiare i modelli di immagine modifica il valore di model, non il sistema di autenticazione o la rotta principale della richiesta. Questo è il vantaggio pratico di un’API di immagini unificata: la scelta del modello diventa una decisione di instradamento all’interno di un’unica pipeline, invece di un’integrazione separata per provider.
Di cosa hai bisogno per automatizzare la generazione di immagini?
Ti serve Python 3.10 o successivo, il pacchetto requests, una chiave CometAPI, una posizione di output scrivibile e almeno un ID di modello di immagini attuale.
Installa l’unica dipendenza:
pip install requests
Imposta la tua chiave sul server, mai nel codice del browser o in un repository:
export COMETAPI_KEY="your-key"
La base URL è https://api.cometapi.com/v1, e i job di text-to-image compatibili usano POST /images/generations. Prima di un deployment, verifica ogni modello nel catalogo dei modelli live; il catalogo restituisce l’ID attuale, l’endpoint supportato, le funzionalità e i metadati di prezzo senza richiedere un header di autorizzazione.
Al 20 agosto 2026, il catalogo live elencava queste due route utili:
| Carico di lavoro | Model ID | Perché è adatto |
|---|---|---|
| Immagini di prodotto con impostazioni controllate | gpt-image-2 | Restituisce dati di utilizzo e contenuto immagine base64 sulla rotta documentata compatibile con OpenAI |
| Concept ad e contenuti ad alto volume | doubao-seedream-4-5-251128 | Usa la stessa rotta di generazione ed è elencato con pricing per richiesta |
La tabella è un punto di partenza, non un’affermazione che i modelli abbiano capacità identiche. Dimensione, qualità, formato, supporto di immagini di riferimento e comportamento della risposta restano specifici del modello. Controlla il record del modello e la documentazione collegata prima di passare parametri opzionali.
Come creare un workflow di generazione immagini in batch in Python
1. Assegna a ogni job un ID durevole
Usa un oggetto JSON per riga così una coda, un export di database o un job da spreadsheet possono alimentare lo stesso worker:
{"id":"sku-1001","kind":"product","prompt":"Studio product photo of a ceramic coffee dripper on a warm neutral background"}
{"id":"campaign-204","kind":"ad","prompt":"Editorial summer travel image, vivid natural light, wide composition, no text"}
{"id":"blog-088","kind":"content","prompt":"Minimal illustration of a developer automating a creative workflow, no text"}
L’ID diventa il nome file di output e la chiave del manifest. In produzione, usalo come chiave di idempotenza e salta gli ID già contrassegnati come riusciti prima di rielaborare una coda.
2. Instrada per tipo di job, poi valida contro il catalogo live
L’esempio mappa il lavoro di prodotto a gpt-image-2 e i job di ads o contenuti a doubao-seedream-4-5-251128. Un job può sovrascrivere quella scelta con il proprio campo model. All’avvio, il worker scarica il catalogo pubblico e rifiuta un ID non più elencato.
Questo è più sicuro che hardcodare un SDK specifico del provider in tutta l’applicazione. Puoi cambiare una rotta in una mappatura dopo aver valutato qualità, latenza e prezzo per i tuoi prompt.
3. Limita la concorrenza invece di lanciare l’intero batch
Il worker parte con quattro richieste concorrenti. Quel numero è un’impostazione applicativa conservativa, non un limite di servizio universale. Misura la latenza e le risposte 429 per il tuo account, poi aumenta o diminuisci MAX_WORKERS in modo deliberato.
Solo le risposte 408, 429 e 5xx vengono ritentate con backoff esponenziale e jitter. Errori di autenticazione, ID di modello non validi e parametri non supportati falliscono immediatamente perché ritentare la stessa richiesta errata aggiunge solo ritardo.
4. Normalizza il risultato prima dello storage
I modelli di immagini non restituiscono sempre lo stesso contenitore. La risposta documentata di GPT Image contiene data[0].b64_json; altri modelli compatibili possono restituire data[0].url. Il worker gestisce entrambi, scrive l’immagine in un file temporaneo e la rinomina solo dopo che il download o la decodifica hanno avuto successo.
Per la produzione, sostituisci la directory locale output/ con S3, R2, GCS o un altro object store. Non trattare un URL ospitato dal provider come storage permanente a meno che la sua policy di retention lo indichi esplicitamente.
5. Registra utilizzo, tentativi e costo stimato
Ogni risultato diventa una riga compatta del manifest con l’ID del job, il modello, il percorso salvato, lo stato e il costo in USD stimato quando il catalogo live fornisce dati di pricing sufficienti. I job falliti mantengono l’errore invece di scomparire dal batch.
Script Python completo per la generazione di immagini in batch
Salva quanto segue come batch_image_pipeline.py, posiziona la coda accanto come jobs.jsonl ed esegui python3 batch_image_pipeline.py.
import base64, json, os, random, time
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
import requests
BASE_URL = "https://api.cometapi.com/v1"
KEY = os.environ["COMETAPI_KEY"]
WORKERS = int(os.getenv("MAX_WORKERS", "4"))
OUT = Path("output")
ROUTES = {
"product": "gpt-image-2",
"ad": "doubao-seedream-4-5-251128",
"content": "doubao-seedream-4-5-251128",
}
catalog = requests.get("https://api.cometapi.com/api/models", timeout=30)
catalog.raise_for_status()
CATALOG = {model["id"]: model for model in catalog.json()["data"]}
def generate(job):
model = job.get("model", ROUTES[job["kind"]])
if model not in CATALOG:
raise ValueError(f"Unknown model: {model}")
payload = {"model": model, "prompt": job["prompt"], "n": 1}
if model == "gpt-image-2":
payload.update(quality="low", size="1024x1024", output_format="jpeg")
for attempt in range(4):
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {KEY}"},
json=payload,
timeout=180,
)
if response.status_code not in {408, 429} and response.status_code < 500:
break
time.sleep(2**attempt + random.random())
response.raise_for_status()
body = response.json()
item = body["data"][0]
if item.get("b64_json"):
data = base64.b64decode(item["b64_json"])
extension = body.get("output_format", "png")
else:
download = requests.get(item["url"], timeout=120)
download.raise_for_status()
data = download.content
extension = {"image/png": "png", "image/webp": "webp"}.get(
download.headers.get("content-type"), "jpg"
)
path = OUT / f"{job['id']}.{extension}"
path.write_bytes(data)
price, usage = CATALOG[model].get("pricing") or {}, body.get("usage", {})
cost = price.get("per_request")
if cost is None and price.get("input") is not None:
cost = (usage.get("input_tokens", 0) * price["input"] +
usage.get("output_tokens", 0) * price["output"]) / 1_000_000
return {"id": job["id"], "model": model, "path": str(path),
"estimated_usd": cost * price.get("ratio", 1) if cost is not None else None}
def safe_generate(job):
try:
return {"status": "success", **generate(job)}
except Exception as error:
return {"id": job["id"], "status": "failed", "error": str(error)}
OUT.mkdir(exist_ok=True)
jobs = [json.loads(line) for line in Path("jobs.jsonl").read_text().splitlines() if line]
with ThreadPoolExecutor(max_workers=WORKERS) as pool:
results = list(pool.map(safe_generate, jobs))
with (OUT / "manifest.jsonl").open("w") as manifest:
manifest.writelines(json.dumps(result) + "\n" for result in results)
Lo script usa il catalogo attuale a runtime, mentre le due mappature di fallback sono esempi verificati il 20 agosto 2026. Ricontrollale prima di pubblicare o distribuire il codice in un’altra data.
Come testare il workflow di generazione immagini in batch
Inizia con un job e un worker:
MAX_WORKERS=1 python3 batch_image_pipeline.py
Una risposta GPT Image riuscita segue questa struttura:
{
"created": 1776841943,
"output_format": "jpeg",
"quality": "low",
"size": "1024x1024",
"usage": {
"input_tokens": 16,
"output_tokens": 208,
"total_tokens": 224
},
"data": [{"b64_json": "<base64-image-data>"}]
}
Il worker decodifica l’immagine, scrive output/<job-id>.jpeg e aggiunge una riga di successo a output/manifest.jsonl. Se un modello restituisce un URL, il worker lo scarica e memorizza il percorso locale nello stesso formato di manifest.
Il codice è stato verificato sintatticamente in locale. Una chiamata di generazione live richiede comunque la tua chiave CometAPI, quindi esegui lo smoke test con un solo job prima di aumentare la concorrenza.
Quanto costa la generazione di immagini in batch?
Il pricing deve essere con data/ora perché le tariffe dei modelli cambiano. Al 20 agosto 2026, il catalogo dei modelli CometAPI live restituiva i seguenti campi di prezzo base e un rapporto di fatturazione pari a 0.8:
gpt-image-2: $5 per 1M input tokens e $30 per 1M output tokens; applicando il rapporto indicato si ottengono tariffe effettive di $4 e $24 per 1M token.doubao-seedream-4-5-251128: $0.04 per richiesta; applicando il rapporto indicato si ottengono $0.032 per richiesta.
La guida ai prezzi di CometAPI spiega la fatturazione basata su token per i modelli con pricing ufficiale e quella per chiamata per i modelli con prezzo per richiesta. Lo script legge il catalogo quando gira e usa la stessa regola:
token cost = ratio × (input tokens × input rate + output tokens × output rate) / 1,000,000
request cost = ratio × per-request price
Ad esempio, la risposta GPT Image documentata sopra riporta 16 input token e 208 output token. Usando i valori del catalogo del 20 agosto, quel risultato illustrativo stima circa $0.005056. Il totale reale cambia con modello, qualità, dimensione, prompt, ritentativi e uso nella risposta. Considera la risposta API e la dashboard di utilizzo dell’account come il registro di fatturazione, non un’ipotesi fissa per immagine.
Metti a budget anche il lavoro non riuscito. Un ritentativo dopo un timeout non confermato può produrre un secondo risultato fatturabile, e un’immagine tecnicamente riuscita che fallisce la revisione consuma comunque budget. Traccia sia il costo API sia il tasso di accettazione:
effective cost per accepted image = total batch spend / approved images
Errori comuni delle API di generazione immagini e come risolverli
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| 401 | Chiave mancante o non valida | Controlla la COMETAPI_KEY lato server |
| 400 | Modello non valido o opzione non supportata | Ricontrolla il catalogo live e rimuovi i campi specifici del modello |
| 429 | Concorrenza eccessiva | Abbassa MAX_WORKERS e mantieni il backoff esponenziale |
| 5xx ripetuti | Guasto temporaneo a monte | Ritenta con un limite, poi sposta il job in una dead-letter queue |
| Nessuna immagine salvata | La risposta ha usato un contenitore diverso | Ispeziona data[0] e supporta b64_json o url |
| Spesa duplicata | Il job è stato rigiocato dopo un errore parziale | Usa ID durevoli e conferma solo dopo il successo dello storage |
Non ritentare ogni errore. Una richiesta 400 permanente resterà non valida, mentre un loop di retry illimitato su 429 può trasformare un picco di traffico in un backlog.
Best practice per la generazione di immagini in produzione su larga scala
Passa da JSON Lines a una coda durevole quando sono coinvolti più worker. Imposta un visibility timeout più lungo del tempo massimo di generazione, conferma un job solo dopo che immagine e manifest sono stati salvati, e invia i job esauriti a una dead-letter queue per la revisione.
Mantieni i controlli opzionali nella configurazione specifica del modello. Un payload condiviso dovrebbe contenere solo campi comuni come model, prompt e n: 1; aggiungi quality, size o output_format solo dopo che la documentazione del modello selezionato li conferma. Se aggiungi l’instradamento di fallback, scegli un modello che supporti lo stesso task e ricostruisci il payload per quel modello invece di riprodurre ciecamente opzioni specifiche del provider.
Archivia la chiave API in un secret manager, limita l’input dei prompt, scansiona gli asset generati secondo la tua policy e tieni gli URL del provider fuori dai record di prodotto a lungo termine. Registra ID job, ID modello, latenza, tentativi, utilizzo, percorso di storage, esito della revisione e data dello snapshot del catalogo. Questi campi ti permettono di confrontare i modelli per costo per immagine accettata invece che solo per prezzo nominale.
Infine, imposta guardrail di budget: una dimensione massima del batch, un limite di retry per job, un alert di spesa giornaliero e una condizione di stop quando scende il tasso di approvazione. Scalare più velocemente un prompt scadente non è un’ottimizzazione.
FAQ sull’automazione della generazione di immagini su larga scala
Qual è il modo più semplice per automatizzare la generazione di immagini su larga scala senza gestire diverse API?
Usa un’unica coda e workflow di storage, poi invia le richieste di immagini compatibili tramite una sola chiave CometAPI e https://api.cometapi.com/v1/images/generations. Cambia l’ID del modello nel tuo livello di instradamento invece di mantenere autenticazioni e SDK separati per provider.
Posso inviare una richiesta e chiedere a più modelli di immagini di generare contemporaneamente?
L’esempio invia un modello per job. Il fan-out è un workflow applicativo: duplica un job con ID e valori di modello distinti, poi confronta gli output salvati. Questo mantiene attribuibili a ciascun modello costi e stato di revisione.
Che concorrenza dovrei usare?
Non esiste un numero universale per ogni account e modello. Inizia con un pool limitato piccolo come quattro worker, monitora latenza e risposte 429, e regola in base all’evidenza.
Dovrei salvare l’URL restituito o l’immagine stessa?
Salva l’immagine nel tuo object storage. Un URL restituito può essere temporaneo, mentre i modelli GPT Image possono restituire contenuto base64 invece di un URL.
Come scelgo il modello più economico?
Calcola il costo per immagine accettata, non solo il prezzo per chiamata. Includi addebiti per token o richieste, ritentativi, download falliti, asset respinti, post-processing e revisione umana. Ricontrolla il catalogo dei modelli live il giorno in cui pubblichi o distribuisci.
Dove dovrei verificare l’endpoint e il formato della risposta?
Usa il Quick Start di CometAPI, la documentazione del catalogo dei modelli, il riferimento per la generazione di immagini e la guida ai prezzi.