nodmix 2026.5.25

package/docs/providers/volcengine.md

@@ -0,0 +1,199 @@
+---
+summary: "Volcano Engine setup (Doubao models, coding endpoints, and Seed Speech TTS)"
+title: "Volcengine (Doubao)"
+read_when:
+  - You want to use Volcano Engine or Doubao models with Nodmix
+  - You need the Volcengine API key setup
+  - You want to use Volcengine Speech text-to-speech
+---
+
+The Volcengine provider gives access to Doubao models and third-party models
+hosted on Volcano Engine, with separate endpoints for general and coding
+workloads. The same bundled plugin can also register Volcengine Speech as a TTS
+provider.
+
+| Detail     | Value                                                      |
+| ---------- | ---------------------------------------------------------- |
+| Providers  | `volcengine` (general + TTS) + `volcengine-plan` (coding)  |
+| Model auth | `VOLCANO_ENGINE_API_KEY`                                   |
+| TTS auth   | `VOLCENGINE_TTS_API_KEY` or `BYTEPLUS_SEED_SPEECH_API_KEY` |
+| API        | OpenAI-compatible models, BytePlus Seed Speech TTS         |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the API key">
+    Run interactive onboarding:
+
+    ```bash
+    nodmix onboard --auth-choice volcengine-api-key
+    ```
+
+    This registers both the general (`volcengine`) and coding (`volcengine-plan`) providers from a single API key.
+
+  </Step>
+  <Step title="Set a default model">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "volcengine-plan/ark-code-latest" },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    nodmix models list --provider volcengine
+    nodmix models list --provider volcengine-plan
+    ```
+  </Step>
+</Steps>
+
+<Tip>
+For non-interactive setup (CI, scripting), pass the key directly:
+
+```bash
+nodmix onboard --non-interactive \
+  --mode local \
+  --auth-choice volcengine-api-key \
+  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"
+```
+
+</Tip>
+
+## Providers and endpoints
+
+| Provider          | Endpoint                                  | Use case       |
+| ----------------- | ----------------------------------------- | -------------- |
+| `volcengine`      | `ark.cn-beijing.volces.com/api/v3`        | General models |
+| `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | Coding models  |
+
+<Note>
+Both providers are configured from a single API key. Setup registers both automatically.
+</Note>
+
+## Built-in catalog
+
+<Tabs>
+  <Tab title="General (volcengine)">
+    | Model ref                                    | Name                            | Input       | Context |
+    | -------------------------------------------- | ------------------------------- | ----------- | ------- |
+    | `volcengine/doubao-seed-1-8-251228`          | Doubao Seed 1.8                 | text, image | 256,000 |
+    | `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000 |
+    | `volcengine/kimi-k2-5-260127`                | Kimi K2.5                       | text, image | 256,000 |
+    | `volcengine/glm-4-7-251222`                  | GLM 4.7                         | text, image | 200,000 |
+    | `volcengine/deepseek-v3-2-251201`            | DeepSeek V3.2                   | text, image | 128,000 |
+  </Tab>
+  <Tab title="Coding (volcengine-plan)">
+    | Model ref                                         | Name                     | Input | Context |
+    | ------------------------------------------------- | ------------------------ | ----- | ------- |
+    | `volcengine-plan/ark-code-latest`                 | Ark Coding Plan          | text  | 256,000 |
+    | `volcengine-plan/doubao-seed-code`                | Doubao Seed Code         | text  | 256,000 |
+    | `volcengine-plan/glm-4.7`                         | GLM 4.7 Coding           | text  | 200,000 |
+    | `volcengine-plan/kimi-k2-thinking`                | Kimi K2 Thinking         | text  | 256,000 |
+    | `volcengine-plan/kimi-k2.5`                       | Kimi K2.5 Coding         | text  | 256,000 |
+    | `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text  | 256,000 |
+  </Tab>
+</Tabs>
+
+## Text-to-speech
+
+Volcengine TTS uses the BytePlus Seed Speech HTTP API and is configured
+separately from the OpenAI-compatible Doubao model API key. In the BytePlus
+console, open Seed Speech > Settings > API Keys and copy the API key, then set:
+
+```bash
+export VOLCENGINE_TTS_API_KEY="byteplus_seed_speech_api_key"
+export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"
+```
+
+Then enable it in `nodmix.json`:
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "volcengine",
+      providers: {
+        volcengine: {
+          apiKey: "byteplus_seed_speech_api_key",
+          voice: "en_female_anna_mars_bigtts",
+          speedRatio: 1.0,
+        },
+      },
+    },
+  },
+}
+```
+
+For voice-note targets, Nodmix asks Volcengine for provider-native
+`ogg_opus`. For normal audio attachments, it asks for `mp3`. Provider aliases
+`bytedance` and `doubao` also resolve to the same speech provider.
+
+The default resource id is `seed-tts-1.0` because that is what BytePlus grants
+to newly created Seed Speech API keys in the default project. If your project
+has TTS 2.0 entitlement, set `VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0`.
+
+<Warning>
+`VOLCANO_ENGINE_API_KEY` is for the ModelArk/Doubao model endpoints and is not a
+Seed Speech API key. TTS needs a Seed Speech API key from the BytePlus Speech
+Console, or a legacy Speech Console AppID/token pair.
+</Warning>
+
+Legacy AppID/token auth remains supported for older Speech Console applications:
+
+```bash
+export VOLCENGINE_TTS_APPID="speech_app_id"
+export VOLCENGINE_TTS_TOKEN="speech_access_token"
+export VOLCENGINE_TTS_CLUSTER="volcano_tts"
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Default model after onboarding">
+    `nodmix onboard --auth-choice volcengine-api-key` currently sets
+    `volcengine-plan/ark-code-latest` as the default model while also registering
+    the general `volcengine` catalog.
+  </Accordion>
+
+  <Accordion title="Model picker fallback behavior">
+    During onboarding/configure model selection, the Volcengine auth choice prefers
+    both `volcengine/*` and `volcengine-plan/*` rows. If those models are not
+    loaded yet, Nodmix falls back to the unfiltered catalog instead of showing an
+    empty provider-scoped picker.
+  </Accordion>
+
+  <Accordion title="Environment variables for daemon processes">
+    If the Gateway runs as a daemon (launchd/systemd), make sure model and TTS
+    env vars such as `VOLCANO_ENGINE_API_KEY`, `VOLCENGINE_TTS_API_KEY`,
+    `BYTEPLUS_SEED_SPEECH_API_KEY`, `VOLCENGINE_TTS_APPID`, and
+    `VOLCENGINE_TTS_TOKEN` are available to that process (for example, in
+    `~/.nodmix/.env` or via `env.shellEnv`).
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+When running Nodmix as a background service, environment variables set in your
+interactive shell are not automatically inherited. See the daemon note above.
+</Warning>
+
+## 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" href="/gateway/configuration" icon="gear">
+    Full config reference for agents, models, and providers.
+  </Card>
+  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
+    Common issues and debugging steps.
+  </Card>
+  <Card title="FAQ" href="/help/faq" icon="circle-question">
+    Frequently asked questions about Nodmix setup.
+  </Card>
+</CardGroup>

