Skip to main content
POST
/
images
/
edits
Edit an image with a prompt
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"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}
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
  }'
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_....

Headers

​
authorization
string | null

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), your organization's trained models (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.

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

​
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
string<uuid> | null

A style model in your organization (forces nano_banana_pro).

​
object_ids
string<uuid>[]

object models in your organization to compose in.

​
person_ids
string<uuid>[]

person models in your organization to compose in.

​
setting_ids
string<uuid>[]

setting models in your organization (maps to internal scenes).

​
color_palette_id
string<uuid> | null

A color palette in your organization (forces nano_banana_pro).

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

​
id
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