nodmix 2026.5.25

package/docs/providers/perplexity-provider.md

@@ -0,0 +1,123 @@
+---
+summary: "Perplexity web search provider setup (API key, search modes, filtering)"
+title: "Perplexity"
+read_when:
+  - You want to configure Perplexity as a web search provider
+  - You need the Perplexity API key or OpenRouter proxy setup
+---
+
+The Perplexity plugin provides web search capabilities through the Perplexity
+Search API or Perplexity Sonar via OpenRouter.
+
+<Note>
+This page is the Perplexity **provider** setup. For the Perplexity **tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
+</Note>
+
+| Property    | Value                                                                  |
+| ----------- | ---------------------------------------------------------------------- |
+| Type        | Web search provider (not a model provider)                             |
+| Auth        | `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
+| Config path | `plugins.entries.perplexity.config.webSearch.apiKey`                   |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the API key">
+    Run the interactive web-search configuration flow:
+
+    ```bash
+    nodmix configure --section web
+    ```
+
+    Or set the key directly:
+
+    ```bash
+    nodmix config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
+    ```
+
+  </Step>
+  <Step title="Start searching">
+    The agent will automatically use Perplexity for web searches once the key is
+    configured. No additional steps are required.
+  </Step>
+</Steps>
+
+## Search modes
+
+The plugin auto-selects the transport based on API key prefix:
+
+<Tabs>
+  <Tab title="Native Perplexity API (pplx-)">
+    When your key starts with `pplx-`, Nodmix uses the native Perplexity Search
+    API. This transport returns structured results and supports domain, language,
+    and date filters (see filtering options below).
+  </Tab>
+  <Tab title="OpenRouter / Sonar (sk-or-)">
+    When your key starts with `sk-or-`, Nodmix routes through OpenRouter using
+    the Perplexity Sonar model. This transport returns AI-synthesized answers with
+    citations.
+  </Tab>
+</Tabs>
+
+| Key prefix | Transport                    | Features                                         |
+| ---------- | ---------------------------- | ------------------------------------------------ |
+| `pplx-`    | Native Perplexity Search API | Structured results, domain/language/date filters |
+| `sk-or-`   | OpenRouter (Sonar)           | AI-synthesized answers with citations            |
+
+## Native API filtering
+
+<Note>
+Filtering options are only available when using the native Perplexity API
+(`pplx-` key). OpenRouter/Sonar searches do not support these parameters.
+</Note>
+
+When using the native Perplexity API, searches support the following filters:
+
+| Filter         | Description                            | Example                             |
+| -------------- | -------------------------------------- | ----------------------------------- |
+| Country        | 2-letter country code                  | `us`, `de`, `jp`                    |
+| Language       | ISO 639-1 language code                | `en`, `fr`, `zh`                    |
+| Date range     | Recency window                         | `day`, `week`, `month`, `year`      |
+| Domain filters | Allowlist or denylist (max 20 domains) | `example.com`                       |
+| Content budget | Token limits per response / per page   | `max_tokens`, `max_tokens_per_page` |
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Environment variable for daemon processes">
+    If the Nodmix Gateway runs as a daemon (launchd/systemd), make sure
+    `PERPLEXITY_API_KEY` is available to that process.
+
+    <Warning>
+    A key exported only in an interactive shell will not be visible to a
+    launchd/systemd daemon unless that environment is explicitly imported. Set
+    the key in `~/.nodmix/.env` or via `env.shellEnv` to ensure the gateway
+    process can read it.
+    </Warning>
+
+  </Accordion>
+
+  <Accordion title="OpenRouter proxy setup">
+    If you prefer to route Perplexity searches through OpenRouter, set an
+    `OPENROUTER_API_KEY` (prefix `sk-or-`) instead of a native Perplexity key.
+    Nodmix will detect the prefix and switch to the Sonar transport
+    automatically.
+
+    <Tip>
+    The OpenRouter transport is useful if you already have an OpenRouter account
+    and want consolidated billing across multiple providers.
+    </Tip>
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Perplexity search tool" href="/tools/perplexity-search" icon="magnifying-glass">
+    How the agent invokes Perplexity searches and interprets results.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full configuration reference including plugin entries.
+  </Card>
+</CardGroup>

package/docs/providers/qianfan.md

@@ -0,0 +1,132 @@
+---
+summary: "Use Qianfan's unified API to access many models in Nodmix"
+read_when:
+  - You want a single API key for many LLMs
+  - You need Baidu Qianfan setup guidance
+title: "Qianfan"
+---
+
+Qianfan is Baidu's MaaS platform, providing a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+| Property | Value                             |
+| -------- | --------------------------------- |
+| Provider | `qianfan`                         |
+| Auth     | `QIANFAN_API_KEY`                 |
+| API      | OpenAI-compatible                 |
+| Base URL | `https://qianfan.baidubce.com/v2` |
+
+## Getting started
+
+<Steps>
+  <Step title="Create a Baidu Cloud account">
+    Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and ensure you have Qianfan API access enabled.
+  </Step>
+  <Step title="Generate an API key">
+    Create a new application or select an existing one, then generate an API key. The key format is `bce-v3/ALTAK-...`.
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --auth-choice qianfan-api-key
+    ```
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    nodmix models list --provider qianfan
+    ```
+  </Step>
+</Steps>
+
+## Built-in catalog
+
+| Model ref                            | Input       | Context | Max output | Reasoning | Notes         |
+| ------------------------------------ | ----------- | ------- | ---------- | --------- | ------------- |
+| `qianfan/deepseek-v3.2`              | text        | 98,304  | 32,768     | Yes       | Default model |
+| `qianfan/ernie-5.0-thinking-preview` | text, image | 119,000 | 64,000     | Yes       | Multimodal    |
+
+<Tip>
+The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
+</Tip>
+
+## Config example
+
+```json5
+{
+  env: { QIANFAN_API_KEY: "bce-v3/ALTAK-..." },
+  agents: {
+    defaults: {
+      model: { primary: "qianfan/deepseek-v3.2" },
+      models: {
+        "qianfan/deepseek-v3.2": { alias: "QIANFAN" },
+      },
+    },
+  },
+  models: {
+    providers: {
+      qianfan: {
+        baseUrl: "https://qianfan.baidubce.com/v2",
+        api: "openai-completions",
+        models: [
+          {
+            id: "deepseek-v3.2",
+            name: "DEEPSEEK V3.2",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 98304,
+            maxTokens: 32768,
+          },
+          {
+            id: "ernie-5.0-thinking-preview",
+            name: "ERNIE-5.0-Thinking-Preview",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 119000,
+            maxTokens: 64000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="Transport and compatibility">
+    Qianfan runs through the OpenAI-compatible transport path, not native OpenAI request shaping. This means standard OpenAI SDK features work, but provider-specific parameters may not be forwarded.
+  </Accordion>
+
+  <Accordion title="Catalog and overrides">
+    The bundled catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
+
+    <Note>
+    Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v3.2`).
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Troubleshooting">
+    - Ensure your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
+    - If models are not listed, confirm your account has the Qianfan service activated.
+    - The default base URL is `https://qianfan.baidubce.com/v2`. Only change it if you use a custom endpoint or proxy.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full Nodmix configuration reference.
+  </Card>
+  <Card title="Agent setup" href="/concepts/agent" icon="robot">
+    Configuring agent defaults and model assignments.
+  </Card>
+  <Card title="Qianfan API docs" href="https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb" icon="arrow-up-right-from-square">
+    Official Qianfan API documentation.
+  </Card>
+</CardGroup>

