Edit an image

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": "<string>",
  "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": "1K",
  "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": "<string>",
    "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": "1K",
    "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: '<string>',
    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: '1K',
    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' => '<string>',
    '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' => '1K',
    '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\": \"<string>\",\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\": \"1K\",\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\": \"<string>\",\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\": \"1K\",\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\": \"<string>\",\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\": \"1K\",\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",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

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": "<string>",
  "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": "1K",
  "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": "<string>",
    "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": "1K",
    "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: '<string>',
    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: '1K',
    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' => '<string>',
    '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' => '1K',
    '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\": \"<string>\",\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\": \"1K\",\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\": \"<string>\",\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\": \"1K\",\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\": \"<string>\",\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\": \"1K\",\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",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

Submit a source image and a prompt describing the edit. The call returns 202 Accepted with a job id; poll GET /images/edits/{id} for the result. The image object takes exactly one of image_id, url, or base64 + mime_type.

Example: masked edit from a URL

Provide the source by url, add an inpaint mask (its presence selects PRO mode), and reuse a style model. The mask is a base64-encoded image marking the region to edit.

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
}

Send exactly one source mode in image. Omit mask for a text-only (SIMPLE) edit. resolution applies only to nano_banana_pro; omit it for the other engines. num_images (1–4) defaults to 1.

Authorizations

Authorization

string

header

required

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

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 — any of these forces the nano_banana_pro engine, mirroring the app), and an engine (a public-safe alias of the internal edit model). num_images defaults to 1.

image

PublicImageEditSource · object

required

The source image: exactly one of image_id, url, or base64+mime_type.

Show child attributes

prompt

string

required

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

Minimum string length: 1

Example:

"Replace the sky with a dramatic sunset"

mask

PublicImageEditMask · object | null

Optional inpaint mask. When present, the edit runs in PRO (mask-based) mode — supported only by the nano_banana_pro and gemini engines (or when trained models force nano_banana_pro).

Show child attributes

engine

string | null

Edit engine — one of nano_banana_pro (default), gemini, or kontext. Omit to use the default. Unknown engines return 422.

Example:

"nano_banana_pro"

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. Forces the nano_banana_pro engine.

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. Forces the nano_banana_pro engine.

resolution

string | null

Output resolution — 1K, 2K, or 4K. Only the nano_banana_pro engine supports it (credits scale 1K:1x, 2K:2x, 4K:4x; omitted = 1K); omit for the other engines.

Example:

"1K"

num_images

integer

default:1

Number of edited images to generate (1-4). Defaults to 1; each output is billed.

Required range: 1 <= x <= 4

Example:

1

output_format

enum<string>

default:png

Encoding of the returned images. v1 supports png only.

Available options:

png

Example:

"png"

webhook_url

string | null

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

Example:

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

Response

Successful Response

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

string<uuid>

required

The image-edit job id — poll GET /images/edits/{id}.

status

enum<string>

required

Initial status: always pending at submit.

Available options:

pending,

processing,

completed,

failed,

cancelled

Example:

"pending"

estimated_credits

integer

required

Credits this job is expected to cost (base 5 x num_images x resolution multiplier for nano_banana_pro).

Example:

5

Overview

Endpoints

Edit an image

Example: masked edit from a URL

Authorizations

Body

Response

​Example: masked edit from a URL

Authorizations

Body

Response

Example: masked edit from a URL