GeraikitaGeraikita AI
MenuGenerazione di immagini

Generazione di immagini

Trasforma una descrizione testuale (prompt) in immagini con i modelli di immagine di Google (famiglia Nano Banana / Gemini Image). L’endpoint è compatibile con la OpenAI Images API — basta puntare l’SDK openai alla base URL di Geraikita, con la stessa gk- key e lo stesso saldo GeraiPoints.

Endpoint

POSThttps://ai.geraikita.com/v1/images/generations
HeaderValore
AuthorizationBearer gk-... (oppure x-api-key: gk-...)
Content-Typeapplication/json

Una richiesta = un prompt, che produce da 1 a 4 immagini. Lo streaming non è supportato — la risposta arriva in un’unica volta quando le immagini sono pronte.

Parametri del body

ParametroTipoDescrizione
modelstringobbligatorioID del modello di immagine, ad es. gemini-3.1-flash-image o gemini-3-pro-image — l’elenco completo è nella tabella dei prezzi qui sotto.
promptstringobbligatorioDescrizione dell’immagine desiderata, al massimo 4000 caratteri.
nintegerfacoltativoNumero di immagini, 1–4. Predefinito 1. Ogni immagine riuscita è addebitata separatamente.
sizestringfacoltativoUno tra auto | 1024x1024 | 1536x1024 | 1024x1536 | 1792x1024 | 1024x1792. Predefinito auto: il modello sceglie il formato, di solito orizzontale 16:9 (circa 1376×768). La dimensione è solo un’indicazione del formato — la risoluzione finale dipende dal modello.
response_formatstringfacoltativourl (predefinito) per un link all’immagine, oppure b64_json per i dati dell’immagine in base64 direttamente nella risposta.

Gli altri campi (ad es. quality o style) vengono ignorati.

Esempi

L’elaborazione richiede di solito 15–45 secondi per richiesta e può arrivare a circa 4 minuti quando si usa il percorso di riserva. Imposta un timeout del client di almeno 300 secondi perché la richiesta non venga interrotta prima che le immagini siano pronte.
curl https://ai.geraikita.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer gk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Poster promozionale di un caffè freddo con zucchero di palma su un tavolo di legno, calda luce del mattino, grande scritta \"SCONTO 20%\" in alto, stile illustrazione flat",
    "n": 1,
    "size": "1024x1024"
  }'

Risposta di esempio

data contiene un oggetto per ogni immagine riuscita — url o b64_json in base a response_format. Se alcune immagini falliscono, gli oggetti possono essere meno di n.

200 OK · application/json
{
  "created": 1793464057,
  "data": [
    { "url": "https://api.geraikita.com/cdn/ai-gambar/2026/11/xxxxxxxxxxxx.jpg" }
  ]
}

Header di risposta: X-Geraikita-Images = numero di immagini riuscite, X-Geraikita-GP-Charged = GeraiPoints addebitati per quella richiesta.

Prezzi

I modelli di immagine sono fatturati per immagine generata con successo — non per token. I prezzi attuali (soggetti a modifiche) sono nella tabella qui sotto e nella pagina dei prezzi.

Al momento non è possibile caricare i prezzi dei modelli di immagine — vedi la pagina dei prezzi.

  • Le immagini non riuscite non vengono addebitate, così come le richieste rifiutate (parametri non validi o violazioni della policy sui contenuti).
  • Il saldo GeraiPoints deve coprire n × il prezzo per immagine prima che la richiesta venga elaborata; altrimenti la risposta è 402.
  • I modelli di immagine non sono inclusi nell’Unlimited plan, in Bansos (piano gratuito) né in altre quote gratuite — vengono sempre scalati dal saldo GeraiPoints.
  • Ogni immagine compare come una riga nella cronologia di utilizzo del dashboard, con l’etichetta Immagine.

Codici di errore

Gli errori seguono il formato OpenAI: un oggetto error con message, type, param e code.

Statotype / codeSignificato
400invalid_request_errorParametro non valido (ad es. n fuori da 1–4, size sconosciuta, prompt vuoto o troppo lungo). Nessun addebito.
400content_policy_violationIl prompt viola la policy sui contenuti (vedi sotto). Nessun addebito.
401—API key mancante o non valida.
402insufficient_quotaGeraiPoints insufficienti per il numero di immagini richiesto — ricarica per favore.
403—Questo modello non è consentito per quella API key — aggiungilo all’elenco dei modelli della key nel dashboard.
404model_not_foundModello sconosciuto o non di immagine.
429rate_limit_exceededTroppe richieste — il limite è di 10 richieste/minuto per key. Attendi quanto indicato dall’header Retry-After.
502image_generation_failedLa generazione dell’immagine non è riuscita lato server. Nessun addebito — riprova.
Esempio di errore
{
  "error": {
    "message": "...",
    "type": "...",
    "param": "...",
    "code": "..."
  }
}

Chiamare un modello di immagine tramite /v1/chat/completions restituisce 400 con un rimando a questo endpoint — usa /v1/images/generations.

Consigli per il prompt

  • I prompt possono essere scritti in italiano, inglese, indonesiano o altre lingue.
  • Il modello può scrivere testo dentro l’immagine — metti il testo esatto tra virgolette, ad es. la scritta "SCONTO 20%".
  • Descrivi soggetto, ambientazione, stile (foto, illustrazione flat, 3D, acquerello), illuminazione e composizione — più sei preciso, più il risultato è fedele.
  • Scegli size in base all’uso: 1024x1024 per il feed, 1024x1792 per storie/verticale, 1792x1024 per banner orizzontali.
  • Ti servono più varianti? Usa n fino a 4 in una sola richiesta — ricorda che ogni immagine riuscita viene addebitata.

Policy sui contenuti

Le seguenti richieste vengono rifiutate:

  • Contenuti sessuali o espliciti.
  • Contenuti che sfruttano o mettono in pericolo minori.
  • Violenza sadica o gore.
  • Figure politiche reali o personaggi pubblici reali.

I rifiuti restituiscono 400 con il codice content_policy_violation e non vengono addebitati.

Link alle immagini e archiviazione

L’URL in data[].url è pubblico — chiunque abbia il link può aprire l’immagine — e non è garantito che resti disponibile per sempre. Scarica e conserva una copia nel tuo archivio subito dopo la generazione, oppure richiedi b64_json per ricevere i dati dell’immagine direttamente nella risposta.