Genera immagini

Generate images from a prompt (and optional trained models)

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"
  }
}

POST

images

generations

Generate images from a prompt (and optional trained models)

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"
  }
}

Invia un prompt per generare da una a quattro immagini. La chiamata restituisce 202 Accepted con un id del job; interroga GET /images/generations/{id} per il risultato. Combina i modelli addestrati della tua organizzazione passando i loro id o i loro nomi — style_id, object_ids, person_ids, setting_ids — più un color_palette_id. Ogni riferimento accetta un nome o un id che si risolve a un modello o a una palette visibile a te. Scegli il modello text-to-image con engine — GET /images/models elenca gli engine che puoi usare.

Esempio: comporre più modelli addestrati

Passa un modello style, uno o più modelli person e setting e una color palette insieme in un’unica richiesta. Ogni riferimento a un modello — tramite id o nome — deve risolversi a un modello completed visibile a te.

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 e setting_ids sono array; style_id e color_palette_id accettano un singolo valore (un nome o un id). num_outputs (1–4) ha come valore predefinito 1 e ogni output viene addebitato. Ometti engine per usare il predefinito nano_banana_pro, oppure passa nano_banana_2_1, nano_banana_2, nano_banana, imagen_4, seedream_4 o flux_1_pro. Ogni engine ha i propri rapporti d’aspetto e le proprie risoluzioni — vedi Engine o GET /images/models; un valore non supportato restituisce 422 prima che vengano addebitati credits. I modelli addestrati e color_palette_id funzionano solo con nano_banana_pro, nano_banana_2_1 e nano_banana_2; gli altri engine restituiscono 422.

Autorizzazioni

Authorization

string

header

obbligatorio

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Corpo

application/json

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.

prompt

string

obbligatorio

Text prompt. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).

Minimum string length: 1

Esempio:

"A minimalist product shot of a ceramic mug on linen, soft daylight"

style_id

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_ids

(string<uuid> | string)[]

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_ids

(string<uuid> | string)[]

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_ids

(string<uuid> | string)[]

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.

color_palette_id

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.

engine

string | null

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.

Esempio:

"nano_banana_pro"

num_outputs

integer

predefinito:1

Number of images to generate (1-4, every engine). Defaults to 1 (the app default is 4); each output is billed.

Intervallo richiesto: 1 <= x <= 4

Esempio:

1

aspect_ratio

string

predefinito:1:1

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.

Esempio:

"1:1"

resolution

string

predefinito:1K

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.

Esempio:

"1K"

output_format

enum<string>

predefinito:png

Encoding of the returned images. v1 supports png only.

Opzioni disponibili:

png

Esempio:

"png"

webhook_url

string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).

Esempio:

"https://example.com/webhooks/samsa"

Risposta

Successful Response

202 body for POST /images/generations (ADR §7.1).

string<uuid>

obbligatorio

The image job id — poll GET /images/generations/{id}.

status

enum<string>

obbligatorio

Initial status: always pending at submit.

Opzioni disponibili:

pending,

processing,

completed,

failed,

cancelled

Esempio:

"pending"

estimated_credits

integer

obbligatorio

Credits this job is expected to cost (base 5 x num_outputs x resolution multiplier).

Esempio:

5

Panoramica

Endpoint

Genera immagini

Esempio: comporre più modelli addestrati

Autorizzazioni

Corpo

Risposta

​Esempio: comporre più modelli addestrati

Autorizzazioni

Corpo

Risposta

Esempio: comporre più modelli addestrati