Éditer une 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"
  }
}

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 par url, 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). resolution s’applique uniquement à nano_banana_pro ; omets-le pour les autres engines. num_images (1–4) vaut 1 par défaut.

Autorisations

Authorization

string

header

requis

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

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 — 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

requis

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

Show child attributes

prompt

string

requis

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

Exemple:

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

Exemple:

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

Exemple:

"1K"

num_images

integer

défaut:1

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

Plage requise: 1 <= x <= 4

Exemple:

1

output_format

enum<string>

défaut:png

Encoding of the returned images. v1 supports png only.

Options disponibles:

png

Exemple:

"png"

webhook_url

string | null

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).

string<uuid>

requis

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

status

enum<string>

requis

Initial status: always pending at submit.

Options disponibles:

pending,

processing,

completed,

failed,

cancelled

Exemple:

"pending"

estimated_credits

integer

requis

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

Exemple:

5

Aperçu Récupérer une édition d'image

Prise en main

APIs

Vérification de contenu

Exemple : édition avec masque à partir d’une URL

Autorisations

Corps

Réponse

​Exemple : édition avec masque à partir d’une URL

Autorisations

Corps

Réponse

Exemple : édition avec masque à partir d’une URL