> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Image & Audio Generation

> High-level text-to-image, audio, video and 3D generation, conditioned image variants, and the two post-processing passes — all nine actions of one tool since 0.50.0 slice 16.

<Info>1 tool. Generated from the live MCP tool schemas — do not edit by hand; run `npm run docs:gen`.</Info>

<Tip>**You don't type these calls.** Ask your agent for what you want in ordinary English — it chooses the tool and fills in the arguments. The JSON on this page is what it sends. New here? Start with [Using the tools](/docs/using-tools).</Tip>

## generate\_image

Generate media from a prompt or an existing image — the high-level entry points that build the graph for you. Every action enqueues on the connected ComfyUI and returns the prompt\_id immediately; the resulting asset\_id arrives in the completion notification. Driven by the `action` parameter:

* action:"image" — Text-to-image. Builds a txt2img workflow, filling any unspecified parameter from your configured defaults (get\_defaults (action:"set") / COMFYUI\_DEFAULT\_\* / config file), auto-selecting a local checkpoint when none is given — checkpoints known to lack a text encoder (e.g. video models) are skipped. `prompt` is required. For full control over the node graph, use create\_workflow + enqueue\_workflow instead.
* action:"audio" — Text-to-audio, supporting the ACE Step 1.5 and Stable Audio 3 model families. Builds the appropriate workflow graph, filling unspecified parameters from your defaults and auto-selecting local models. `model_family`, `prompt` and `duration` are required. Requires a running ComfyUI with the corresponding model files installed.
* action:"video" — Text-to-video, or image-to-video when `image` is given (animate a start frame). Composes an LTX-2.3 distilled workflow on your LOCAL GPU using the render-verified Comfy-Org node stack (gemma text encoder + abliterated/distilled LoRAs). Needs the LTX-2.3 models (\~24-46GB): install with apply\_manifest --path packs/ltx-2.3-txt2vid/manifest.yaml (or ltx-2.3-img2vid for i2v); returns an actionable error if the checkpoint is missing. `seconds` is converted to an 8n+1 frame count. For i2v, higher `strength` means MORE adherence to the start frame but LESS motion (1.0 can freeze the clip) — keep \~0.6. This minimal path omits the synchronized audio + stage-2 spatial upscale that the full ltx-2.3 packs ship. `prompt` is required. The video is written under output/video/ — find it with get\_image (action:"list\_outputs") (VHS/SaveVideo outputs may not appear in /history).
* action:"3d" — Generate a 3D model (glb/obj/fbx) from a text prompt or an input image, using the connected ComfyUI's hosted partner 3D nodes (Tripo, Meshy, Rodin, Hunyuan3D — auto-detected from the server; these are paid API nodes needing a comfy.org API key/login on the server or COMFY\_API\_KEY here). `mode` is required ("text" needs `prompt`, "image" needs `image`). Poll queue (action:"status") / get\_history (action:"list") for the resulting model file (saved to ComfyUI's output directory). If the server has no 3D-capable API nodes, returns an actionable error naming local-pack alternatives.
* action:"controlnet" — Image conditioned by a ControlNet preprocessed image (pose skeleton, depth, canny, normal, etc.) plus a text prompt. Upload the control image first with upload\_image (action:"image"), then pass its filename as `control_image`. `prompt` and `control_image` are required; `checkpoint` and `controlnet_model` auto-resolve from local models. control\_image must ALREADY be a preprocessed map (this action does not run the preprocessor); requires a running ComfyUI with a matching controlnet model in models/controlnet/.
* action:"ip\_adapter" — Image guided by a reference image's style/subject via IP-Adapter, plus a text prompt. Requires the ComfyUI\_IPAdapter\_plus custom nodes. Upload the reference first with upload\_image (action:"image"), then pass its filename as `reference_image`. `prompt` and `reference_image` are required; `checkpoint` auto-resolves. Requires a running ComfyUI with ComfyUI\_IPAdapter\_plus and a matching IP-Adapter model installed, or the workflow will fail at execution time.
* action:"regenerate" — Re-enqueue the workflow that produced an EXISTING ASSET, optionally applying `overrides`. Overrides are applied to any node input matching the key name (e.g. cfg, steps, sampler\_name, scheduler, seed, denoise, text). Seeds are re-randomized by default so each call yields a fresh image unless seed is explicitly passed in overrides. `asset_id` is required. To re-run from execution HISTORY rather than a registered asset, use enqueue\_workflow (action:"rerun").
* action:"upscale" — Upscale an image with an ESRGAN super-resolution model. Builds an UpscaleModelLoader → ImageUpscaleWithModel workflow (scale=2 supersamples the 4x result back down for sharper output) and enqueues it on your LOCAL GPU. Upload the source first with upload\_image (action:"image") (or stage a prior output with upload\_image (action:"stage")), then pass its filename as `image`. Needs an upscale model in models/upscale\_models/ (e.g. 4x-ClearRealityV1 / 4x\_foolhardy\_Remacri, provided by the anima/ernie packs or download\_model); returns an actionable error if none is found. `image` is required.
* action:"remove\_background" — Remove an image's background, returning a transparent (RGBA) cutout. Builds a LoadImage → BiRefNetRMBG → SaveImage workflow using the ComfyUI-RMBG (BiRefNet) matting node and enqueues it on your LOCAL GPU. Upload the source first with upload\_image (action:"image") (or stage a prior output with upload\_image (action:"stage")), then pass its filename as `image`. Requires the ComfyUI-RMBG custom node (pack: wan-transparent, or install\_custom\_node 'comfyui-rmbg'); the BiRefNet model auto-downloads on first run. If the node isn't installed, returns an actionable error telling you how to install it. `image` is required.

