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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The id of the image asset to vary.
Request Body required
Section titled “Request Body required ”What to generate. Only prompt is required; leave the other
settings out to use the image-edit server’s defaults.
object
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.
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.
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.
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.
Responses
Section titled “ Responses ”The job was queued.
The queued job and the image it works from. Follow the job with GET /jobs/{id}.
object
The queued job’s id.
The source image’s id, as sent in the path.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedConflict (slug taken, would create cycle, etc.)
object
Human-readable error summary
Example
the request could not be completedRequest shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).
object
Human-readable error summary
Example
the request could not be completed