Skip to content

Generate an AI variation of an image

POST
/assets/{id}/edit/img2img

Queues a job that sends an image asset and your prompt to the instance’s AI image-edit server and saves the picture it generates as a new asset. The answer is a 202 with the job’s id; the source image isn’t changed.

Follow the job with GET /jobs/{id}. When its status is done, its result holds derivative_asset_id, the new asset, and can also hold seed_used, prompt_used and model_used. If it fails for good, status becomes failed, with the reason in last_error. A retried job can generate again, so one request can occasionally leave more than one new asset, and each request queues a new job.

To start a job you need the mcp.client.use and mcp.client.images.write capabilities (system.admin covers both), the asset must have the built-in Image type (asset_type 1), and an image-edit server must be set. Ownership of the source and its access rules aren’t checked, and an asset in the trash can be used too.

Everything else is checked when the job runs, so a 202 doesn’t mean the generation will succeed: the server must be registered and enabled with an enabled img2img tool, which can require a further capability, and cost limits apply. If the instance keeps restricted and embargoed content on local servers, such a source is only sent to a server registered as local. Your capabilities and the source’s sensitivity are taken when you make the request; the image itself is read when the job runs. Generation always goes to the server the app started with: a changed server setting takes effect after a restart, even though this endpoint checks the current setting.

The new asset is an Image titled “AI variation of” followed by the source’s title, or “Untitled” if it has none. It has the same owner as the source, whoever made the request, so a source with no owner gives an asset with no owner. Whatever the source’s settings, it’s public, active and not marked mature, with no team and no AI declaration. It doesn’t go through the usual upload processing, so no previews are queued for it. A separate generation record is saved with it, but no endpoint returns that record yet; the job still shows what you sent.

A 403 means a capability is missing, 404 that no asset has that id, 409 that no image-edit server is set, and 422 that the asset’s type isn’t that built-in Image type. A missing or blank prompt gets the JSON 400. A body that isn’t valid JSON, or a number of the wrong type, gets a plain-text 400, and server errors get a plain-text 500, not the JSON shown.

id
required
string format: uuid

The id of the image asset to vary.

What to generate. Only prompt is required; leave the other settings out to use the image-edit server’s defaults.

object
prompt
required

What the variation should show. Surrounding whitespace is trimmed and it can’t be blank; the length limits shown here aren’t checked by the server.

string
>= 1 characters <= 2000 characters
denoise_strength

How far to move away from the source image: low values stay close to it, and 1 ignores it. Leave it out, or send 0 or less, to use the server’s default (0.7 with the bundled ComfyUI bridge), so 0 doesn’t mean “no change”. Values above 1 aren’t refused.

number
<= 1
steps

How many generation steps to run. Leave it out, or send 0 or less, for the server’s default (20 with the bundled ComfyUI bridge). The limit of 100 isn’t checked.

integer
>= 1 <= 100
seed

A fixed seed for repeatable results. Leave it out or send 0 for a random one; the seed used can appear in the job’s result as seed_used, not in this response.

integer

The job was queued.

The queued job and the image it works from. Follow the job with GET /jobs/{id}.

object
job_id
required

The queued job’s id.

string format: uuid
source_asset_id
required

The source image’s id, as sent in the path.

string format: uuid

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Conflict (slug taken, would create cycle, etc.)

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object
error
required

Human-readable error summary

string
Example
the request could not be completed