Vai al contenuto principale
Trasforma un prompt testuale in immagini con POST /images/generations, componendo facoltativamente i modelli style, object, person e setting addestrati della tua organizzazione, più una color palette. Passa engine per scegliere il modello text-to-image; omettilo per usare l’engine predefinito, nano_banana_pro. GET /images/models elenca gli engine che puoi usare, con i loro limiti e i loro credits.

​
Engine

Ogni engine accetta num_outputs da 1 a 4; i valori predefiniti sono aspect_ratio 1:1 e resolution 1K. Un rapporto d’aspetto o una risoluzione che l’engine non supporta restituisce 422 prima che vengano addebitati credits — la richiesta non viene mai rimodellata.
  • Modelli addestrati e palette. style_id, object_ids, person_ids, setting_ids e color_palette_id funzionano con nano_banana_pro, nano_banana_2_1 e nano_banana_2. Con nano_banana, imagen_4, seedream_4 o flux_1_pro restituiscono 422 (con param = il campo) — non vengono mai scartati, e l’engine non viene mai cambiato.
  • Altri endpoint. Questo elenco vale per POST /images/generations (e per lo strumento MCP generate_image). Magic Edit e img2img accettano propri valori di engine: entrambi accettano nano_banana_pro, nano_banana_2 e nano_banana_2_1, e Magic Edit accetta anche gemini e kontext.
  • Organizzazioni limitate ai modelli addestrati. Alcune organizzazioni generano solo con i loro modelli addestrati. Per loro, GET /images/models restituisce un elenco data vuoto con unavailable_reason: "organization_restricted", qualsiasi engine restituisce 422, e una richiesta deve omettere engine e passare almeno un modello addestrato (style_id, object_ids, person_ids, setting_ids) o un color_palette_id.

​
Pattern asincrono

La generazione è asincrona. POST /images/generations restituisce immediatamente 202 Accepted con un id del job, uno status e un valore estimated_credits. Interroga GET /images/generations/{id} finché status non è completed (oppure failed/cancelled), poi leggi le immagini prodotte — ognuna include un presigned URL valido per 24 ore. Un job i cui output non hanno superato tutti la pipeline di compliance termina failed con error delivery_blocked_compliance: <codes> (vedi Blocchi di compliance). Passa un webhook_url per essere notificato invece di interrogare (vedi Webhook).

​
Credits

Ogni output costa 5 credits a 1K, con scalatura in base alla risoluzione (1K ×1, 2K ×2, 4K ×4) e moltiplicato per num_outputs — uguale su ogni engine. I costi attingono dal pool della tua organizzazione; un pool esaurito restituisce 402. Vedi Prezzi.

Quickstart

Una guida completa dallo zero all’immagine con curl, Python e TypeScript.