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"
}
}Édition d'images
Éditer une image
Soumets un job Magic Edit — une image source plus un prompt, avec masque et style optionnels.
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"
}
}Soumets une image source et un prompt décrivant l’édition. L’appel renvoie
202 Accepted avec un id de job ; interroge
GET /images/edits/{id} pour le résultat.
L’objet image prend exactement un parmi image_id, url, ou base64 +
mime_type.
Exemple : édition avec masque à partir d’une URL
Fournis la source parurl, ajoute un mask d’inpaint (sa présence sélectionne le
mode PRO), et réutilise un modèle style. Le mask est une image encodée en base64
marquant la région à éditer.
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
}
Envoie exactement un mode de source dans
image. Omets mask pour une édition
uniquement textuelle (SIMPLE) ; un mask ne fonctionne que sur nano_banana_pro
et gemini. resolution (1K, 2K, 4K) s’applique à nano_banana_pro,
nano_banana_2 et nano_banana_2_1 ; omets-le pour gemini et kontext. Les
modèles entraînés et color_palette_id ne fonctionnent qu’avec nano_banana_pro
— un autre engine nommé renvoie 422. num_images (1–4) vaut 1 par défaut.
Voir Engines et credits.Réponse
Le corps202 renvoie en écho le engine et la résolution effectifs, pour que tu
voies à quoi l’édition tourne et ce qu’elle coûte :
202 Accepted
{
"id": "6b0e2f7c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
"status": "pending",
"estimated_credits": 5,
"engine": "nano_banana_pro",
"resolution": "1K"
}
resolution vaut null sur gemini et kontext. estimated_credits est le
montant débité : 5 / 10 / 20 par output en 1K / 2K / 4K sur les engines Nano
Banana, 5 fixes par output sur gemini et kontext, × num_images.Autorisations
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
Corps
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:
1Exemple:
"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.
Exemple:
"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.
Exemple:
"4K"
Number of edited images to generate (1-4). Defaults to 1; each output is billed.
Plage requise:
1 <= x <= 4Exemple:
1
Encoding of the returned images. v1 supports png only.
Options disponibles:
png Exemple:
"png"
Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).
Exemple:
"https://example.com/webhooks/samsa"
Réponse
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.
Options disponibles:
pending, processing, completed, failed, cancelled Exemple:
"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.
Exemple:
20
The engine this edit runs on (the requested engine, or nano_banana_pro when omitted). Never switched silently.
Exemple:
"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).
Exemple:
"4K"