<Tip>**In plain terms:** The one-line way to get a picture — and, through `action`, the same one-line way to get audio, a video clip, a 3D model, a re-run of an earlier image, an upscale, or a background removed. You do not need a workflow open, or any workflow at all: describe what you want and this builds and runs a sensible graph for you. Everything except `action` and the one or two fields that action needs is optional and falls back to your saved defaults.</Tip>

### Parameters

<ParamField path="action" type="enum" required>
  What to generate. action:"image"/action:"video" require `prompt`; action:"audio" requires `model_family`+`prompt`+`duration`; action:"3d" requires `mode` (+ `prompt` or `image`); action:"controlnet" requires `prompt`+`control_image`; action:"ip\_adapter" requires `prompt`+`reference_image`; action:"regenerate" requires `asset_id`; action:"upscale" and action:"remove\_background" require `image`. Options: `action:"image"`, `action:"audio"`, `action:"video"`, `action:"3d"`, `action:"controlnet"`, `action:"ip_adapter"`, `action:"regenerate"`, `action:"upscale"`, `action:"remove_background"`.
</ParamField>

<ParamField path="prompt" type="string">
  Positive text prompt. REQUIRED for actions "image", "audio", "video", "controlnet" and "ip\_adapter"; for action:"3d" it is required in mode "text" and optional (passed through only if the chosen node accepts it) in mode "image". Unused by action:"regenerate", action:"upscale" and action:"remove\_background".
</ParamField>

<ParamField path="negative_prompt" type="string">
  Negative prompt (default: empty / from defaults). Used by actions "image", "video", "controlnet", "ip\_adapter" and — for the Stable Audio 3 family only — "audio".
</ParamField>

<ParamField path="width" type="integer">
  Image width in pixels. Actions "image", "controlnet", "ip\_adapter".
</ParamField>

<ParamField path="height" type="integer">
  Image height in pixels. Actions "image", "controlnet", "ip\_adapter".
</ParamField>

<ParamField path="steps" type="integer">
  Sampling steps. Actions "image", "audio", "video", "controlnet", "ip\_adapter" (video defaults to 8 for the distilled model).
</ParamField>

<ParamField path="cfg" type="number">
  CFG scale. Actions "image", "audio", "video", "controlnet", "ip\_adapter" (video defaults to 1.0 for the distilled model).
</ParamField>

<ParamField path="sampler" type="string">
  Sampler name (e.g. euler, dpmpp\_2m). Actions "image", "audio", "controlnet", "ip\_adapter".
</ParamField>

<ParamField path="scheduler" type="string">
  Scheduler (e.g. normal, karras). Actions "image", "audio", "controlnet", "ip\_adapter".
</ParamField>

<ParamField path="seed" type="integer">
  Seed (omit to randomize). Actions "image", "audio", "video", "controlnet", "ip\_adapter".
</ParamField>

<ParamField path="checkpoint" type="string">
  Checkpoint filename; auto-selected from local models if omitted. The relevant checkpoint differs per action: a diffusion checkpoint for "image"/"controlnet"/"ip\_adapter", the LTX checkpoint for "video", the Stable Audio 3 checkpoint for "audio".
</ParamField>

<ParamField path="batch_size" type="integer">
  action:"image" — number of images to generate.
</ParamField>

<ParamField path="filename_prefix" type="string">
  Output filename prefix. action:"audio" (default audio/ace\_step or audio/stable\_audio\_3), action:"video" (default 'video/ltx-2.3') and action:"remove\_background" (default 'ComfyUI\_cutout').
</ParamField>