package/docs/providers/vydra.md

@@ -0,0 +1,180 @@
+---
+summary: "Use Vydra image, video, and speech in Nodmix"
+read_when:
+  - You want Vydra media generation in Nodmix
+  - You need Vydra API key setup guidance
+title: "Vydra"
+---
+
+The bundled Vydra plugin adds:
+
+- Image generation via `vydra/grok-imagine`
+- Video generation via `vydra/veo3` and `vydra/kling`
+- Speech synthesis via Vydra's ElevenLabs-backed TTS route
+
+Nodmix uses the same `VYDRA_API_KEY` for all three capabilities.
+
+| Property        | Value                                                                     |
+| --------------- | ------------------------------------------------------------------------- |
+| Provider id     | `vydra`                                                                   |
+| Plugin          | bundled, `enabledByDefault: true`                                         |
+| Auth env var    | `VYDRA_API_KEY`                                                           |
+| Onboarding flag | `--auth-choice vydra-api-key`                                             |
+| Direct CLI flag | `--vydra-api-key <key>`                                                   |
+| Contracts       | `imageGenerationProviders`, `videoGenerationProviders`, `speechProviders` |
+| Base URL        | `https://www.vydra.ai/api/v1` (use the `www` host)                        |
+
+<Warning>
+  Use `https://www.vydra.ai/api/v1` as the base URL. Vydra's apex host (`https://vydra.ai/api/v1`) currently redirects to `www`. Some HTTP clients drop `Authorization` on that cross-host redirect, which turns a valid API key into a misleading auth failure. The bundled plugin uses the `www` base URL directly to avoid that.
+</Warning>
+
+## Setup
+
+<Steps>
+  <Step title="Run interactive onboarding">
+    ```bash
+    nodmix onboard --auth-choice vydra-api-key
+    ```
+
+    Or set the env var directly:
+
+    ```bash
+    export VYDRA_API_KEY="vydra_live_..."
+    ```
+
+  </Step>
+  <Step title="Choose a default capability">
+    Pick one or more of the capabilities below (image, video, or speech) and apply the matching configuration.
+  </Step>
+</Steps>
+
+## Capabilities
+
+<AccordionGroup>
+  <Accordion title="Image generation">
+    Default image model:
+
+    - `vydra/grok-imagine`
+
+    Set it as the default image provider:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          imageGenerationModel: {
+            primary: "vydra/grok-imagine",
+          },
+        },
+      },
+    }
+    ```
+
+    Current bundled support is text-to-image only. Vydra's hosted edit routes expect remote image URLs, and Nodmix does not add a Vydra-specific upload bridge in the bundled plugin yet.
+
+    <Note>
+    See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Video generation">
+    Registered video models:
+
+    - `vydra/veo3` for text-to-video
+    - `vydra/kling` for image-to-video
+
+    Set Vydra as the default video provider:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          videoGenerationModel: {
+            primary: "vydra/veo3",
+          },
+        },
+      },
+    }
+    ```
+
+    Notes:
+
+    - `vydra/veo3` is bundled as text-to-video only.
+    - `vydra/kling` currently requires a remote image URL reference. Local file uploads are rejected up front.
+    - Vydra's current `kling` HTTP route has been inconsistent about whether it requires `image_url` or `video_url`; the bundled provider maps the same remote image URL into both fields.
+    - The bundled plugin stays conservative and does not forward undocumented style knobs such as aspect ratio, resolution, watermark, or generated audio.
+
+    <Note>
+    See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Video live tests">
+    Provider-specific live coverage:
+
+    ```bash
+    NODMIX_LIVE_TEST=1 \
+    NODMIX_LIVE_VYDRA_VIDEO=1 \
+    pnpm test:live -- extensions/vydra/vydra.live.test.ts
+    ```
+
+    The bundled Vydra live file now covers:
+
+    - `vydra/veo3` text-to-video
+    - `vydra/kling` image-to-video using a remote image URL
+
+    Override the remote image fixture when needed:
+
+    ```bash
+    export NODMIX_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"
+    ```
+
+  </Accordion>
+
+  <Accordion title="Speech synthesis">
+    Set Vydra as the speech provider:
+
+    ```json5
+    {
+      messages: {
+        tts: {
+          provider: "vydra",
+          providers: {
+            vydra: {
+              apiKey: "${VYDRA_API_KEY}",
+              voiceId: "21m00Tcm4TlvDq8ikWAM",
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Defaults:
+
+    - Model: `elevenlabs/tts`
+    - Voice id: `21m00Tcm4TlvDq8ikWAM`
+
+    The bundled plugin currently exposes one known-good default voice and returns MP3 audio files.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Provider directory" href="/providers/index" icon="list">
+    Browse all available providers.
+  </Card>
+  <Card title="Image generation" href="/tools/image-generation" icon="image">
+    Shared image tool parameters and provider selection.
+  </Card>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared video tool parameters and provider selection.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent defaults and model configuration.
+  </Card>
+</CardGroup>