# Media Generation Nodes

> Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: `crates/cheng-nodes/src/nodes/builtin/ai/media_generation`, `crates/cheng-nodes/src/nodes/builtin/tools/media_generation`

Image, video, and audio generation each get a node. They are thin fronts over a provider call: you
supply a prompt and the provider-specific options, and you get an artifact back rather than inline
bytes. Model and provider selection follows the same configuration path as the LLM nodes, so a
workflow that already has a configured provider does not need a second set of credentials.

## Generate Image Tool — `tools/generate_image`

Agent tool: generate an image from a text prompt; returns workspace artifact references. Configure the provider connection (llm_config) on the canvas.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `prompt` | string (port) | — | `""` | Text prompt describing the image to generate. Connection port, not a form field. Control: `textarea` |
| `llm_config` | object (port) | — | `null` | Provider connection config (from ai/llm_config or JSON). Connection port, not a form field. Control: `text` |
| `size` | string | — | `null` | Image size, e.g. 1024x1024 (provider-defined values). Control: `select` |
| `aspect_ratio` | string | — | `null` | Aspect ratio, e.g. 16:9 (providers that take ratios instead of sizes). Control: `select` |
| `quality` | string | — | `null` | Provider-defined quality tier, e.g. standard / hd |
| `style` | string | — | `null` | Provider-defined style, e.g. vivid / natural |
| `count` | integer | — | `null` | Number of images to generate (default 1). Control: `number` |
| `output_filename` | string | — | `null` | Output filename; extension is corrected to match the actual format |
| `content` | array<any> (port) | — | `null` | Non-text multimodal inputs as a JSON array, e.g. [{"type":"image_url","url":"https://…","role":"source_image"}]; text belongs in prompt. Connection port, not a form field. Control: `json` |
| `source_image` | string | — | `null` | Image to transform (image-to-image / editing): an https URL, an artifact:// URI, or a data: URI. Providers differ in how much of the original they keep; strength-style controls belong in provider_options |
| `source_image_artifact` | object (port) | — | `null` | Image to transform; connect from an upstream .artifact port. Connection port, not a form field. |
| `mask_image` | string | — | `null` | Inpainting mask over the source image; provider support is narrow — OpenAI wants a same-size RGBA PNG whose transparent pixels are the region to repaint |
| `provider_options` | object (port) | — | `null` | Provider-specific options JSON merged into the request body. Connection port, not a form field. Control: `json` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `artifact` | object (port) | Generated image artifact reference (primary output). Connection port, not a form field. |
| `artifacts` | array<object> (port) | All generated image artifact references. Connection port, not a form field. |
| `url` | string | artifact:// URI of the first image (compatibility only) |
| `status` | string | Final status: completed / failed / timeout |
| `error` | string | Error message when generation failed |
| `metadata` | any | Diagnostic metadata (job id, attempts, elapsed ms, provider extras) |

## Generate Video Tool — `tools/generate_video`

Agent tool: generate a video from a text prompt (async submit/poll); returns a workspace artifact reference. Configure the provider connection (llm_config) on the canvas.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `prompt` | string (port) | — | `""` | Text prompt describing the video to generate. Connection port, not a form field. Control: `textarea` |
| `llm_config` | object (port) | — | `null` | Provider connection config (from ai/llm_config or JSON). Connection port, not a form field. Control: `text` |
| `duration` | integer | — | `null` | Video duration in seconds (provider-defined values). Control: `number` |
| `resolution` | string | — | `null` | Video resolution, e.g. 1080P / 720P (provider-defined). Control: `select` |
| `aspect_ratio` | string | — | `null` | Aspect ratio, e.g. 16:9 (providers that support it). Control: `select` |
| `seed` | integer | — | `null` | Deterministic seed when the provider supports it. Control: `number` |
| `poll_timeout_secs` | integer | — | `null` | Max seconds to poll the async job before giving up (default 600). Control: `number` |
| `poll_interval_secs` | integer | — | `null` | Seconds between job status polls (default 5). Control: `number` |
| `output_filename` | string | — | `null` | Output filename; extension is corrected to match the actual format |
| `content` | array<any> (port) | — | `null` | Non-text multimodal inputs as a JSON array, e.g. [{"type":"image_url","url":"https://…","role":"first_frame"}]; text belongs in prompt. Connection port, not a form field. Control: `json` |
| `first_frame_image` | string | — | `null` | First-frame image URL: an https URL, an artifact:// URI, or a data: URI |
| `last_frame_image` | string | — | `null` | Last-frame image URL: an https URL, an artifact:// URI, or a data: URI |
| `first_frame_artifact` | object (port) | — | `null` | First-frame image artifact; connect from ai/image_generation.artifact. Connection port, not a form field. |
| `last_frame_artifact` | object (port) | — | `null` | Last-frame image artifact; connect from ai/image_generation.artifact. Connection port, not a form field. |
| `provider_options` | object (port) | — | `null` | Provider-specific options JSON merged into the request body. Connection port, not a form field. Control: `json` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `artifact` | object (port) | Generated video artifact reference (primary output). Connection port, not a form field. |
| `poster_artifact` | object (port) | Poster/cover image artifact when the provider returns one. Connection port, not a form field. |
| `status` | string | Final status: completed / failed / timeout / invalid_input |
| `error` | string | Error message when generation failed |
| `metadata` | any | Diagnostic metadata: provider job id, poll attempts, elapsed ms |

## Generate Audio Tool — `tools/generate_audio`

Agent tool: synthesize speech (TTS) from text; returns a workspace artifact reference. Configure the provider connection (llm_config) on the canvas.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `text` | string (port) | — | `""` | Text to synthesize into speech. Connection port, not a form field. Control: `textarea` |
| `llm_config` | object (port) | — | `null` | Provider connection config (from ai/llm_config or JSON). Connection port, not a form field. Control: `text` |
| `voice` | string | — | `null` | TTS voice id, e.g. alloy / nova (provider-defined) |
| `format` | string | — | `null` | Audio output format, e.g. mp3 / wav / opus |
| `speed` | number | — | `null` | TTS speed multiplier (e.g. 0.5 - 2.0). Control: `number` |
| `output_filename` | string | — | `null` | Output filename; extension is corrected to match the actual format |
| `provider_options` | object (port) | — | `null` | Provider-specific options JSON merged into the request body. Connection port, not a form field. Control: `json` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `artifact` | object (port) | Generated audio artifact reference (primary output). Connection port, not a form field. |
| `status` | string | Final status: completed / failed / timeout |
| `error` | string | Error message when generation failed |
| `metadata` | any | Diagnostic metadata (elapsed ms, provider extras) |

## Next steps

- [Media Input Nodes](/docs/nodes-media-input)
- [LLM Nodes](/docs/nodes-llm)
- [LLM & Model Configuration](/docs/config-llm-models)