Gemini 3.1 Flash Image Preview

• Modello: gemini-3.1-flash-image-preview (fisso)
• Funzionalità: Da testo a immagine, da immagine a immagine (fino a 14 riferimenti), fino a 4K, proporzioni estreme, ricerca Google opzionale

Non chiamare questo modello tramite /v1/chat/completions — riceverai 400 con un suggerimento di utilizzare l’API Images.

Endpoint

Modalità	Endpoint	Quando usare
Sincrono (consigliato)	POST https://apimaster.ai/v1/images/generations	Una singola richiesta HTTP; la piattaforma interroga il servizio upstream e restituisce { "data": [{ "url" }] }
Asincrono	POST https://apimaster.ai/v1/images/generations/async → GET https://apimaster.ai/v1/tasks/{task_id}?model=gemini-3.1-flash-image-preview	Operazioni lunghe, code personalizzate

Avvio rapido (sincrono)

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "Cyberpunk city at night, neon lights",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

Successo

{
  "created": 1782633696,
  "data": [{ "url": "https://apimaster.ai/imgs/1782633695067198543.jpg" }]
}

Imposta il timeout di lettura HTTP a ≥ 180s per 2K/4K. Scarica o replica gli URL prontamente — scadono.

Flusso asincrono

Invio

curl -s "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

Risposta all’invio

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

Polling

curl -s "https://apimaster.ai/v1/tasks/TASK_ID?model=gemini-3.1-flash-image-preview" \
  -H "Authorization: Bearer YOUR_API_KEY"

In caso di successo, leggi data.result.images[0].url. Stati tipici: in_progress → succeeded / completed.

Attendi 10–20s prima del primo poll, poi ogni 3–5s.

Autenticazione

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parametri del corpo

Campo	Tipo	Obbligatorio	Note
model	string	sì	gemini-3.1-flash-image-preview
prompt	string	sì	Descrizione della scena
size	string	no	Proporzioni; vedi sotto
resolution	string	no	0.5K / 1K / 2K / 4K, default 1K; case-insensitive
n	integer	no	Solo 1 supportato (numerico, non stringa)
image_urls	array	no	Immagini di riferimento (URL o data URI)
google_search	boolean	no	Grounding con ricerca testuale Google
google_image_search	boolean	no	Richiede google_search: true

Risoluzione e fasce di prezzo

Valore	~pixel	Prezzo rispetto a base 1K
0.5K	~512	uguale a 1K
1K	~1024	base
2K	~2048	× 4/3
4K	~4096	× 2

Addebito effettivo = prezzo del canale × moltiplicatore risoluzione × rapporto gruppo. Vedi marketplace o log della console.

Errori

HTTP	Significato
400	Parametri errati o endpoint sbagliato (chat)
401	Chiave API non valida
402	Saldo insufficiente
408	Timeout del polling sincrono — riprova in asincrono o abbassa la risoluzione
500 / 502	Errore del servizio upstream o della piattaforma

Le proporzioni non valide possono apparire come 500 quando è configurato un solo canale.

Note

• I log di utilizzo includono result_url per l’anteprima dell’immagine e request_data.effective_resolution.
• Il prezzo varia in base al canale e alla risoluzione — vedi marketplace.