<ParamField path="image" type="string">
  Filename of an image in ComfyUI's input dir (upload it first with upload\_image (action:"image"), or stage a prior output with upload\_image (action:"stage")). REQUIRED for action:"upscale" and action:"remove\_background"; the start frame for action:"video" image-to-video; the input image for action:"3d" in mode "image".
</ParamField>

<ParamField path="model" type="string">
  Model file for the post-processing actions: action:"upscale" — an upscale model in models/upscale\_models/ (auto-selected from local models if omitted); action:"remove\_background" — the BiRefNet matting model (default 'BiRefNet\_toonout'; auto-downloaded by ComfyUI-RMBG).
</ParamField>

<ParamField path="scale" type="number">
  action:"upscale" — net upscale factor: 2 or 4 (default 4).
</ParamField>

<ParamField path="control_image" type="string">
  action:"controlnet" — filename of the (already-uploaded, already-preprocessed) control image in ComfyUI's input dir. REQUIRED for that action.
</ParamField>

<ParamField path="controlnet_model" type="string">
  action:"controlnet" — ControlNet model file (in models/controlnet/); auto-selected if omitted.
</ParamField>

<ParamField path="reference_image" type="string">
  action:"ip\_adapter" — filename of the (already-uploaded) reference image in ComfyUI's input dir. REQUIRED for that action.
</ParamField>

<ParamField path="weight" type="number">
  action:"ip\_adapter" — IP-Adapter influence on the output, typically 0.0-1.0 (default 0.8); higher = closer to the reference.
</ParamField>

<ParamField path="preset" type="string">
  action:"ip\_adapter" — IPAdapterUnifiedLoader preset (default 'PLUS (high strength)').
</ParamField>

<ParamField path="weight_type" type="enum">
  action:"ip\_adapter" — IPAdapter weight mode (default 'standard' — required by current IPAdapter\_plus builds). Options: `standard`, `prompt is more important`, `style transfer`.
</ParamField>

<ParamField path="strength" type="number">
  Two DIFFERENT knobs sharing one field, each with its own range, checked when the action runs: action:"video" (i2v only) — adherence to the start frame, 0-1 inclusive (default 0.6; higher = LESS motion); action:"controlnet" — conditioning strength, must be > 0, typically 0.0-2.0 (default 1.0; higher = stronger adherence to the control image).
</ParamField>

<ParamField path="seconds" type="number">
  action:"video" — clip length in seconds (default 4; \~10s max).
</ParamField>

<ParamField path="resolution" type="string">
  action:"video" — 'WIDTHxHEIGHT' e.g. '768x512' (rounded to multiples of 32; default 768x512).
</ParamField>

<ParamField path="fps" type="number">
  action:"video" — frames per second (default 25).
</ParamField>

<ParamField path="mode" type="enum">
  action:"3d" — "text" = text-to-3D from `prompt`; "image" = image-to-3D from an uploaded input `image`. REQUIRED for that action. Options: `text`, `image`.
</ParamField>

<ParamField path="node" type="string">
  action:"3d" — explicit 3D API node class\_type to use (e.g. "MeshyTextToModelNode"); auto-selected if omitted. Use list\_api\_nodes with filter "3d" to see options.
</ParamField>

<ParamField path="inputs" type="object">
  action:"3d" — provider-specific extra inputs passed through to the node (e.g. style, texture, quality). Use list\_api\_nodes (action:"schema") on the chosen node for valid keys.
</ParamField>

<ParamField path="model_family" type="enum">
  action:"audio" — audio model family; determines which workflow template and model loaders to use. REQUIRED for that action. Options: `ace_step_1.5`, `stable_audio_3`.
</ParamField>

<ParamField path="duration" type="number">
  action:"audio" — audio duration in seconds. REQUIRED for that action.
</ParamField>

<ParamField path="unet" type="string">
  action:"audio" — ACE UNet model filename (in models/diffusion\_models/); auto-selected if omitted.
</ParamField>

<ParamField path="vae" type="string">
  action:"audio" — ACE VAE model filename (in models/vae/); auto-selected if omitted.
</ParamField>

<ParamField path="clip_a" type="string">
  action:"audio" — primary text encoder filename (in models/text\_encoders/); auto-selected if omitted.
</ParamField>

<ParamField path="clip_b" type="string">
  action:"audio" — secondary text encoder filename (in models/text\_encoders/); auto-selected if omitted.
</ParamField>

<ParamField path="clip" type="string">
  action:"audio" — Stable Audio CLIP encoder filename (in models/text\_encoders/); auto-selected if omitted.
</ParamField>

<ParamField path="lyrics" type="string">
  action:"audio" — lyrics or song structure description (ACE only — section-by-section breakdown).
</ParamField>

<ParamField path="language" type="string">
  action:"audio" — language code for prompt (ACE only, default: 'en').
