curl --request POST \
--url https://api.samsa.ai/public/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
"style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"person_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"setting_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engine": "nano_banana_pro",
"num_outputs": 1,
"aspect_ratio": "1:1",
"resolution": "1K",
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/generations"
payload = {
"prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
"style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"person_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"setting_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engine": "nano_banana_pro",
"num_outputs": 1,
"aspect_ratio": "1:1",
"resolution": "1K",
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'A minimalist product shot of a ceramic mug on linen, soft daylight',
style_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
object_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
person_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
setting_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
color_palette_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
engine: 'nano_banana_pro',
num_outputs: 1,
aspect_ratio: '1:1',
resolution: '1K',
output_format: 'png',
webhook_url: 'https://example.com/webhooks/samsa'
})
};
fetch('https://api.samsa.ai/public/v1/images/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/images/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'A minimalist product shot of a ceramic mug on linen, soft daylight',
'style_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'object_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'person_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'setting_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'color_palette_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'engine' => 'nano_banana_pro',
'num_outputs' => 1,
'aspect_ratio' => '1:1',
'resolution' => '1K',
'output_format' => 'png',
'webhook_url' => 'https://example.com/webhooks/samsa'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/images/generations"
payload := strings.NewReader("{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/generations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"estimated_credits": 5
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}Generate images
Submit an image-generation job — prompt plus optional trained models — and get a job id back.
curl --request POST \
--url https://api.samsa.ai/public/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
"style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"person_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"setting_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engine": "nano_banana_pro",
"num_outputs": 1,
"aspect_ratio": "1:1",
"resolution": "1K",
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/generations"
payload = {
"prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
"style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"person_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"setting_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engine": "nano_banana_pro",
"num_outputs": 1,
"aspect_ratio": "1:1",
"resolution": "1K",
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'A minimalist product shot of a ceramic mug on linen, soft daylight',
style_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
object_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
person_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
setting_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
color_palette_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
engine: 'nano_banana_pro',
num_outputs: 1,
aspect_ratio: '1:1',
resolution: '1K',
output_format: 'png',
webhook_url: 'https://example.com/webhooks/samsa'
})
};
fetch('https://api.samsa.ai/public/v1/images/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/images/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'A minimalist product shot of a ceramic mug on linen, soft daylight',
'style_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'object_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'person_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'setting_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'color_palette_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'engine' => 'nano_banana_pro',
'num_outputs' => 1,
'aspect_ratio' => '1:1',
'resolution' => '1K',
'output_format' => 'png',
'webhook_url' => 'https://example.com/webhooks/samsa'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/images/generations"
payload := strings.NewReader("{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/generations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"A minimalist product shot of a ceramic mug on linen, soft daylight\",\n \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"object_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"person_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"setting_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"engine\": \"nano_banana_pro\",\n \"num_outputs\": 1,\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"output_format\": \"png\",\n \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"estimated_credits": 5
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}202 Accepted
with a job id; poll GET /images/generations/{id}
for the result. Combine your organization’s trained models by passing their ids or
names — style_id, object_ids, person_ids, setting_ids — plus a
color_palette_id. Each ref accepts a name or id that resolves to a model or
palette visible to you. Pick the text-to-image model with engine — list the
engines you can use with GET /images/models.
Example: compose multiple trained models
Pass astyle model, one or more person and setting models, and a color
palette together in one request. Every model reference — by id or name — must
resolve to a completed model visible to you.
curl -X POST https://api.samsa.ai/public/v1/images/generations \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Our founder presenting on stage at the product launch, cinematic lighting",
"style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
"person_ids": ["c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
"setting_ids": ["a9b8c7d6-e5f4-4a3b-2c1d-0e1f2a3b4c5d"],
"color_palette_id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
"engine": "nano_banana_pro",
"aspect_ratio": "16:9",
"resolution": "2K",
"num_outputs": 2
}'
{
"prompt": "Our founder presenting on stage at the product launch, cinematic lighting",
"style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
"person_ids": ["c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
"setting_ids": ["a9b8c7d6-e5f4-4a3b-2c1d-0e1f2a3b4c5d"],
"color_palette_id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
"engine": "nano_banana_pro",
"aspect_ratio": "16:9",
"resolution": "2K",
"num_outputs": 2
}
object_ids, person_ids, and setting_ids are arrays; style_id and
color_palette_id take a single value (a name or id). num_outputs (1–4)
defaults to 1 and each output is billed. Omit engine to use the default
nano_banana_pro, or pass nano_banana_2_1, nano_banana_2, nano_banana,
imagen_4, seedream_4, or flux_1_pro. Each engine has its own aspect ratios
and resolutions — see Engines or
GET /images/models; an unsupported value
returns 422 before any credits are charged. Trained models and
color_palette_id work only with nano_banana_pro, nano_banana_2_1, and
nano_banana_2; other engines return 422.Authorizations
Body
POST /images/generations body (ADR §8, §10).
Trained-model refs (style_id, object_ids, person_ids, setting_ids) and the
color_palette_id color-palette ref combine on the Gemini engines — each accepts a
NAME or its UUID id, resolved within your visible set (a model/palette you own,
including private ones, or a non-private one shared within your organization);
setting_ids maps to the internal scene_ids (ADR §8.2). The standalone engines
(nano_banana, imagen_4, seedream_4, flux_1_pro) reject refs with a 422.
engine is the public text-to-image catalog (ADR §8.3, GET /images/models). Note
num_outputs defaults to 1 for API ergonomics — the internal app default is 4.
A style model NAME or its UUID id (from list_models), resolved within your visible set — a model you own (including your own private models) or a non-private one shared with your organization. A name matching more than one visible model is rejected — pass the id. Must be completed.
object models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.
person models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.
setting models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id. Maps to internal scenes.
Generation engine — one of nano_banana_pro (Nano Banana Pro, default), nano_banana_2_1 (Nano Banana 2.1), nano_banana_2 (Nano Banana 2), nano_banana (Nano Banana), imagen_4 (Imagen 4), seedream_4 (Seedream 4), flux_1_pro (Flux.1 Pro). Omit to use the default. Each engine has its own aspect ratios and resolutions — list them with GET /images/models. Trained models (style_id, object_ids, person_ids, setting_ids) work only with nano_banana_pro, nano_banana_2_1, nano_banana_2, and color_palette_id only with nano_banana_pro, nano_banana_2_1, nano_banana_2; other engines return 422 (refs are never dropped and the engine is never switched). Unknown engines return 422. Some organizations generate only with their trained models: there any engine returns 422 — omit it and pass at least one trained model or a color_palette_id. Compatibility note (2026-10): nano_banana keeps its engine id, limits and price, but now runs on the Google API like every Nano Banana engine (it ran on FAL before). Its outputs take the same provenance and labelled-download path as all other generations.
"nano_banana_pro"
Aspect ratio for the generated image(s), 1:1 (default). Valid values depend on the engine (see aspect_ratios in GET /images/models): nano_banana_pro/nano_banana_2_1/nano_banana_2: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8; nano_banana: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9; imagen_4: 1:1, 16:9, 9:16, 4:3, 3:4; seedream_4/flux_1_pro: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Unsupported ratios return 422 before any credits are charged.
"1:1"
Output resolution, 1K (default). Valid values depend on the engine (see resolutions in GET /images/models): nano_banana_pro/nano_banana_2_1/nano_banana_2: 1K, 2K, 4K; nano_banana/seedream_4/flux_1_pro: 1K; imagen_4: 1K, 2K. Credits scale 1K:1x, 2K:2x, 4K:4x per output; unsupported values return 422 before any credits are charged.
"1K"
Response
Successful Response
202 body for POST /images/generations (ADR §7.1).