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"
}
}Bildbearbeitung
Ein Bild bearbeiten
Reiche einen Magic-Edit-Job ein — ein Quellbild plus einen Prompt, optional maskiert und stilisiert.
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"
}
}Reiche ein Quellbild und einen Prompt ein, der die Bearbeitung beschreibt. Der
Aufruf gibt
202 Accepted mit einer Job-id zurück; frage
GET /images/edits/{id} nach dem Ergebnis ab.
Das image-Objekt nimmt genau eines von image_id, url oder base64 +
mime_type.
Beispiel: maskierte Bearbeitung von einer URL
Gib die Quelle perurl an, füge eine Inpaint-mask hinzu (ihr Vorhandensein
wählt den PRO-Modus) und nutze ein style-Modell wieder. Die mask ist ein
base64-codiertes Bild, das den zu bearbeitenden Bereich markiert.
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
}
Sende genau einen Quellmodus in
image. Lass mask für eine reine
Text-Bearbeitung (SIMPLE) weg; eine mask funktioniert nur auf nano_banana_pro
und gemini. resolution (1K, 2K, 4K) gilt für nano_banana_pro,
nano_banana_2 und nano_banana_2_1; lass es bei gemini und kontext weg.
Trainierte Modelle und color_palette_id funktionieren nur mit nano_banana_pro
— eine andere genannte Engine liefert 422. num_images (1–4) ist
standardmäßig 1. Siehe
Engines und Credits.Antwort
Der202-Body gibt die effektive Engine und Auflösung zurück, sodass du siehst,
womit der Edit läuft und was er kostet:
202 Accepted
{
"id": "6b0e2f7c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
"status": "pending",
"estimated_credits": 5,
"engine": "nano_banana_pro",
"resolution": "1K"
}
resolution ist null auf gemini und kontext. estimated_credits ist der
abgebuchte Betrag: 5 / 10 / 20 pro output bei 1K / 2K / 4K auf den
Nano-Banana-Engines, pauschal 5 pro output auf gemini und kontext, ×
num_images.Autorisierungen
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
Body
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:
1Beispiel:
"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.
Beispiel:
"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.
Beispiel:
"4K"
Number of edited images to generate (1-4). Defaults to 1; each output is billed.
Erforderlicher Bereich:
1 <= x <= 4Beispiel:
1
Encoding of the returned images. v1 supports png only.
Verfügbare Optionen:
png Beispiel:
"png"
Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).
Beispiel:
"https://example.com/webhooks/samsa"
Antwort
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.
Verfügbare Optionen:
pending, processing, completed, failed, cancelled Beispiel:
"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.
Beispiel:
20
The engine this edit runs on (the requested engine, or nano_banana_pro when omitted). Never switched silently.
Beispiel:
"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).
Beispiel:
"4K"