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"
}
}Bilder generieren
Reiche einen Bildgenerierungs-Job ein — Prompt plus optionale trainierte Modelle — und erhalte eine Job-id zurück.
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 mit einer Job-id zurück; frage
GET /images/generations/{id} nach dem
Ergebnis ab. Kombiniere die trainierten Modelle deiner Organisation, indem du ihre
ids oder Namen übergibst — style_id, object_ids, person_ids, setting_ids —
plus eine color_palette_id. Jede Referenz akzeptiert einen Namen oder eine id,
die zu einem für dich sichtbaren Modell oder einer für dich sichtbaren Palette
aufgelöst wird. Wähle das Text-to-Image-Modell mit engine — die Engines, die du
nutzen kannst, listet GET /images/models.
Beispiel: mehrere trainierte Modelle komponieren
Übergib einstyle-Modell, ein oder mehrere person- und setting-Modelle sowie
eine color palette gemeinsam in einer Anfrage. Jede Modellreferenz — per id oder
Name — muss auf ein für dich sichtbares completed-Modell aufgelöst werden.
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 und setting_ids sind Arrays; style_id und
color_palette_id nehmen einen einzelnen Wert (einen Namen oder eine id).
num_outputs (1–4) ist standardmäßig 1 und jedes Ergebnis (output) wird
abgerechnet. Lass engine weg, um die Standard-Engine nano_banana_pro zu
verwenden, oder übergib nano_banana_2_1, nano_banana_2, nano_banana,
imagen_4, seedream_4 oder flux_1_pro. Jede Engine hat eigene
Seitenverhältnisse und Auflösungen — siehe
Engines oder
GET /images/models; ein nicht
unterstützter Wert gibt 422 zurück, bevor Credits berechnet werden. Trainierte
Modelle und color_palette_id funktionieren nur mit nano_banana_pro,
nano_banana_2_1 und nano_banana_2; andere Engines liefern 422.Autorisierungen
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
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.
Text prompt. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).
1"A minimalist product shot of a ceramic mug on linen, soft daylight"
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.
A color palette NAME or its UUID id, resolved within your visible set — a palette you created (including private ones) or a non-private palette shared with your organization. A name matching more than one visible palette is rejected — pass the id.
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"
Number of images to generate (1-4, every engine). Defaults to 1 (the app default is 4); each output is billed.
1 <= x <= 41
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"
Encoding of the returned images. v1 supports png only.
png "png"
Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).
"https://example.com/webhooks/samsa"
Antwort
Successful Response
202 body for POST /images/generations (ADR §7.1).
The image job id — poll GET /images/generations/{id}.
Initial status: always pending at submit.
pending, processing, completed, failed, cancelled "pending"
Credits this job is expected to cost (base 5 x num_outputs x resolution multiplier).
5