Images

Edit Image

Edit an image you generated earlier, guided by a prompt. One to six outputs per call.

Every image_url must be an image your own account generated. Uploads and external URLs are rejected before you are charged.

Billed per output image. Outputs are screened after generation; withheld ones are deleted and refunded.

Upscaling: model: "spicy-upscale-1" with one image_url and scale 2 (default, $0.02) or 4 (images up to about 1 megapixel, $0.04). No prompt; detail is restored rather than enlarged, the picture and person stay the same. Returns one image with width and height, screened and labelled like any output.

POST/v1/images/editsTry it

Edit Image

cURL

curl --request POST \
  --url https://api.spicyapi.com/v1/images/edits \
  --header 'Authorization: Bearer $SPICYAPI_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "spicy-image-edit-1",
    "prompt": "change the background to a hotel suite",
    "image_url": "https://cdn.spicyapi.com/outputs/a1b2/req_8f2a91c4-0.png",
    "n": 2
  }'

200

JSON

{
  "id": "req_31c7de05",
  "object": "image.edit",
  "model": "spicy-image-edit-1",
  "created": 1755950400,
  "data": [
    { "url": "https://cdn.spicyapi.com/outputs/a1b2/req_31c7de05-0.png" },
    { "url": "https://cdn.spicyapi.com/outputs/a1b2/req_31c7de05-1.png" }
  ],
  "cost_usd": 0.30
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your SpicyAPI key (sk-spicy-…). Create one in the dashboard under API Keys.

Body

application/json

modelstringrequired

An image-edit model id, e.g. spicy-image-edit-1.

promptstringrequired

The change to make. Up to 2000 characters.

image_urlstring

A single source image. Use this or image_urls.

image_urlsstring[]

Up to 3 source images, all owned by your account. With character the sheet counts as one, so up to 2 of yours.

negative_promptstring

What to avoid.

enhance_promptboolean

Let the model expand the prompt with lighting, camera and detail cues before generating. Defaults to false: the prompt is sent exactly as written.

sizestring

Output width*height, one of the model's limits.sizes (1024*1024, 832*1216, 1216*832, 1280*1280, 1440*1440, 1024*1536, 1536*1024, 1080*1920, 1920*1080, 1152*2048, 2048*1152). When omitted the model chooses the output size.

ninteger

How many variations to return, 1 to 6 (the model's limits.maxOutputs). Billed per image. Defaults to 1.

seedinteger

Reproducibility seed.

characterstring

A saved character id (chr_...). The character's reference sheet goes in as Image 1 and your image_urls follow as Image 2 and 3; image_urls becomes optional.

mask_urlstring

Inpainting: a black and white mask (an https URL or a PNG or JPEG data URL), white where the image should change and black where it must stay. Works with exactly one image_url, no character and no size. The prompt describes the change; the result is blended back so everything under black is the original, pixel for pixel, with a soft edge. Same price as an edit.

dry_runboolean

When true, validates and screens the request and returns { object: "dry_run", cost_usd, moderation } without generating or charging. A blocked prompt still returns the normal 422.

userstring

Your own id for the end user making this request (up to 128 characters; send an opaque id, not an email). Send it if your product serves many people: declined-prompt history, strikes and suspensions are then kept per end user, so one person's behaviour never affects another's requests or your account. After 10 severe violations that user gets 403 end_user_suspended; the id is echoed back as user in every screening error so you can act on it. It is stored with the requests it was sent on, so DELETE /v1/end-users/{user} can erase that person's data.

Response

200 · application/json

Successful Response

idstringrequired

Request id.

objectstringrequired

Always image.edit.

dataImage · object[]required

One entry per edited image.

withheldinteger

How many outputs were withheld by the post-generation image screen. Those are deleted and refunded, so cost_usd covers only the images in data. Omitted when zero.

characterstring

The character id used, when one was passed.

cost_usdnumberrequired

What this request cost, in US dollars, already debited from your balance.

Was this page helpful?

Suggest edits Raise issue

List Images