Edit an image with a prompt (Magic Edit)
curl --request POST \
--url https://api.samsa.ai/public/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": {
"image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "https://cdn.example.com/photo.png",
"base64": "<string>",
"mime_type": "image/png"
},
"prompt": "Replace the sky with a dramatic sunset",
"mask": {
"base64": "<string>"
},
"engine": "nano_banana_pro",
"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",
"resolution": "4K",
"num_images": 1,
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/edits"
payload = {
"image": {
"image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "https://cdn.example.com/photo.png",
"base64": "<string>",
"mime_type": "image/png"
},
"prompt": "Replace the sky with a dramatic sunset",
"mask": { "base64": "<string>" },
"engine": "nano_banana_pro",
"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",
"resolution": "4K",
"num_images": 1,
"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({
image: {
image_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
url: 'https://cdn.example.com/photo.png',
base64: '<string>',
mime_type: 'image/png'
},
prompt: 'Replace the sky with a dramatic sunset',
mask: {base64: '<string>'},
engine: 'nano_banana_pro',
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',
resolution: '4K',
num_images: 1,
output_format: 'png',
webhook_url: 'https://example.com/webhooks/samsa'
})
};
fetch('https://api.samsa.ai/public/v1/images/edits', 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/edits",
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([
'image' => [
'image_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'url' => 'https://cdn.example.com/photo.png',
'base64' => '<string>',
'mime_type' => 'image/png'
],
'prompt' => 'Replace the sky with a dramatic sunset',
'mask' => [
'base64' => '<string>'
],
'engine' => 'nano_banana_pro',
'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',
'resolution' => '4K',
'num_images' => 1,
'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/edits"
payload := strings.NewReader("{\n \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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/edits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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/edits")
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 \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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": 20,
"engine": "nano_banana_pro",
"resolution": "4K"
}{
"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"
}
}Modifica di immagini
Modifica un'immagine
Invia un job Magic Edit — un’immagine sorgente più un prompt, facoltativamente con mask e stile.
POST
/
images
/
edits
Edit an image with a prompt (Magic Edit)
curl --request POST \
--url https://api.samsa.ai/public/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": {
"image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "https://cdn.example.com/photo.png",
"base64": "<string>",
"mime_type": "image/png"
},
"prompt": "Replace the sky with a dramatic sunset",
"mask": {
"base64": "<string>"
},
"engine": "nano_banana_pro",
"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",
"resolution": "4K",
"num_images": 1,
"output_format": "png",
"webhook_url": "https://example.com/webhooks/samsa"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/edits"
payload = {
"image": {
"image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "https://cdn.example.com/photo.png",
"base64": "<string>",
"mime_type": "image/png"
},
"prompt": "Replace the sky with a dramatic sunset",
"mask": { "base64": "<string>" },
"engine": "nano_banana_pro",
"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",
"resolution": "4K",
"num_images": 1,
"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({
image: {
image_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
url: 'https://cdn.example.com/photo.png',
base64: '<string>',
mime_type: 'image/png'
},
prompt: 'Replace the sky with a dramatic sunset',
mask: {base64: '<string>'},
engine: 'nano_banana_pro',
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',
resolution: '4K',
num_images: 1,
output_format: 'png',
webhook_url: 'https://example.com/webhooks/samsa'
})
};
fetch('https://api.samsa.ai/public/v1/images/edits', 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/edits",
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([
'image' => [
'image_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'url' => 'https://cdn.example.com/photo.png',
'base64' => '<string>',
'mime_type' => 'image/png'
],
'prompt' => 'Replace the sky with a dramatic sunset',
'mask' => [
'base64' => '<string>'
],
'engine' => 'nano_banana_pro',
'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',
'resolution' => '4K',
'num_images' => 1,
'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/edits"
payload := strings.NewReader("{\n \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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/edits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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/edits")
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 \"image\": {\n \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"url\": \"https://cdn.example.com/photo.png\",\n \"base64\": \"<string>\",\n \"mime_type\": \"image/png\"\n },\n \"prompt\": \"Replace the sky with a dramatic sunset\",\n \"mask\": {\n \"base64\": \"<string>\"\n },\n \"engine\": \"nano_banana_pro\",\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 \"resolution\": \"4K\",\n \"num_images\": 1,\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": 20,
"engine": "nano_banana_pro",
"resolution": "4K"
}{
"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’immagine sorgente e un prompt che descrive la modifica. La chiamata
restituisce
202 Accepted con un id del job; interroga
GET /images/edits/{id} per il risultato.
L’oggetto image accetta esattamente uno tra image_id, url, oppure
base64 + mime_type.
Esempio: modifica con mask da un URL
Fornisci la sorgente tramiteurl, aggiungi un mask di inpaint (la sua
presenza seleziona la modalità PRO) e riutilizza un modello style. Il mask è
un’immagine codificata in base64 che segna la regione da modificare.
curl -X POST https://api.samsa.ai/public/v1/images/edits \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "url": "https://cdn.example.com/product-photo.png" },
"prompt": "Replace the plain background with our branded gradient",
"mask": { "base64": "iVBORw0KGgoAAAANSUhEUgAA...." },
"style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
"engine": "nano_banana_pro",
"resolution": "1K",
"num_images": 1
}'
{
"image": { "url": "https://cdn.example.com/product-photo.png" },
"prompt": "Replace the plain background with our branded gradient",
"mask": { "base64": "iVBORw0KGgoAAAANSUhEUgAA...." },
"style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
"engine": "nano_banana_pro",
"resolution": "1K",
"num_images": 1
}
Invia esattamente una modalità sorgente in
image. Ometti mask per una
modifica solo testuale (SIMPLE); un mask funziona solo su nano_banana_pro e
gemini. resolution (1K, 2K, 4K) si applica a nano_banana_pro,
nano_banana_2 e nano_banana_2_1; omettila per gemini e kontext. I modelli
addestrati e color_palette_id funzionano solo con nano_banana_pro — un altro
engine indicato restituisce 422. num_images (1–4) ha come valore predefinito
1. Vedi Engine e credits.Risposta
Il corpo202 riporta l’engine e la risoluzione effettivi, così vedi con cosa
gira la modifica e quanto costa:
202 Accepted
{
"id": "6b0e2f7c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
"status": "pending",
"estimated_credits": 5,
"engine": "nano_banana_pro",
"resolution": "1K"
}
resolution è null su gemini e kontext. estimated_credits è l’importo
dedotto: 5 / 10 / 20 per output a 1K / 2K / 4K sugli engine Nano Banana, 5
fissi per output su gemini e kontext, × num_images.Autorizzazioni
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
Corpo
application/json
POST /images/edits body (ADR §8, §10) — Magic Edit.
Supply a prompt and a source image; optionally a mask (auto-selects PRO
mode), trained models you own (including your own private models) or shared within
your organization (style_id/object_ids/person_ids/
setting_ids, color_palette_id — only on nano_banana_pro; any other named
engine is a 422, never a silent switch), an engine (a public-safe alias of the
internal edit model) and a resolution (Nano Banana engines only). The source
aspect ratio is kept. num_images defaults to 1.
The source image: exactly one of image_id, url, or base64+mime_type.
Show child attributes
Show child attributes
Text prompt describing the edit. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).
Minimum string length:
1Esempio:
"Replace the sky with a dramatic sunset"
Optional inpaint mask. When present, the edit runs in PRO (mask-based) mode — supported only by the nano_banana_pro, gemini engines; any other engine returns 422.
Show child attributes
Show child attributes
Edit engine — one of nano_banana_pro (Nano Banana Pro, default), nano_banana_2 (Nano Banana 2), nano_banana_2_1 (Nano Banana 2.1), gemini (Nano Banana), kontext (Flux Kontext). Omit to use the default. Unknown engines return 422. Trained models and a color palette work only with nano_banana_pro (also used when engine is omitted); naming any other engine together with them returns 422 — the engine is never switched silently.
Esempio:
"nano_banana_pro"
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. Only with nano_banana_pro (another named engine is a 422).
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. Only with nano_banana_pro (another named engine is a 422).
Output resolution — 1K, 2K, or 4K on nano_banana_pro, nano_banana_2, nano_banana_2_1 (credits scale 1K:1x, 2K:2x, 4K:4x; omitted = 1K). gemini, kontext have a fixed resolution — omit it there (a value returns 422). The response echoes the effective resolution.
Esempio:
"4K"
Number of edited images to generate (1-4). Defaults to 1; each output is billed.
Intervallo richiesto:
1 <= x <= 4Esempio:
1
Encoding of the returned images. v1 supports png only.
Opzioni disponibili:
png Esempio:
"png"
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/edits (ADR §7.1).
The image-edit job id — poll GET /images/edits/{id}.
Initial status: always pending at submit.
Opzioni disponibili:
pending, processing, completed, failed, cancelled Esempio:
"pending"
Credits this job is expected to cost — and the amount deducted: 5 x num_images x resolution multiplier on nano_banana_pro, nano_banana_2, nano_banana_2_1 (1K:1x, 2K:2x, 4K:4x), 5 x num_images on gemini, kontext.
Esempio:
20
The engine this edit runs on (the requested engine, or nano_banana_pro when omitted). Never switched silently.
Esempio:
"nano_banana_pro"
The output resolution this edit runs at (the requested resolution, or the engine default 1K); null for the fixed-resolution engines (gemini, kontext).
Esempio:
"4K"