package/docs/providers/qwen.md

@@ -0,0 +1,332 @@
+---
+summary: "Use Qwen Cloud via Nodmix's bundled qwen provider"
+read_when:
+  - You want to use Qwen with Nodmix
+  - You previously used Qwen OAuth
+title: "Qwen"
+---
+
+<Warning>
+
+**Qwen OAuth has been removed.** The free-tier OAuth integration
+(`qwen-portal`) that used `portal.qwen.ai` endpoints is no longer available.
+See [Issue #49557](https://github.com/nodmix/nodmix/issues/49557) for
+background.
+
+</Warning>
+
+Nodmix now treats Qwen as a first-class bundled provider with canonical id
+`qwen`. The bundled provider targets the Qwen Cloud / Alibaba DashScope and
+Coding Plan endpoints and keeps legacy `modelstudio` ids working as a
+compatibility alias.
+
+- Provider: `qwen`
+- Preferred env var: `QWEN_API_KEY`
+- Also accepted for compatibility: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`
+- API style: OpenAI-compatible
+
+<Tip>
+If you want `qwen3.6-plus`, prefer the **Standard (pay-as-you-go)** endpoint.
+Coding Plan support can lag behind the public catalog.
+</Tip>
+
+## Getting started
+
+Choose your plan type and follow the setup steps.
+
+<Tabs>
+  <Tab title="Coding Plan (subscription)">
+    **Best for:** subscription-based access through the Qwen Coding Plan.
+
+    <Steps>
+      <Step title="Get your API key">
+        Create or copy an API key from [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys).
+      </Step>
+      <Step title="Run onboarding">
+        For the **Global** endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice qwen-api-key
+        ```
+
+        For the **China** endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice qwen-api-key-cn
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          agents: {
+            defaults: {
+              model: { primary: "qwen/qwen3.5-plus" },
+            },
+          },
+        }
+        ```
+      </Step>
+      <Step title="Verify the model is available">
+        ```bash
+        nodmix models list --provider qwen
+        ```
+      </Step>
+    </Steps>
+
+    <Note>
+    Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
+    work as compatibility aliases, but new setup flows should prefer the canonical
+    `qwen-*` auth-choice ids and `qwen/...` model refs. If you define an exact
+    custom `models.providers.modelstudio` entry with another `api` value, that
+    custom provider owns `modelstudio/...` refs instead of the Qwen compatibility
+    alias.
+    </Note>
+
+  </Tab>
+
+  <Tab title="Standard (pay-as-you-go)">
+    **Best for:** pay-as-you-go access through the Standard Model Studio endpoint, including models like `qwen3.6-plus` that may not be available on the Coding Plan.
+
+    <Steps>
+      <Step title="Get your API key">
+        Create or copy an API key from [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys).
+      </Step>
+      <Step title="Run onboarding">
+        For the **Global** endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice qwen-standard-api-key
+        ```
+
+        For the **China** endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice qwen-standard-api-key-cn
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          agents: {
+            defaults: {
+              model: { primary: "qwen/qwen3.5-plus" },
+            },
+          },
+        }
+        ```
+      </Step>
+      <Step title="Verify the model is available">
+        ```bash
+        nodmix models list --provider qwen
+        ```
+      </Step>
+    </Steps>
+
+    <Note>
+    Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
+    work as compatibility aliases, but new setup flows should prefer the canonical
+    `qwen-*` auth-choice ids and `qwen/...` model refs. If you define an exact
+    custom `models.providers.modelstudio` entry with another `api` value, that
+    custom provider owns `modelstudio/...` refs instead of the Qwen compatibility
+    alias.
+    </Note>
+
+  </Tab>
+</Tabs>
+
+## Plan types and endpoints
+
+| Plan                       | Region | Auth choice                | Endpoint                                         |
+| -------------------------- | ------ | -------------------------- | ------------------------------------------------ |
+| Standard (pay-as-you-go)   | China  | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1`      |
+| Standard (pay-as-you-go)   | Global | `qwen-standard-api-key`    | `dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| Coding Plan (subscription) | China  | `qwen-api-key-cn`          | `coding.dashscope.aliyuncs.com/v1`               |
+| Coding Plan (subscription) | Global | `qwen-api-key`             | `coding-intl.dashscope.aliyuncs.com/v1`          |
+
+The provider auto-selects the endpoint based on your auth choice. Canonical
+choices use the `qwen-*` family; `modelstudio-*` remains compatibility-only.
+You can override with a custom `baseUrl` in config.
+
+<Tip>
+**Manage keys:** [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) |
+**Docs:** [docs.qwencloud.com](https://docs.qwencloud.com/developer-guides/getting-started/introduction)
+</Tip>
+
+## Built-in catalog
+
+Nodmix currently ships this bundled Qwen catalog. The configured catalog is
+endpoint-aware: Coding Plan configs omit models that are only known to work on
+the Standard endpoint.
+
+| Model ref                   | Input       | Context   | Notes                                              |
+| --------------------------- | ----------- | --------- | -------------------------------------------------- |
+| `qwen/qwen3.5-plus`         | text, image | 1,000,000 | Default model                                      |
+| `qwen/qwen3.6-plus`         | text, image | 1,000,000 | Prefer Standard endpoints when you need this model |
+| `qwen/qwen3-max-2026-01-23` | text        | 262,144   | Qwen Max line                                      |
+| `qwen/qwen3-coder-next`     | text        | 262,144   | Coding                                             |
+| `qwen/qwen3-coder-plus`     | text        | 1,000,000 | Coding                                             |
+| `qwen/MiniMax-M2.5`         | text        | 1,000,000 | Reasoning enabled                                  |
+| `qwen/glm-5`                | text        | 202,752   | GLM                                                |
+| `qwen/glm-4.7`              | text        | 202,752   | GLM                                                |
+| `qwen/kimi-k2.5`            | text, image | 262,144   | Moonshot AI via Alibaba                            |
+
+<Note>
+Availability can still vary by endpoint and billing plan even when a model is
+present in the bundled catalog.
+</Note>
+
+## Thinking Controls
+
+For reasoning-enabled Qwen Cloud models, the bundled provider maps Nodmix
+thinking levels to DashScope's top-level `enable_thinking` request flag. Disabled
+thinking sends `enable_thinking: false`; other thinking levels send
+`enable_thinking: true`.
+
+## Multimodal add-ons
+
+The `qwen` plugin also exposes multimodal capabilities on the **Standard**
+DashScope endpoints (not the Coding Plan endpoints):
+
+- **Video understanding** via `qwen-vl-max-latest`
+- **Wan video generation** via `wan2.6-t2v` (default), `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-r2v-flash`, `wan2.7-r2v`
+
+To use Qwen as the default video provider:
+
+```json5
+{
+  agents: {
+    defaults: {
+      videoGenerationModel: { primary: "qwen/wan2.6-t2v" },
+    },
+  },
+}
+```
+
+<Note>
+See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
+</Note>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Image and video understanding">
+    The bundled Qwen plugin registers media understanding for images and video
+    on the **Standard** DashScope endpoints (not the Coding Plan endpoints).
+
+    | Property      | Value                 |
+    | ------------- | --------------------- |
+    | Model         | `qwen-vl-max-latest`  |
+    | Supported input | Images, video       |
+
+    Media understanding is auto-resolved from the configured Qwen auth — no
+    additional config is needed. Ensure you are using a Standard (pay-as-you-go)
+    endpoint for media understanding support.
+
+  </Accordion>
+
+  <Accordion title="Qwen 3.6 Plus availability">
+    `qwen3.6-plus` is available on the Standard (pay-as-you-go) Model Studio
+    endpoints:
+
+    - China: `dashscope.aliyuncs.com/compatible-mode/v1`
+    - Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1`
+
+    If the Coding Plan endpoints return an "unsupported model" error for
+    `qwen3.6-plus`, switch to Standard (pay-as-you-go) instead of the Coding Plan
+    endpoint/key pair.
+
+    Nodmix's bundled Qwen catalog does not advertise `qwen3.6-plus` on Coding
+    Plan endpoints, but explicitly configured `qwen/qwen3.6-plus` entries under
+    `models.providers.qwen.models` are honored on Coding Plan baseUrls so you
+    can opt that model in if Aliyun enables it on your subscription. The
+    upstream API still decides whether the call succeeds.
+
+  </Accordion>
+
+  <Accordion title="Capability plan">
+    The `qwen` plugin is being positioned as the vendor home for the full Qwen
+    Cloud surface, not just coding/text models.
+
+    - **Text/chat models:** bundled now
+    - **Tool calling, structured output, thinking:** inherited from the OpenAI-compatible transport
+    - **Image generation:** planned at the provider-plugin layer
+    - **Image/video understanding:** bundled now on the Standard endpoint
+    - **Speech/audio:** planned at the provider-plugin layer
+    - **Memory embeddings/reranking:** planned through the embedding adapter surface
+    - **Video generation:** bundled now through the shared video-generation capability
+
+  </Accordion>
+
+  <Accordion title="Video generation details">
+    For video generation, Nodmix maps the configured Qwen region to the matching
+    DashScope AIGC host before submitting the job:
+
+    - Global/Intl: `https://dashscope-intl.aliyuncs.com`
+    - China: `https://dashscope.aliyuncs.com`
+
+    That means a normal `models.providers.qwen.baseUrl` pointing at either the
+    Coding Plan or Standard Qwen hosts still keeps video generation on the correct
+    regional DashScope video endpoint.
+
+    Current bundled Qwen video-generation limits:
+
+    - Up to **1** output video per request
+    - Up to **1** input image
+    - Up to **4** input videos
+    - Up to **10 seconds** duration
+    - Supports `size`, `aspectRatio`, `resolution`, `audio`, and `watermark`
+    - Reference image/video mode currently requires **remote http(s) URLs**. Local
+      file paths are rejected up front because the DashScope video endpoint does not
+      accept uploaded local buffers for those references.
+
+  </Accordion>
+
+  <Accordion title="Streaming usage compatibility">
+    Native Model Studio endpoints advertise streaming usage compatibility on the
+    shared `openai-completions` transport. Nodmix keys that off endpoint
+    capabilities now, so DashScope-compatible custom provider ids targeting the
+    same native hosts inherit the same streaming-usage behavior instead of
+    requiring the built-in `qwen` provider id specifically.
+
+    Native-streaming usage compatibility applies to both the Coding Plan hosts and
+    the Standard DashScope-compatible hosts:
+
+    - `https://coding.dashscope.aliyuncs.com/v1`
+    - `https://coding-intl.dashscope.aliyuncs.com/v1`
+    - `https://dashscope.aliyuncs.com/compatible-mode/v1`
+    - `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
+
+  </Accordion>
+
+  <Accordion title="Multimodal endpoint regions">
+    Multimodal surfaces (video understanding and Wan video generation) use the
+    **Standard** DashScope endpoints, not the Coding Plan endpoints:
+
+    - Global/Intl Standard base URL: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
+    - China Standard base URL: `https://dashscope.aliyuncs.com/compatible-mode/v1`
+
+  </Accordion>
+
+  <Accordion title="Environment and daemon setup">
+    If the Gateway runs as a daemon (launchd/systemd), make sure `QWEN_API_KEY` is
+    available to that process (for example, in `~/.nodmix/.env` or via
+    `env.shellEnv`).
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared video tool parameters and provider selection.
+  </Card>
+  <Card title="Alibaba (ModelStudio)" href="/providers/alibaba" icon="cloud">
+    Legacy ModelStudio provider and migration notes.
+  </Card>
+  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
+    General troubleshooting and FAQ.
+  </Card>
+</CardGroup>