</ParamField>

<ParamField path="musical_key" type="string">
  action:"audio" — target musical key (ACE only, e.g. 'C major', 'E minor'; default: 'C major').
</ParamField>

<ParamField path="shift" type="number">
  action:"audio" — ModelSamplingAuraFlow shift parameter (ACE only, default: 3).
</ParamField>

<ParamField path="guidance_scale" type="number">
  action:"audio" — TextEncodeAceStepAudio1.5 cfg\_scale, the text encoder guidance scale (ACE only, default: 2).
</ParamField>

<ParamField path="bpm" type="integer">
  action:"audio" — TextEncodeAceStepAudio1.5 tempo in beats per minute (ACE only, 10-300, default: 120).
</ParamField>

<ParamField path="timesignature" type="enum">
  action:"audio" — TextEncodeAceStepAudio1.5 time signature (ACE only, one of '2'/'3'/'4'/'6', default: '4'). Options: `2`, `3`, `4`, `6`.
</ParamField>

<ParamField path="temperature" type="number">
  action:"audio" — TextEncodeAceStepAudio1.5 LLM sampling temperature (ACE only, 0-2, default: 0.85).
</ParamField>

<ParamField path="top_p" type="number">
  action:"audio" — TextEncodeAceStepAudio1.5 LLM top-p nucleus sampling (ACE only, 0-2000, default: 0.9).
</ParamField>

<ParamField path="top_k" type="integer">
  action:"audio" — TextEncodeAceStepAudio1.5 LLM top-k sampling (ACE only, 0-100, default: 0 = disabled).
</ParamField>

<ParamField path="min_p" type="number">
  action:"audio" — TextEncodeAceStepAudio1.5 LLM min-p sampling (ACE only, 0-1, default: 0).
</ParamField>

<ParamField path="generate_audio_codes" type="boolean">
  action:"audio" — generate audio codes via the TextEncodeAceStepAudio1.5 LLM (ACE only, default: true).
</ParamField>

<ParamField path="audio_quality" type="enum">
  action:"audio" — SaveAudioMP3 bitrate/quality (ACE only, one of 'V0'/'128k'/'320k', default: '320k'). Options: `V0`, `128k`, `320k`.
</ParamField>

<ParamField path="asset_id" type="string">
  action:"regenerate" — asset id of the source generation. REQUIRED for that action.
</ParamField>

<ParamField path="overrides" type="object">
  action:"regenerate" — map of input-name → new value applied to every node that already has that input. Common keys: cfg, steps, sampler\_name, scheduler, seed, denoise, text.
</ParamField>

<ParamField path="disable_random_seed" type="boolean">
  action:"regenerate" and action:"3d" — if true, do not randomize seed fields. For action:"regenerate", combine with `overrides.seed` to reproduce the exact original image.
</ParamField>

### Examples

**You say:** Make me a picture of a red fox in the snow.

```json theme={null}
{
  "tool": "generate_image",
  "arguments": {
    "action": "image",
    "prompt": "a red fox in deep snow, golden hour, sharp focus"
  }
}
```

**You get back:** The finished image, inline in the conversation, plus the seed and settings that produced it so you can ask for the same thing again.

**You say:** Same fox, but widescreen, more detail, and keep it repeatable.

```json theme={null}
{
  "tool": "generate_image",
  "arguments": {
    "action": "image",
    "prompt": "a red fox in deep snow, golden hour, sharp focus",
    "negative_prompt": "blurry, watermark, text",
    "width": 1344,
    "height": 768,
    "steps": 30,
    "cfg": 4.5,
    "seed": 12345
  }
}
```

**You get back:** The same fields plus the image. Because `seed` was pinned, running this again with the same settings gives the same picture — that is how you iterate on one image instead of rolling a new one each time.

**You say:** Turn that fox picture into a short clip of it walking.

```json theme={null}
{
  "tool": "generate_image",
  "arguments": {
    "action": "video",
    "prompt": "a red fox walking through deep snow, camera slowly pushing in",
    "seconds": 5,
    "resolution": "832x480",
    "fps": 16
  }
}
```

**You get back:** A path to the rendered video file plus the settings used. Video takes far longer than a still — minutes, not seconds — so the agent will usually tell you it has started and then report back.

**You say:** That one was nearly right — run it again with more steps.

```json theme={null}
{
  "tool": "generate_image",
  "arguments": {
    "action": "regenerate",
    "asset_id": "a3f9c1",
    "overrides": {
      "steps": 40
    }
  }
}
```

**You get back:** A new render from the EXACT graph that produced that asset, with only the fields you named changed. The seed is re-rolled unless you pass one, so this gives you a fresh take rather than the same image.

***