Usare l’API di immagini Gemini tramite proxy
Scegli il formato dell’API, genera un’immagine e riprendi l’attività quando scade il tempo di attesa.
Un proxy per l’API di immagini Gemini è un gateway tra la tua applicazione e un modello di immagini Gemini. Per usarlo servono l’ID di un modello capace di produrre immagini, il formato della richiesta previsto dal servizio e un modo per ottenere il file. Cambiare l’URL di base di un client di testo non dimostra il supporto alla generazione di immagini.
Il flusso documentato da OmniaKey è creare un’attività → consultarne lo stato → scaricare il risultato, a partire da POST /v1/media/tasks. Questa guida segue l’intero percorso e chiarisce le differenze rispetto all’API nativa di Google e alle interfacce compatibili con OpenAI.
Documentazione verificata il 14 ottobre 2026. Questa guida all’integrazione di OmniaKey si basa sui documenti pubblici di Google e OmniaKey. Non abbiamo eseguito generazioni a pagamento né misurato velocità o qualità dei fornitori. La presenza nel catalogo non garantisce i permessi della tua chiave o un canale disponibile al momento della chiamata.
Quale tipo di proxy ti serve?
Qui parliamo di un servizio API che gestisce richieste al modello, autenticazione e risposte. Un proxy di rete inoltra il traffico, ma non converte da solo un formato di API di immagini in un altro. Scegli in base alla specifica pubblicata dal servizio.
| Interfaccia | Formato della richiesta | Dove arriva l’immagine |
|---|---|---|
| Gemini GenerateContent | /v1beta/models/MODEL:generateContent, con contents e i campi supportati di generationConfig | Parti di immagine come candidates[].content.parts[].inlineData |
| Proxy compatibile con OpenAI | Endpoint e schema delle immagini documentati dal fornitore | Dati o URL nel formato di risposta previsto dal servizio |
| Attività di immagini OmniaKey | /v1/media/tasks, con model, type, operation, input, parameters | Prima un ID, poi assets[] dopo lo stato succeeded |
La guida attuale di Google alle immagini usa esempi dell’Interactions API. Il riferimento GenerateContent descrive un contratto distinto. Non mescolare i campi o i parser delle risposte e non presumere che il proxy offra entrambi.
Anche comprensione e generazione delle immagini sono capacità diverse. Un modello può descrivere una foto e restituire soltanto testo. Una chiamata di testo riuscita non verifica la generazione o la modifica. La dicitura «compatibile con OpenAI» non dimostra nemmeno che una specifica rotta supporti tutti i metodi dell’SDK.
Scegli un modello di immagini preciso
La documentazione di Google distingue questi ID:
- Nano Banana 2.1:
gemini-nano-banana-2.1, il punto di partenza consigliato da Google per nuovi flussi generali di immagini. - Nano Banana Pro:
gemini-3-pro-image, un’opzione distinta per compiti visivi più impegnativi. - Nano Banana 2:
gemini-3.1-flash-image, la generazione precedente, non un alias di 2.1.
Copia l’ID dal servizio che chiamerai. Verifica permessi, generazione o modifica, dimensioni e unità di fatturazione. Per 2.1, OmniaKey documenta parameters.aspect_ratio e parameters.image_size, con livelli 1K, 2K e 4K. Questi campi non sono intercambiabili con imageConfig di Google o con size e quality di GPT Image.
Consulta la pagina di Nano Banana 2.1 per l’offerta attuale e il confronto fra 2.1 e Pro per la scelta del modello.
Genera un’immagine con OmniaKey
Servono Bash, cURL, jq e una chiave OmniaKey nella variabile d’ambiente locale OMNIAKEY_API_KEY. Esegui i comandi sul backend o sul computer di sviluppo; non esporre la chiave nel codice del browser. Il semplice prompt in inglese permette di controllare prima il flusso dell’API, poi la qualità del risultato.
1. Crea e salva l’attività
Scegli un Idempotency-Key unico per questa richiesta logica. Il valore nell’esempio è dimostrativo: cambialo per una nuova attività e conserva la stessa chiave e lo stesso corpo nei tentativi successivi di quell’attività. Salva entrambi prima dell’invio.
curl --fail-with-body --silent --show-error \
https://api.omniakey.com/v1/media/tasks \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gemini-image-demo-20261014-001" \
-d '{
"model": "gemini-nano-banana-2.1",
"type": "image",
"operation": "generate",
"input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
"parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
}' -o task.json
Prosegui solo se cURL termina correttamente e task.json contiene un id. Una nuova attività restituisce 202 Accepted; ripetere chiave e corpo recupera l’attività originale con 200. Accettata non significa che l’immagine sia pronta. Consulta il ciclo di vita delle attività, in inglese.
2. Interroga l’ID salvato
Questo esempio Bash limita il numero di controlli. Raggiunto il limite, l’ID rimane disponibile per continuare più tardi. L’attività non viene annullata né ricreata.
TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
curl --fail-with-body --silent --show-error \
"https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-o result.json || exit 1
STATUS="$(jq -er '.status' result.json)" || exit 1
case "$STATUS" in
succeeded) break ;;
failed|canceled) jq '.error' result.json; exit 1 ;;
queued|processing) sleep 3 ;;
*) exit 1 ;;
esac
done
Se la creazione va in timeout prima di restituire l’ID, ripeti lo stesso corpo con la stessa chiave di idempotenza. Se hai già un ID, interroga quell’attività. Una chiave nuova può creare un secondo lavoro fatturabile. Il recupero dipende dalla conservazione: i record restano disponibili per 24 ore dalla creazione.
3. Scarica soltanto un risultato riuscito
jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
"$ASSET_URL" -o generated-image
Leggi mime_type per scegliere l’estensione corretta, poi controlla che il file si apra e abbia le dimensioni attese. Gli URL firmati scadono. Finché attività e file sono disponibili, una nuova interrogazione può fornire un URL aggiornato. Scarica i risultati da conservare: il collegamento non è uno spazio di archiviazione permanente.
Modifica un’immagine di riferimento
Usa operation: "edit" e dati Base64 incorporati in input.image, oppure input.images per più riferimenti quando supportati. L’istruzione di modifica resta in input.prompt. La documentazione dell’API immagini, in inglese mostra la struttura completa.
Il limite è 1 MiB per l’intero corpo della richiesta, Base64 compreso. Comprimi o ridimensiona il riferimento se necessario. I limiti di caricamento dell’API diretta di Google non sostituiscono quelli del proxy. Inizia con un’immagine piccola e una modifica chiara, poi verifica anche i dettagli che dovevano restare invariati.
Cambiare prompt, riferimento, modello o parametro significa creare una richiesta diversa e richiede una chiave nuova. Usare la stessa chiave con un corpo diverso restituisce 409 idempotency_key_reused.
Individua il livello del problema
| Sintomo | Cosa verificare | Azione successiva |
|---|---|---|
401 / 403 | Chiave, host, autenticazione e permessi del modello | Correggi credenziali o autorizzazioni prima di riprovare |
400 / 404 | Endpoint, ID, campi e proprietario dell’attività | Controlla il contratto senza inventare alias |
413 | Dimensione totale, Base64 compreso | Riduci l’immagine in ingresso |
409 idempotency_key_reused | Stessa chiave con un corpo diverso | Recupera con il corpo originale o usa una nuova chiave per un altro lavoro |
429 | Quota, frequenza e concorrenza | Leggi l’errore, riduci il carico e usa attese crescenti con un limite quando opportuno |
503 | Configurazione o capacità temporanea | worker_disabled e no_available_channel richiedono controlli su configurazione e disponibilità |
| Solo testo o uscita vuota | Supporto alle immagini, filtri di sicurezza, parser | In GenerateContent controlla promptFeedback, finishReason e tutte le parti |
| Timeout delle verifiche | L’attività è ancora in esecuzione? | Riprendi lo stesso ID senza creare una nuova attività |
La guida Google alla risoluzione dei problemi descrive il servizio di Google. Il proxy aggiunge un altro livello. Registra stato HTTP, codice di errore, ID e durata senza dati sensibili. Non inserire nei log chiavi o riferimenti privati. Un JSON con 200 non dimostra di avere un’immagine utilizzabile.
Confronta i costi e valida l’integrazione
La fatturazione diretta di Google e il prezzo di un proxy sono offerte separate. Prima di elaborare un lotto, controlla i prezzi attuali di OmniaKey e l’unità del modello. Non applicare il prezzo dei token di testo all’uscita di immagini e non presumere che un abbonamento personale Gemini paghi le chiamate del proxy.
Una misura utile è totale effettivamente addebitato ÷ numero di immagini approvate. Includi i tentativi fatturati e le immagini scartate in revisione. È una formula di pianificazione, non un benchmark misurato o una promessa di prezzo inferiore.
Prima di aumentare il volume, verifica cinque casi semplici:
- Un prompt restituisce un’immagine che si apre, nel formato e nelle dimensioni attesi.
- La modifica di un riferimento applica il cambiamento preservando i dettagli necessari.
- Ripetere chiave e corpo restituisce lo stesso ID dell’attività.
- Dopo un timeout locale puoi continuare tramite ID senza creare un altro lavoro.
- Un parametro invalido o un modello non disponibile produce un errore comprensibile, non un falso successo.
Registra ID del modello, parametri, durata, stato finale, addebito ed esito della verifica. Controlla il trattamento dei prompt e dei riferimenti prima di inviare materiale di produzione.
Domande frequenti
Basta cambiare l’URL di base dell’SDK?
Solo se il proxy documenta l’endpoint, i campi e la risposta con immagini attesi dall’SDK. Prova l’operazione sulle immagini: una chiamata di chat riuscita non basta.
Un proxy elimina i limiti di Gemini?
No. Possono applicarsi insieme i limiti del fornitore, del modello, del proxy e dell’account. Un gateway non garantisce generazione illimitata o disponibilità regionale.
Da quale modello conviene iniziare?
Controlla il catalogo attuale e valuta un modello supportato con una piccola attività. La guida Nano Banana 2.1 spiega le novità del modello; questo articolo si concentra sul collegamento e sulla verifica dell’API.
Fonti e prossimo passo
Le fonti principali sono la guida alle immagini, il riferimento GenerateContent, la risoluzione dei problemi di Google e i documenti OmniaKey citati. Questi collegamenti alla documentazione sono in inglese. Specifiche verificate il 14 ottobre 2026; conferma l’accesso al modello prima di eseguire l’esempio.