Generate an AI image variation of the source asset

POST

/assets/{id}/edit/img2img

• Local development behind nginx (port 8088 by default)

Enqueues an aiedit.img2img job that dispatches a prompt + the source image’s bytes to the operator-configured MCP image-edit server (see /admin/system/aiedit). The job runs async (ComfyUI generation can take seconds-to-minutes); endpoint returns 202 + the job id. Poll /jobs/{id} for status; on completion the job result carries the new derivative asset id. A creative_lineage row links the derivative back to the source for the asset detail panel.

Requires capabilities mcp.client.use (umbrella) plus the per-tool capability operator pinned on the img2img grant (typically mcp.client.images.write).

Errors:

• 400 if the request body is missing / malformed.
• 401 if the caller is unauthenticated.
• 403 if the caller lacks the required capabilities.
• 404 if the source asset doesn’t exist.
• 409 if no MCP image-edit server is configured.
• 422 if the source asset is not an image (audio / video / doc / archive — img2img only applies to images).

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body ^required

Payload for POST /assets/{id}/edit/img2img. Zero-value knobs (denoise_strength, steps, seed) tell the bridge to apply its own defaults; the operator’s workflow defaults stay authoritative unless the caller explicitly overrides.

object

prompt

required

Steers the variation. Required even when empty-like (e.g. ”.”) to keep the operator’s audit trail human-readable.

string

>= 1 characters <= 2000 characters

denoise_strength

0 = no change from source; 1 = ignore source entirely (effectively txt2img). Bridge default is 0.7.

number

<= 1

steps

Inference step count. Bridge default is 20.

integer

>= 1 <= 100

seed

0 (or omitted) = random; the response carries the actual seed used.

integer

Responses

202

Img2img job enqueued.

The 202 response for the enqueue endpoints. Caller polls /jobs/{job_id} for status; on completion the job result carries the new derivative asset id.

object

job_id

required

The enqueued jobs.* row id.

string format: uuid

source_asset_id

required

The asset the variation derives from. Echoed for caller-side correlation.

string format: uuid

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

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

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

409

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

object

error

required

Human-readable error summary

string

Example

the request could not be completed

422

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