package/docs/providers/runway.md

@@ -0,0 +1,103 @@
+---
+summary: "Runway video generation setup in Nodmix"
+title: "Runway"
+read_when:
+  - You want to use Runway video generation in Nodmix
+  - You need the Runway API key/env setup
+  - You want to make Runway the default video provider
+---
+
+Nodmix ships a bundled `runway` provider for hosted video generation. The plugin is enabled by default and registers the `runway` provider against the `videoGenerationProviders` contract.
+
+| Property        | Value                                                             |
+| --------------- | ----------------------------------------------------------------- |
+| Provider id     | `runway`                                                          |
+| Plugin          | bundled, `enabledByDefault: true`                                 |
+| Auth env vars   | `RUNWAYML_API_SECRET` (canonical) or `RUNWAY_API_KEY`             |
+| Onboarding flag | `--auth-choice runway-api-key`                                    |
+| Direct CLI flag | `--runway-api-key <key>`                                          |
+| API             | Runway task-based video generation (`GET /v1/tasks/{id}` polling) |
+| Default model   | `runway/gen4.5`                                                   |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the API key">
+    ```bash
+    nodmix onboard --auth-choice runway-api-key
+    ```
+  </Step>
+  <Step title="Set Runway as the default video provider">
+    ```bash
+    nodmix config set agents.defaults.videoGenerationModel.primary "runway/gen4.5"
+    ```
+  </Step>
+  <Step title="Generate a video">
+    Ask the agent to generate a video. Runway will be used automatically.
+  </Step>
+</Steps>
+
+## Supported modes and models
+
+The provider exposes seven Runway models split across three modes. The same model id can serve more than one mode (for example `gen4.5` works for both text-to-video and image-to-video).
+
+| Mode           | Models                                                                 | Reference input         |
+| -------------- | ---------------------------------------------------------------------- | ----------------------- |
+| Text-to-video  | `gen4.5` (default), `veo3.1`, `veo3.1_fast`, `veo3`                    | None                    |
+| Image-to-video | `gen4.5`, `gen4_turbo`, `gen3a_turbo`, `veo3.1`, `veo3.1_fast`, `veo3` | 1 local or remote image |
+| Video-to-video | `gen4_aleph`                                                           | 1 local or remote video |
+
+Local image and video references are supported via data URIs.
+
+| Aspect ratios         | Allowed values                              |
+| --------------------- | ------------------------------------------- |
+| Text-to-video         | `16:9`, `9:16`                              |
+| Image and video edits | `1:1`, `16:9`, `9:16`, `3:4`, `4:3`, `21:9` |
+
+<Warning>
+  Video-to-video currently requires `runway/gen4_aleph`. Other Runway model ids reject video reference inputs.
+</Warning>
+
+<Note>
+  Picking a Runway model id from the wrong column produces an explicit error before the API request leaves Nodmix. The provider validates `model` against the mode's allowlist (`TEXT_ONLY_MODELS`, `IMAGE_MODELS`, `VIDEO_MODELS`) in `extensions/runway/video-generation-provider.ts`.
+</Note>
+
+## Configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      videoGenerationModel: {
+        primary: "runway/gen4.5",
+      },
+    },
+  },
+}
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Environment variable aliases">
+    Nodmix recognizes both `RUNWAYML_API_SECRET` (canonical) and `RUNWAY_API_KEY`.
+    Either variable will authenticate the Runway provider.
+  </Accordion>
+
+  <Accordion title="Task polling">
+    Runway uses a task-based API. After submitting a generation request, Nodmix
+    polls `GET /v1/tasks/{id}` until the video is ready. No additional
+    configuration is needed for the polling behavior.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared tool parameters, provider selection, and async behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent default settings including video generation model.
+  </Card>
+</CardGroup>