npm - @model-go/docs-core - Versions diffs - 0.1.1 → 0.1.2 - Mend

@model-go/docs-core 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/dist/content.generated.js +1 -1
package/package.json +1 -1

package/dist/content.generated.js CHANGED Viewed

@@ -1,4 +1,4 @@
 // 由 scripts/build-content.mjs 生成，请勿手改。
-export const DOCS_PAGES = {"china/en/about/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [Quickstart](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","china/en/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: Configure CC Switch and Claude Code with ModelGo.\n---\n\n# CC Switch\n\nCC Switch is a desktop provider manager for Claude Code, Codex, Gemini, OpenCode, OpenClaw, and more. This guide uses Claude Code as an example and shows how to add and enable ModelGo.\n\n## Before you start\n\n- Install [CC Switch](https://github.com/farion1231/cc-switch/releases) and make sure it opens normally.\n- Install Claude Code and launch it at least once.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open the Claude Code configuration\n\nOpen CC Switch, select **Claude** at the top, and click **+** to add a configuration.\n\n![CC Switch overview](/images/agents/cc-switch/overview.webp)\n\n![Add a Claude configuration in CC Switch](/images/agents/cc-switch/claude-add.webp)\n\n## 2. Add a ModelGo provider\n\nPaste the following JSON into the configuration editor. Replace `your-model-id` with a logical model name from the model catalog and `sk-your-token` with your ModelGo API key:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-your-token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"your-model-id\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"your-model-id\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![Edit the ModelGo configuration in CC Switch](/images/agents/cc-switch/config-cn.webp)\n\nIf your CC Switch version supports environment placeholders, you can use `{env:MODELGO_API_KEY}` for the token and set it in the terminal where you start Claude Code:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | API key created in the ModelGo console |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A logical model name from the model catalog |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable logical model name |\n\n:::note\n- Use the ModelGo root URL for the Anthropic base URL. Do not append `/v1/messages`; Claude Code adds that path.\n- Keep the API key in the local CC Switch configuration or an environment variable. Do not commit it to a repository.\n- Name the provider **ModelGo** so it is easy to identify and switch later.\n:::\n\n## 3. Save and enable the provider\n\nSet the provider name to **ModelGo**, then click **Add** or **Save**. Return to the Claude configuration list and enable the ModelGo entry.\n\n![Add the ModelGo provider in CC Switch](/images/agents/cc-switch/provider-cn.webp)\n\n![Enable the ModelGo profile in CC Switch](/images/agents/cc-switch/use-cn.webp)\n\nStart Claude Code:\n\n```bash\nclaude\n```\n\nEnter a simple task such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n## 4. Verify the configuration\n\nTo verify the API key and model access separately:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse an `id` from the response as the logical model name for `ANTHROPIC_MODEL` and `ANTHROPIC_SMALL_FAST_MODEL`.\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nConfirm that the token is a valid ModelGo API key and that the CC Switch profile does not contain an old token. Remove extra spaces or line breaks.\n\n### 404 or endpoint errors\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`. Do not use `{{ api_endpoint }}/v1/messages` or a full request path.\n\n### Model unavailable\n\nMake sure the model name exactly matches a logical model in the [model catalog]({{ site_endpoint }}/models) and is enabled for the API key.\n\n### Claude Code still uses the old profile\n\nConfirm that the ModelGo profile is enabled in CC Switch. Fully restart the terminal, then run `claude` again.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [CC Switch Quick Start](https://cc-switch.cc/docs/getting-started/quick-start/): learn the interface and profile switching flow.\n- [CC Switch Provider Setup](https://cc-switch.cc/en/tutorials/provider-setup): learn custom provider fields and credential management.\n","china/en/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: Connect Cherry Studio to ModelGo through a custom provider.\n---\n\n# Cherry Studio\n\nCherry Studio includes several built-in providers, but ModelGo is not one of them. Use Cherry Studio's **Custom Provider** flow to create a ModelGo provider, then fetch and add the models you need. ModelGo exposes both OpenAI-compatible and Anthropic-compatible endpoints.\n\n## Prerequisites\n\n- Cherry Studio is installed and you can open its Settings page.\n- You have created or copied an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- You have confirmed the logical model ID to use in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open model service settings\n\nOpen Cherry Studio **Settings**, go to **Model Services**, and click **+ Add Provider** at the bottom of the provider list.\n\n![Open the provider picker in Cherry Studio](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. Add a custom provider\n\nIn the **Add Custom Provider** dialog, enter:\n\n| Setting | Value for ModelGo |\n| --- | --- |\n| Provider name | `ModelGo` |\n| API key | The API key created in the ModelGo console |\n| OpenAI endpoint | `{{ api_endpoint }}/v1` |\n| Anthropic endpoint | `{{ api_endpoint }}` (only for Anthropic-compatible models or Agent mode) |\n\nClick **Add** to save the provider. Use the OpenAI endpoint for regular chats and model discovery. Do not append `/v1` to the Anthropic endpoint; Cherry Studio builds the protocol path for you.\n\n![Add the ModelGo custom provider](/images/agents/cherry-studio/custom-provider.webp)\n\n:::note\n- Do not enter a full `/chat/completions` or `/messages` URL.\n- Use `{{ api_endpoint }}/v1` for OpenAI-compatible requests and `{{ api_endpoint }}` for Anthropic-compatible requests.\n:::\n\n## 3. Fetch and add models\n\nReturn to the ModelGo provider page and click **Get Models**. Cherry Studio reads the logical models available to the current API key.\n\n![Fetch ModelGo models in Cherry Studio](/images/agents/cherry-studio/fetch-models.webp)\n\nIn the model picker, click **+** next to individual models or choose **Add All Models**.\n\n![Add all ModelGo models in Cherry Studio](/images/agents/cherry-studio/model-picker.webp)\n\nAdded models appear in the ModelGo provider's model section. Adding only the models you use keeps the model picker easier to navigate.\n\n![ModelGo models in the provider list](/images/agents/cherry-studio/model-list.webp)\n\n## 4. Enable the provider and start chatting\n\nTurn on the switch in the upper-right corner of the ModelGo provider page and run the API key check. Start a new chat, select **ModelGo** and one of the models you added, then send a short message.\n\nFor OpenAI-compatible models, the OpenAI endpoint is enough. For Claude or Cherry Studio Agent mode, configure the Anthropic endpoint and add an Anthropic-compatible model as well.\n\n## Verify the configuration\n\nYou can verify model discovery from a terminal:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical ModelGo model IDs to add in Cherry Studio.\n\n## Troubleshooting\n\n### 401 or authentication failure\n\nCheck that the API key was copied in full with no extra spaces, and that the provider switch is enabled.\n\n### 404 or an invalid endpoint path\n\nSet the OpenAI endpoint to `{{ api_endpoint }}/v1` and the Anthropic endpoint to `{{ api_endpoint }}`. Do not enter the complete `/v1/chat/completions` or `/v1/messages` path.\n\n### The model list is empty\n\nFirst verify `/v1/models` with the `curl` command above, then confirm the model is enabled for your API key in the model catalog. After fetching, click **+** or **Add All Models**; fetching alone does not add models to the picker.\n\n### Agent mode cannot send a request\n\nSet the Anthropic endpoint to `{{ api_endpoint }}` and add a model that supports the Anthropic-compatible protocol. The Anthropic endpoint is not required for ordinary OpenAI-compatible chats.\n\n## Related documentation\n\n- [First call](../quickstart/quickstart): Create an API key, inspect models, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): Learn how to keep API keys safe.\n- [Cherry Studio custom providers](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang): Follow Cherry Studio's official custom-provider flow.\n- [Cherry Studio provider settings](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers): Learn how Base URLs, model management, and connection checks work.\n","china/en/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: Configure Claude Code with ModelGo's Anthropic-compatible API.\n---\n\n# Claude Code\n\nClaude Code is a terminal-based AI coding assistant. Configure its Anthropic-compatible endpoint to use ModelGo models and API keys.\n\n## Before you start\n\n- Install Node.js.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Claude Code\n\nRun:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nVerify the installation:\n\n```bash\nclaude --version\n```\n\n## 2. Configure ModelGo\n\n### macOS / Linux\n\nCreate and edit the Claude Code settings file:\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\nRun these commands in PowerShell:\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\nPaste the following into `settings.json`. Replace `YOUR_MODELGO_API_KEY` and `YOUR_MODELGO_MODEL` with a real ModelGo API key and logical model name:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\nUse the ModelGo root URL for `ANTHROPIC_BASE_URL`; do not append `/v1/messages`. Claude Code adds the path and calls ModelGo's `POST /v1/messages` endpoint.\n\n:::note\n- If you use one model only, set all five model variables to the same ModelGo logical model so an unavailable auxiliary model does not prevent startup.\n- Keep the API key in your local settings. Do not commit `settings.json` or share it with others.\n:::\n\n## 3. Optional: skip official account onboarding\n\nIf the first `claude` launch stops at the official account login flow, create `.claude.json` in your user directory with the completed-onboarding flag.\n\nmacOS / Linux:\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell:\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. Start Claude Code\n\nChange to your project directory and start Claude Code:\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\nOn the first visit, choose **Trust This Folder** to allow Claude Code to access project files. Send a simple coding request; a normal response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A ModelGo logical model name |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The same callable ModelGo logical model name |\n\nFind a model in the [Model Gallery]({{ site_endpoint }}/models), or query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that `ANTHROPIC_AUTH_TOKEN` is a valid ModelGo API key and contains no extra spaces.\n\n### 403 or model unavailable\n\nMake sure all five model variables use ModelGo logical model names allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`, not `{{ api_endpoint }}/v1/messages`; Claude Code adds `/v1/messages` itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code): see the latest installation and configuration guidance.\n","china/en/agents/cline.md":"---\ntitle: Cline\ndescription: Configure Cline with ModelGo's OpenAI-compatible API.\n---\n\n# Cline\n\nCline is an AI coding assistant for VS Code. Select the `OpenAI Compatible` provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install VS Code.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cline\n\nOpen the VS Code Extensions marketplace, search for **Cline**, and install the extension.\n\n![Install Cline from the VS Code Extensions marketplace](/images/agents/cline/cline-market.webp)\n\n## 2. Configure ModelGo\n\nAfter installation, click the Cline icon in the VS Code activity bar and open **API Configuration**.\n\n![Open Cline API Configuration](/images/agents/cline/cline-config-cn.webp)\n\nFill in the following values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | Your ModelGo API key |\n| Model ID | A ModelGo logical model name |\n\nClick **Done** to save.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL. Do not include `/chat/completions`; Cline appends the endpoint path.\n- Use a logical model name available to the current API key in the Model Catalog rather than copying the example from the screenshot.\n- Keep the API key in your local Cline settings. Do not commit it or share screenshots containing it.\n:::\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. Start using Cline\n\nOpen the Cline panel and send a simple coding request, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Complete a conversation in Cline](/images/agents/cline/cline-chat.webp)\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in the API Key field.\n\n### 403 or model unavailable\n\nMake sure Model ID is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`; do not paste a full `/chat/completions` URL.\n\n### The model list is empty\n\nRequest `GET {{ api_endpoint }}/v1/models` to verify the endpoint. If Cline does not show the model in its list, enter Model ID manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Cline OpenAI Compatible docs](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx): see Cline's official provider configuration guidance.\n","china/en/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: Connect CodeBuddy to ModelGo.\n---\n\n# CodeBuddy\n\nCodeBuddy Code is Tencent Cloud's terminal coding assistant. Environment variables override its API endpoint, key, and model so requests can use ModelGo.\n\n## Prerequisites\n\n- Node.js 18+ and CodeBuddy CLI are installed; `codebuddy --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. Configure ModelGo variables\n\nSet these variables in the shell that starts CodeBuddy:\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-your-token\"\nexport CODEBUDDY_MODEL=\"your-model-id\"\n```\n\n`CODEBUDDY_AUTH_TOKEN` is CodeBuddy platform login, not the ModelGo model key.\n\n:::note\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Non-interactive `codebuddy -p` requires `CODEBUDDY_API_KEY`.\n- Keep keys and model IDs in a local profile or secret manager.\n:::\n\n## 3. Start and verify\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\ncodebuddy -p \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### CodeBuddy still uses its default model\n\nConfirm variables are visible in the current shell, then fully restart `codebuddy`.\n\n### 401 or 404 responses\n\nCheck `CODEBUDDY_API_KEY`, `CODEBUDDY_MODEL`, and `CODEBUDDY_BASE_URL`; do not put a full endpoint path in the Base URL.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [CodeBuddy CLI quickstart](https://www.codebuddy.ai/docs/cli/quickstart): Review installation, login, and first run.\n- [CodeBuddy CLI environment variables](https://www.codebuddy.ai/docs/cli/env-vars): Review endpoint, key, and model variables.\n","china/en/agents/codex.md":"---\ntitle: Codex\ndescription: Configure Codex CLI with ModelGo's Responses API.\n---\n\n# Codex\n\nCodex is OpenAI's command-line AI coding assistant. With a custom `model_provider`, Codex CLI can send Responses API requests to ModelGo.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Codex\n\nRun this command in macOS, Linux, or Windows:\n\n```bash\nnpm install -g @openai/codex\n```\n\nVerify the installation:\n\n```bash\ncodex --version\n```\n\nIf Codex shows an upgrade prompt on first launch, choose **Skip** and finish the ModelGo setup first.\n\n![Skip the Codex upgrade prompt](/images/agents/codex/codex-start.webp)\n\n## 2. Configure ModelGo\n\nCodex reads its user-level model and provider settings from `~/.codex/config.toml`. Create the file first:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\nPaste the following into `config.toml`, replacing `YOUR_MODELGO_MODEL` with a logical model name allowed for the current API key:\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\nThe `base_url` is ModelGo's OpenAI-compatible API root. Codex appends `/v1/responses` when it sends a request.\n\n## 3. Set the API key\n\nStore your ModelGo API key in the `MODELGO_API_KEY` environment variable. Do not put the real key directly in `config.toml`.\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\nCheck that the variable is set without printing the key:\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- Keep `MODELGO_API_KEY` in your local environment. Do not commit it or share terminal screenshots containing it.\n- `model` must be a ModelGo logical model name. The `gpt-5.6-sol` shown in the screenshot is only an example; replace it with a model you can call.\n- `wire_api = \"responses\"` is required by current Codex configurations. Do not use the deprecated `wire_api = \"chat\"`.\n:::\n\n:::note Start a new conversation after changing the API key or endpoint\n- In a multi-turn conversation, Codex continues to send prior Responses context. That context may include encrypted reasoning data that can only be handled by the original upstream account.\n- If you change `MODELGO_API_KEY` or `base_url`, or a proxy or account pool routes the same conversation to another upstream account, start a new Codex conversation. Do not continue or resume the existing conversation, or the request may fail with `400 invalid_encrypted_content`.\n:::\n\n## 4. Start and verify\n\nChange to a local project directory and run:\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\nWhen Codex asks for permission to work in the project, trust the directory as appropriate. After the welcome screen appears, send a simple coding request such as “Describe this project in three sentences.”\n\n![Codex project welcome screen](/images/agents/codex/codex-skip.webp)\n\nA normal model response confirms that ModelGo is connected.\n\n![Start a conversation in Codex](/images/agents/codex/codex-chat.webp)\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### Provider not found at startup\n\nMake sure the file is the user-level `~/.codex/config.toml`, and that `model_provider = \"modelgo\"` matches `[model_providers.modelgo]`.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces or newlines.\n\n### 403 or model unavailable\n\nMake sure `model` is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `base_url` to `{{ api_endpoint }}/v1`. Do not include `/responses` or `/v1/responses`; Codex appends the path.\n\n### Chat wire API deprecation warning\n\nAdd `wire_api = \"responses\"` under `[model_providers.modelgo]`, then upgrade Codex CLI:\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### `400 invalid_encrypted_content`\n\nThis usually means the conversation contains encrypted context created by the original upstream account, but the current request was handled by a different upstream account.\n\nCheck whether the API key or Base URL changed, or whether a proxy or account pool switched upstream accounts. If a switch occurred, start a new conversation instead of continuing or resuming the existing one.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Codex configuration reference](https://developers.openai.com/codex/config-reference/): see current `config.toml` fields.\n","china/en/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: Connect Copilot CLI to ModelGo.\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI supports BYOK. Provider environment variables can route model requests to ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Copilot CLI is installed and `copilot --help` works.\n- GitHub/Copilot authentication is complete.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know a logical model ID that supports tool calling and streaming.\n\n## 1. Configure ModelGo BYOK\n\nSet these variables in the shell that starts Copilot CLI:\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"your-model-id\"\ncopilot\n```\n\nIf needed, define the key first:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nThe `openai` provider type targets OpenAI Chat Completions-compatible services.\n\n:::note\n- GitHub login and the ModelGo API key are separate credentials.\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Prefer a model with tool calling, streaming, and a large context window.\n:::\n\n## 2. Verify the model\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\nAsk Copilot CLI to perform a small read-only task, such as listing project entry points.\n\n## Troubleshooting\n\n### Copilot still uses its default model\n\nConfirm `COPILOT_MODEL` and `COPILOT_PROVIDER_BASE_URL` are visible in the current shell, then restart `copilot`.\n\n### 401, 404, or tool-call errors\n\nCheck the key, Base URL, and logical model ID. Choose a model with the required streaming and tool-calling capabilities.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models): Review provider variables and model requirements.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","china/en/agents/crush.md":"---\ntitle: Crush\ndescription: Connect Crush to ModelGo.\n---\n\n# Crush\n\nCrush is Charmbracelet's terminal coding agent. Its OpenAI-compatible provider support lets you route requests through ModelGo.\n\n## Prerequisites\n\n- Node.js 18+, Go, or Homebrew is available; `crush --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\nYou can also use `npm install -g @charmland/crush`, `go install github.com/charmbracelet/crush@latest`, or `winget install charmbracelet.crush` on Windows.\n\n## 2. Add a ModelGo provider\n\nCrush reads project `.crushrc`/`crushrc` files and the global `~/.config/crush/crushrc` (Windows: `%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`).\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/your-model-id --name \"your-model-id\"\n```\n\nReplace `your-model-id` with a ModelGo logical model ID.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL; do not append `/chat/completions`.\n- Keep the API key in `MODELGO_API_KEY` instead of committing it to a config file.\n- `modelgo/your-model-id` is Crush's provider/model identifier.\n:::\n\n## 3. Start and verify\n\n```bash\ncrush\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck the `crushrc` filename and path, then restart Crush. Project configuration takes precedence over global configuration.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is available in the same shell and that the Base URL is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n- [Crush repository](https://github.com/charmbracelet/crush): Read installation, provider, and command references.\n- [Crush config schema](https://github.com/charmbracelet/crush/blob/main/schema.json): Check `crushrc` fields.\n","china/en/agents/cursor.md":"---\ntitle: Cursor\ndescription: Configure Cursor with ModelGo's OpenAI-compatible API.\n---\n\n# Cursor\n\nCursor is an AI coding editor. With a custom OpenAI Base URL, Cursor can call ModelGo logical models.\n\n## Before you start\n\n- Install [Cursor](https://www.cursor.com/).\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cursor\n\nVisit the [Cursor website](https://www.cursor.com/) and download the build for your operating system.\n\n![Cursor download page](/images/agents/cursor/install.webp)\n\n## 2. Open Cursor model settings\n\nOpen Cursor settings and go to **Models**.\n\n![Open Models in Cursor Settings](/images/agents/cursor/settings.webp)\n\n## 3. Add and enable a model\n\nClick **Add model**, enter a logical model name from the [model catalog]({{ site_endpoint }}/models), and save it.\n\n![Add a model in Cursor](/images/agents/cursor/add-model.webp)\n\nIn **Model Names**, keep the models you want to use and disable the rest.\n\n![Enable the target model in Cursor](/images/agents/cursor/model-list.webp)\n\n## 4. Configure the ModelGo endpoint\n\nIn **Settings → Models → API Keys**, configure the OpenAI-compatible endpoint:\n\n| Setting | ModelGo value |\n| --- | --- |\n| OpenAI API Key | Your ModelGo API key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | A logical model name from the ModelGo catalog |\n\n![Configure the ModelGo endpoint in Cursor](/images/agents/cursor/config-cn.webp)\n\nIf your Cursor release uses the alternate settings layout, enter the same ModelGo values there.\n\n![Alternate Cursor settings layout](/images/agents/cursor/config-global.webp)\n\nClick **Verify** or **Save**. Cursor may use slightly different labels in different releases, but the API key, Base URL, and model name have the same meaning.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- Use a logical model name from the ModelGo catalog instead of copying the example in the screenshot.\n- If Verify fails, send a test message in chat or use the command below to check the endpoint and key.\n:::\n\n## 5. Test the connection\n\nReturn to the Cursor chat, select the model you added, and send a simple message. A normal response confirms the integration.\n\n![Test a ModelGo model in Cursor](/images/agents/cursor/chat.webp)\n\nYou can also list the models available to the API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nMake sure the API key is complete, has no extra spaces, and is entered in **OpenAI API Key**.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions` to it.\n\n### Verify fails or the model is unavailable\n\nCheck that the model name is a logical ModelGo model and that the model is enabled for the API key.\n\n### The chat returns no content\n\nRun `GET {{ api_endpoint }}/v1/models` to verify connectivity and the key, then confirm the target model is enabled in Model Names.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [Cursor documentation](https://docs.cursor.com/): see Cursor settings, models, and custom API configuration.\n","china/en/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: Configure DeepSeek Harness with ModelGo's OpenAI-compatible API.\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness (DSH) is an open-source agent framework from DeepSeek AI. It combines models, tools, filesystems, terminals, sessions, and a Web UI into a runnable agent. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22 or later.\n- Install pnpm 11 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start DeepSeek Harness\n\nThe current source-install path is:\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![Start DeepSeek Harness from source](/images/agents/deepseek-harness/install.webp)\n\nThe terminal prints the Web UI address. The default is `http://127.0.0.1:3080`; use the address printed by your terminal if the port is already in use.\n\nFor a quick preview, you can also run:\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. Configure ModelGo\n\nOpen the address printed by the terminal, click the sidebar button in the upper-left corner, and then click **Settings**.\n\n![Open DeepSeek Harness settings](/images/agents/deepseek-harness/settings.webp)\n\nSelect **Models** and click **Add custom provider**.\n\n![Add a custom provider](/images/agents/deepseek-harness/model-picker.webp)\n\nUse these values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider ID | `modelgo` |\n| Display name | `ModelGo` |\n| API URL | `{{ api_endpoint }}/v1` |\n| API protocol | `openai-completions` |\n| API key | ModelGo API key |\n| Model ID | A logical model name from the Model Catalog |\n| Display name | You can use the same value as the model ID |\n\n![Fill in the ModelGo custom provider](/images/agents/deepseek-harness/provider-config.webp)\n\nClick **Create provider** to save the configuration. Keep these points in mind:\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the API URL. Do not append `/chat/completions`; DSH builds the request path for the `openai-completions` protocol.\n- The model ID must be a logical ModelGo model name allowed by the API key. Do not copy the example model from the screenshot.\n- Keep the API key in your local configuration. Do not commit it or share it in screenshots.\n:::\n\n## 3. Start a session\n\nReturn to the main view, choose a workspace, and then select the ModelGo model you just added.\n\n![Select the ModelGo model](/images/agents/deepseek-harness/session.webp)\n\nSend a simple task such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### The Web UI does not open\n\nMake sure `pnpm dsh web` is still running and open the port printed by the terminal. The default is `3080`; DSH may choose another port when it is occupied.\n\n### 401 or authentication failed\n\nCheck that the API key is complete, has no extra spaces, and was created in the ModelGo Console.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet the API URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Select `openai-completions` as the API protocol.\n\n### The model list is empty\n\nCheck that a model ID is present and that the custom provider was saved. You can verify the ModelGo endpoint first:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [DeepSeek Harness official website](https://www.deepseek.com/harness/): see the latest installation and product information.\n- [DeepSeek Harness GitHub repository](https://github.com/deepseek-ai/deepseek-harness): view source and releases.\n","china/en/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: Connect Factory Droid to ModelGo.\n---\n\n# Factory Droid\n\nFactory Droid is Factory's terminal agent. Its BYOK custom model settings can point Droid at ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Node.js 18+ and the Droid CLI are installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\nInside Droid, `/settings` opens the settings screen.\n\n## 2. Configure a ModelGo custom model\n\nMerge this `customModels` entry into `~/.factory/settings.json` (Windows: `%USERPROFILE%\\\\.factory\\\\settings.json`):\n\n```json\n{\n  \"customModels\": [{\n    \"model\": \"your-model-id\",\n    \"displayName\": \"ModelGo / your-model-id\",\n    \"baseUrl\": \"{{ api_endpoint }}/v1\",\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"provider\": \"openai\"\n  }]\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nRestart Droid and choose the custom model from `/models` or the model picker.\n\n:::note\n- Set `baseUrl` to `{{ api_endpoint }}/v1`; do not add `/chat/completions`.\n- `model` must be a ModelGo logical model ID.\n- Merge `customModels` into the existing file so other settings remain intact.\n:::\n\n## 3. Verify a request\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"your-model-id\" \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### The model is not listed\n\nValidate the JSON, keep `customModels` at the top level, and fully restart Droid.\n\n### Authentication or endpoint errors\n\nCheck the environment variable in the shell that launches Droid and remove duplicate `/v1` or full paths from `baseUrl`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Factory Droid settings](https://docs.factory.ai/droid-cli/settings): Find `settings.json` and settings entry points.\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok): Review custom model fields.\n","china/en/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: Configure Hermes Agent with ModelGo's OpenAI-compatible API.\n---\n\n# Hermes Agent\n\nHermes Agent is a terminal-based AI agent. With a custom provider, Hermes can use ModelGo's OpenAI-compatible API to call models.\n\n## Before you start\n\n- Install Node.js 22 or newer.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm the ModelGo logical model name you want to use in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Hermes Agent\n\nmacOS or Linux:\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\nReopen your terminal and verify the installation:\n\n```bash\nhermes --version\n```\n\n## 2. Configure ModelGo\n\nPut your API key in an environment variable for the current shell. Never commit a real key to a repository or public script:\n\n```bash\nexport MODELGO_API_KEY=\"your-ModelGo-API-key\"\nexport MODELGO_MODEL=\"your-ModelGo-logical-model-name\"\n```\n\nIf you are not sure which model name to use, query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse `hermes config set` to create a custom provider. Replace `<model>` with a logical model name from the Model Gallery or the `GET /v1/models` response:\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\nIf your Hermes version includes the interactive setup wizard, you can run:\n\n```bash\nhermes model\n```\n\nChoose **Custom endpoint**, enter the ModelGo Base URL, API key, and model name, and select **Chat Completions** as the protocol.\n\n:::note\n- Some older Hermes releases label the Chat Completions protocol as `openai_messages`. If `chat_completions` is rejected, upgrade Hermes or select Chat Completions in the `hermes model` wizard.\n:::\n\n## 3. Check the configuration and start a session\n\nCheck the Hermes configuration:\n\n```bash\nhermes config check\n```\n\nStart Hermes after the check passes:\n\n```bash\nhermes\n```\n\nSend a message such as “Introduce ModelGo in three sentences.” A model response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API mode | `chat_completions` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model ID | A ModelGo logical model name, not the upstream provider's raw model ID |\n\nHermes stores non-sensitive settings in `~/.hermes/config.yaml` and API keys and other secrets in `~/.hermes/.env`. Do not share or commit files under `~/.hermes/` that contain credentials.\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nMake sure the API key is valid and has not been revoked or expired, then run:\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 403 or model unavailable\n\nCheck that `model.default` is a ModelGo logical model allowed by the policy attached to your API key.\n\n### 404 or endpoint not found\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions`; Hermes adds the request path itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs): see the latest installer, configuration, and CLI reference.\n","china/en/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: Connect Kilo CLI to ModelGo.\n---\n\n# Kilo CLI\n\nKilo CLI is a terminal coding agent with custom OpenAI-compatible providers. Because ModelGo CLI automation is not available for Kilo CLI, use `/connect` or a `kilo.jsonc` file.\n\n## Prerequisites\n\n- Node.js 18+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\nRun `kilo` in a project; `/connect` opens the interactive provider setup.\n\n## 2. Add a ModelGo provider\n\nCreate `kilo.jsonc` in the project root (or edit the global config):\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/your-model-id\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"ModelGo / your-model-id\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nAlternatively choose `/connect` → `OpenAI Compatible` and enter the same Base URL, key, and model ID.\n\n:::note\n- Use lowercase provider ID `modelgo`; select `modelgo/your-model-id`.\n- `baseURL` is `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- The model ID must match a ModelGo logical model.\n:::\n\n## 3. Verify the configuration\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck JSONC syntax, the provider ID, and the `model` path, then restart Kilo.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is exported and `baseURL` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Kilo CLI documentation](https://kilo.ai/docs/code-with-ai/platforms/cli): Review installation, `/connect`, and CLI commands.\n- [Kilo custom models](https://kilo.ai/docs/code-with-ai/agents/custom-models): Review OpenAI Compatible provider fields.\n","china/en/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: Configure Kilo Code with ModelGo's OpenAI-compatible API.\n---\n\n# Kilo Code\n\nKilo Code is an AI coding assistant for VS Code and JetBrains. Use its OpenAI-compatible provider to connect Kilo Code to ModelGo models and API keys.\n\n## Before you start\n\n- Install VS Code or a JetBrains IDE.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Kilo Code\n\n### VS Code\n\nOpen the VS Code Marketplace, search for **Kilo Code**, verify the publisher, and install the extension. Then open the Kilo Code panel from the activity bar.\n\n![Install Kilo Code from the VS Code Marketplace](/images/agents/kilo-code/vscode-market.webp)\n\nOn the first install, VS Code asks you to confirm the publisher. Verify that it is Kilo Code, then click **Trust Publisher & Install**.\n\n![Trust the Kilo Code publisher](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\nOpen Settings / Preferences → Plugins, search the Marketplace for **Kilo Code**, and install the plugin. Restart the IDE after installation so the plugin takes effect.\n\n![Install Kilo Code from the JetBrains Marketplace](/images/agents/kilo-code/jetbrains-market.webp)\n\nWhen installing a third-party plugin, JetBrains displays its plugin notice. Confirm it and click **Accept** to finish the installation.\n\n![Confirm the JetBrains third-party plugin notice](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. Configure ModelGo in VS Code\n\nOpen Kilo Code settings, go to **Providers**, select **OpenAI Compatible**, and enter:\n\nFrom the Kilo Code welcome screen, first choose **Bring my own Key**:\n\n![Choose Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model | A ModelGo logical model name |\n\n![Kilo Code VS Code configuration](/images/agents/kilo-code/vscode-config-cn.webp)\n\nAfter saving, Kilo Code attempts to load models from the compatible `/v1/models` endpoint. If the target model is not in the picker, choose **Use custom** and enter the logical model name from the Model Gallery.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append `/chat/completions`. Kilo Code adds the standard path when it sends a request.\n- The model shown in the screenshot is only an interface example. Replace it with a ModelGo logical model allowed for the API key.\n- Keep the API key in Kilo Code's local settings. Do not commit it to a repository or include it in screenshots.\n:::\n\n## 3. Configure ModelGo in JetBrains\n\nOpen Kilo Code settings, click **Bring my own Key**, select **OpenAI Compatible**, and use the same values as in VS Code:\n\n![Choose Bring my own Key in JetBrains](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**: `{{ api_endpoint }}/v1`\n2. **API key**: your ModelGo API key\n3. **Model**: a ModelGo logical model name\n4. Click **Save**.\n\n![ModelGo provider settings in JetBrains](/images/agents/kilo-code/jetbrains-config-cn.webp)\n\nIf the model picker is empty, verify that the Base URL is reachable, then choose the custom-model option and enter the logical model name manually.\n\n![Kilo Code completing a task in JetBrains](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. Verify the connection\n\nOpen a local project and send a simple coding request in the Kilo Code panel, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Kilo Code completing a coding task](/images/agents/kilo-code/vscode-start.webp)\n\nTo inspect the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in **API key**, not the Base URL field.\n\n### 403 or model unavailable\n\nMake sure **Model** is a logical model listed in the ModelGo Model Gallery and allowed by the policy attached to the API key. Do not use an upstream provider's raw model ID unless the gallery explicitly lists it.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Kilo Code appends the endpoint path when it sends the request.\n\n### The model picker is empty\n\nUse `GET {{ api_endpoint }}/v1/models` to check the API key and endpoint. If the endpoint works, choose **Use custom** and enter the logical model name manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Kilo Code documentation](https://kilo.ai/docs): see the latest extension installation and provider setup guidance.\n","china/en/agents/nanobot.md":"---\ntitle: nanobot\ndescription: Connect nanobot to ModelGo.\n---\n\n# nanobot\n\nnanobot is a lightweight terminal agent that configures providers and model presets in JSON. It can call ModelGo through its OpenAI-compatible API.\n\n## Prerequisites\n\n- Python 3.11+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\nThe default config is `~/.nanobot/config.json`.\n\n## 2. Configure a ModelGo provider\n\nMerge these fields into `~/.nanobot/config.json`:\n\n```json\n{\n  \"providers\": {\"modelgo\": {\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"apiBase\": \"{{ api_endpoint }}/v1\"\n  }},\n  \"modelPresets\": {\"ModelGo\": {\n    \"provider\": \"modelgo\",\n    \"model\": \"your-model-id\",\n    \"maxTokens\": 4096,\n    \"contextWindowTokens\": 65536,\n    \"temperature\": 0.1\n  }},\n  \"agents\": {\"defaults\": {\"modelPreset\": \"ModelGo\"}}\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nLeave `apiType` unset for a custom OpenAI-compatible endpoint.\n\n:::note\n- Preserve existing channels and tools fields when merging the JSON.\n- Keep the key in `MODELGO_API_KEY`, not in a committed config file.\n- The model must be a ModelGo logical model ID.\n:::\n\n## 3. Verify the connection\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### nanobot cannot find the model\n\nMake sure `modelPresets.ModelGo.provider` matches `providers.modelgo` and that the JSON is valid.\n\n### 401 or endpoint errors\n\nConfirm the key is exported and `apiBase` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [nanobot OpenAI-compatible provider guide](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md): Review the JSON configuration.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","china/en/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: Connect Oh My Pi to ModelGo.\n---\n\n# Oh My Pi\n\nOh My Pi (`omp`) is a terminal coding agent. Declare an OpenAI-compatible provider in `models.yml`, then select models as `provider-id/model-id`.\n\n## Prerequisites\n\n- Bun or the official installer is available.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux can also use the official installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. Add a ModelGo provider\n\nEdit `~/.omp/agent/models.yml`:\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: your-model-id\n        name: ModelGo / your-model-id\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` is the environment variable name:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\n:::note\n- Use `openai-completions` and `{{ api_endpoint }}/v1` for the endpoint.\n- Select models as `modelgo/your-model-id`.\n- Keep the real API key out of `models.yml` and source control.\n:::\n\n## 3. Select and verify\n\n```bash\nomp --list-models\nomp --model modelgo/your-model-id\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSend a small read-only task in the session.\n\n## Troubleshooting\n\n### ModelGo is missing from the model list\n\nCheck `~/.omp/agent/models.yml`, YAML indentation, and restart `omp`.\n\n### 401 or endpoint errors\n\nConfirm `MODELGO_API_KEY` is exported and `baseUrl` has no duplicate `/v1` or full endpoint path.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Oh My Pi providers](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md): Review provider, API, and key settings.\n- [Oh My Pi models](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md): Review model selection and `models.yml`.\n","china/en/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: Configure OpenClaw with ModelGo's OpenAI-compatible API.\n---\n\n# OpenClaw\n\nOpenClaw is an open-source, self-hosted personal AI assistant. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22.22.3 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\nVerify the installation:\n\n```bash\nopenclaw --version\n```\n\n## 2. Set the API key\n\nOpenClaw can read a provider API key from an environment variable. Set your ModelGo API key as `MODELGO_API_KEY`:\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. Configure the ModelGo provider\n\nCreate and open the OpenClaw configuration file:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\nPaste the following into `openclaw.json`, replacing `YOUR_MODELGO_MODEL` with a logical model name from the Model Catalog:\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | A ModelGo logical model name |\n| `agents.defaults.model.primary` | `modelgo/<logical-model-name>` |\n\n:::note\n- Use `{{ api_endpoint }}/v1` as `baseUrl`; do not append `/chat/completions`.\n- Set `contextWindow` and `maxTokens` to values supported by the selected model. The values above are generic examples; use the Model Catalog as the source of truth.\n- Set `reasoning` to `true` when the selected model supports reasoning.\n- Inject the API key through the environment. Do not write a real key into the config file or commit it.\n:::\n\n## 4. Start and verify\n\nSave the configuration and run:\n\n```bash\nopenclaw onboard --install-daemon\n```\n\nCheck the active provider and model:\n\n```bash\nopenclaw models status\n```\n\nIf the status is healthy, start the Gateway:\n\n```bash\nopenclaw gateway start\n```\n\nSend a simple message in OpenClaw, such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### Model not found\n\nMake sure `models.providers.modelgo.models[].id` matches the model name in `agents.defaults.model.primary`, which must use the `modelgo/<model-name>` format.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` exists in the current terminal and that `apiKey` is `${MODELGO_API_KEY}` with no extra spaces.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `baseUrl` to `{{ api_endpoint }}/v1`; do not use a full `/chat/completions` URL. OpenClaw appends the path for `openai-completions`.\n\n### Gateway did not load the new configuration\n\nRestart the Gateway after editing the file:\n\n```bash\nopenclaw gateway restart\n```\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [OpenClaw custom provider docs](https://docs.openclaw.ai/gateway/config-tools): see provider, Base URL, and model list configuration.\n","china/en/agents/opencode.md":"---\ntitle: OpenCode\ndescription: Configure OpenCode with ModelGo's OpenAI-compatible API.\n---\n\n# OpenCode\n\nOpenCode is an open-source terminal AI coding agent. Its custom provider support lets you connect any OpenAI-compatible endpoint, including ModelGo, from a terminal, IDE, or desktop client.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Install OpenCode and confirm that `opencode -v` works in your terminal.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenCode\n\nRun:\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nYou can also use the installation method provided by the OpenCode project. A version printed by `opencode -v` confirms a successful installation.\n\n## 2. Configure the ModelGo provider\n\nOpenCode reads user configuration from:\n\n- macOS/Linux: `~/.config/opencode/opencode.json`\n- Windows: `%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\nCreate or edit `opencode.json`. Replace `your-model-id` with a logical model name from the model catalog:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"your-model-id\"\n        }\n      }\n    }\n  }\n}\n```\n\nSet the environment variable:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `name` | `ModelGo`, the display name in OpenCode |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | A logical model ID and display name from the model catalog |\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- `modelgo` is a local provider ID and can be changed. Use the new ID when selecting a model.\n- Keep the API key in an environment variable instead of committing it to a config file.\n- Model IDs must exactly match logical model names from the ModelGo catalog.\n:::\n\n## 3. Select a model and start a chat\n\nStart OpenCode:\n\n```bash\nopencode\n```\n\nEnter `/models` to open the model picker, then select a model under the **ModelGo** provider.\n\n![Open the model picker in OpenCode](/images/agents/opencode/model-search.webp)\n\nThe **ModelGo** provider label confirms that OpenCode recognized the provider.\n\n![Identify ModelGo in the OpenCode model list](/images/agents/opencode/provider-name.webp)\n\nYou can also type `ModelGo` in the picker to filter the list:\n\n![Filter ModelGo models in OpenCode](/images/agents/opencode/provider-filter.webp)\n\nSelect the model and enter a simple task such as “Describe this project in three sentences.”\n\n![Start a chat with ModelGo in OpenCode](/images/agents/opencode/chat.webp)\n\n## 4. Verify the configuration\n\nIf the model list is empty, confirm that the API key can reach ModelGo:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical model names to use in `models`.\n\n## Troubleshooting\n\n### OpenCode cannot find the config file\n\nCheck that the file is named `opencode.json` and is in `~/.config/opencode/` (or `%USERPROFILE%\\\\.config\\\\opencode\\\\` on Windows). A project-level file with the same name can override user settings.\n\n### 401 or authentication errors\n\nConfirm that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces. Restart OpenCode after changing the variable.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as `baseURL`; do not append `/chat/completions`.\n\n### Empty model list or unavailable model\n\nMake sure the ID in `models` exactly matches a logical ModelGo model and that the model is enabled for the API key.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [OpenCode Providers documentation](https://opencode.ai/docs/providers): configure providers, credentials, and custom Base URLs.\n- [OpenCode configuration documentation](https://opencode.ai/docs/config/): learn the config file structure and model options.\n","china/en/agents/zcode.md":"---\ntitle: ZCode\ndescription: Configure ZCode with ModelGo's OpenAI-compatible API.\n---\n\n# ZCode\n\nZCode is a desktop AI coding environment from Zhipu AI for Windows, macOS, and Linux. It supports custom OpenAI-compatible providers, so you can use ModelGo models and API keys directly in ZCode.\n\n## Before you start\n\n- Install the ZCode desktop app.\n- Create an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name that the API key can call in the [Model catalog]({{ site_endpoint }}/models).\n\n## 1. Install ZCode\n\nOpen the [ZCode download page](https://zcode.z.ai/en/docs/install) and download the package for your operating system. ZCode provides macOS, Windows, and Linux builds; Linux users can choose `.deb`, `.rpm`, or AppImage.\n\n![ZCode download page](/images/agents/zcode/install.webp)\n\nComplete the installation and launch ZCode. On first launch, choose a workspace and finish the onboarding flow to reach the main interface.\n\n![ZCode platform installers](/images/agents/zcode/setup.webp)\n\n## 2. Add the ModelGo provider\n\nClick the settings icon in the lower-left corner, open **Model settings**, then click **Add provider** at the bottom of the provider list.\n\n![Open ZCode Model settings and add a provider](/images/agents/zcode/provider-fields.webp)\n\nEnter the following values:\n\n| Setting | ModelGo value |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | A ModelGo API key created in the [console]({{ console_endpoint }}/api-keys) |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | Click **Add model** and enter a logical model name from the model catalog |\n| Context window | Use the model's actual context length; if unsure, start with `200000` |\n\n![ModelGo provider settings](/images/agents/zcode/provider-saved-global.webp)\n\nClick **Add provider** to save. Keep these details in mind:\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not enter the full `/chat/completions` URL. ZCode appends the request path based on the API format.\n- Name is only the local display name. Use `ModelGo`; do not enter an upstream vendor name.\n- Model IDs must be logical model names from the ModelGo catalog. Do not copy the example model in the screenshot.\n- Keep the API key in the local ZCode settings and out of repositories or public screenshots.\n:::\n\n## 3. Add a model and start a chat\n\nClick **Add model**, enter a ModelGo logical model name, and save it. You can add multiple models as needed.\n\n![Select a ModelGo model in ZCode](/images/agents/zcode/chat.webp)\n\nReturn to the chat view, select **ModelGo** and the model you added, then enter a simple task such as “Describe this project in three sentences.” A successful response confirms the integration.\n\nTo verify which models the API key can call, run:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nCheck that the API key is complete, has no extra spaces, and is entered in the **API Key** field.\n\n### 403 or model unavailable\n\nConfirm that the Model list uses a logical model name from the ModelGo catalog and that the API key is allowed to call it.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL and choose **Chat completions (/chat/completions)**. Do not paste a complete endpoint path into Base URL.\n\n### Empty model list or provider cannot be saved\n\nMake sure at least one model has been added and the Base URL is reachable. If needed, verify the API key and endpoint with `GET {{ api_endpoint }}/v1/models`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): learn how to use API keys safely.\n- [ZCode installation docs](https://zcode.z.ai/en/docs/install): see the latest installation instructions.\n- [ZCode model connection docs](https://zcode.z.ai/en/docs/configuration): see custom provider and model settings.\n","china/en/models/audio/minimax.md":"---\ntitle: MiniMax Audio Inbound Protocol\ndescription: Drive platform-managed synchronous speech synthesis with MiniMax T2A request and response bodies.\n---\n\n# MiniMax Audio Inbound Protocol\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | Catalog-advertised MiniMax T2A inbound |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK alias with the same semantics |\n\nThis is **MiniMax synchronous speech synthesis (T2A V2)** as an inbound protocol. The gateway accepts a MiniMax `T2aV2Req` body as-is (`model`, `text`, `voice_setting`, `audio_setting`, `stream`, and other MiniMax fields) and **renders a MiniMax `T2aV2Resp`**, so a client written against MiniMax's own documentation can decode this surface directly.\n\n`model` is the platform logical model name; policy, routing, and billing apply as usual. The logical model must advertise `minimax_t2a` in `public_protocols`, or the gateway rejects the call as a protocol mismatch.\n\nFor OpenAI-shaped binary audio, see [Speech](./speech).\n\n## Synthesize\n\nThe two paths are equivalent:\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"Hello from ModelGo.\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\nA successful non-stream response is MiniMax JSON. Audio lives in `data.audio` as a **hexadecimal string** (not a raw `audio/mpeg` body):\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\nVerified 2026-09-10 on domestic production with `speech-2.8-turbo` against `POST /minimax/v1/t2a_v2` (hex truncated). The same model on `POST /v1/audio/speech` returns `model_protocol_not_offered`.\n\nOnly numeric `base_resp.status_code` **`0`** is success. HTTP 200 with a non-zero `status_code` is still a failed invoke.\n\n### Streaming\n\nSet `\"stream\": true`. The response is SSE whose events are MiniMax JSON (incremental hex audio), not OpenAI chat `choices[].delta` chunks.\n\n### Failures and HTTP status\n\nIn-band MiniMax errors are echoed to the caller. The gateway maps `status_code` to HTTP:\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| any other non-`0` | `502` |\n\n### Billing\n\nUsage is the upstream **character** count (`usage.characters`, else `extra_info.usage_characters`). The gateway does not bill `len(text)`.\n\n## Conventions\n\n- `model` is the platform logical model name; whether this lane is allowed is the model's `public_protocols`.\n- The path does not pick the upstream family. Routing on the logical model decides MiniMax-direct vs a Bailian adaptor.\n- Providers on the route must declare MiniMax T2A. An OpenAI-compatible relay alone returns `provider_unsupported`.\n","china/en/models/audio/speech.md":"---\ntitle: Speech\ndescription: OpenAI-compatible text-to-speech endpoint.\n---\n\n# Speech\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\nThe request is JSON (OpenAI `{input, voice}`) and the response body is binary audio returned with the upstream `Content-Type`.\n\n**Check `public_protocols` first.** Domestic `speech-2.8-hd` / `speech-2.8-turbo` currently offer MiniMax T2A, not this endpoint (`model_protocol_not_offered`). Use [MiniMax Audio Inbound Protocol](./minimax).\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"Hello from ModelGo.\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\nFor MiniMax-native fields (voice mix, subtitles, hex JSON, SSE), see [MiniMax Audio Inbound Protocol](./minimax).\n","china/en/models/audio/transcriptions.md":"---\ntitle: Transcriptions\ndescription: OpenAI-compatible speech-to-text endpoint.\n---\n\n# Transcriptions\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\nThis endpoint typically uploads audio as `multipart/form-data` and returns JSON with recognized `text`.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/en/models/audio/translations.md":"---\ntitle: Translations\ndescription: OpenAI-compatible audio translation endpoint.\n---\n\n# Translations\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\nUploads follow the same shape as transcriptions and return translated text in JSON.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/en/models/images/edits.md":"---\ntitle: Image Edits\ndescription: OpenAI-compatible image edit endpoint.\n---\n\n# Image Edits\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\nThis endpoint uses `multipart/form-data` and forwards the original body and `Content-Type` upstream, so clients should call `POST /v1/images/edits` with multipart upload semantics.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\nIf the routed upstream model does not support image editing, the gateway returns `provider_unsupported`.\n","china/en/models/images/gemini-image.md":"---\ntitle: Gemini 3 / 3.1 Image Generation (Google native protocol)\ndescription: Call gemini-3-pro-image, gemini-3.1-flash-image and gemini-3.1-flash-lite-image on the official Gemini API generateContent protocol — responseModalities, aspectRatio / imageSize tiers, inlineData responses and token-based billing. The Google GenAI SDK works by changing base_url.\n---\n\n# Gemini 3 / 3.1 Image Generation (Google native protocol)\n\n| Model (used in the path) | Positioning | Available `imageSize` |\n| --- | --- | --- |\n| `gemini-3-pro-image` | Quality tier | `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-image` | Speed / cost balance | `512px` / `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-lite-image` | Lowest cost | `1K` only |\n\nThe ModelGo gateway accepts image generation requests on the Gemini API **`generateContent`** protocol unchanged: `contents` + `generationConfig`, returning `candidates[].content.parts[].inlineData` synchronously. The gateway routes to a supplier and bills the call; which supplier renders the image is invisible to the caller. **The model name in the URL path is authoritative** — the body does not carry a model.\n\n> With the Google GenAI SDK, point `http_options.base_url` at `{{ api_endpoint }}` and use your ModelGo API key as `api_key`. Both `x-goog-api-key: $KEY` and `Authorization: Bearer $KEY` are accepted.\n>\n> Google's newer Interactions API is not yet supported; use `generateContent`.\n\n## 1. Create an image\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:generateContent` (also accepted under `/v1/models/...`)\n\n### Text to image\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [{\"text\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\"}]}],\n    \"generationConfig\": {\n      \"responseModalities\": [\"IMAGE\"],\n      \"imageConfig\": {\"aspectRatio\": \"16:9\", \"imageSize\": \"2K\"}\n    }\n  }'\n```\n\n### Image to image\n\nPut reference images into `parts` as `inlineData` (base64) or `fileData` (public URL):\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3-pro-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [\n      {\"text\": \"Replace the background with a neon night street, keep the cat's pose\"},\n      {\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"<base64>\"}}\n    ]}],\n    \"generationConfig\": {\"responseModalities\": [\"IMAGE\"], \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}}\n  }'\n```\n\n`fileData` form: `{\"fileData\": {\"fileUri\": \"https://example-cdn.com/cat.png\"}}` — must be a direct link the upstream can `GET`.\n\n### Response\n\n```json\n{\n  \"candidates\": [{\n    \"content\": {\n      \"role\": \"model\",\n      \"parts\": [{\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"iVBORw0KGgo...\"}}]\n    },\n    \"finishReason\": \"STOP\",\n    \"index\": 0\n  }],\n  \"usageMetadata\": {\n    \"promptTokenCount\": 18,\n    \"candidatesTokenCount\": 1680,\n    \"totalTokenCount\": 1698,\n    \"promptTokensDetails\": [{\"modality\": \"TEXT\", \"tokenCount\": 18}],\n    \"candidatesTokensDetails\": [{\"modality\": \"IMAGE\", \"tokenCount\": 1680}]\n  },\n  \"modelVersion\": \"gemini-3.1-flash-image\"\n}\n```\n\n- The image is in `parts[].inlineData.data` (base64). When `responseModalities` includes `TEXT`, `parts` may also contain a `{\"text\": ...}` part.\n- `modelVersion` echoes the model name from the request path.\n\nSave to a file:\n\n```bash\ncurl -s \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"contents\":[{\"parts\":[{\"text\":\"a red ball on a wooden table\"}]}],\"generationConfig\":{\"responseModalities\":[\"IMAGE\"]}}' \\\n  | python3 -c '\nimport sys, json, base64\nfor p in json.load(sys.stdin)[\"candidates\"][0][\"content\"][\"parts\"]:\n    if \"inlineData\" in p:\n        open(\"out.png\", \"wb\").write(base64.b64decode(p[\"inlineData\"][\"data\"])); break'\n```\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `contents[].role` | string | `user` |\n| `contents[].parts[].text` | string | The prompt. Describes the image; for image-to-image, describes the change |\n| `contents[].parts[].inlineData` | object | Reference image, `{\"mimeType\": \"image/png\", \"data\": \"<base64>\"}` |\n| `contents[].parts[].fileData` | object | Reference image URL, `{\"fileUri\": \"https://...\"}` |\n| `systemInstruction` | object | Optional system instruction, same as Gemini text calls |\n| `generationConfig.responseModalities` | string[] | `[\"IMAGE\"]` for image only; `[\"TEXT\",\"IMAGE\"]` for interleaved text and image |\n| `generationConfig.imageConfig.aspectRatio` | string | `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` |\n| `generationConfig.imageConfig.imageSize` | string | Resolution tier; per-model values in the first table, default `1K` |\n\n- `candidateCount` > 1 → `400`: one image per request.\n- `tools`, `responseSchema` / `responseMimeType` → `400`: image models do not support tool calls or structured output.\n- `:streamGenerateContent` → `400`: image generation does not stream.\n- An `imageSize` the model does not offer (e.g. `2K` on `gemini-3.1-flash-lite-image`) → `400`; it is **never silently downgraded**, and nothing is charged.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared tier; if no supplier can currently produce it the request returns `400` and nothing is charged.\n\n### Resolution tiers\n\n| Tier | Pixel budget | Measured output (example) |\n| --- | --- | --- |\n| `512px` | ~0.25 MP | — |\n| `1K` (default) | ~1 MP | default → 1408×768 |\n| `2K` | ~4 MP | `16:9` → 2752×1536 |\n| `4K` | ~16 MP | `9:16` → 3072×5504 |\n\nThe tier sets the total pixel budget; **exact width and height are determined by `aspectRatio`**. Without an `aspectRatio` the default is the supplier's roughly 16:9 output.\n\n## 3. Full example (Python, Google GenAI SDK)\n\n```python\nimport os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(api_key=os.environ[\"MODELGO_API_KEY\"],\n                      http_options={\"base_url\": \"{{ api_endpoint }}\"})\n\nresp = client.models.generate_content(\n    model=\"gemini-3.1-flash-image\",\n    contents=\"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    config=types.GenerateContentConfig(\n        response_modalities=[\"IMAGE\"],\n        image_config=types.ImageConfig(aspect_ratio=\"16:9\", image_size=\"2K\"),\n    ),\n)\nfor part in resp.candidates[0].content.parts:\n    if part.inline_data:\n        open(\"cat.png\", \"wb\").write(part.inline_data.data)\nprint(resp.usage_metadata.candidates_token_count)\n```\n\nFor image-to-image, pass a list as `contents`: `[\"Replace the background with a neon night street\", types.Part.from_bytes(data=open(\"cat.png\",\"rb\").read(), mime_type=\"image/png\")]`.\n\n## 4. Billing\n\n- **Token-based**: text in `promptTokensDetails` at `input`, images at `image_input`; in `candidatesTokensDetails`, `IMAGE` at `image_output` and `TEXT` at `output`.\n- Output image tokens grow with the tier (measured): `1K` ≈ 1120, `2K` ≈ 1680, `4K` ≈ 2000.\n- A reservation is frozen at request time and settled from the actual `usageMetadata` values.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- Prices are those shown in the console's model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `imageSize` not offered by the model; `aspectRatio` outside the table; `candidateCount` > 1; `tools` / `responseSchema` / `responseMimeType` present; `:streamGenerateContent` called; no supplier can currently produce the requested tier | Fix per the parameter table; use `generateContent` |\n| No `inlineData` in `parts` | `responseModalities` did not include `IMAGE`, or the prompt was blocked by safety policy (`finishReason` other than `STOP`) | Pass `[\"IMAGE\"]` explicitly; check `finishReason` |\n| Reference image ignored | `fileData.fileUri` is not a public direct link (auth / redirect / 403) | Use `inlineData` or a direct link on your own CDN |\n| `401` | Invalid API key or missing `x-goog-api-key` / `Authorization` header | Check the key |\n","china/en/models/images/generations.md":"---\ntitle: Image Generation\ndescription: OpenAI-compatible image generation endpoint.\n---\n\n# Image Generation\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\nThe request body follows the OpenAI Images-compatible shape and is forwarded to an upstream provider that supports image generation. The main entrypoint is `POST /v1/images/generations`.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\nCommon optional fields include `size`, `quality`, and `n`, subject to upstream model support.\n\n## Verified Seedream limit\n\n`doubao-seedream-5.0-lite` rejects `size=1024x1024` (HTTP 400 `provider_invalid`, at least 3686400 pixels). `2048x2048` succeeded on 2026-09-10. Full curl: [API catalog](../../../quickstart/openapi).\n","china/en/models/images/gpt-image-2.md":"---\ntitle: GPT Image (gpt-image-2 / gpt-image-1.5) Image Generation / Editing (OpenAI Images native protocol)\ndescription: Call gpt-image-2 / gpt-image-1.5 on the official OpenAI Images API — generations for text-to-image, edits for image-to-image and mask editing, size / quality parameters, b64_json responses and token-based billing. The official OpenAI SDK works by changing base_url.\n---\n\n# GPT Image (gpt-image-2 / gpt-image-1.5) Image Generation / Editing (OpenAI Images native protocol)\n\n| Model | Endpoints | Default-tier output tokens (`1024x1024` + `quality: auto`, measured) |\n| --- | --- | --- |\n| `gpt-image-2` | generations / edits | 196 |\n| `gpt-image-1.5` | generations / edits | 4444 |\n\n| Endpoint | Capability | Body | Required fields |\n| --- | --- | --- | --- |\n| `POST /v1/images/generations` | Text to image | JSON | `model`, `prompt` |\n| `POST /v1/images/edits` | Image to image / mask editing (multiple references) | `multipart/form-data` | `model`, `prompt`, `image[]` |\n\nBoth models share the same parameter set and the same endpoints; only the `model` field differs. Their output token counts and prices differ (see \"Billing\").\n\nThe ModelGo gateway accepts `gpt-image-2` / `gpt-image-1.5` requests on the official OpenAI Images API paths with the official request/response shapes unchanged; the gateway routes to a supplier and bills the call. Which supplier renders the image is invisible to the caller. Images are returned **synchronously** — there is no polling.\n\n> With the official OpenAI SDK, point `base_url` at `{{ api_endpoint }}/v1` and use your ModelGo API key as `api_key`.\n\n## 1. Create an image\n\n### Text to image\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-image-2\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    \"size\": \"1536x1024\",\n    \"quality\": \"high\",\n    \"output_format\": \"png\"\n  }'\n```\n\n### Image to image / mask editing\n\n`POST {{ api_endpoint }}/v1/images/edits` (`multipart/form-data`)\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=gpt-image-2\" \\\n  -F \"prompt=Replace the background with a neon night street, keep the cat's pose\" \\\n  -F \"image[]=@./cat.png\" \\\n  -F \"mask=@./mask.png\" \\\n  -F \"size=1024x1024\" \\\n  -F \"quality=medium\" \\\n  -F \"input_fidelity=high\"\n```\n\n- `image[]` may be repeated to send several reference images in one request.\n- `mask` is optional: a PNG with the same dimensions as the first `image[]`; transparent areas are repainted.\n\n### Response\n\n```json\n{\n  \"created\": 1757318400,\n  \"data\": [{\"b64_json\": \"iVBORw0KGgoAAAANSUhEUgAA...\"}],\n  \"usage\": {\n    \"input_tokens\": 17,\n    \"input_tokens_details\": {\"text_tokens\": 17, \"image_tokens\": 0},\n    \"output_tokens\": 5488,\n    \"output_tokens_details\": {\"image_tokens\": 5488, \"text_tokens\": 0},\n    \"total_tokens\": 5505\n  }\n}\n```\n\nImages are always returned as `data[].b64_json` (base64). Save to a file:\n\n```bash\ncurl -s {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gpt-image-2\",\"prompt\":\"a red ball on a wooden table\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.png\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model` | string | all | `gpt-image-2` / `gpt-image-1.5` |\n| `prompt` | string | all | Required. Describes the image; for edits, describes the change to make |\n| `image[]` | file | edits | Required. One or more reference images (png / jpeg / webp) |\n| `mask` | file | edits | Optional. PNG mask with the same dimensions as the image; transparent areas are repainted |\n| `input_fidelity` | string | edits | How closely to follow the reference image, `low` / `high` |\n| `n` | int | all | Number of images, default `1` |\n| `size` | string | all | `1024x1024` / `1536x1024` / `1024x1536` / `auto`, default `auto`. Larger sizes depend on supplier availability |\n| `quality` | string | all | `low` / `medium` / `high` / `auto`, default `auto`. Directly determines the output token count |\n| `output_format` | string | all | `png` / `jpeg` / `webp` |\n| `output_compression` | int | all | `0`–`100`, only for `jpeg` / `webp` |\n| `background` | string | all | `opaque` / `transparent` / `auto` |\n| `moderation` | string | all | Content moderation level, passed through |\n\n- **`response_format` does not apply to the gpt-image family.** The gateway strips the field before forwarding, without an error; images are always returned as `b64_json` — there is no `url` form.\n- A `size` / `quality` outside the table, or a missing `prompt` → HTTP `400`, nothing charged.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared `size` / `quality`; if no supplier can currently produce that tier the request returns `400` and nothing is charged.\n\n### Output token reference (measured)\n\n| Model | `size` | `quality` | `output_tokens_details.image_tokens` |\n| --- | --- | --- | --- |\n| `gpt-image-2` | `1024x1024` | `auto` (default) | 196 |\n| `gpt-image-2` | `1536x1024` | `high` | 5488 |\n| `gpt-image-1.5` | `1024x1024` | `auto` (default) | 4444 |\n\nOutput tokens are determined by model, size and quality together: on gpt-image-2, `high` is more than an order of magnitude above the default tier; at the same default tier, gpt-image-1.5 emits more than 20× the output tokens of gpt-image-2. Token counts and prices differ between the two models, so re-check cost before switching.\n\n## 3. Full example (Python, official OpenAI SDK)\n\n```python\nimport base64, os\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/v1\")\n\n# Text to image\nr = client.images.generate(model=\"gpt-image-2\", prompt=\"An orange cat on a windowsill, film grain\",\n                           size=\"1536x1024\", quality=\"high\", output_format=\"png\")\nopen(\"cat.png\", \"wb\").write(base64.b64decode(r.data[0].b64_json))\nprint(r.usage.output_tokens_details.image_tokens)\n\n# Image to image (mask editing)\nwith open(\"cat.png\", \"rb\") as img, open(\"mask.png\", \"rb\") as mask:\n    e = client.images.edit(model=\"gpt-image-2\", prompt=\"Replace the background with a neon night street\",\n                           image=[img], mask=mask, size=\"1024x1024\", quality=\"medium\")\nopen(\"cat-neon.png\", \"wb\").write(base64.b64decode(e.data[0].b64_json))\n```\n\n## 4. Billing\n\n- **Token-based**, with three prices: text input (`input`), image input (`image_input`) and image output (`image_output`), each per million tokens. The image portion of the output is billed at the `image_output` price.\n- gpt-image-2 and gpt-image-1.5 each have their own price card, and their output token counts for the same tier differ materially (196 vs 4444 at the default tier), so the cost of one request cannot be inferred from the other model.\n- A reservation is frozen at request time and settled from the returned `usage`: `input_tokens_details.text_tokens` → `input`, `input_tokens_details.image_tokens` → `image_input`, `output_tokens_details.image_tokens` → `image_output`.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- Prices are those shown in the console's model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `size` / `quality` outside the parameter table; missing `prompt`; edits missing `image[]` or `mask` dimensions differ from the image; no supplier can currently produce the requested tier | Fix per the parameter table or change tier |\n| `response_format: \"url\"` sent but `b64_json` returned | The gpt-image family does not support the field; the gateway strips it silently | Decode `data[].b64_json` |\n| `429` | Rate limit hit | Back off and retry; contact the platform for a higher quota |\n| `401` | Invalid API key or missing `Authorization` header | Check the key |\n","china/en/models/images/qwen-image.md":"---\ntitle: Qwen Image Generation and Editing 3.0 (Bailian native protocol)\ndescription: Call qwen-image-3.0 / qwen-image-3.0-pro on either of two synchronous inbound lanes — OpenAI-compatible and Bailian DashScope native — with text to image and image to image (1-3 reference images), the two spellings of size, the 1k / 2k resolution tiers and per-image billing. The official Bailian SDK works by changing base_url.\n---\n\n# Qwen Image Generation and Editing 3.0 (Bailian native protocol)\n\n## Models\n\n| Model | Output resolution | Notes |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | Total pixels 512×512 – 2048×2048 | Pro tier; the 2k tier costs more than 1k |\n| `qwen-image-3.0` | Same | Standard tier; both tiers priced the same |\n\nBoth models serve **text to image (T2I)** and **image to image / editing (I2I)**: no reference image means T2I, 1–3 reference images mean I2I. Images are returned **synchronously** — no polling.\n\n> **The async task lane is not supported.** This family is served only on the synchronous endpoints; a call to `/v1/content_generation/tasks` is refused.\n\n## Two inbound lanes\n\nOne model, two spellings, identical capability. Pick whichever matches the code you already have:\n\n| Lane | Path | Who it is for |\n| --- | --- | --- |\n| OpenAI-compatible | `POST /v1/images/generations` | Apps already written against the OpenAI Images protocol or SDK — change `base_url` and `model` only |\n| Bailian native | `POST /api/v1/services/aigc/multimodal-generation/generation` | Apps already using the Bailian DashScope SDK — change `base_url` only |\n\n> **The two lanes spell `size` differently and neither accepts the other's spelling**: the OpenAI-compatible lane uses the letter `x` (`1024x1024`), the Bailian native lane uses an asterisk (`1024*1024`). The wrong one returns `400` naming the separator it expects; it is **not** silently rewritten — mixing the two protocols should surface here rather than as a harder problem further down.\n\n## 1. OpenAI-compatible lane\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### Text to image\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"A fluffy ginger cat on a sunlit windowsill, afternoon light, film grain\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### Image to image / editing\n\nNo multipart: the reference images go in the top-level `image` field.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"Keep her facial features; change the outfit to a champagne silk shirt and a dark grey blazer\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### Response\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- Images are PNG, and the **link is valid for 24 hours** — download promptly and do not persist the URL.\n- `usage` carries **image counts and tiers, not token usage**: this family bills purely per image (see Billing).\n- `response_format: \"b64_json\"` does not error but is ignored; the response still carries an image URL.\n\n### Using the OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # Generation is slow; 40-60s for a single image in practice\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"A fluffy ginger cat on a sunlit windowsill, film grain\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # extensions go through extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` are not OpenAI parameters: pass them via `extra_body` with the OpenAI SDK, or at the top level of the request body over plain HTTP.\n\n## 2. Bailian native lane\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\nRequest and response are Bailian's own shapes in both directions — the gateway does not translate.\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### Constraints of this lane\n\n- `input.messages` carries **exactly one** object and `role` must be `user` (single-turn only).\n- `content` carries **exactly one** `{\"text\": ...}`; omitting it or passing several returns `400`.\n- `{\"image\": ...}` 0–3 entries: 0 is text to image, 1–3 is image to image.\n- Generation parameters live under `parameters` (not at the top level): `size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`.\n- With the official Bailian SDK (`dashscope`), point `dashscope.base_http_api_url` at `{{ api_endpoint }}/api/v1` and use your ModelGo API key.\n\n## 3. Parameters\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt` (compat lane) / `content[].text` (native lane) | string | Required, non-empty. Chinese and English; up to about 4500 tokens recommended |\n| `image` (compat lane) / `content[].image` (native lane) | string / string[] | Reference images, 1–3. **`null` and an empty array are refused** |\n| `size` | string | `WxH` on the compat lane, `W*H` on the native lane. Omitted means the model picks a resolution from the prompt |\n| `n` | int | 1–6 output images, default 1. **Must be an integer**; the string form (e.g. `\"1\"`) returns `400` |\n| `negative_prompt` | string | What to keep out of the picture |\n| `seed` | int | `0` – `2147483647`. A fixed seed makes results relatively stable |\n| `prompt_extend` | boolean | Prompt rewriting, default `true` (recommended) |\n| `prompt_extend_mode` | string | `direct` (default, T2I and I2I) / `agent` (finer, **text to image only**) |\n| `enable_thinking` | boolean | Thinking mode, default `true`. Better images, longer latency. Only effective when `prompt_extend=true` |\n| `watermark` | boolean | Watermark, default `false` |\n\n### Validation happens before the call\n\nThe following are refused at creation (HTTP `400`) — nothing reaches the upstream and nothing is charged:\n\n- `n` is not an integer in 1–6, or is written as a string or a decimal;\n- `size` total pixels fall outside 512×512 – 2048×2048, or the aspect ratio is outside 1:8 – 8:1;\n- `size` uses the other lane's separator (the error names whether `x` or `*` is expected);\n- `image` is `null`, an empty array, or more than 3 entries;\n- `prompt_extend_mode: \"agent\"` is combined with `image` (APE is text to image only);\n- `seed` is outside `0` – `2147483647`;\n- on the native lane, `messages` is not exactly one, or `content` does not carry exactly one `text`.\n\n### Reference image requirements\n\n- Formats: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF.\n- Width and height between 384 and 2048 pixels recommended; at most 10 MB each.\n- Public URLs (HTTP / HTTPS) or Base64 (`data:{MIME_type};base64,{base64_data}`).\n- A public URL must be directly `GET`-able by the upstream: no auth, no redirect, no Referer / Cookie dependency. Some sites return 403 to non-browser clients, which fails the request.\n\n## 4. Billing\n\n**Per image, not per token.** Input (reference) and output (generated) images are priced separately, each split into a 1k and a 2k tier:\n\n| Model | Output tier | Output price | Input price |\n| --- | --- | --- | --- |\n| `qwen-image-3.0-pro` | 1k | CNY 0.25 / image | CNY 0.02 / image |\n| `qwen-image-3.0-pro` | 2k | CNY 0.50 / image | CNY 0.02 / image |\n| `qwen-image-3.0` | 1k | CNY 0.18 / image | CNY 0.02 / image |\n| `qwen-image-3.0` | 2k | CNY 0.18 / image | CNY 0.02 / image |\n\n**The tier is decided by the OUTPUT pixel area**: an area of 2,250,000 (that is, 1500×1500) or less is `1k`, anything larger is `2k`. **The input tier is judged by the output area too**, not by the size of the reference image — that is the upstream's own rule. `output_image_type` / `input_image_type` in the response `usage` name the tier the call actually hit.\n\nCharge = output count × that tier's output price + input count × input price. Measured examples (China production, 2026-09-11):\n\n| Request | `usage` | Settled |\n| --- | --- | --- |\n| `qwen-image-3.0`, `1024x1024`, `n=1`, T2I | `output_image_count: 1`, `qima_output_1k` | CNY 0.18 |\n| `qwen-image-3.0`, `1024x1024`, `n=2`, T2I | `output_image_count: 2`, `qima_output_1k` | CNY 0.36 |\n| `qwen-image-3.0-pro`, `1024x1024`, `n=1`, T2I | `output_image_count: 1`, `qima_output_1k` | CNY 0.25 |\n| `qwen-image-3.0-pro`, `2048x2048`, `n=1`, T2I | `output_image_count: 1`, `qima_output_2k` | CNY 0.50 |\n\n**Text to image incurs no input charge**: with no reference image `input_image_count` is 0 and only the output count settles.\n\n## 5. Full example (Python, official Bailian SDK)\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt; modern minimalist cafe background\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","china/en/models/images/seedream.md":"---\ntitle: Seedream Image Generation (Volcengine Ark native protocol)\ndescription: Call the Seedream family (doubao-seedream-5.0-pro / 5.0-lite / 5.0 / 4.5) on the official Volcengine Ark Images API — text to image / multi-reference, per-model size tiers and explicit pixel sizes, url / b64_json responses and per-image billing. The official Ark SDK works by changing base_url.\n---\n\n# Seedream Image Generation (Volcengine Ark native protocol)\n\n## Models and tiers\n\n| Model | Default `size` | Offered `size` | Typical output (measured) |\n| --- | --- | --- | --- |\n| `doubao-seedream-5.0-pro` | `2K` | `1K` / `1.5K` / `2K`, or `WxH` | `1K` ≈ 1152×864; `1.5K` ≈ 1792×1344; `2K` + 16:9 prompt → 2816×1584 |\n| `doubao-seedream-5.0-lite` | `2K` | `2K` / `3K` / `4K`, or `WxH` with total pixels ≥ 3,686,400 | `2K` → 2048×2048; `3K` → 3072×3072; `4K` → 4096×4096 |\n| `doubao-seedream-5.0` | `2K` | Same as 5.0 lite | Same as 5.0 lite |\n| `doubao-seedream-4.5` | `2K` | `2K` / `4K`, or `WxH` with total pixels ≥ 3,686,400 (**no `3K`**) | `2K` → 2048×2048; `4K` → 4096×4096 |\n\n- All four models share the same inbound `POST /api/v3/images/generations`, support text to image and image to image (single / multiple references), and require `model` and `prompt`.\n- `doubao-seedream-5.0` is an alias of `doubao-seedream-5.0-lite`: Ark has no standalone 5.0 model, so the two share tiers and price.\n- 5.0 pro does **not** offer `3K` / `4K`; 5.0 lite / 5.0 / 4.5 do **not** offer `1K` / `1.5K` (Ark requires at least 3,686,400 pixels); 4.5 additionally does **not** offer `3K`. A tier outside the table is refused at creation (HTTP `400`) — nothing is rendered, nothing is charged.\n- On 5.0 pro, `1.5K` is priced the same as `1K` (Ark pricing) and is served by only part of the supplier pool, so fewer lanes are available than for the other tiers.\n\nThe ModelGo gateway accepts Seedream requests on the official Volcengine Ark **Images API** path with the official request/response shapes unchanged; the gateway routes to a supplier and bills the call. Which supplier renders the image is invisible to the caller. Images are returned **synchronously** — there is no polling.\n\n> With the official Ark SDK (`volcenginesdkarkruntime`), point `base_url` at `{{ api_endpoint }}/api/v3` and use your ModelGo API key as `api_key`.\n\n## 1. Create an image\n\n`POST {{ api_endpoint }}/api/v3/images/generations`\n\n### Text to image (5.0 pro)\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, 16:9 landscape, film grain\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### Text to image (5.0 lite)\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### Image to image / multiple references\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"Place the cat from the first image into the neon street of the second image\",\n    \"image\": [\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n    \"size\": \"1280x720\",\n    \"response_format\": \"b64_json\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"model\": \"doubao-seedream-5.0-pro\",\n  \"created\": 1757318400,\n  \"data\": [{\"url\": \"https://ark-content-generation.tos-cn-beijing.volces.com/...\", \"size\": \"2816x1584\", \"output_format\": \"jpeg\"}],\n  \"usage\": {\"generated_images\": 1, \"input_images\": 0, \"output_tokens\": 17424, \"total_tokens\": 17424}\n}\n```\n\n- `model` always echoes the logical model you requested (e.g. `doubao-seedream-5.0-lite`), not Ark's internal version id (which looks like `doubao-seedream-5-0-260128` / `doubao-seedream-4-5-251128` / `doubao-seedream-5-0-pro-260628`).\n- `response_format` defaults to `url`; **the link is valid for 24 hours** — download promptly and do not persist the URL.\n- With `response_format: \"b64_json\"`, `data[].b64_json` carries the base64 image directly.\n- `data[].size` is the actual output resolution and `output_format` the actual encoding.\n- `usage.output_tokens` / `total_tokens` are informational values echoed from upstream and **are not billed**; settlement uses `usage.generated_images` only.\n\nSave to a file:\n\n```bash\ncurl -s {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedream-5.0-lite\",\"prompt\":\"a red ball on a wooden table\",\"size\":\"2K\",\"response_format\":\"b64_json\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.jpg\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `model` | string | `doubao-seedream-5.0-pro` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0` / `doubao-seedream-4.5` |\n| `prompt` | string | Required. Describes the image; with tier sizes, describe the composition / aspect here |\n| `image` | string / string[] | Reference image URL (single) or array of URLs (multiple references); must be public direct links the upstream can `GET` |\n| `size` | string | Resolution tier (default `2K`; the tiers offered per model are listed under \"Models and tiers\"), or explicit pixels `WxH` (e.g. `1280x720`, `2560x1440`) |\n| `seed` | int | Random seed |\n| `guidance_scale` | number | Prompt adherence |\n| `watermark` | boolean | Add a watermark, default `true` |\n| `response_format` | string | `url` (default, valid 24 hours) / `b64_json` |\n| `output_format` | string | Output encoding, passed through |\n\n- `sequential_image_generation: \"auto\"` (image sets) is not supported on 5.0 pro → `400`.\n- `stream: true` → `400`: streaming is not supported.\n- Any field outside the table → `400`; unknown fields are rejected, not ignored.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared `size`; if no supplier can currently produce that tier the request returns `400` and nothing is charged.\n\n### Resolution tiers\n\n| Model | `size` form | Output | Measured example |\n| --- | --- | --- | --- |\n| 5.0 pro | `1K` / `1.5K` / `2K` (default) | The tier sets the total pixel budget; the aspect ratio follows the composition described in `prompt` | `\"2K\"` + 16:9 prompt → 2816×1584; `\"1.5K\"` → 1792×1344; `\"1K\"` → 1152×864 |\n| 5.0 lite / 5.0 | `2K` (default) / `3K` / `4K` | The tier sets the output edge length | `\"2K\"` → 2048×2048; `\"3K\"` → 3072×3072; `\"4K\"` → 4096×4096 |\n| 4.5 | `2K` (default) / `4K` | Same; 4.5 does not offer `3K` | `\"2K\"` → 2048×2048; `\"4K\"` → 4096×4096 |\n| all | `WxH` | Exactly the requested dimensions; aspect ratio between 1/16 and 16. 5.0 lite / 5.0 / 4.5 require total pixels ≥ 3,686,400 | 5.0 pro: `\"1280x720\"` → 1280×720; 5.0 lite: `\"2560x1440\"` → 2560×1440 |\n\n- A `size` outside the table (a tier the model does not offer, pixels below the minimum, or aspect out of range) is rejected at creation (HTTP `400`); it is never silently downgraded or upgraded, and nothing is charged.\n\n### Reference image requirements\n\n- Must be a direct link the upstream server can `GET`: no auth, no redirects, no Referer / Cookie dependency.\n- Some sites return 403 to non-browser fetches, which fails the request — not billed. Use your own object storage or CDN.\n\n## 3. Full example (Python, official Ark SDK)\n\n```python\nimport os, requests\nfrom volcenginesdkarkruntime import Ark\n\nclient = Ark(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/api/v3\")\n\n# 5.0 pro: tier + aspect described in the prompt\nr = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"An orange cat on a windowsill, 16:9 landscape, film grain\",\n                           size=\"2K\", watermark=False)\nimg = r.data[0]\nprint(r.model, img.size, r.usage.generated_images)\nopen(\"cat.jpg\", \"wb\").write(requests.get(img.url, timeout=60).content)\n\n# 5.0 lite: default 2K tier (2048x2048)\nl = client.images.generate(model=\"doubao-seedream-5.0-lite\",\n                           prompt=\"An orange cat on a windowsill, film grain\",\n                           size=\"2K\", watermark=False)\nopen(\"cat-lite.jpg\", \"wb\").write(requests.get(l.data[0].url, timeout=60).content)\n\n# Multiple references\ne = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"Place the cat from the first image into the neon street of the second image\",\n                           image=[\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n                           size=\"1280x720\")\nopen(\"cat-neon.jpg\", \"wb\").write(requests.get(e.data[0].url, timeout=60).content)\n```\n\n## 4. Billing\n\n- **Per image**: settlement uses `usage.generated_images` at a flat price per image, independent of the `size` tier.\n- **One price per model**: 5.0 pro / 5.0 lite / 5.0 / 4.5 each have their own price card in the console's model list and the prices differ (5.0 and 5.0 lite share one price).\n- A reservation is frozen at request time and settled on the actual number of generated images.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- An HTTP `200` whose `data[]` contains no `url` / `b64_json` at all (e.g. every entry is an `error`) is not billed.\n- A content-moderation refusal (e.g. `OutputImageSensitiveContentDetected`) returns HTTP `400` with the upstream error code; it is neither billed nor retried.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `size` outside the tier table or `WxH` out of bounds; missing `prompt`; `sequential_image_generation` / `stream` or another unsupported field present; no supplier can currently produce the requested tier | Fix per the parameter table or change tier |\n| `400` (5.0 lite / 5.0 / 4.5) | `size` below the model's minimum: `1K` / `1.5K`, or `WxH` with total pixels < 3,686,400; `3K` on 4.5 | Use `2K` / `4K` (`3K` also on lite / 5.0), or `WxH` with total pixels ≥ 3,686,400 (e.g. `2560x1440`) |\n| `400` (5.0 pro) | `3K` / `4K` requested; 5.0 pro does not offer those tiers | Use `1K` / `1.5K` / `2K` or `WxH` |\n| `400` with `metadata.upstream_error_code` such as `OutputImageSensitiveContentDetected` | Upstream content moderation refused the request; not billed, not retried | Adjust the `prompt` / reference images and retry |\n| Generation failed | Upstream could not download a URL in `image` | Use a publicly downloadable direct link |\n| `data[].url` download returns `403` / `404` | The 24-hour link has expired | Regenerate, or use `response_format: \"b64_json\"` |\n| `401` | Invalid API key or missing `Authorization` header | Check the key |\n","china/en/models/realtime/api.md":"---\ntitle: Realtime API reference\ndescription: Handshake, events, and audio formats for GET /api-ws/v1/realtime (WebSocket).\n---\n\n# Realtime API reference: `GET /api-ws/v1/realtime`\n\nThis endpoint is a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol verbatim in both directions with **no protocol translation**; the full field definitions and the tool-calling (Function Calling / MCP) events follow Bailian's official [client events](https://help.aliyun.com/zh/model-studio/client-events) and [server events](https://help.aliyun.com/zh/model-studio/server-events). This page covers the handshake, auth, event list, and audio conventions needed to integrate.\n\n## Request\n\n| Item | Value |\n| --- | --- |\n| Method | `GET` (WebSocket upgrade) |\n| Path | `/api-ws/v1/realtime` |\n| Full URL | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<logical model>` |\n| Query | `model` (required) — the platform logical model, not the upstream model |\n| Header | `Authorization: Bearer <mgk_ API Key>` (required) |\n| Header | `X-Request-ID` (optional) — propagated to the call log; the `request_id` starts with `gw_rt_` |\n\nOnly a logical model whose `public_protocols` includes `dashscope_realtime` can use this surface.\n\n## Handshake errors {#handshake-errors}\n\nFailures before the WebSocket upgrade are returned as HTTP status codes with a body of:\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | Trigger | Observed message (cn production, 2026-10-08) |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | no API key | `missing api key` |\n| 401 | `unauthorized` | invalid / disabled key | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | model not in catalog | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | model does not advertise `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | no route for the model in the policy (including its fallback chain) | `no route for model <model>` |\n| 503 | `no_provider` | a route exists but no provider instance is available | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | preauthorization failed (balance / budget) | `billing: insufficient funds` |\n\nAfter a successful upgrade (HTTP 101), later problems are delivered as an in-band `error` event, then the connection closes:\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## Session configuration `session.update`\n\nAfter connecting, the server first sends `session.created`; the client overrides with `session.update`, and a valid update is acknowledged with `session.updated`. Common fields:\n\n| Field | Values | Default |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | see Bailian's voice list | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | server VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | any text | empty |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | enabled |\n\n`turn_detection: null` disables the server VAD so the client commits and triggers responses manually.\n\n## Client events\n\n| Event | Purpose |\n| --- | --- |\n| `session.update` | Update session config (modalities, voice, audio format, VAD, instructions, …) |\n| `input_audio_buffer.append` | Append Base64 audio to the input buffer |\n| `input_image_buffer.append` | Append a Base64 image (JPG/JPEG; audio must have been sent first) |\n| `input_audio_buffer.commit` | Commit the audio buffer in manual mode (does not trigger a response) |\n| `input_audio_buffer.clear` | Clear the audio buffer |\n| `conversation.item.create` | Create an item: plain text input, `function_call_output`, `mcp_approval_response` |\n| `response.create` | Trigger one model response |\n| `response.cancel` | Cancel the in-progress response (interruption) |\n\n## Server events\n\n| Event | Meaning |\n| --- | --- |\n| `session.created` / `session.updated` | Session created / config applied |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD detected the user starting / stopping (interruption trigger) |\n| `input_audio_buffer.committed` / `cleared` | Audio buffer committed / cleared |\n| `conversation.item.created` | An item was created |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | Input speech transcription (streaming preview / final) |\n| `response.created` | A response turn began |\n| `response.output_item.added` / `response.content_part.added` | Output item / content part began |\n| `response.text.delta` / `response.text.done` | Text-only streaming / full text |\n| `response.audio_transcript.delta` / `.done` | Transcript of the audio output |\n| `response.audio.delta` / `response.audio.done` | Base64 output audio (24 kHz PCM) / end of audio |\n| `response.output_item.done` / `response.content_part.done` | Output item / content part completed |\n| `response.done` | Response turn ended; `response.usage` carries per-modality token usage |\n\nTool-calling events (`response.function_call_arguments.delta` / `.done`) and the MCP events (`mcp_*`) are documented in Bailian's server-events reference.\n\nObserved event order for one voice turn (cn production, 2026-10-08):\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## Audio formats\n\n| Direction | Format | Field |\n| --- | --- | --- |\n| Uplink (input) | 16000 Hz, 16-bit little-endian, mono PCM, Base64 | `audio` of `input_audio_buffer.append` |\n| Downlink (output) | 24000 Hz, 16-bit little-endian, mono PCM, Base64 | `delta` of `response.audio.delta` |\n\nSending input audio in full 100 ms frames (3200 bytes per frame) proved most reliable. `input_audio_buffer.append` only buffers; whether it is committed is decided by VAD or by a client `input_audio_buffer.commit`.\n\n## VAD and interruption\n\n- With a non-`null` `turn_detection`, the server auto-detects speech boundaries and, after `silence_duration_ms` of silence (default 800 ms), auto-commits and triggers a response.\n- When the user speaks again: the server emits `input_audio_buffer.speech_started` → the client **stops playback** and sends `response.cancel` → `response.done` (cancelled) arrives → a new turn begins.\n- `turn_detection: null` is manual mode: after recording, the client sends `input_audio_buffer.commit` (wait for `input_audio_buffer.committed`) then `response.create`.\n\n## Usage and billing\n\nEach turn's `response.done.response.usage` carries per-modality tokens:\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\nThe gateway settles the accumulated session usage at close: a session-level estimate is held at connect (currently about ¥1.2; insufficient balance fails the handshake with `402`), then refund/top-up applies based on actual usage; a session with no usage releases the hold. See the [guide](./guide#billing).\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Upstream rate limit | 60 RPM |\n\n## Related\n\n- [Realtime (WebSocket) models guide](./guide)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","china/en/models/realtime/guide.md":"---\ntitle: Realtime (WebSocket) models\ndescription: Call Qwen-Omni-Realtime over WebSocket for live voice chat, interruption, and omni-modal input.\n---\n\n# Realtime (WebSocket) models\n\nRealtime models do **not** use `/v1/chat/completions`; they are called over a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol **verbatim in both directions** — there is no protocol translation: you send Bailian events and receive Bailian events. This page covers connection, a runnable minimal example, and billing; the exact event and error schema is in the [API reference](./api).\n\n## What it does\n\n- **Live voice chat**: speak and get streamed text and audio back as you go.\n- **Interruption**: when the user speaks again the server emits `input_audio_buffer.speech_started`; the client stops playback and sends `response.cancel` to interrupt the current reply.\n- **Omni-modal input**: streaming audio, images (frames sampled from video), and plain text.\n- **Text + audio output**: the model produces both text and speech.\n\n## Supported models\n\nA logical model can use this surface only if its catalog `public_protocols` includes `dashscope_realtime`. The realtime model currently available is `qwen3.8-omni-flash-realtime` (check the marketplace for what is actually listed). Check the model marketplace at [{{ console_endpoint }}]({{ console_endpoint }}) to confirm whether a model offers this protocol.\n\n## Connecting\n\n| Item | Value |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<logical model>` (required) |\n| Auth | `Authorization: Bearer <mgk_ API Key>` |\n| Request ID | optional `X-Request-ID`; the call-log `request_id` starts with `gw_rt_` |\n\nHandshake failures are returned as HTTP status codes (e.g. an invalid key is `401 unauthorized`, a model without the realtime protocol is `403 model_protocol_not_offered`, insufficient balance is `402`); see the full list in the [API reference](./api#handshake-errors).\n\n## Minimal example\n\nThe examples below run **server-side**: connect with an `mgk_` API key, configure the session, push 16 kHz PCM audio, commit, request a reply, and write the returned 24 kHz PCM to `reply.pcm`.\n\n:::note\n- A browser's native `WebSocket` constructor **cannot set an `Authorization` header**, so the API key must not be placed in a browser connection.\n- For browser microphone capture, relay through your own server (which holds the key and opens the connection), or use an authenticated server-side proxy.\n- The Python / Node.js examples below are server-side and run as-is.\n:::\n\nPrepare input: capture the microphone, or save 16 kHz, 16-bit little-endian, mono, **headerless** PCM as `input.pcm`. If you have a WAV, extract the raw PCM first:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython (`pip install websocket-client`):\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js (`npm install ws`):\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\nWrap the returned `reply.pcm` (24 kHz, 16-bit, mono) into a playable WAV:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\nTo smoke-test connectivity without audio, send one `conversation.item.create` with an `input_text` content item, then `response.create`, to get a text-only reply.\n\n## Session configuration\n\nRight after connecting, the server sends `session.created` (with defaults); the client overrides with `session.update`. Common fields:\n\n| Field | Meaning |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` (default) or `[\"text\"]` |\n| `voice` | output voice, default `Tina`; prefer `audio.output.voice` |\n| `turn_detection` | server VAD: `{\"type\":\"server_vad\"}` or `{\"type\":\"semantic_vad\"}`; `null` = client-side manual commit |\n| `audio.input.format` | input format, e.g. `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | output format, e.g. `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | system persona |\n| `audio.input.transcription` | input transcription; the server enables it automatically (model `qwen3-asr-flash-realtime`) |\n\nThe legacy `input_audio_format` / `output_audio_format` fields still work, but new integrations should use `audio.input.format` / `audio.output.format`.\n\n## Interruption\n\nWith a non-`null` `turn_detection`, the server VAD drives turns. When the user speaks again:\n\n1. the server emits `input_audio_buffer.speech_started`;\n2. the client **stops playing** buffered reply audio and sends `response.cancel`;\n3. the server then emits `response.done` (status cancelled) and starts a new turn.\n\nIn manual mode (`turn_detection: null`) the client sends `input_audio_buffer.commit` and `response.create` after recording.\n\n## Billing {#billing}\n\n- **Token-based, per modality**: input is split into text/image/video and audio; output into text and audio. When the model produces speech, the audio **and** its transcript text are billed separately.\n- **Preauthorization at connect**: a session-level estimate is held when the connection opens (currently about ¥1.2). If the balance cannot cover it, the handshake returns `402` and no connection is established.\n- **Settled after close on actual usage**: the total of every `response.done` `usage` over the connection is settled at close — refund or top-up applies. A session that meters nothing releases the hold and charges nothing.\n\nCheck the console model page for current prices; for example, domestic `qwen3.8-omni-flash-realtime` (CNY / million tokens) is priced at input text/image/video `1.5`, input audio `6`, output text `4.5`, output audio `12`.\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced; the socket is closed and settled at the cap) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Audio history | up to 100 turns / 600 s |\n| Video history | up to 50 turns / 240 s |\n| Upstream rate limit | 60 RPM |\n\n## Next steps\n\n- [API reference: `GET /api-ws/v1/realtime`](./api)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","china/en/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: Re-order candidate documents by relevance to a query.\n---\n\n# Rerank\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | Re-rank documents by relevance to a query |\n| `POST` | `/v1/reranks` | Alias, equivalent to `/v1/rerank` |\n\nThe Rerank endpoint takes a query and a set of candidate documents and returns them ordered by relevance. It is commonly used for the re-ranking stage in retrieval-augmented (RAG) pipelines. `/v1/rerank` and `/v1/reranks` are two equivalent paths to the same capability.\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"Which protocols does ModelGo support\",\n    \"documents\":[\n      \"OpenAI and Anthropic compatible protocols\",\n      \"The weather is nice today\",\n      \"Supports image, video, vector, and audio capabilities\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## Key conventions\n\n- `model` must be the platform logical model name; the body is forwarded per the upstream Rerank protocol, and whether specific fields (e.g. `top_n`, `return_documents`) take effect depends on the routed upstream model.\n- The response typically contains a relevance score and rank index for each document.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","china/en/models/text/generation.md":"---\ntitle: Text Generation\ndescription: Unified guidance for OpenAI Responses, Chat Completions compatibility, and Anthropic Messages.\n---\n\n# Text Generation\n\nThe gateway exposes the following public text entrypoints. Prefer `POST /v1/responses` for new integrations, and use the others for SDK compatibility or native Claude clients.\n\n| Protocol | Method and path | Use |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | Preferred unified text generation API for new projects |\n| OpenAI | `POST /v1/chat/completions` | Widely compatible chat completion endpoint |\n| OpenAI | `POST /v1/completions` | Legacy text completions, only for compatibility |\n| Anthropic | `POST /v1/messages` | Claude native message format |\n| OpenAI | `GET /v1/models` | List logical models available under the current routing |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"Introduce ModelGo in three sentences.\"\n  }'\n```\n\nUse this entrypoint when you want a single OpenAI-compatible response API with a forward-looking request shape.\n\n## OpenAI Chat Completions compatibility {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this for existing OpenAI SDK flows that still depend on chat completions. New projects should usually start from `POST /v1/responses`.\n\n## OpenAI Completions (legacy)\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"Introduce ModelGo in three sentences.\",\n    \"max_tokens\":256\n  }'\n```\n\nThe legacy text-completions endpoint, only for call chains that still use a `prompt`. New projects should use Responses or Chat Completions above. `stream` is likewise delivered over SSE. Most current chat models do not offer this protocol: `qwen3.6-flash` returned HTTP 400 `model_protocol_not_offered` on 2026-09-10.\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this when the client already speaks Claude's native `/v1/messages` schema. The gateway preserves the native event-stream framing for streamed Anthropic responses.\n\n## Listing models\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` returns the logical models allowed by the API key's bound policy (resolved against the platform model catalog). It does not probe upstream capabilities at request time and may differ from the console; billing and policy follow the console and bound policies.\n\n## Key conventions\n\n- `model` must be the platform logical model name.\n- `GET /v1/models` is available; the list is derived from the API key's bound policy and the platform model catalog.\n- Both OpenAI and Anthropic style endpoints may return upstream-native `usage`.\n- Stream failures may arrive as error chunks; do not rely only on `data: [DONE]`.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","china/en/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI-compatible embedding endpoint.\n---\n\n# Embeddings\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Multimodal (image/text) embeddings |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` may be a single string or an array of strings. The response follows the OpenAI-compatible embeddings shape.\n\n## Multimodal embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\nFor embedding inputs that mix text and image content. The `input` shape depends on the routed model's multimodal capabilities; whether it takes effect is determined by the upstream model.\n","china/en/models/video/ark.md":"---\ntitle: Seedance Video Inbound Protocol\ndescription: Drive platform-managed async Seedance video tasks over Ark's own paths, with Ark-shaped request and response bodies.\n---\n\n# Seedance Video Inbound Protocol\n\nBeyond the standard video protocols, the Doubao Seedance series (`doubao-seedance-*`) can also be\ncalled over **Volcengine Ark's own paths**, with request and response bodies following Ark's\ncontent-generation protocol:\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | Create a content generation (video) task |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Poll task status and result |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent**, see below) |\n\nThis is a **platform-managed** lane: the path is Ark's own, but the request runs on the gateway's\nstandard async task pipeline — the very same one behind\n[Generic Async Content Generation Tasks](./async-tasks), just spelled with Ark's path. It therefore\nkeeps per-dimension metering, task persistence, artifact delivery, and preauthorize/settle intact.\n\n## Create a task\n\nThe body follows Ark's content-generation protocol, and `model` is the **platform logical model\nname** (e.g. `doubao-seedance-2.0-mini`):\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a neon city cat\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" } }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\nValid values for `resolution` / `ratio` / `duration` **vary by model** — the Fast and Mini variants of\nSeedance 2.0, for instance, do not support `1080p`, and `duration` has a floor of 4 seconds. Follow the\ncapability notes for the model you are calling; out-of-range values are rejected at create time.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll answer with exactly the Ark task object documented under\n[Generic Async Content Generation Tasks](./async-tasks) — it is the same pipeline, so the response\npayload and every field's meaning (`status` values, `content.video_url`, `error`, when `usage` is\nomitted) are identical to that page and are not repeated here.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nA successful cancel voids the preauthorization; nothing is settled.\n\n**Not every upstream supports cancelling, though.** Whether a task can be cancelled depends on\nwhether the supplier serving it implements cancellation, and because this lane does not pin an\nupstream family, two calls on the same logical model may differ — one cancellable, one not. Two\nfailure shapes:\n\n| Case | Response |\n| --- | --- |\n| The supplier serving the task cannot cancel | `400` / `4003` `provider_unsupported`, `endpoint not supported by provider` |\n| The task already reached a terminal state (`succeeded` / `failed`) | `409` `task_already_terminal`, `task already finished; nothing to cancel` |\n\nWhen a cancel fails the preauthorization is not released early — it follows the normal\nsettle/expiry path once the task reaches a terminal state. So **do not treat \"create then cancel\"\nas a reliable way to back out of a charge.**\n\n## Key conventions\n\n- **`id` is the gateway task id, not the upstream one.** Polling and cancelling only accept that id,\n  so hold on to the `id` returned by create.\n- **The response shape is fixed.** Whichever upstream actually serves the request, create and poll\n  both answer with the same Ark task object — it does not change when routing changes.\n- **The lane does not pin an upstream family.** The URL spelling plays no part in routing: whoever\n  the logical model behind `model` routes to serves it. Seedance is carried by several suppliers on\n  the platform, so two calls on the same logical model may land on different upstreams — that is\n  expected.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the Ark paths — use `content.video_url` from the response.\n- Whether a model is offered on this lane depends on its catalog `public_protocols` including\n  `content_generation`; without it the call is refused with `4005`. Check with\n  `GET {{ api_endpoint }}/v1/models`.\n\nIf you do not need Ark's path and field style, [OpenAI-Compatible Video Flow](./openai-compatible) is\nthe more standardized choice.\n","china/en/models/video/async-tasks.md":"---\ntitle: Generic Async Content Generation Tasks\ndescription: A platform-managed async task entrypoint for image, video, and other content generation capabilities.\n---\n\n# Generic Async Content Generation Tasks\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | Create a generic async content generation task (image / video / ...) |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | Poll a generic content generation task |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent** — see \"Cancel a task\" in [Seedance Video Inbound Protocol](./ark)) |\n\n`/v1/content_generation/tasks` is a more general async task entrypoint than the standard OpenAI-compatible video flow. It covers image, video, and other generation capabilities that must run as backend tasks.\n\n## Create a task\n\nThe body follows the upstream generic generation shape and must include at least `model`:\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\nVerified 2026-09-10 on domestic production: create returned `status=queued` with a `gw_…` id; polling the same id ended at `succeeded` with `resolution=720p`, `ratio=16:9`, `duration=5`. The same model on `POST /v1/video/generations` is `model_protocol_not_offered`. `DELETE` cancel returned `provider_unsupported` on that upstream.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll both answer with the **same** Ark-shaped task object, regardless of which upstream served the request:\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` is one of `queued` / `running` / `succeeded` / `failed`; `id` is the **gateway task id**, and it is the only id polling and cancelling accept.\n\n## Three spellings, one pipeline\n\nThe same managed async pipeline has three inbound spellings. Which one you pick depends only on whose payload style you want to write your client against:\n\n| Entry point | Request body | Response body |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | Generic generation shape | Ark task object (above) |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark content-generation native body | Ark task object |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax video-generation V2 native body | MiniMax shapes (`{\"task_id\"}` / `{\"task\":{…}}`) |\n\nBilling, task persistence, artifact delivery, and preauthorize/settle behave identically across all three.\n\n## When to use it\n\n- The platform capability is asynchronous but does not use the OpenAI Video-standard request / response shape\n- You want a unified platform-managed create-and-poll flow instead of handling each vendor's native protocol yourself\n- You are calling a video model such as Jimeng that is exposed only through the managed async lane\n\n## Key conventions\n\n- `model` is still the platform logical model name; the platform decides which upstream implementation handles the task.\n- Request fields depend on the routed capability; the response shape, by contrast, is fixed — see above.\n- If you do not want to manage multiple vendor-specific polling styles, prefer this entrypoint.\n\nFor the standard OpenAI-compatible video protocol, see [OpenAI-Compatible Video Flow](./openai-compatible).\n","china/en/models/video/kling-v3.md":"---\ntitle: Kling 3.0 (kling-v3) Text / Image to Video (Kling native protocol)\ndescription: Call kling-v3 on Kling's official API — text2video / image2video, mode tiers, the sound switch, polling, download and billing. Kling's official SDK works by changing the host.\n---\n\n# Kling 3.0 (kling-v3) Text / Image to Video (Kling native protocol)\n\n| Endpoint | Capability | Required fields |\n| --- | --- | --- |\n| `POST /kling/v1/videos/text2video` | Text to video | `model_name`, `prompt` |\n| `POST /kling/v1/videos/image2video` | Image to video (first frame, optional last frame) | `model_name`, `prompt`, `image` |\n\nModelGo accepts Kling's official API paths and request/response shapes (`model_name`, `mode`, `sound`, `duration`, `aspect_ratio`, …); the gateway routes to a supplier and bills. Which supplier renders the clip is invisible to the caller. Polling follows the official rule: **the same path + `/{task_id}`**.\n\n> With Kling's official SDK or samples, replace the API host with `{{ api_endpoint }}/kling` and authenticate with `Authorization: Bearer $MODELGO_API_KEY` (no Kling JWT signing).\n\n## 1. Create a task\n\n### Text to video\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\",\n    \"mode\": \"std\",\n    \"duration\": \"5\",\n    \"aspect_ratio\": \"16:9\",\n    \"sound\": \"on\",\n    \"cfg_scale\": 0.5\n  }'\n```\n\n### Image to video\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/image2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"The dog slowly turns its head\",\n    \"image\": \"https://example-cdn.com/dog.jpg\",\n    \"mode\": \"pro\",\n    \"duration\": \"5\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"task_status\": \"submitted\", \"created_at\": 1788773081000, \"updated_at\": 1788773081000}\n}\n```\n\n`data.task_id` is the gateway task id; use it to poll and to fetch content.\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model_name` | string | all | Always `kling-v3` |\n| `prompt` | string | all | Required on text2video; optional on image2video (as in the official API). ≤ 2500 chars |\n| `image` | string | image2video | Required. **Publicly downloadable** URL of the first frame. A text2video request must not carry `image` / `image_tail` (it is refused rather than silently treated as text-to-video) |\n| `image_tail` | string | image2video | Last-frame image URL |\n| `mode` | string | all | Tier: `std` (720P), `pro` (1080P) or `4k`, **default `pro`** |\n| `duration` | string / int | all | Whole seconds, 3–15, default `5` |\n| `aspect_ratio` | string | text2video | `16:9` / `9:16` / `1:1`, default `16:9`; image to video follows the first frame |\n| `sound` | string | all | `on` / `off`, default `off`. **Switches to the with-audio price tier** |\n| `negative_prompt` | string | all | Negative prompt |\n| `cfg_scale` | number | all | Prompt adherence in [0, 1], default 0.5 |\n| `callback_url` / `external_task_id` | string | all | Accepted but inert: the gateway does not call back; poll by `task_id` |\n\n### Tiers\n\n| `mode` | Output |\n| --- | --- |\n| `std` | 1280×720 (per aspect ratio) |\n| `pro` | 1920×1080 (per aspect ratio), default |\n| `4k` | 4K (per aspect ratio), served only by suppliers that render it; priced separately |\n\n- **Only these three tiers are offered.** Any other value is refused at create time (HTTP `400`). The gateway routes by deliverable tier: a `4k` request only goes to a supplier that renders 4K and is never downgraded silently; if no 4K-capable supplier is available the create returns `400` and nothing is charged.\n\n### First-frame image requirements (image2video)\n\n- A direct link the upstream can `GET`; JPG / PNG, ≤ 10 MB, each side ≥ 300 px, aspect 1:2.5–2.5:1.\n- A frame the upstream cannot fetch fails the task (`task_status=failed`) without billing. Use your own object storage or CDN.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/kling/v1/videos/text2video/{task_id}` (tasks created via image2video poll at `.../image2video/{task_id}`)\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video/gw_6dce033e-9243-4a64-9c57-73d08a8e379a \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"succeed\",\n    \"task_result\": {\"videos\": [{\"id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"url\": \"{{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content\", \"duration\": \"6\"}]},\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773250000\n  }\n}\n```\n\n- `task_status`: `submitted` → `processing` → `succeed` / `failed`. On failure `task_status_msg` carries the reason and the task is **not billed**.\n- Generation usually takes 1–3 minutes; poll every 5–10 s with backoff.\n- `videos[].url` points at the gateway content endpoint (API key required); `duration` is the delivered length in seconds.\n\n## 4. Download the video\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o kling.mp4\n```\n\nStreams `video/mp4`, `Range` supported. Only the owning API key (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}/kling/v1/videos\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\"}\n\ndef generate(kind: str, body: dict, out: str, timeout: int = 600) -> None:\n    body.setdefault(\"model_name\", \"kling-v3\")\n    r = requests.post(f\"{BASE}/{kind}\", json=body, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"data\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        data = requests.get(f\"{BASE}/{kind}/{task_id}\", headers=H, timeout=30).json()[\"data\"]\n        if data[\"task_status\"] == \"succeed\":\n            break\n        if data[\"task_status\"] == \"failed\":\n            raise RuntimeError(data.get(\"task_status_msg\", \"generation failed\"))\n        time.sleep(8)\n    url = data[\"task_result\"][\"videos\"][0][\"url\"]\n    with requests.get(url, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"text2video\", {\"prompt\": \"A small red ball rolling across a wooden table\", \"mode\": \"std\", \"duration\": \"5\", \"sound\": \"on\"}, \"t2v.mp4\")\ngenerate(\"image2video\", {\"prompt\": \"The dog slowly turns its head\", \"image\": \"https://example-cdn.com/dog.jpg\", \"mode\": \"pro\", \"duration\": \"5\"}, \"i2v.mp4\")\n```\n\n## 6. Billing\n\n- **Video seconds × unit price**, keyed on three dimensions: input mode (text / image), tier (`std` 720P / `pro` 1080P / `4k`) and audio (`sound`).\n- The requested `duration` is pre-authorized at create time; the task settles on the **delivered** seconds. Some suppliers deliver about one extra second (5 s requested, 6 s delivered); `videos[].duration` is the settled figure.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`failed`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `mode` not `std`/`pro`/`4k`; `sound` not `on`/`off`; `model_name` missing; `prompt` missing on text2video; `image` missing on image2video; `image`/`image_tail` sent to text2video; no supplier renders the requested tier right now | Fix per the parameter table or switch endpoint / tier |\n| `task_status=failed` | Upstream could not fetch the first frame, or generation failed | Use a publicly downloadable direct link |\n| Poll returns `task_not_found` | `task_id` not created by this key, or polled under a different endpoint family | Poll on the same path used to create |\n| `/content` returns `409` / `404` | Not completed / artifact expired | Poll to `succeed`; download promptly |\n","china/en/models/video/minimax.md":"---\ntitle: MiniMax Video Inbound Protocol\ndescription: Drive platform-managed async video tasks with MiniMax video-generation V2 request and response bodies, for the MiniMax-H3 family.\n---\n\n# MiniMax Video Inbound Protocol\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | Create a video generation task |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | Poll task status and result |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | Cancel an unfinished task and release its preauthorization |\n\nThis is **MiniMax video generation V2** as an inbound protocol, aimed mainly at the MiniMax-H3 family.\nLike the Ark lane it runs on the platform-managed async pipeline — the request body is MiniMax's own\nshape, and **the responses are rendered in MiniMax's shape too**, so a client written against\nMiniMax's own documentation can decode this surface directly.\n\nThe task lives on the platform, so per-dimension metering, artifact\ndelivery, and preauthorize/settle all apply as usual.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a boy playing basketball by the sea\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\nCreate answers the bare task handle from MiniMax's documentation:\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### Request fields\n\n`content[]` is a multimodal array; `type` and `role` together decide what each part is:\n\n| `type` | Valid `role` | Meaning |\n| --- | --- | --- |\n| `text` | — | Prompt |\n| `image_url` | `first_frame` / `last_frame` | First / last frame image |\n| `image_url` | `reference_image` | Reference image |\n| `video_url` | `reference_video` | Reference video |\n| `audio_url` | `reference_audio` | Reference audio |\n\n- **Frames and references cannot be mixed**: a request carrying `first_frame` / `last_frame` may not\n  also carry any `reference_*` part, and vice versa — they map to two different upstream jobs.\n- `resolution`, `duration`, and `ratio` are flat siblings of `content`. For MiniMax-H3 the accepted\n  values are `resolution` ∈ `768P` / `2K`, `duration` an integer in `4`–`15`, and `ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`. Omitting one applies the upstream default\n  (`2K`, 5 seconds) — **and bills at that default tier**.\n- Prompt length is capped at roughly 7000 characters.\n- Which values are actually supported still depends on the logical model behind `model`.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nPoll answers a `task` envelope — a **different shape** from create:\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` is one of `queued` / `running` / `succeeded` / `failed`.\n- On success the artifact URL is in `task.content.url`.\n- `usage` is denominated in **seconds** (H3 is quoted per second of output), not tokens; it is\n  omitted when the upstream reports only token counts and no seconds.\n- On failure a `task.error` (`code` / `message`) is added. That field is not part of MiniMax's\n  documented success schema — it is included so a failure reason is visible at all, and a client\n  decoding the documented struct simply ignores it.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCancelling voids the preauthorization. Note that this lane never reports MiniMax's documented\n`cancelled` status — a cancelled task is surfaced as `failed`, which is what makes its\npreauthorization be released rather than settled.\n\n## Key conventions\n\n- **`id` / `task_id` are the gateway task id**, not the upstream one; polling and cancelling only\n  accept that id.\n- The lane does not pin an upstream family; the logical model behind `model` decides who serves the\n  request, and the URL spelling plays no part in it.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the MiniMax paths.\n\nFor the most standardized experience, use [OpenAI-Compatible Video Flow](./openai-compatible).\n","china/en/models/video/openai-compatible.md":"---\ntitle: OpenAI-Compatible Video Flow\ndescription: Standard OpenAI Video-compatible endpoints for task creation, polling, and asset retrieval.\n---\n\n# OpenAI-Compatible Video Flow\n\n> **Video models accept their vendor's official native protocol only**: [Wan 2.7 (DashScope)](./wan27), [Kling 3.0 (Kling)](./kling-v3), [Veo 3.1 (Google)](./veo31). `wan2.7-t2v` / `wan2.7-i2v` / `kling-v3` / `veo-3.1` / `veo-3.1-fast` no longer accept `POST /v1/video/generations` on this page (the gateway answers `400` with `app_error_id=4005 model_protocol_not_offered`). Task polling `GET /v1/videos/{task_id}` and the artifact endpoint `GET /v1/videos/{task_id}/content` keep working for tasks created on the native protocols; the generic async lane is documented under [Async content generation tasks](./async-tasks).\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | Create an OpenAI-compatible video task |\n| `GET` | `/v1/videos/{task_id}` | Poll video task status and result |\n| `GET` | `/v1/videos/{task_id}/content` | Fetch the produced content of a finished video task |\n\nThis set of endpoints is the platform's **standard video protocol**: the request uses OpenAI Video-compatible fields, and the platform translates it into the upstream vendor's async video task format.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\nA successful create returns a `task_id`. Subsequent polling and content fetches are all keyed by that `task_id`.\n\n## Poll task status\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` is one of `queued` / `in_progress` / `completed` / `failed`; on `completed`, the produced asset URL appears in `metadata.url`.\n\n## Fetch the asset\n\nOnce the task is done, you can fetch the asset bytes through the content endpoint. The gateway **streams the `video/mp4` bytes directly** (no `302` redirect to object storage), supports `Range` requests, and only the API key that owns the task (or a console session in the same tenant) may read it:\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\nContent availability depends on the backend \"media delivery\" setting:\n\n- `404` (`content_delivery_disabled`) when delivery is disabled\n- `409` (`task_not_completed`) when the task is still running\n- `404` (`content_not_available`) when the asset has expired or is missing\n\n## Key conventions\n\n- This is the standard OpenAI-compatible video entrypoint; clients do not need to understand vendor-native protocols.\n- Whether fields such as `duration` or `size` are supported, and which upstream vendor is selected, depends on the logical model referenced by `model`.\n- Video generation is asynchronous. Poll with backoff to avoid unnecessary rate-limit pressure.\n\nFor the more generic async task entrypoint, see [Generic Async Content Generation Tasks](./async-tasks). To write against a vendor's own payload style while keeping platform-managed billing and task handling, see the [Seedance Video Inbound Protocol](./ark) and the [MiniMax Video Inbound Protocol](./minimax).\n","china/en/models/video/veo31.md":"---\ntitle: Veo 3.1 / Veo 3.1 Fast Text to Video (Google native protocol)\ndescription: Call veo-3.1 and veo-3.1-fast on the official Google Gemini API Veo protocol — predictLongRunning create, operations polling, download, USD billing. The Google GenAI SDK works by changing base_url.\n---\n\n# Veo 3.1 / Veo 3.1 Fast Text to Video (Google native protocol)\n\n| Official model id (in the path) | Platform model | Positioning |\n| --- | --- | --- |\n| `veo-3.1-generate-preview` | `veo-3.1` | Quality model, native audio |\n| `veo-3.1-fast-generate-preview` | `veo-3.1-fast` | Speed-optimized, lower cost |\n\nModelGo accepts Veo requests on the Google Gemini API **long-running-operation** protocol unchanged: `predictLongRunning` create → `operations` poll → download. The body matches Google's documentation (`instances` + `parameters`); the gateway routes to a supplier and bills.\n\n> With the Google GenAI SDK, set `http_options.base_url` to `{{ api_endpoint }}` and use your ModelGo API key. Both `x-goog-api-key: $KEY` and `Authorization: Bearer $KEY` are accepted.\n\n## 1. Create a task\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:predictLongRunning` (`/v1/models/...` is accepted too)\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"instances\": [{\"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\"}],\n    \"parameters\": {\"aspectRatio\": \"16:9\", \"resolution\": \"1080p\", \"durationSeconds\": 8, \"generateAudio\": true}\n  }'\n```\n\n### Response\n\n```json\n{\"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\", \"done\": false}\n```\n\n`name` is the official operation name; its last segment is the gateway task id. Poll by appending `name` to `/v1beta/`.\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `instances[0].prompt` | string | Required for text-to-video; may be omitted when `image` is given. Scene and motion description |\n| `instances[0].image` | object | First frame (image to video). **URL forms only**: `{\"imageUri\": \"https://...\"}` / `gcsUri`; inline `bytesBase64Encoded` is refused |\n| `instances[0].lastFrame` | object | Last frame, same forms |\n| `parameters.resolution` | string | `720p` or `1080p`, **default `720p`** |\n| `parameters.durationSeconds` | int | `4` / `6` / `8`, default `8`. **1080p requires 8 seconds** |\n| `parameters.aspectRatio` | string | `16:9` or `9:16`, default `16:9` |\n| `parameters.generateAudio` | boolean | Veo 3.1 always generates an audio track; billing does not distinguish audio |\n| `parameters.negativePrompt` | string | Negative prompt |\n| `parameters.seed` | int | Random seed |\n| `parameters.sampleCount` / `numberOfVideos` | int | Must be `1` — one video per task; larger values are refused |\n| `parameters.personGeneration` | string | Passed through |\n\n### Resolution tiers\n\n| Tier | Output |\n| --- | --- |\n| `720p` | 1280×720 (16:9) / 720×1280 (9:16), default |\n| `1080p` | 1920×1080 / 1080×1920 |\n\n- **Only these two tiers are offered.** `4k` is refused at create time (HTTP `400`); nothing is rendered at a lower tier silently and nothing is charged.\n- One video per task; exactly one `instance` is accepted.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/v1beta/{operation.name}`, i.e. `GET /v1beta/models/{model}/operations/{task_id}`\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\",\n  \"done\": true,\n  \"response\": {\n    \"@type\": \"type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse\",\n    \"generateVideoResponse\": {\"generatedSamples\": [{\"video\": {\"uri\": \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\"}}]}\n  }\n}\n```\n\n- `done=false` while running; on failure `done=true` with `error.{code,message}` and the task is **not billed**.\n- An 8-second clip usually takes 1–2 minutes; poll every 5–10 s with backoff.\n- Transient upstream errors surface as `502` at create; not billed, just retry.\n\n## 4. Download the video\n\n`generatedSamples[].video.uri` points at the gateway content endpoint; as with Google's own uri, the API key is required:\n\n```bash\ncurl \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -o veo.mp4\n```\n\nStreams `video/mp4` (with an AAC track), `Range` supported. Only the owning API key (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"x-goog-api-key\": os.environ[\"MODELGO_API_KEY\"]}\n\ndef generate(model: str, prompt: str, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/v1beta/models/{model}:predictLongRunning\",\n                      json={\"instances\": [{\"prompt\": prompt}], \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    name = r.json()[\"name\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(name)\n        op = requests.get(f\"{BASE}/v1beta/{name}\", headers=H, timeout=30).json()\n        if op.get(\"done\"):\n            break\n        time.sleep(8)\n    if \"error\" in op:\n        raise RuntimeError(op[\"error\"][\"message\"])\n    uri = op[\"response\"][\"generateVideoResponse\"][\"generatedSamples\"][0][\"video\"][\"uri\"]\n    with requests.get(uri, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"veo-3.1-fast-generate-preview\", \"A small red ball rolling across a wooden table\",\n         {\"resolution\": \"1080p\", \"durationSeconds\": 8, \"aspectRatio\": \"16:9\"}, \"veo-fast.mp4\")\ngenerate(\"veo-3.1-generate-preview\", \"A cinematic drone shot over a misty forest at dawn\",\n         {\"resolution\": \"720p\", \"durationSeconds\": 4}, \"veo.mp4\")\n```\n\n## 6. Billing\n\n- **Priced in USD**, billed as **video seconds × resolution-tier unit price**, converted to the account currency at the daily rate on settlement.\n- The requested `durationSeconds` are pre-authorized at create time; the task settles on the delivered seconds.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`done=true` + `error`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `resolution` outside 720p / 1080p; `sampleCount` > 1; several `instances`; inline base64 `image` | Fix per the parameter table; use an image URL |\n| Create returns `502` | Transient upstream error | Retry; not billed |\n| Poll returns `task_not_found` | The operation was not created by this key | Check `name` and the key |\n| Download `409` / `404` | Not completed / artifact expired | Poll to `done=true`; download promptly |\n","china/en/models/video/wan27.md":"---\ntitle: Wan 2.7 Text / Image to Video (DashScope native protocol)\ndescription: Call wan2.7-t2v / wan2.7-i2v on Alibaba Bailian's official DashScope video-synthesis API — create, poll, download, billing. The official DashScope SDK works by changing base_url.\n---\n\n# Wan 2.7 Text / Image to Video (DashScope native protocol)\n\n| Model | Capability | Required fields |\n| --- | --- | --- |\n| `wan2.7-t2v` | Text to video | `input.prompt` |\n| `wan2.7-i2v` | Image to video (first frame, optional last frame) | `input.prompt`, `input.img_url` |\n\nWan 2.7's official protocol is Alibaba Bailian's **DashScope asynchronous video synthesis** API. The ModelGo gateway accepts the official paths and request/response shapes unchanged: **create → poll → fetch content**. Which supplier renders the clip is a routing decision inside the gateway and invisible to the caller.\n\n> With the official DashScope SDK, point `base_url` (`DASHSCOPE_HTTP_BASE_URL`) at `{{ api_endpoint }}` and use your ModelGo API key as `api_key`.\n\n## 1. Create a task\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis`\n\nHeaders: `Authorization: Bearer $MODELGO_API_KEY`, `X-DashScope-Async: enable`, `Content-Type: application/json`.\n\n### Text to video\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-t2v\",\n    \"input\": {\"prompt\": \"A fluffy orange kitten playing with a ball of yarn on a sunny windowsill\"},\n    \"parameters\": {\"resolution\": \"1080P\", \"duration\": 5, \"prompt_extend\": true}\n  }'\n```\n\n### Image to video\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-i2v\",\n    \"input\": {\"prompt\": \"The cat slowly tilts its head and blinks\", \"img_url\": \"https://example-cdn.com/cat.jpg\"},\n    \"parameters\": {\"resolution\": \"720P\", \"duration\": 5}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\", \"task_status\": \"PENDING\", \"submit_time\": \"2026-09-07 17:05:59.000\"},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n`output.task_id` is the gateway task id; use it to poll and to fetch content.\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model` | string | all | `wan2.7-t2v` or `wan2.7-i2v` |\n| `input.prompt` | string | all | Required. Scene and motion description |\n| `input.img_url` | string | i2v | Required. **Publicly downloadable** URL of the first frame. A `wan2.7-t2v` request must not carry `img_url` / `last_frame_url` (it is refused rather than silently treated as text-to-video) |\n| `input.last_frame_url` | string | i2v | Last-frame image URL for first/last-frame interpolation |\n| `input.audio_url` | string | all | Driving audio URL (wav/mp3) |\n| `input.negative_prompt` | string | all | Negative prompt |\n| `parameters.resolution` | string | all | Tier `720P` / `1080P`, default `1080P` |\n| `parameters.size` | string | t2v | Pixel spelling of the same tier, e.g. `1280*720`, `1920*1080` |\n| `parameters.duration` | int | all | Duration in seconds, default `5` |\n| `parameters.prompt_extend` | boolean | all | Let the upstream rewrite the prompt |\n| `parameters.watermark` | boolean | all | Add a watermark |\n| `parameters.seed` | int | all | Random seed |\n| `parameters.audio` | boolean | all | Generate audio |\n\n### Resolution tiers\n\n| Tier | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 |\n| --- | --- | --- | --- | --- | --- |\n| 720P | `1280*720` | `720*1280` | `960*960` | `1088*832` | `832*1088` |\n| 1080P | `1920*1080` | `1080*1920` | `1440*1440` | `1632*1248` | `1248*1632` |\n\n- **Only 720P / 1080P are offered.** `4K` or a `size` outside the table is refused at create time (HTTP `400`); nothing is rendered at a lower tier silently and nothing is charged.\n- **Routed by deliverable tier.** The gateway only hands a request to a supplier that renders the stated tier (for example `wan2.7-t2v` at 720P is currently rendered by the official Bailian lane only); no supplier renders 1080P in its place while 720P is billed. If no supplier can render the tier right now the create returns `400` and nothing is charged.\n- `input` keys not in the table above (e.g. `first_clip_url`, `ref_images_url`) are not supported on this endpoint and are refused rather than ignored.\n\n### First-frame image requirements (i2v)\n\n- A direct link the upstream can `GET`: no auth, no redirects, no Referer / Cookie dependency.\n- Some hosts return 403 to non-browser fetches; the task then fails (`task_status=FAILED`) and is not billed. Use your own object storage or CDN.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/api/v1/tasks/{task_id}`\n\n```bash\ncurl {{ api_endpoint }}/api/v1/tasks/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"output\": {\n    \"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\",\n    \"task_status\": \"SUCCEEDED\",\n    \"submit_time\": \"2026-09-07 17:05:59.000\",\n    \"end_time\": \"2026-09-07 17:09:06.000\",\n    \"video_url\": \"{{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content\"\n  },\n  \"usage\": {\"video_duration\": 6, \"video_count\": 1},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n- `task_status`: `PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`. On failure `output.code` / `output.message` carry the reason and the task is **not billed**.\n- Generation usually takes 1–3 minutes; poll every 5–10 s with backoff.\n- `output.video_url` points at the gateway content endpoint and requires the API key. Do not persist it; artifacts have a retention period.\n\n## 4. Download the video\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o cat.mp4\n```\n\nStreams `video/mp4`, `Range` supported. Only the API key that owns the task (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python, SDK style)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\", \"X-DashScope-Async\": \"enable\"}\n\ndef synthesize(model: str, inp: dict, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/api/v1/services/aigc/video-generation/video-synthesis\",\n                      json={\"model\": model, \"input\": inp, \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"output\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        o = requests.get(f\"{BASE}/api/v1/tasks/{task_id}\", headers=H, timeout=30).json()[\"output\"]\n        if o[\"task_status\"] == \"SUCCEEDED\":\n            break\n        if o[\"task_status\"] == \"FAILED\":\n            raise RuntimeError(o.get(\"message\") or o.get(\"code\"))\n        time.sleep(8)\n    with requests.get(o[\"video_url\"], headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\nsynthesize(\"wan2.7-t2v\", {\"prompt\": \"A fluffy orange kitten playing with yarn\"}, {\"resolution\": \"1080P\", \"duration\": 5}, \"t2v.mp4\")\nsynthesize(\"wan2.7-i2v\", {\"prompt\": \"The cat slowly tilts its head and blinks\", \"img_url\": \"https://example-cdn.com/cat.jpg\"}, {\"resolution\": \"720P\", \"duration\": 5}, \"i2v.mp4\")\n```\n\n## 6. Billing\n\n- **Video seconds × resolution-tier unit price.** The requested `duration` is pre-authorized at create time; the task settles on the **delivered** seconds (`usage.video_duration`). The upstream may deliver one extra second (5 s requested, 6 s delivered) — 6 s are billed.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`FAILED`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `resolution` / `size` outside 720P / 1080P; `input.prompt` missing; `input.img_url` missing on i2v; `input.img_url` / `input.last_frame_url` sent with a t2v model (use `wan2.7-i2v`); unsupported `input` key; no supplier renders the requested tier right now | Fix per the parameter table or switch model / tier |\n| `task_status=FAILED` | Upstream could not fetch `img_url`, or generation failed | Use a publicly downloadable direct link |\n| Poll returns `task_not_found` | `task_id` was not created by this key | Check `task_id` and the key |\n| `/content` returns `409` / `404` | Not completed / artifact expired | Poll to `SUCCEEDED`; download promptly |\n","china/en/quickstart/agent-clients.md":"---\ntitle: AI Tool Setup\ndescription: Choose an AI client or Agent and use it with ModelGo models.\n---\n\n# AI Tool Setup\n\nModelGo supports common AI coding clients and Agents. After you create an API key, use the official configuration tool for one-click setup; clients not covered by that tool can be configured manually through a custom provider.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\nSelect one or more tools when prompted. To configure every supported tool in an automated workflow, use:\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n## Supported AI tools\n\n:::agent-tools\n| Tool | Official config tool | Manual setup docs |\n| --- | --- | --- |\n| Hermes Agent | Supported | [Setup guide](../agents/hermes-agent) |\n| Claude Code | Supported | [Setup guide](../agents/claude-code) |\n| Kilo Code | Not supported | [Setup guide](../agents/kilo-code) |\n| Cline | Not supported | [Setup guide](../agents/cline) |\n| Codex | Supported | [Setup guide](../agents/codex) |\n| OpenClaw | Supported | [Setup guide](../agents/openclaw) |\n| DeepSeek Harness | Not supported | [Setup guide](../agents/deepseek-harness) |\n| ZCode | Not supported | [Setup guide](../agents/zcode) |\n| Cursor | Not supported | [Setup guide](../agents/cursor) |\n| OpenCode | Supported | [Setup guide](../agents/opencode) |\n| CC Switch | Supported | [Setup guide](../agents/cc-switch) |\n| Cherry Studio | Not supported | [Setup guide](../agents/cherry-studio) |\n| Crush | Supported | [Setup guide](../agents/crush) |\n| Factory Droid | Supported | [Setup guide](../agents/factory-droid) |\n| Copilot CLI | Supported | [Setup guide](../agents/copilot-cli) |\n| nanobot | Supported | [Setup guide](../agents/nanobot) |\n| Oh My Pi | Supported | [Setup guide](../agents/oh-my-pi) |\n| CodeBuddy | Supported | [Setup guide](../agents/codebuddy) |\n| Kilo CLI | Not supported | [Setup guide](../agents/kilo-cli) |\n:::\n\n## Before you connect\n\n1. Create an API key in the [console]({{ console_endpoint }}/api-keys).\n2. Run the command above and select the clients or Agents you want to configure.\n3. Confirm the site, Base URL, and masked API key when prompted. The configuration tool verifies the connection automatically.\n\nTo manage your ModelGo account, models, calls, and Skills from the terminal, continue to [CLI Tools](cli).\n\n## Integration guide\n\nMost tools only need the following information to connect to ModelGo:\n\n1. **API address**: Use `{{ api_endpoint }}/v1` for OpenAI-compatible APIs, or `{{ api_endpoint }}` for Anthropic-compatible APIs.\n2. **API key**: The token created in [ModelGo Console]({{ console_endpoint }}/api-keys).\n3. **Model name**: The logical model ID selected from the [Model Catalog]({{ site_endpoint }}/models).\n\nSee the setup guide for each tool above for the exact configuration steps.\n","china/en/quickstart/authentication.md":"---\ntitle: Authentication\ndescription: API key handling, supported headers, precedence, and common auth failures.\n---\n\n# Authentication\n\nAll model endpoints authenticate with an API key.\n\n## Recommended header\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic-style clients may also use:\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini-style clients may also use:\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nWhen several are present, precedence is `Authorization` > `x-api-key` > `x-goog-api-key`.\n\n## Get & manage\n\n- Console: `{{ console_endpoint }}`\n- An API key is shown in full only once, at creation time\n- Revoking or disabling a key takes effect after the auth cache expires\n\n## Common failures\n\n| HTTP | error_class | Meaning |\n| --- | --- | --- |\n| `401` | `auth` | Missing, invalid, disabled, or expired API key |\n| `403` | `policy` | Key is valid but not allowed to call the model |\n\nSee [Errors & Rate Limits](errors) for the unified error shape.\n","china/en/quickstart/cli.md":"---\ntitle: CLI Tools\ndescription: Choose the official command-line tool for your task and complete your ModelGo setup.\n---\n\n# CLI Tools\n\nModelGo provides two official command-line tools. Choose the task you want to complete and run the corresponding command.\n\n:::tools\n@model-go/config | Connect AI coding clients | Configure Claude Code, Codex, and other common clients with one command. | npx @model-go/config -r {{ region_flag }} | View npm package | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | Use the official CLI | Pair it with official ModelGo Skills so an AI agent can operate ModelGo directly. | npx @model-go/cli@latest install | View npm package | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## Connect AI coding clients `@model-go/config` {#connect-ai-clients}\n\nTo use ModelGo in Claude Code, Codex, OpenCode, or another supported AI coding client, choose guided setup or configure all clients with a single command.\n\n**Guided setup**\n\nFollow the terminal prompts to enter your API key, select clients, review the configuration, and verify connectivity after the changes are written.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**One-command setup (non-interactive, suitable for automation)**\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n### Supported clients\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\nGuided setup lets you select one or more clients; use `--only all` to configure every supported client at once.\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Enter your [ModelGo API key]({{ console_endpoint }}/api-keys). |\n| `02` | Select one or more clients, or choose “Configure all.” |\n| `03` | Review the site, Base URL, masked API key, and selected clients. |\n| `04` | Confirm the changes, write the client configuration, and verify connectivity. |\n\n> **Setup succeeded:** the terminal reports that configuration is complete and the connectivity check passes, then shows how to start the selected client.\n\n[View @model-go/config on npm](https://www.npmjs.com/package/@model-go/config)\n\n## Let an AI agent operate ModelGo `@model-go/cli` {#install-agent-tools}\n\nInstall the official CLI and ModelGo Skills when you want an agent such as Claude Code or Codex to use ModelGo directly. The installer sets up the CLI, distributes Skills, selects the site, and optionally signs you in.\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Confirm installation of `@model-go/cli` when npm asks. |\n| `02` | Choose Simplified Chinese or English. The rest of the installation prompts will use your selected language. |\n| `03` | Install or upgrade the ModelGo CLI and install ModelGo Skills. |\n| `04` | Select the environment for this site (`{{ api_endpoint }}`). |\n| `05` | Choose whether to sign in through the browser now, or skip and run `modelgo auth login` later. |\n\n### Using the CLI after installation\n\nAfter installation, restart your AI agent or open a new session. ModelGo Skills lets the agent call the ModelGo CLI directly to perform queries and operations, so you can ask in natural language, for example:\n\n- “Which models does ModelGo currently support?”\n- “What is my current ModelGo account balance?”\n\nTo use the CLI yourself, run `modelgo` in your terminal to see every available command and option:\n\n```bash\nmodelgo\n```\n\nThe most common commands are grouped by task:\n\n| Task | Common commands | What they do |\n| --- | --- | --- |\n| Authentication | `modelgo auth login`, `modelgo auth status`, `modelgo auth logout` | Sign in to ModelGo, inspect the current authentication state, or clear local credentials. |\n| Environments | `modelgo env list`, `modelgo env current`, `modelgo env use <name>` | List environments, show the active environment, or switch sites. Use `env add` and `env remove` to manage custom environments. |\n| Workspaces | `modelgo tenant list`, `modelgo tenant use <slug>` | List the workspaces available to your account and use a workspace slug or ID to select the workspace for subsequent CLI commands. |\n| Account and usage | `modelgo balance`, `modelgo permissions`, `modelgo logs` | View balances and transactions, account permissions, call logs, and usage statistics. |\n| Model calls | `modelgo models`, `modelgo chat`, `modelgo embeddings`, `modelgo call` | List available models, make chat or embedding requests, or call any `/v1/*` model endpoint directly. |\n| Keys and payments | `modelgo key`, `modelgo pay` | Manage the model API key stored for the active environment or configure x402 pay-per-call payments. |\n| CLI maintenance | `modelgo update`, `modelgo --version`, `modelgo --help` | Update the CLI, print its version, or reopen the complete help output. |\n\nRun `modelgo <command> --help` to inspect the options for a specific command. For `balance`, `permissions`, and `logs`, you can also use the global `--tenant <slug\\|id>` option to target a workspace for that command only.\n\n[View @model-go/cli on npm](https://www.npmjs.com/package/@model-go/cli)\n\n:::note Security\n- Prefer the interactive API-key prompt instead of putting a key directly in a command.\n- Never commit an API key to source control or paste it into a shared script.\n- If you skipped login during CLI installation, run `modelgo auth login` later.\n:::\n\n## Continue exploring\n\n- [First API Call](quickstart): make your first model call.\n- [Authentication](authentication): learn how to use and protect your API key.\n","china/en/quickstart/errors.md":"---\ntitle: Errors & Rate Limits\ndescription: Unified error shape, common categories, and rate-limit handling.\n---\n\n# Errors & Rate Limits\n\n## Error shape\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\nBesides the `error` object, the body carries a top-level `trace_id` field (matching the `X-Trace-ID` response header; omitted when tracing is disabled) so you can grep logs by it. `metadata.reason` is an optional subtype (for example `model_not_in_catalog`). Full catalog and verified examples: [API catalog](openapi).\n\n## Common categories\n\n| error_class | HTTP | Meaning |\n| --- | --- | --- |\n| `client_invalid` | 400 | Bad request shape or parameters |\n| `model_protocol_not_offered` | 400 | The logical model does not declare this inbound protocol (`app_error_id=4005`). Switch endpoint or model |\n| `provider_invalid` | 400 | Upstream rejected the request (upstream returned a 4xx other than 401/403/408/429) |\n| `provider_unsupported` | 400 | The upstream does not support this endpoint (for example some video models reject `DELETE` cancel) |\n| `provider_timeout` | 408 | Upstream request timed out |\n| `auth` | 401 | API key authentication failed |\n| `billing_insufficient` | 402 | Insufficient balance |\n| `policy` | 403 | Model not allowed or no policy bound |\n| `quota` | 429 | Platform quota or limit hit |\n| `provider_rate_limit` | 429 | Upstream rate limit (upstream returned 429) |\n| `gateway_internal` | 500 | Gateway internal error (catch-all) |\n| `billing_system` | 502 | Billing system unavailable |\n| `provider_server` | 502 | Upstream server error |\n| `provider_unauthorized` | 502 | Upstream credential rejected (bucketed as 5xx; upstream-key issues are not exposed to callers) |\n| `provider_unavailable` | 503 | No available provider |\n| `route_unconfigured` | 503 | Model route has no upstream configured |\n\n## Billing of failed requests\n\n- Pre-authorization: every accepted request freezes balance based on an estimate; after the request ends it is settled by actual usage and any excess is released immediately.\n- Successful requests, and streaming requests that already delivered content, are settled by the usage actually returned.\n- **Requests that were dispatched to the upstream provider but ultimately failed** (upstream 4xx/5xx, upstream timeout, mid-stream disconnect, or the client closing the connection while waiting for the response) are settled at the pre-authorized amount and are not refunded. The upstream provider has already incurred cost for such requests; the platform bears it at the pre-authorized figure and bills the caller accordingly.\n- Requests rejected before reaching an upstream provider (validation, authentication, policy, quota, insufficient balance, gateway internal errors) release the full pre-authorization and incur no charge.\n- The settlement basis is visible in the console's usage transactions; records settled at the pre-authorized amount carry the failure reason.\n\n## Troubleshooting\n\n- Keep `X-Request-ID` and `X-Trace-ID` from the response headers; the error body also carries a top-level `trace_id` with the same value.\n- On `429`, honor the `Retry-After` response header and back off exponentially (the platform sets it when a platform rate limit is hit).\n- If a streaming response delivers a chunk with an `error` field, treat it as a failure (such a mid-stream break maps to `provider_stream_broken` and is not returned as a separate HTTP status).\n\nFor endpoint details see:\n\n- [Text Generation](../models/text/generation)\n- [Image Generation](../models/images/generations)\n- [OpenAI-Compatible Video Flow](../models/video/openai-compatible)\n- [Generic Async Content Generation Tasks](../models/video/async-tasks)\n- [Seedance Video Inbound Protocol](../models/video/ark)\n- [MiniMax Video Inbound Protocol](../models/video/minimax)\n","china/en/quickstart/openapi.md":"---\ntitle: API catalog\ndescription: Full customer-facing OpenAPI list, auth, protocol matching, and verified examples.\n---\n\n# API catalog\n\nThis page lists the public model-calling HTTP APIs (`mgk_` API Key, gateway `{{ api_endpoint }}`).\n\n## Before you call\n\n1. Create an API key (`mgk_`) at `{{ console_endpoint }}`. The full secret is shown once.\n2. `export MODELGO_API_KEY=\"your-key\"`.\n3. Call `GET /v1/models` for logical model names.\n4. A model only accepts endpoints listed in its `public_protocols`. Hitting any other path returns HTTP 400, `error_class=model_protocol_not_offered` (`app_error_id=4005`).\n\n## Auth\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic clients may send `x-api-key`; Gemini clients may send `x-goog-api-key`. Priority: `Authorization` > `x-api-key` > `x-goog-api-key`. See [Authentication](authentication).\n\nMissing or invalid key (HTTP 401):\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\nKeep `X-Request-ID`, `X-Trace-ID`, and body `trace_id`.\n\n## Protocol matching\n\n| Model | Endpoint | Result |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`, `POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`, `POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations` with `size` ≥ ~1920×1920 | 200 |\n\n## Catalog\n\n**Public** means the gateway mounts the route. Whether a given model accepts it still depends on `public_protocols` and the key's policy.\n\n### Text and model list\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | Public | Logical models allowed for this key |\n| `POST` | `/v1/responses` | Public | OpenAI Responses (preferred) |\n| `POST` | `/v1/chat/completions` | Public | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | Public | Legacy; most chat models do not offer it |\n| `POST` | `/v1/messages` | Public | Anthropic Messages |\n\n### Vectors / images / audio / rerank\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | Public | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Public | Needs a multimodal-embedding protocol |\n| `POST` | `/v1/images/generations` | Public | Image generation |\n| `POST` | `/v1/images/edits` | Public | Multipart image edits |\n| `POST` | `/v1/audio/speech` | Public | OpenAI TTS; not every speech model offers it |\n| `POST` | `/minimax/v1/t2a_v2` | Public | MiniMax native TTS; see [MiniMax audio inbound](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | Public | Multipart STT |\n| `POST` | `/v1/audio/translations` | Public | Multipart translation |\n| `POST` | `/v1/rerank` | Public | Rerank |\n| `POST` | `/v1/reranks` | Public / alias | Same as `/v1/rerank` |\n\n### Managed async video\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST`/`GET`/`DELETE` | `/v1/content_generation/tasks` and `.../{task_id}` | Public | Generic async tasks |\n| `POST`/`GET`/`DELETE` | `/ark/api/v3/contents/generations/tasks` and `.../{task_id}` | Public | Same pipeline, Ark spelling |\n| `POST`/`GET`/`DELETE` | `/minimax/v2/video_generation` and `.../{task_id}` | Public | MiniMax video V2; pricing dimensions required |\n| `POST`/`GET`/`DELETE` | `/v1/video/generations`, `/v1/videos/{task_id}`, `/v1/videos/{task_id}/content` | Public | OpenAI-compatible video; model must offer it |\n\nCancel (`DELETE`) may return `provider_unsupported` if the upstream has no cancel API.\n\n## Verified calls\n\nList models:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nChat Completions:\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":64}'\n```\n\nEmpty `{}` → HTTP 400 `client_invalid`. Unknown model → HTTP 403 `policy` / `model_not_in_catalog`.\n\nResponses: `POST /v1/responses` with `input` + `max_output_tokens`. Messages: `POST /v1/messages` with `x-api-key` and `max_tokens`. The Messages response `model` field may be an upstream id, not the logical name.\n\nEmbeddings: `text-embedding-3-small` returned 1536-d vectors.\n\nImages: `doubao-seedream-5.0-lite` rejects `1024x1024` (`provider_invalid`, min 3686400 pixels). `2048x2048` succeeded.\n\nSpeech: use [MiniMax audio inbound](../models/audio/minimax) for `speech-2.8-*`.\n\nVideo: Seedance uses `/v1/content_generation/tasks` (create returns `{\"id\",\"model\",\"status\":\"queued\"}`; poll later returns `status=succeeded`, plus `resolution` / `ratio` / `duration`). `/v1/video/generations` is `model_protocol_not_offered` for `doubao-seedance-2.0-mini`.\n\n## Streaming\n\nSet `stream: true`. OpenAI-shaped endpoints use `text/event-stream` frames `data: {json}` ending with `data: [DONE]`. `/v1/messages` keeps native Anthropic `event:` frames. A chunk with `error` is a failure even if HTTP status was 200.\n\n## Limits\n\n- Rate limits: HTTP 429 (`quota` or `provider_rate_limit`); honor `Retry-After`.\n- No client idempotency key on sync calls. Each async POST creates a new task; poll by returned `id`.\n- No pagination on this surface; `GET /v1/models` returns the full list for the key.\n\nSee [Errors](errors), [Text generation](../models/text/generation), [MiniMax audio inbound](../models/audio/minimax), [Async tasks](../models/video/async-tasks).\n","china/en/quickstart/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [First API Call](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","china/en/quickstart/quickstart.md":"---\ntitle: First API Call\ndescription: Create an API key, choose a model, and make your first request with the Responses API.\n---\n\n# First API Call\n\nYou can reuse an existing OpenAI or Anthropic SDK with ModelGo, or follow the three steps below to make your first request with the Responses API.\n\n## Connect with standard protocols\n\nModelGo supports both OpenAI and Anthropic standard protocols. If your project already uses either SDK, you can usually keep the existing integration and replace only the Base URL and API key.\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## Make your first API call in three steps\n\nIf this is your first ModelGo integration, complete these three steps to send a request and receive a generated result.\n\n### 1. Create an API key\n\n- Sign in to the [console]({{ console_endpoint }}).\n- Open the API Keys page and create a new API key.\n- Store it in an environment variable instead of placing it directly in your code:\n\n```bash\nexport MODELGO_API_KEY=\"your-api-key\"\n```\n\n### 2. Choose a model\n\nThe `model` request field must use a ModelGo logical model name. Browse models in the [Model Catalog]({{ site_endpoint }}/models) or use the following request to list the logical models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative. Choose a model name and replace `<model>` in the next step.\n\n### 3. Send your first request\n\nWe recommend starting with `POST /v1/responses`. Run the example in your preferred language:\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"Introduce ModelGo in three sentences.\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"Introduce ModelGo in three sentences.\",\n)\n\nprint(response.output_text)\n```\n\nA successful request returns the model-generated result. With the Python SDK, read the generated text from `response.output_text`.\n\n## Use other compatible protocols\n\nIf your project already uses another compatible interface, you can keep its existing request shape:\n\n- [Use Chat Completions](../models/text/generation#chat-completions): For existing OpenAI Chat Completions integrations.\n- [Use Anthropic Messages](../models/text/generation#anthropic-messages): For existing Claude SDK or Anthropic Messages integrations.\n\n## Continue exploring\n\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See the complete Responses, Chat Completions, and Anthropic Messages documentation.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n","china/zh/about/overview.md":"---\ntitle: 平台概览\ndescription: 了解 ModelGo 的统一模型 API、兼容协议、模型能力与生产调用管理方式。\n---\n\n# 平台概览\n\n## ModelGo 概述\n\nModelGo 是面向生产环境的 AI 模型聚合网关。通过一个 API Key 和统一的 API，你可以调用文本、图像、视频、音频、向量与重排模型，无需为不同模型重复维护接入代码。\n\n无论你是在验证模型效果、开发 AI 功能，还是将模型调用投入生产，都可以通过相同的开发流程完成接入，并在一个平台内管理权限、用量、日志和安全策略。\n\n## 一个 API，调用多种模型\n\nModelGo 将不同类型的模型能力接入到同一套开发流程中。你可以根据业务场景选择对应能力，并进入详细文档查看接口、参数与调用示例。\n\n| 模型类别 | 模型能力 | 查看文档 |\n| --- | --- | --- |\n| 文本 | 对话、内容生成、推理与工具调用 | [文本生成](../models/text/generation) |\n| 图像 | 根据文本生成图像，或编辑已有图像 | [图像生成](../models/images/generations) · [图像编辑](../models/images/edits) |\n| 视频 | 生成视频，并通过异步任务查询进度与结果 | [标准视频接口](../models/video/openai-compatible) · [异步任务](../models/video/async-tasks) |\n| 向量 | 生成文本或多模态 Embeddings，用于语义检索与 RAG | [Embeddings](../models/vectors/embeddings) |\n| 音频 | 语音合成、语音识别与语音翻译 | [语音合成](../models/audio/speech) · [MiniMax 音频](../models/audio/minimax) · [语音转文本](../models/audio/transcriptions) · [语音翻译](../models/audio/translations) |\n| 重排 | 对候选结果重新排序，提升搜索和 RAG 的检索效果 | [Rerank](../models/rerank/rerank) |\n\n你也可以在模型广场查看可用模型，在模型体验中测试模型效果，或通过 `GET /v1/models` 获取当前 API Key 可调用的模型列表。\n\n## 使用熟悉的协议与工具\n\nModelGo 兼容 OpenAI 与 Anthropic 文本协议。已经使用相关 SDK 或客户端的项目，通常只需要替换 Base URL 和 API Key，即可沿用现有调用方式。\n\n根据客户端使用的协议选择对应地址：\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n所有请求使用同一套 ModelGo API Key 进行鉴权。你可以在[控制台]({{ console_endpoint }})创建 API Key，具体请求头与安全建议请查看[认证鉴权](authentication)。\n\n## 为生产调用而设计\n\nModelGo 不只提供统一接口，也提供模型调用进入真实业务后需要的管理能力：\n\n- **稳定调用**：在接入层统一处理模型路由与故障回退，减少单一路径异常对业务的影响。\n- **权限与安全**：通过工作空间、成员和 API Key 划分调用权限，并限制预算、可用模型与调用来源。\n- **用量与成本**：按时间、工作空间、模型、成员和 API Key 查看请求数、Token 用量与消费金额。\n- **调用追踪**：通过 Request ID、调用状态、延迟和错误信息定位同步调用与异步任务问题。\n\n## 开始使用\n\n如果是第一次接入 ModelGo，建议按以下顺序开始：\n\n- [快速开始](quickstart)：获取 API Key，并完成第一次模型调用。\n- [接口清单](openapi)：全量对外路径、协议匹配规则与已验证示例。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的调用示例。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n\n:::note 开发前请注意\n- 请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名，而不是上游厂商的原始模型 ID。\n- 通过 `GET /v1/models` 可以查询当前 API Key 有权调用的逻辑模型。返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。\n- 文本流式响应使用 SSE 传输，并以 `data: [DONE]` 表示响应结束。\n- 视频等异步生成接口会先返回 `task_id`，需要使用该 ID 查询任务进度和结果。\n- 排查调用问题时，请保留响应中的 `X-Request-ID`，方便定位具体请求。\n:::\n","china/zh/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: 使用 ModelGo 配置 CC Switch 和 Claude Code。\n---\n\n# CC Switch\n\nCC Switch 是桌面端配置管理工具，可以统一管理 Claude Code、Codex、Gemini、OpenCode、OpenClaw 等工具的 Provider。下面以 Claude Code 为例，将 ModelGo 添加到 CC Switch 并启用。\n\n## 接入前准备\n\n- 已安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)，并能正常打开。\n- 已安装 Claude Code，并至少启动过一次。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 打开 Claude Code 配置\n\n打开 CC Switch，在顶部选择 **Claude**，点击右侧的 **+** 新增配置。\n\n![CC Switch 主界面](/images/agents/cc-switch/overview.webp)\n\n![在 CC Switch 中添加 Claude 配置](/images/agents/cc-switch/claude-add.webp)\n\n## 2. 添加 ModelGo Provider\n\n在配置编辑器中粘贴下面的 JSON。将 `你的模型名` 替换为模型广场中的逻辑模型名，将 `sk-你的token` 替换为 ModelGo API Key：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-你的token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"你的模型名\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"你的模型名\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![在 CC Switch 中编辑 ModelGo 配置](/images/agents/cc-switch/config-cn.webp)\n\n如果你的 CC Switch 版本支持环境变量占位符，可以将 Token 改为 `{env:MODELGO_API_KEY}`，并在启动 Claude Code 的终端中设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | ModelGo 控制台创建的 API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | 模型广场中的逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的逻辑模型名 |\n\n:::note\n- Anthropic Base URL 填写 ModelGo 根地址，不要追加 `/v1/messages`；Claude Code 会自动请求 `/v1/messages`。\n- API Key 只保存在本机 CC Switch 配置或环境变量中，不要提交到代码仓库。\n- CC Switch 的 Provider 名称可以填写 `ModelGo`，方便后续识别和切换。\n:::\n\n## 3. 保存并启用\n\n填写 Provider 名称 **ModelGo** 后点击 **Add** 或 **Save**。回到 Claude 配置列表，选中 ModelGo 配置并启用。\n\n![在 CC Switch 中添加 ModelGo Provider](/images/agents/cc-switch/provider-cn.webp)\n\n![在 CC Switch 中启用 ModelGo 配置](/images/agents/cc-switch/use-cn.webp)\n\n启动 Claude Code：\n\n```bash\nclaude\n```\n\n输入一条简单任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n## 4. 验证配置\n\n如果需要单独验证 API Key 和模型，可执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果中的 `id` 即可作为 `ANTHROPIC_MODEL` 和 `ANTHROPIC_SMALL_FAST_MODEL` 的逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 Token 是有效的 ModelGo API Key，且当前 CC Switch 配置没有残留的旧 Token。复制 Token 时不要带空格或换行。\n\n### 返回 404 或找不到接口\n\n确认 `ANTHROPIC_BASE_URL` 为 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages` 或完整请求路径。\n\n### 模型不可用\n\n确认模型名与[模型广场]({{ site_endpoint }}/models)中的逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n### 修改后 Claude Code 仍使用旧配置\n\n在 CC Switch 中确认 ModelGo 配置已启用，然后完全退出并重新打开终端，再运行 `claude`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [CC Switch 官方快速开始](https://cc-switch.cc/docs/getting-started/quick-start/)：了解界面和配置切换流程。\n- [CC Switch Provider 配置教程](https://cc-switch.cc/en/tutorials/provider-setup)：了解自定义 Provider 字段和凭据管理。\n","china/zh/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: 通过自定义服务商将 Cherry Studio 接入 ModelGo。\n---\n\n# Cherry Studio\n\nCherry Studio 已内置多个官方服务商，但 ModelGo 不在预置列表中。请使用“自定义服务商”创建一个 ModelGo Provider，再获取并添加模型。ModelGo 同时提供 OpenAI 兼容接口和 Anthropic 兼容接口，可按使用场景选择。\n\n## 接入前准备\n\n- 已安装 Cherry Studio，并能打开设置页面。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的逻辑模型名。\n\n## 1. 打开模型服务设置\n\n打开 Cherry Studio 的“设置”，进入“模型服务”，点击左侧底部的“+ 添加服务商”。\n\n![在 Cherry Studio 中打开添加服务商](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. 添加自定义服务商\n\n在“添加自定义提供商”窗口中填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| 提供商名称 | `ModelGo` |\n| API 密钥 | ModelGo 控制台创建的 API Key |\n| OpenAI 地址 | `{{ api_endpoint }}/v1` |\n| Anthropic 地址 | `{{ api_endpoint }}`（仅在使用 Anthropic 兼容模型或 Agent 模式时填写） |\n\n点击“添加”保存。OpenAI 地址用于普通聊天和模型列表；Anthropic 地址不要追加 `/v1`，Cherry Studio 会按协议补全请求路径。\n\n![添加 ModelGo 自定义提供商](/images/agents/cherry-studio/custom-provider.webp)\n\n:::note\n- 不要把完整的 `/chat/completions` 或 `/messages` 写进地址。\n- OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`，Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n:::\n\n## 3. 获取并添加模型\n\n回到 ModelGo 服务商页面，点击“获取模型列表”。Cherry Studio 会从 ModelGo 的模型接口读取当前 API Key 可用的逻辑模型。\n\n![在 Cherry Studio 中获取 ModelGo 模型列表](/images/agents/cherry-studio/fetch-models.webp)\n\n模型列表弹窗打开后，可以按需点击单个模型右侧的“+”，也可以点击“添加全部模型”。\n\n![在 Cherry Studio 中添加全部 ModelGo 模型](/images/agents/cherry-studio/model-picker.webp)\n\n添加完成后，模型会出现在 ModelGo 服务商的模型区域。只添加自己需要的模型可以让选择器更简洁。\n\n![ModelGo 服务商中的模型列表](/images/agents/cherry-studio/model-list.webp)\n\n## 4. 启用并开始对话\n\n在 ModelGo 服务商右上角打开开关，确认 API 密钥检测通过。新建对话时选择 **ModelGo** 及刚添加的模型，然后发送一条简单消息验证调用。\n\n如果只使用 OpenAI 兼容模型，保留 OpenAI 地址即可；使用 Claude 等 Anthropic 兼容模型或 Cherry Studio Agent 模式时，再配置 Anthropic 地址并添加对应模型。\n\n## 验证配置\n\n可以在终端检查 API Key 是否能读取模型列表：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是 Cherry Studio 中应添加的 ModelGo 逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认服务商右上角开关已打开。\n\n### 返回 404 或接口路径错误\n\nOpenAI 地址应为 `{{ api_endpoint }}/v1`，Anthropic 地址应为 `{{ api_endpoint }}`。不要填写完整的 `/v1/chat/completions` 或 `/v1/messages`。\n\n### 获取模型列表为空\n\n先用上面的 `curl` 验证 `/v1/models`，再确认模型已在模型广场开通。获取列表后还要点击模型右侧的“+”或“添加全部模型”，仅获取列表不会自动加入选择器。\n\n### Agent 模式无法调用\n\n确认已填写 Anthropic 地址 `{{ api_endpoint }}`，并添加支持 Anthropic 兼容协议的模型。普通 OpenAI 兼容聊天不需要填写该地址。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cherry Studio 自定义服务商文档](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang)：查看官方的自定义服务商流程。\n- [Cherry Studio Provider 设置说明](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers)：了解 Base URL、模型管理和连通性检测规则。\n","china/zh/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: 使用 ModelGo 的 Anthropic 兼容接口配置 Claude Code。\n---\n\n# Claude Code\n\nClaude Code 是运行在终端中的 AI 编程助手。通过配置 Anthropic 兼容接口，你可以让 Claude Code 使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 Node.js。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Claude Code\n\n在终端执行：\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n安装完成后检查版本：\n\n```bash\nclaude --version\n```\n\n## 2. 配置 ModelGo\n\n### macOS / Linux\n\n创建并编辑 Claude Code 配置文件：\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\n在 PowerShell 中执行：\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\n将下面内容写入 `settings.json`。把 `YOUR_MODELGO_API_KEY` 和 `YOUR_MODELGO_MODEL` 替换为真实的 ModelGo API Key 与逻辑模型名：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n`ANTHROPIC_BASE_URL` 填写 ModelGo 的根地址，不要追加 `/v1/messages`。Claude Code 会自动请求 ModelGo 的 `POST /v1/messages` 接口。\n\n:::note\n- 如果你只使用一个模型，建议将五个模型变量都设置为同一个 ModelGo 逻辑模型名，避免辅助模型未授权导致启动失败。\n- API Key 仅写入本机配置，不要将 `settings.json` 提交到代码仓库或分享给他人。\n:::\n\n## 3. 可选：跳过官方账号初始化\n\n如果首次输入 `claude` 时卡在官方账号登录引导，可以在用户目录创建 `.claude.json`，写入已完成初始化标识。\n\nmacOS / Linux：\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell：\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. 启动 Claude Code\n\n进入你的项目目录并启动：\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\n首次进入项目时，选择 **Trust This Folder**，允许 Claude Code 访问项目文件。然后输入一条简单的编码需求，能够正常返回结果即表示接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | ModelGo 平台逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n\n模型名可以通过[模型广场]({{ site_endpoint }}/models)确认，也可以查询当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的 ModelGo API Key，复制时不要带多余空格。\n\n### 返回 403 或模型不可用\n\n确认五个模型变量使用的都是当前 API Key 策略允许调用的 ModelGo 逻辑模型名。\n\n### 返回 404 或找不到接口\n\n`ANTHROPIC_BASE_URL` 应填写 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages`；Claude Code 会自动补充 `/v1/messages`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)：查看最新安装与配置说明。\n","china/zh/agents/cline.md":"---\ntitle: Cline\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cline。\n---\n\n# Cline\n\nCline 是 VS Code 中的 AI 编程助手。选择 `OpenAI Compatible` Provider 后，可以通过 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 VS Code。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cline\n\n打开 VS Code 扩展市场，搜索 **Cline** 并安装扩展。\n\n![在 VS Code 扩展市场安装 Cline](/images/agents/cline/cline-market.webp)\n\n## 2. 配置 ModelGo\n\n安装完成后，点击 VS Code 左侧工具栏中的 Cline 图标，打开 **API Configuration**。\n\n![打开 Cline API Configuration](/images/agents/cline/cline-config-cn.webp)\n\n按下表填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | ModelGo API Key |\n| Model ID | ModelGo 平台逻辑模型名 |\n\n点击 **Done** 保存。\n\n:::note\n- Base URL 使用 `{{ api_endpoint }}/v1`，不要填写 `/chat/completions`；Cline 会自动拼接接口路径。\n- Model ID 使用模型广场中当前 API Key 可调用的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 只保存在本机 Cline 设置中，不要提交到代码仓库或截图分享。\n:::\n\n如需先确认当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. 开始使用\n\n在 Cline 面板输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n![Cline 完成一次对话](/images/agents/cline/cline-chat.webp)\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写在 API Key 字段。\n\n### 返回 403 或模型不可用\n\n确认 Model ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应为 `{{ api_endpoint }}/v1`，不要粘贴完整的 `/chat/completions` URL。\n\n### 模型列表为空\n\n先请求 `GET {{ api_endpoint }}/v1/models` 验证接口；若 Cline 下拉列表不显示模型，可直接手动输入 Model ID。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Cline OpenAI Compatible 文档](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx)：查看 Cline 官方 Provider 配置说明。\n","china/zh/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: 通过 ModelGo 接入 CodeBuddy。\n---\n\n# CodeBuddy\n\nCodeBuddy Code 是腾讯云的终端 AI 编程工具。它支持用环境变量覆盖 API 地址、Key 和模型，因此无需修改项目代码即可接入 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已安装 CodeBuddy CLI，并能执行 `codebuddy --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. 配置 ModelGo 环境变量\n\n在启动 CodeBuddy 的同一终端设置：\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-你的token\"\nexport CODEBUDDY_MODEL=\"你的模型名\"\n```\n\n`CODEBUDDY_BASE_URL` 覆盖请求地址，`CODEBUDDY_API_KEY` 用于模型调用，`CODEBUDDY_MODEL` 指定 ModelGo 逻辑模型。不要将 `CODEBUDDY_AUTH_TOKEN` 与 ModelGo API Key 混用；前者是 CodeBuddy 平台登录凭据。\n\n:::note\n- Base URL 填 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- 若使用非交互模式 `codebuddy -p`，必须设置 `CODEBUDDY_API_KEY`。\n- API Key 和模型名建议写进本地 shell profile 或密钥管理器，不要提交到仓库。\n:::\n\n## 3. 启动并验证\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\n```\n\n在会话中让 CodeBuddy 执行一个只读任务；非交互调用示例：\n\n```bash\ncodebuddy -p \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 仍然使用默认模型或地址\n\n确认环境变量在当前终端可见，并完全退出后重新启动 `codebuddy`。检查变量名拼写是否为大写形式。\n\n### 401 或 404\n\n检查 `CODEBUDDY_API_KEY`、`CODEBUDDY_MODEL` 和 `CODEBUDDY_BASE_URL`，不要把完整接口路径写进 Base URL。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [CodeBuddy CLI 快速开始](https://www.codebuddy.ai/docs/cli/quickstart)：查看安装、登录和首次运行流程。\n- [CodeBuddy CLI 环境变量](https://www.codebuddy.ai/docs/cli/env-vars)：查看 `CODEBUDDY_BASE_URL`、`CODEBUDDY_API_KEY` 和模型变量。\n","china/zh/agents/codex.md":"---\ntitle: Codex\ndescription: 使用 ModelGo 的 Responses API 配置 Codex CLI。\n---\n\n# Codex\n\nCodex 是 OpenAI 的命令行 AI 编程助手。通过自定义 `model_provider`，可以将 Codex CLI 的 Responses API 请求发送到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Codex\n\n在 macOS、Linux 或 Windows 终端中执行：\n\n```bash\nnpm install -g @openai/codex\n```\n\n安装完成后检查版本：\n\n```bash\ncodex --version\n```\n\n首次启动时，如果 Codex 提示有新版本可用，可以选择 **Skip**，先完成 ModelGo 配置。\n\n![跳过 Codex 升级提示](/images/agents/codex/codex-start.webp)\n\n## 2. 配置 ModelGo\n\nCodex 从用户目录下的 `~/.codex/config.toml` 读取模型和 Provider 配置。先创建目录和配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\n将下面内容粘贴到 `config.toml`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中当前 API Key 可调用的逻辑模型名：\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\n其中，`base_url` 使用 ModelGo 的 OpenAI 兼容根地址，Codex 会自动请求 `/v1/responses`。\n\n## 3. 设置 API Key\n\n将 ModelGo API Key 保存到系统环境变量 `MODELGO_API_KEY`。不要把真实 API Key 直接写入 `config.toml`。\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n检查变量是否已生效（只输出是否存在，不要打印 Key 内容）：\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- `MODELGO_API_KEY` 只应保存在本机环境变量中，不要提交到代码仓库或分享终端截图。\n- `model` 必须填写 ModelGo 逻辑模型名；截图中的 `gpt-5.6-sol` 仅为示例，请替换为你实际可调用的模型。\n- `wire_api = \"responses\"` 是当前 Codex 配置要求；不要使用已经弃用的 `wire_api = \"chat\"`。\n:::\n\n:::note 切换 API Key 或服务地址后请新建会话\n- Codex 在多轮对话中会继续携带之前的 Responses 上下文，其中可能包含只能由原上游账号继续处理的加密推理内容。\n- 如果你更换了 `MODELGO_API_KEY`、`base_url`，或者代理、号池将同一会话切换到其他上游账号，请新建 Codex 会话，不要继续或恢复原会话，否则请求可能返回 `400 invalid_encrypted_content`。\n:::\n\n## 4. 启动并验证\n\n进入一个本地项目目录，执行：\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\n首次进入项目时，按提示选择信任当前目录。看到 Codex 欢迎界面后，输入一条简单的编码需求，例如“用三句话介绍这个项目”。\n\n![Codex 首次进入项目的欢迎界面](/images/agents/codex/codex-skip.webp)\n\n能够正常返回模型结果，即表示 ModelGo 接入成功。\n\n![Codex 开始对话](/images/agents/codex/codex-chat.webp)\n\n如需先确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 启动后提示找不到 Provider\n\n确认配置文件路径是用户目录下的 `~/.codex/config.toml`，并检查 `model_provider = \"modelgo\"` 与 `[model_providers.modelgo]` 的名称一致。\n\n### 返回 401 或认证失败\n\n检查当前终端是否已设置 `MODELGO_API_KEY`，并确认 API Key 没有多余空格或换行。\n\n### 返回 403 或模型不可用\n\n确认 `model` 使用模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`base_url` 应填写 `{{ api_endpoint }}/v1`。不要填写完整的 `/responses` 或 `/v1/responses`，Codex 会自动拼接路径。\n\n### 出现 Chat wire API 弃用提示\n\n在 `[model_providers.modelgo]` 中加入 `wire_api = \"responses\"`，并升级到最新 Codex CLI：\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### 返回 `400 invalid_encrypted_content`\n\n这通常说明当前会话携带了原上游账号生成的加密上下文，但本轮请求被另一个上游账号处理。\n\n先检查是否更换过 API Key、Base URL，或者代理、号池是否切换了上游账号。发生过切换时，请新建会话，不要继续或恢复原会话。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Codex 配置参考](https://developers.openai.com/codex/config-reference/)：查看当前 Codex 的 `config.toml` 字段说明。\n","china/zh/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: 通过 ModelGo 接入 Copilot CLI。\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI 支持 BYOK（Bring Your Own Key）。设置 Provider 环境变量后，Copilot CLI 会把模型请求发送到 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 GitHub Copilot CLI，并能执行 `copilot --help`。\n- 已完成 GitHub 登录或组织要求的 Copilot 认证。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认支持工具调用和流式输出的逻辑模型。\n\n## 1. 配置 ModelGo BYOK\n\n在启动 Copilot CLI 的同一终端设置：\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"你的模型名\"\ncopilot\n```\n\n如果还没有通用环境变量，可直接设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\n```\n\n`openai` Provider 类型用于 OpenAI Chat Completions 兼容服务；`COPILOT_MODEL` 填 ModelGo 逻辑模型 ID。\n\n:::note\n- Copilot CLI 仍可能需要 GitHub 登录；登录身份与模型请求所用的 ModelGo Key 是两套凭据。\n- Base URL 填 `{{ api_endpoint }}/v1`，不要写 `/chat/completions`。\n- 建议选择支持 tool calling、streaming 且上下文窗口较大的模型。\n:::\n\n## 2. 验证模型\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\n在会话中让 Copilot CLI 执行一个只读任务，例如“列出项目入口文件”，确认能正常返回结果。\n\n## 常见问题\n\n### Copilot CLI 仍调用默认模型\n\n确认 `COPILOT_MODEL` 与 `COPILOT_PROVIDER_BASE_URL` 在当前终端可见，并重新启动 `copilot`。\n\n### 返回 401、404 或不支持工具调用\n\n检查 API Key、Base URL 和逻辑模型名；如果模型不支持工具调用或流式响应，请在模型广场更换模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)：查看 Provider 环境变量和模型要求。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","china/zh/agents/crush.md":"---\ntitle: Crush\ndescription: 通过 ModelGo 接入 Crush。\n---\n\n# Crush\n\nCrush 是 Charmbracelet 提供的终端 AI 编程 Agent。它支持 OpenAI 兼容 Provider，可通过 `crushrc` 将请求转发到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+、Go 或 Homebrew。\n- 已安装 Crush，并能执行 `crush --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\n也可以使用 `npm install -g @charmland/crush`、`go install github.com/charmbracelet/crush@latest`，Windows 用户可执行 `winget install charmbracelet.crush`。\n\n## 2. 添加 ModelGo Provider\n\nCrush 的项目配置放在项目根目录的 `.crushrc` 或 `crushrc`，全局配置放在 `~/.config/crush/crushrc`（Windows：`%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`）。推荐使用 CLI 写入配置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/你的模型名 --name \"你的模型名\"\n```\n\n将 `你的模型名` 替换为模型广场中的逻辑模型 ID。`openai-compat` 表示使用 OpenAI Chat Completions 兼容协议。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- API Key 建议通过 `MODELGO_API_KEY` 环境变量提供，不要写入仓库。\n- `modelgo/你的模型名` 是 Crush 的 Provider/模型标识，Provider ID 可按需修改。\n:::\n\n## 3. 启动并验证\n\n```bash\ncrush\n```\n\n在模型选择器中选择 ModelGo 模型，发送一条简单请求。也可先验证目录接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 找不到 Provider\n\n确认 `crushrc` 路径和文件名正确，并重新启动 Crush。项目配置会覆盖全局配置。\n\n### 返回 401 或 404\n\n检查 `MODELGO_API_KEY` 是否生效，Base URL 是否为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Crush 官方仓库](https://github.com/charmbracelet/crush)：查看安装、Provider 和命令参考。\n- [Crush 配置 Schema](https://github.com/charmbracelet/crush/blob/main/schema.json)：查看 `crushrc` 字段定义。\n","china/zh/agents/cursor.md":"---\ntitle: Cursor\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cursor。\n---\n\n# Cursor\n\nCursor 是一款 AI 编程编辑器。通过自定义 OpenAI Base URL，Cursor 可以调用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 [Cursor](https://www.cursor.com/)。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cursor\n\n访问 [Cursor 官网](https://www.cursor.com/)，下载并安装适合你操作系统的版本。\n\n![Cursor 官网下载页面](/images/agents/cursor/install.webp)\n\n## 2. 打开 Cursor 模型设置\n\n打开 Cursor 设置，进入 **Models** 页面。\n\n![打开 Cursor Settings 的 Models](/images/agents/cursor/settings.webp)\n\n## 3. 添加并启用模型\n\n点击 **Add model**，输入[模型广场]({{ site_endpoint }}/models)中的逻辑模型名，然后保存。\n\n![在 Cursor 中添加模型](/images/agents/cursor/add-model.webp)\n\n在 **Model Names** 列表中保留需要使用的模型，并关闭不需要的模型。\n\n![在 Cursor 中启用目标模型](/images/agents/cursor/model-list.webp)\n\n## 4. 配置 ModelGo 接口\n\n在 **Settings → Models → API Keys** 中配置 OpenAI 兼容接口：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| OpenAI API Key | ModelGo API Key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | ModelGo 模型广场中的逻辑模型名 |\n\n![在 Cursor 中配置 ModelGo 接口](/images/agents/cursor/config-cn.webp)\n\n如果你的 Cursor 使用另一版设置界面，可参考下面的布局，填写相同的 ModelGo 参数。\n\n![Cursor 另一版设置界面](/images/agents/cursor/config-global.webp)\n\n点击 **Verify** 或 **Save** 保存配置。Cursor 的不同版本可能会调整设置项名称，但 Base URL、API Key 和模型名的含义不变。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- 模型名必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图里的示例。\n- 如果 Verify 无法完成，可先在聊天窗口直接发送请求，或用下方命令检查接口和 Key。\n:::\n\n## 5. 测试连接\n\n回到 Cursor 聊天窗口，选择刚添加的模型，发送一条简单消息。能够正常返回结果，即表示接入成功。\n\n![在 Cursor 中测试 ModelGo 模型](/images/agents/cursor/chat.webp)\n\n也可以在终端查看当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 API Key 复制完整且没有多余空格，并检查是否填入 **OpenAI API Key** 字段。\n\n### 返回 404 或接口路径错误\n\n确认 Base URL 为 `{{ api_endpoint }}/v1`，不要把 `/chat/completions` 拼到 Base URL 后面。\n\n### Verify 失败或模型不可用\n\n确认模型名是 ModelGo 模型广场中的逻辑模型名，并检查该模型是否已对当前 API Key 开通。\n\n### 聊天窗口没有返回内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 验证网络和 Key，再确认 Cursor 的 Model Names 列表中已启用目标模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cursor 官方文档](https://docs.cursor.com/)：查看 Cursor 设置、模型和自定义 API 配置说明。\n","china/zh/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 DeepSeek Harness。\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness（DSH）是 DeepSeek AI 开源的智能体框架，可以将模型、工具、文件系统、终端、会话和 Web UI 组合成可运行的 Agent。通过自定义提供方，DSH 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已安装 pnpm 11 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装并启动 DeepSeek Harness\n\nDeepSeek Harness 当前推荐从源码安装：\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![从源码启动 DeepSeek Harness](/images/agents/deepseek-harness/install.webp)\n\n终端会打印 Web UI 地址，默认是 `http://127.0.0.1:3080`。如果端口已被占用，请以终端实际打印的地址为准。\n\n如果只想快速体验，也可以直接运行：\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. 配置 ModelGo\n\n在浏览器打开终端打印的地址，点击左上角侧边栏按钮，然后点击 **设置**。\n\n![打开 DeepSeek Harness 设置](/images/agents/deepseek-harness/settings.webp)\n\n在设置中选择 **模型**，点击 **添加自定义提供方**。\n\n![添加自定义提供方](/images/agents/deepseek-harness/model-picker.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider ID | `modelgo` |\n| 显示名称 | `ModelGo` |\n| API 地址 | `{{ api_endpoint }}/v1` |\n| API 协议 | `openai-completions` |\n| API 密钥 | ModelGo API Key |\n| 模型 ID | 模型广场中的逻辑模型名 |\n| 显示名称 | 可填写与模型 ID 相同的名称 |\n\n![填写 ModelGo 自定义提供方](/images/agents/deepseek-harness/provider-config.webp)\n\n点击 **创建提供方** 保存配置。配置时请注意：\n\n:::note\n- API 地址填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`；DSH 会根据 `openai-completions` 协议拼接请求路径。\n- 模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例模型。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 开始会话\n\n回到主界面，选择一个工作区，再选择刚刚添加的 ModelGo 模型。\n\n![选择 ModelGo 模型开始会话](/images/agents/deepseek-harness/session.webp)\n\n输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 已接入成功。\n\n## 常见问题\n\n### Web UI 无法打开\n\n确认 `pnpm dsh web` 进程仍在运行，并访问终端打印的实际端口。默认端口是 `3080`，端口冲突时 DSH 可能会自动使用其他端口。\n\n### 返回 401 或认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写的是 ModelGo 控制台创建的 API Key。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\nAPI 地址应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。API 协议请选择 `openai-completions`。\n\n### 模型列表为空\n\n检查模型 ID 是否填写，并确认 DSH 的自定义提供方已保存。必要时可以先用下面的命令验证 ModelGo 接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [DeepSeek Harness 官方网站](https://www.deepseek.com/harness/)：查看最新安装方式和产品说明。\n- [DeepSeek Harness GitHub 仓库](https://github.com/deepseek-ai/deepseek-harness)：查看源码和版本信息。\n","china/zh/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: 通过 ModelGo 接入 Factory Droid。\n---\n\n# Factory Droid\n\nFactory Droid 是 Factory 的终端 Agent。通过 BYOK 自定义模型，可以让 Droid 使用 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 Node.js 18+ 和 Droid CLI。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装并启动 Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\n也可以使用 Factory 官方安装器。进入 Droid 后输入 `/settings` 可打开设置。\n\n## 2. 配置 ModelGo 自定义模型\n\n编辑 `~/.factory/settings.json`（Windows：`%USERPROFILE%\\\\.factory\\\\settings.json`），合并以下 `customModels` 配置：\n\n```json\n{\n  \"customModels\": [\n    {\n      \"model\": \"你的模型名\",\n      \"displayName\": \"ModelGo / 你的模型名\",\n      \"baseUrl\": \"{{ api_endpoint }}/v1\",\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"provider\": \"openai\"\n    }\n  ]\n}\n```\n\n先设置 Key：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n重新启动 Droid，在 `/models` 或模型选择器中选择 `ModelGo / 你的模型名`。\n\n:::note\n- `baseUrl` 填 `{{ api_endpoint }}/v1`，不要附加 `/chat/completions`。\n- `model` 必须使用 ModelGo 模型广场中的逻辑模型 ID。\n- 保留原有 `settings.json` 字段，只合并 `customModels`，不要覆盖其他个人设置。\n:::\n\n## 3. 验证请求\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"你的模型名\" \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 模型没有出现在列表中\n\n检查 JSON 是否有效、`customModels` 是否位于文件顶层，并完全退出后重新启动 Droid。\n\n### 认证失败或接口路径错误\n\n确认环境变量已在启动 Droid 的同一终端中设置，且 `baseUrl` 没有重复的 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Factory Droid 设置](https://docs.factory.ai/droid-cli/settings)：查看 `settings.json` 的位置和设置入口。\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok)：了解自定义模型字段和模型独立性。\n","china/zh/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Hermes Agent。\n---\n\n# Hermes Agent\n\nHermes Agent 是一款运行在终端中的 AI Agent。通过自定义 Provider，Hermes 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的 ModelGo 逻辑模型名。\n\n## 1. 安装 Hermes Agent\n\nmacOS 或 Linux：\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell：\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\n重新打开终端后，检查安装是否成功：\n\n```bash\nhermes --version\n```\n\n## 2. 配置 ModelGo\n\n先把 API Key 放入当前终端的环境变量。不要把真实 Key 提交到代码仓库或公开脚本中：\n\n```bash\nexport MODELGO_API_KEY=\"你的-ModelGo-API-Key\"\nexport MODELGO_MODEL=\"你的-ModelGo-逻辑模型名\"\n```\n\n如果还不确定模型名，可以先查询当前 API Key 可用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n然后使用 `hermes config set` 写入自定义 Provider。将 `<model>` 替换为模型广场或 `GET /v1/models` 返回的逻辑模型名：\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\n如果你的 Hermes 版本通过 `hermes model` 提供配置向导，也可以运行：\n\n```bash\nhermes model\n```\n\n选择 **Custom endpoint**，依次填写下方配置表中的 ModelGo Base URL、API Key 和模型名，并选择 **Chat Completions** 协议。\n\n:::note\n- 部分旧版本将 Chat Completions 协议显示为 `openai_messages`。如果 `chat_completions` 被提示为无效，请升级 Hermes，或在 `hermes model` 向导中选择 Chat Completions。\n:::\n\n## 3. 检查配置并开始对话\n\n检查 Hermes 配置：\n\n```bash\nhermes config check\n```\n\n检查通过后启动 Hermes：\n\n```bash\nhermes\n```\n\n输入一条消息，例如“用三句话介绍 ModelGo”。如果能返回模型结果，说明接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API 模式 | `chat_completions` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model ID | ModelGo 的平台逻辑模型名，不是上游厂商原始模型 ID |\n\nHermes 会将非敏感配置保存到 `~/.hermes/config.yaml`，API Key 等敏感信息保存到 `~/.hermes/.env`。不要分享或提交 `~/.hermes/` 下包含密钥的文件。\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n确认 API Key 没有被撤销或过期，并重新执行：\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 返回 403 或模型不可用\n\n确认 `model.default` 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要再拼接 `/chat/completions`；Hermes 会在请求时补充具体路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs)：查看安装器、配置项和 CLI 的最新说明。\n","china/zh/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: 通过 ModelGo 接入 Kilo CLI。\n---\n\n# Kilo CLI\n\nKilo CLI 是终端 AI 编程 Agent。它支持自定义 OpenAI 兼容 Provider；由于 ModelGo CLI 尚未提供官方自动配置，本文采用 Kilo 的 `/connect` 与配置文件方式。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\n进入项目目录后运行 `kilo`，首次启动可使用 `/connect` 添加 Provider。\n\n## 2. 添加 ModelGo Provider\n\n在项目根目录创建 `kilo.jsonc`（或编辑全局配置），加入 OpenAI 兼容 Provider：\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/你的模型名\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"ModelGo / 你的模型名\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n也可以在 TUI 中选择 `/connect` → `OpenAI Compatible`，填写同样的 Base URL、API Key 和模型 ID。\n\n:::note\n- Provider ID 使用小写 `modelgo`；模型选择格式为 `modelgo/你的模型名`。\n- `baseURL` 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- Kilo CLI 的模型 ID 必须与 ModelGo 模型广场逻辑模型名一致。\n:::\n\n## 3. 验证配置\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\n在模型选择器中选中 ModelGo 模型，发送一条只读任务确认连接。\n\n## 常见问题\n\n### Provider 没有出现在选择器\n\n检查 `kilo.jsonc` 的 JSONC 格式、Provider ID 和 `model` 路径，并重新启动 Kilo。\n\n### 401 或 404\n\n确认 `MODELGO_API_KEY` 已导出，`baseURL` 为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Kilo CLI 官方文档](https://kilo.ai/docs/code-with-ai/platforms/cli)：查看安装、`/connect` 和 CLI 命令。\n- [Kilo 自定义模型](https://kilo.ai/docs/code-with-ai/agents/custom-models)：查看 OpenAI Compatible Provider 字段和模型格式。\n","china/zh/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Kilo Code。\n---\n\n# Kilo Code\n\nKilo Code 是一款支持 VS Code 和 JetBrains 的 AI 编程助手。通过 OpenAI 兼容 Provider，你可以在 Kilo Code 中使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 VS Code 或 JetBrains IDE。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Kilo Code\n\n### VS Code\n\n打开 VS Code 扩展市场，搜索 **Kilo Code**，确认发布者后安装扩展。安装完成后，打开左侧 Kilo Code 面板。\n\n![在 VS Code 扩展市场安装 Kilo Code](/images/agents/kilo-code/vscode-market.webp)\n\n首次安装时，VS Code 会要求确认是否信任发布者。确认发布者为 Kilo Code 后，点击 **Trust Publisher & Install**。\n\n![确认信任 Kilo Code 发布者](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\n打开 Settings / Preferences → Plugins，在 Marketplace 搜索 **Kilo Code** 并安装。安装完成后重启 IDE，使扩展生效。\n\n![在 JetBrains Marketplace 安装 Kilo Code](/images/agents/kilo-code/jetbrains-market.webp)\n\n安装第三方插件时，JetBrains 会显示插件声明。确认后点击 **接受**，完成安装。\n\n![确认 JetBrains 第三方插件声明](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. 在 VS Code 中配置 ModelGo\n\n打开 Kilo Code 的设置，进入 **Providers**，选择 **OpenAI Compatible**，填写以下信息：\n\n先在 Kilo Code 的欢迎页选择 **Bring my own Key**：\n\n![选择 Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model | ModelGo 平台逻辑模型名 |\n\n![Kilo Code VS Code 配置界面](/images/agents/kilo-code/vscode-config-cn.webp)\n\n保存后，Kilo Code 会尝试从兼容的 `/v1/models` 接口获取模型。如果下拉列表中没有目标模型，可以选择 **Use custom**，手动输入模型广场中的逻辑模型名。\n\n:::note\n- Base URL 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。Kilo Code 会自动拼接标准路径。\n- 截图中的模型名仅为界面示例，请替换为当前 API Key 可调用的 ModelGo 逻辑模型名。\n- API Key 只填写在本机的 Kilo Code 设置中，不要提交到代码仓库或截图分享。\n:::\n\n## 3. 在 JetBrains 中配置 ModelGo\n\n打开 Kilo Code 设置，点击 **Bring my own Key**，选择 **OpenAI Compatible**，然后填写与 VS Code 相同的配置：\n\n![在 JetBrains 中选择 Bring my own Key](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**：`{{ api_endpoint }}/v1`\n2. **API Key**：ModelGo API Key\n3. **Model**：ModelGo 逻辑模型名\n4. 点击 **Save** 保存。\n\n![JetBrains 中的 ModelGo Provider 配置](/images/agents/kilo-code/jetbrains-config-cn.webp)\n\n如果模型下拉列表为空，先确认 Base URL 可访问，再选择自定义模型并手动输入逻辑模型名。\n\n![在 JetBrains 中完成一次编码任务](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. 检查配置并开始对话\n\n进入一个本地项目，在 Kilo Code 面板中输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回模型结果，即表示接入成功。\n\n![Kilo Code 完成一次编码任务](/images/agents/kilo-code/vscode-start.webp)\n\n如需检查当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整，确认没有多余空格，并确认填写在 **API Key** 而不是 Base URL 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 **Model** 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。不要直接填写上游厂商原始模型 ID，除非模型广场明确提供该名称。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。Kilo Code 会在请求时补充具体接口路径。\n\n### 模型下拉列表没有内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 检查 API Key 和接口是否可用；如果接口正常，使用 **Use custom** 手动输入逻辑模型名。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Kilo Code 官方文档](https://kilo.ai/docs)：查看最新的扩展安装和 Provider 配置说明。\n","china/zh/agents/nanobot.md":"---\ntitle: nanobot\ndescription: 通过 ModelGo 接入 nanobot。\n---\n\n# nanobot\n\nnanobot 是轻量级终端 Agent。它通过 JSON 配置 Provider 和模型预设，可直接使用 ModelGo 的 OpenAI 兼容 API。\n\n## 接入前准备\n\n- 已安装 Python 3.11+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\n配置文件默认位于 `~/.nanobot/config.json`。\n\n## 2. 配置 ModelGo Provider\n\n编辑 `~/.nanobot/config.json`，合并以下字段：\n\n```json\n{\n  \"providers\": {\n    \"modelgo\": {\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"apiBase\": \"{{ api_endpoint }}/v1\"\n    }\n  },\n  \"modelPresets\": {\n    \"ModelGo\": {\n      \"provider\": \"modelgo\",\n      \"model\": \"你的模型名\",\n      \"maxTokens\": 4096,\n      \"contextWindowTokens\": 65536,\n      \"temperature\": 0.1\n    }\n  },\n  \"agents\": { \"defaults\": { \"modelPreset\": \"ModelGo\" } }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nnanobot 对 OpenAI 兼容自定义端点无需额外填写 `apiType`；`apiBase` 使用带 `/v1` 的根地址。\n\n:::note\n- 保留原配置中的 channels、tools 等字段，只合并 providers、modelPresets 和 agents.defaults。\n- API Key 使用环境变量，不要把真实 Key 写进 JSON 或提交到仓库。\n- 模型名必须是 ModelGo 模型广场中的逻辑模型 ID。\n:::\n\n## 3. 验证连接\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### `nanobot` 找不到模型\n\n确认 `modelPresets.ModelGo.provider` 与 `providers.modelgo` 的 ID 一致，并检查 JSON 格式。\n\n### 401 或请求地址错误\n\n确认 API Key 环境变量已导出，`apiBase` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [nanobot OpenAI 兼容 Provider 指南](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md)：查看完整 JSON 配置说明。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","china/zh/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: 通过 ModelGo 接入 Oh My Pi。\n---\n\n# Oh My Pi\n\nOh My Pi（命令 `omp`）是终端 AI 编程 Agent。它支持在 `models.yml` 中声明 OpenAI 兼容 Provider，并按 `provider-id/model-id` 选择模型。\n\n## 接入前准备\n\n- 已安装 Bun 或使用官方安装脚本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux 也可以执行官方安装脚本：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. 添加 ModelGo Provider\n\n编辑 `~/.omp/agent/models.yml`，加入：\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: 你的模型名\n        name: ModelGo / 你的模型名\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` 填环境变量名，而不是 Key 本身：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n:::note\n- `api` 使用 `openai-completions`，`baseUrl` 使用 `{{ api_endpoint }}/v1`。\n- 模型选择格式为 `modelgo/你的模型名`。\n- 不要把真实 API Key 写入 `models.yml`，并确认文件权限仅当前用户可读。\n:::\n\n## 3. 选择模型并验证\n\n```bash\nomp --list-models\nomp --model modelgo/你的模型名\n```\n\n进入会话后发送一条简单任务；也可先检查 ModelGo 模型目录：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 模型列表没有 ModelGo\n\n确认文件路径为 `~/.omp/agent/models.yml`，YAML 缩进正确，并重新启动 `omp`。\n\n### 401 或接口路径错误\n\n确认 `MODELGO_API_KEY` 已导出，`baseUrl` 没有重复 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Oh My Pi Provider 文档](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md)：查看 Provider、API 类型和密钥配置。\n- [Oh My Pi 模型文档](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md)：查看模型选择和 `models.yml` 结构。\n","china/zh/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenClaw。\n---\n\n# OpenClaw\n\nOpenClaw 是一款开源、自托管的个人 AI 助手。通过自定义 Provider，可以让 OpenClaw 使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22.22.3 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\n检查安装是否成功：\n\n```bash\nopenclaw --version\n```\n\n## 2. 设置 API Key\n\nOpenClaw 配置支持从环境变量读取 Provider API Key。将 ModelGo API Key 设置为 `MODELGO_API_KEY`：\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. 配置 ModelGo Provider\n\n创建并打开 OpenClaw 配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\n将下面内容粘贴到 `openclaw.json`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | ModelGo 逻辑模型名 |\n| `agents.defaults.model.primary` | `modelgo/<逻辑模型名>` |\n\n:::note\n- `baseUrl` 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- `contextWindow` 和 `maxTokens` 应与所选模型的限制匹配；上方数值是通用示例，请以模型广场信息为准。\n- 如果模型支持推理，可将对应模型的 `reasoning` 改为 `true`。\n- API Key 通过环境变量注入，不要把真实 Key 写入配置文件或提交到仓库。\n:::\n\n## 4. 启动并验证\n\n保存配置后，在终端执行：\n\n```bash\nopenclaw onboard --install-daemon\n```\n\n查看当前模型和 Provider 状态：\n\n```bash\nopenclaw models status\n```\n\n如果状态正常，启动 Gateway：\n\n```bash\nopenclaw gateway start\n```\n\n在 OpenClaw 对话界面发送一条简单消息，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 接入成功。\n\n## 常见问题\n\n### 找不到模型\n\n确认 `models.providers.modelgo.models[].id` 与 `agents.defaults.model.primary` 中的模型名一致，并使用 `modelgo/<模型名>` 格式。\n\n### 返回 401 或认证失败\n\n检查当前终端是否存在 `MODELGO_API_KEY`，并确认 `apiKey` 使用 `${MODELGO_API_KEY}`，没有多余空格。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`baseUrl` 应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；OpenClaw 会按 `openai-completions` 协议拼接路径。\n\n### Gateway 没有加载新配置\n\n修改配置后重启 Gateway：\n\n```bash\nopenclaw gateway restart\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [OpenClaw 自定义 Provider 文档](https://docs.openclaw.ai/gateway/config-tools)：查看 Provider、Base URL 和模型列表配置说明。\n","china/zh/agents/opencode.md":"---\ntitle: OpenCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenCode。\n---\n\n# OpenCode\n\nOpenCode 是一个开源终端 AI 编程 Agent，支持通过自定义 Provider 接入 OpenAI 兼容接口。配置 ModelGo 后，可以在终端、IDE 或桌面端使用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已安装 OpenCode，并能在终端执行 `opencode -v`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenCode\n\n在终端执行：\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nWindows 用户也可以使用 OpenCode 官方提供的安装方式。安装完成后，执行 `opencode -v`，看到版本号即表示安装成功。\n\n## 2. 配置 ModelGo Provider\n\nOpenCode 默认从以下位置读取用户配置：\n\n- macOS/Linux：`~/.config/opencode/opencode.json`\n- Windows：`%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\n创建或编辑 `opencode.json`，填入以下内容。将 `你的模型名` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"你的模型名\"\n        }\n      }\n    }\n  }\n}\n```\n\n设置环境变量：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `name` | `ModelGo`，用于界面显示 |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | 模型广场中的逻辑模型 ID 和显示名称 |\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- `modelgo` 是本地 Provider ID，可以按需修改；修改后选择模型时使用新的 Provider ID。\n- API Key 通过环境变量读取，不要把真实 Key 直接写入配置文件或提交到仓库。\n- 模型 ID 必须是 ModelGo 模型广场中的逻辑模型名，不要直接照抄示例。\n:::\n\n## 3. 选择模型并开始对话\n\n启动 OpenCode：\n\n```bash\nopencode\n```\n\n输入 `/models` 打开模型选择器，搜索并选择 **ModelGo** Provider 下的模型。\n\n![在 OpenCode 中打开模型选择器](/images/agents/opencode/model-search.webp)\n\n模型列表中显示 **ModelGo** 的条目，即表示 Provider 已被识别。\n\n![在 OpenCode 模型列表中识别 ModelGo](/images/agents/opencode/provider-name.webp)\n\n也可以在模型选择器中输入 `ModelGo` 进行筛选：\n\n![在 OpenCode 中筛选 ModelGo 模型](/images/agents/opencode/provider-filter.webp)\n\n选择模型后输入一条简单任务，例如“用三句话介绍这个项目”。\n\n![在 OpenCode 中使用 ModelGo 开始对话](/images/agents/opencode/chat.webp)\n\n## 4. 验证配置\n\n如果模型列表为空，可以先确认 API Key 能访问 ModelGo：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是可填入 `models` 配置的逻辑模型名。\n\n## 常见问题\n\n### OpenCode 找不到配置文件\n\n确认文件名为 `opencode.json`，并放在 `~/.config/opencode/`（Windows 为 `%USERPROFILE%\\\\.config\\\\opencode\\\\`）目录下。也可以在项目目录放置同名配置覆盖用户配置。\n\n### 返回 401 或认证失败\n\n确认当前终端已设置 `MODELGO_API_KEY`，且 API Key 没有多余空格。重新打开终端后再启动 OpenCode。\n\n### 返回 404 或接口路径错误\n\n确认 `baseURL` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n### 模型列表为空或模型不可用\n\n确认 `models` 中的 ID 与模型广场逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [OpenCode 官方 Providers 文档](https://opencode.ai/docs/providers)：查看 Provider、凭据和自定义 Base URL 的配置方式。\n- [OpenCode 官方配置文档](https://opencode.ai/docs/config/)：了解配置文件结构及模型选项。\n","china/zh/agents/zcode.md":"---\ntitle: ZCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 ZCode。\n---\n\n# ZCode\n\nZCode 是智谱 AI 推出的桌面 AI 编程工具，支持 Windows、macOS 和 Linux。ZCode 支持自定义 OpenAI 兼容供应商，配置后可以直接使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 ZCode 桌面客户端。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 ZCode\n\n访问 [ZCode 官方下载页](https://zcode.z.ai/cn/docs/install)，根据操作系统下载对应安装包。ZCode 提供 macOS、Windows 和 Linux 版本，Linux 用户可以选择 `.deb`、`.rpm` 或 AppImage。\n\n![ZCode 官方下载页](/images/agents/zcode/install.webp)\n\n下载完成后，按系统提示完成安装并启动 ZCode。首次启动时可以选择工作区；完成引导后进入主界面。\n\n![ZCode 全平台安装包](/images/agents/zcode/setup.webp)\n\n## 2. 添加 ModelGo 供应商\n\n在 ZCode 左下角点击设置图标，进入 **Model settings**，然后在供应商列表底部点击 **Add provider**。\n\n![打开 ZCode Model settings 并添加供应商](/images/agents/zcode/provider-fields.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在 [控制台]({{ console_endpoint }}/api-keys) 创建的 ModelGo API Key |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | 点击 **Add model**，填写模型广场中的逻辑模型名 |\n| Context window | 按模型实际上下文长度填写；不确定时可先填 `200000` |\n\n![ModelGo 供应商配置示例](/images/agents/zcode/provider-saved.webp)\n\n点击 **Add provider** 保存。配置时请注意：\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；ZCode 会根据 API format 自动拼接路径。\n- Name 是本机显示名称，填写 `ModelGo` 即可，不需要填写上游厂商名称。\n- Model list 中的模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 添加模型并开始对话\n\n点击 **Add model**，输入一个 ModelGo 逻辑模型名并保存。可以按需添加多个模型。\n\n![ZCode 中选择 ModelGo 模型](/images/agents/zcode/chat.webp)\n\n回到对话界面，在模型下拉菜单中选择 **ModelGo** 和刚添加的模型，输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n如需确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认填写在 **API Key** 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 Model list 中填写的是模型广场中的逻辑模型名，且当前 API Key 策略允许调用该模型。\n\n### 返回 404 或接口路径错误\n\nBase URL 应为 `{{ api_endpoint }}/v1`，API format 请选择 **Chat completions (/chat/completions)**，不要把完整接口路径填入 Base URL。\n\n### 模型列表为空或无法保存\n\n确认至少添加了一个模型，并检查 Base URL 是否可以访问。必要时先用 `GET {{ api_endpoint }}/v1/models` 验证 API Key 和接口。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [ZCode 安装文档](https://zcode.z.ai/cn/docs/install)：查看最新安装说明。\n- [ZCode 连接模型文档](https://zcode.z.ai/cn/docs/configuration)：查看自定义供应商和模型配置说明。\n","china/zh/models/audio/minimax.md":"---\ntitle: MiniMax 音频入站协议\ndescription: 用 MiniMax T2A 原厂请求体与响应体做平台托管的同步语音合成。\n---\n\n# MiniMax 音频入站协议\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | 目录公示的 MiniMax T2A 入站 |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK 别名，语义相同 |\n\n这是 **MiniMax 同步语音合成（T2A V2）** 的原厂入站协议。请求体按 MiniMax `T2aV2Req` 原样接收（`model`、`text`、`voice_setting`、`audio_setting`、`stream` 等），**响应体也按 MiniMax `T2aV2Resp` 渲染**，照 MiniMax 官方文档写的客户端可以直接解析。\n\n`model` 填写平台逻辑模型名，策略、路由与计费照常生效。逻辑模型必须在 `public_protocols` 中声明 `minimax_t2a`，否则网关返回协议不匹配。\n\n只需要 OpenAI 形态的二进制音频时，见[语音合成](./speech)。\n\n## 合成\n\n两条路径等价，任选其一：\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"你好，欢迎使用 ModelGo。\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\n非流式成功响应是 MiniMax JSON，音频在 `data.audio`，为**十六进制字符串**（不是 `audio/mpeg` 直出）：\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\n2026-09-10 国内生产用 `speech-2.8-turbo` 打 `POST /minimax/v1/t2a_v2` 得到上述形态（hex 已截断）。同一模型打 `POST /v1/audio/speech` 返回 `model_protocol_not_offered`。\n\n`base_resp.status_code` **只有数字 `0` 表示成功**。HTTP 200 但 `status_code != 0` 仍按调用失败处理。\n\n### 流式\n\n请求里加 `\"stream\": true`，响应为 SSE，每帧仍是 MiniMax JSON（含增量 hex 音频），不是 OpenAI chat 的 `choices[].delta`。\n\n### 失败与 HTTP\n\n带内错误会把 MiniMax JSON 回传给调用方，并按 `status_code` 映射 HTTP 状态：\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| 其余非 `0` | `502` |\n\n### 计费\n\n按上游报告的 **字符数** 计量（`usage.characters`，否则 `extra_info.usage_characters`），不会用 `text` 的字符串长度估算。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；是否可走本通道以该模型的 `public_protocols` 为准。\n- 路径不参与选路：由逻辑模型的路由决定 MiniMax 直连或百炼等 adaptor。\n- 路由上的 Provider 必须声明支持 MiniMax T2A；仅 OpenAI 兼容中继时会返回 `provider_unsupported`。\n","china/zh/models/audio/speech.md":"---\ntitle: 语音合成\ndescription: OpenAI 兼容 text-to-speech 接口说明。\n---\n\n# 语音合成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\n请求体为 JSON（OpenAI `{input, voice}`），响应体为二进制音频，`Content-Type` 由上游决定并原样返回。\n\n**先确认模型声明了 OpenAI TTS 协议。** 国内生产上的 `speech-2.8-hd` / `speech-2.8-turbo` 当前走 MiniMax T2A，打本接口会返回 `model_protocol_not_offered`。这两款模型请用 [MiniMax 音频入站协议](./minimax)。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"你好，欢迎使用 ModelGo。\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\n需要 MiniMax 原厂字段（音色、字幕、hex JSON、SSE）时，见[MiniMax 音频入站协议](./minimax)。\n","china/zh/models/audio/transcriptions.md":"---\ntitle: 语音转文本\ndescription: OpenAI 兼容 speech-to-text 接口说明。\n---\n\n# 语音转文本\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\n该接口通常以 `multipart/form-data` 上传音频文件和 `model` 字段，响应为 JSON，包含识别出的 `text`。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/zh/models/audio/translations.md":"---\ntitle: 语音翻译\ndescription: OpenAI 兼容语音翻译接口说明。\n---\n\n# 语音翻译\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\n上传方式与语音转文本一致，响应为 JSON。适合把音频内容翻译为目标文本输出。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/zh/models/images/edits.md":"---\ntitle: 图像编辑\ndescription: OpenAI 兼容图像编辑接口说明。\n---\n\n# 图像编辑\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\n该接口使用 `multipart/form-data` 上传原图和 `model` 字段。网关会保留原始 body 与 `Content-Type` 向上游透传，因此调用时应直接使用 `POST /v1/images/edits` 的 multipart 方式。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\n如果上游模型不支持图像编辑，平台会返回 `provider_unsupported`。\n","china/zh/models/images/gemini-image.md":"---\ntitle: Gemini 3 / 3.1 图像生成（Google 原生协议）\ndescription: 按 Google Gemini API 官方 generateContent 协议调用 gemini-3-pro-image、gemini-3.1-flash-image、gemini-3.1-flash-lite-image：responseModalities、aspectRatio / imageSize 档位、inlineData 响应与按 token 计费口径。Google GenAI SDK 改 base_url 即可直连。\n---\n\n# Gemini 3 / 3.1 图像生成（Google 原生协议）\n\n| 模型（路径中使用） | 定位 | 可选 `imageSize` |\n| --- | --- | --- |\n| `gemini-3-pro-image` | 质量版 | `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-image` | 速度与成本均衡 | `512px` / `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-lite-image` | 最低成本 | 仅 `1K` |\n\nModelGo 按 Google Gemini API 的 **`generateContent`** 协议原样接收图像生成请求：`contents` + `generationConfig`，同步返回 `candidates[].content.parts[].inlineData`。网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。**URL 路径中的模型名是唯一权威**，请求体中无需再写模型。\n\n> 使用 Google GenAI SDK 时，把 `http_options.base_url` 指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key 即可。鉴权头同时接受 `x-goog-api-key: $KEY` 与 `Authorization: Bearer $KEY`。\n>\n> Google 新推出的 Interactions API 暂不支持，请使用 `generateContent`。\n\n## 1. 创建图像\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:generateContent`（也接受 `/v1/models/...`）\n\n### 文生图\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [{\"text\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\"}]}],\n    \"generationConfig\": {\n      \"responseModalities\": [\"IMAGE\"],\n      \"imageConfig\": {\"aspectRatio\": \"16:9\", \"imageSize\": \"2K\"}\n    }\n  }'\n```\n\n### 图生图\n\n参考图以 `inlineData`（base64）或 `fileData`（公网 URL）放进 `parts`：\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3-pro-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [\n      {\"text\": \"把背景换成霓虹夜景，保留猫的姿态\"},\n      {\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"<base64>\"}}\n    ]}],\n    \"generationConfig\": {\"responseModalities\": [\"IMAGE\"], \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}}\n  }'\n```\n\n`fileData` 写法：`{\"fileData\": {\"fileUri\": \"https://example-cdn.com/cat.png\"}}`，必须是上游可直接 `GET` 的直链。\n\n### 响应\n\n```json\n{\n  \"candidates\": [{\n    \"content\": {\n      \"role\": \"model\",\n      \"parts\": [{\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"iVBORw0KGgo...\"}}]\n    },\n    \"finishReason\": \"STOP\",\n    \"index\": 0\n  }],\n  \"usageMetadata\": {\n    \"promptTokenCount\": 18,\n    \"candidatesTokenCount\": 1680,\n    \"totalTokenCount\": 1698,\n    \"promptTokensDetails\": [{\"modality\": \"TEXT\", \"tokenCount\": 18}],\n    \"candidatesTokensDetails\": [{\"modality\": \"IMAGE\", \"tokenCount\": 1680}]\n  },\n  \"modelVersion\": \"gemini-3.1-flash-image\"\n}\n```\n\n- 图像在 `parts[].inlineData.data`（base64）。`responseModalities` 含 `TEXT` 时，`parts` 中可能另有 `{\"text\": ...}` 段。\n- `modelVersion` 回显请求路径中的模型名。\n\n保存到文件：\n\n```bash\ncurl -s \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"contents\":[{\"parts\":[{\"text\":\"a red ball on a wooden table\"}]}],\"generationConfig\":{\"responseModalities\":[\"IMAGE\"]}}' \\\n  | python3 -c '\nimport sys, json, base64\nfor p in json.load(sys.stdin)[\"candidates\"][0][\"content\"][\"parts\"]:\n    if \"inlineData\" in p:\n        open(\"out.png\", \"wb\").write(base64.b64decode(p[\"inlineData\"][\"data\"])); break'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `contents[].role` | string | `user` |\n| `contents[].parts[].text` | string | 提示词。画面内容描述；图生图时描述如何修改 |\n| `contents[].parts[].inlineData` | object | 参考图，`{\"mimeType\": \"image/png\", \"data\": \"<base64>\"}` |\n| `contents[].parts[].fileData` | object | 参考图 URL，`{\"fileUri\": \"https://...\"}` |\n| `systemInstruction` | object | 可选，系统指令，与 Gemini 文本调用一致 |\n| `generationConfig.responseModalities` | string[] | `[\"IMAGE\"]` 只出图；`[\"TEXT\",\"IMAGE\"]` 图文混排 |\n| `generationConfig.imageConfig.aspectRatio` | string | `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` |\n| `generationConfig.imageConfig.imageSize` | string | 分辨率档位，各模型可选值见首表，缺省 `1K` |\n\n- `candidateCount` > 1 → `400`：一次只出一张。\n- `tools`、`responseSchema` / `responseMimeType` → `400`：图像模型不支持工具调用与结构化输出。\n- `:streamGenerateContent` → `400`：图像生成不支持流式。\n- 模型不提供的 `imageSize`（如 `gemini-3.1-flash-lite-image` 传 `2K`）→ `400`，**不会静默降档生成**，不产生费用。\n- **按可交付档位选路。** 网关只把请求交给能按所声明档位交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 分辨率档位\n\n| 档位 | 像素量级 | 实测输出（示例） |\n| --- | --- | --- |\n| `512px` | 约 0.25 MP | — |\n| `1K`（缺省） | 约 1 MP | 缺省 → 1408×768 |\n| `2K` | 约 4 MP | `16:9` → 2752×1536 |\n| `4K` | 约 16 MP | `9:16` → 3072×5504 |\n\n档位决定总像素量级，**精确宽高由 `aspectRatio` 决定**；不指定 `aspectRatio` 时缺省为供应商的近似 16:9 输出。\n\n## 3. 完整示例（Python，Google GenAI SDK）\n\n```python\nimport os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(api_key=os.environ[\"MODELGO_API_KEY\"],\n                      http_options={\"base_url\": \"{{ api_endpoint }}\"})\n\nresp = client.models.generate_content(\n    model=\"gemini-3.1-flash-image\",\n    contents=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    config=types.GenerateContentConfig(\n        response_modalities=[\"IMAGE\"],\n        image_config=types.ImageConfig(aspect_ratio=\"16:9\", image_size=\"2K\"),\n    ),\n)\nfor part in resp.candidates[0].content.parts:\n    if part.inline_data:\n        open(\"cat.png\", \"wb\").write(part.inline_data.data)\nprint(resp.usage_metadata.candidates_token_count)\n```\n\n图生图时把 `contents` 换成列表：`[\"把背景换成霓虹夜景\", types.Part.from_bytes(data=open(\"cat.png\",\"rb\").read(), mime_type=\"image/png\")]`。\n\n## 4. 计费口径\n\n- **按 token 计费**：`promptTokensDetails` 中的文本按 `input`、图像按 `image_input`；`candidatesTokensDetails` 中 `IMAGE` 按 `image_output`、`TEXT` 按 `output`。\n- 输出图像 token 随档位增长（实测）：`1K` ≈ 1120，`2K` ≈ 1680，`4K` ≈ 2000。\n- 请求时预授权冻结，响应返回后按 `usageMetadata` 实际值结算。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- 各模型单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `imageSize` 不在该模型可选档位内；`aspectRatio` 不在参数表内；`candidateCount` > 1；带了 `tools` / `responseSchema` / `responseMimeType`；调用了 `:streamGenerateContent`；当前无供应商能出所请求档位 | 按参数表修正，改用 `generateContent` |\n| `parts` 中没有 `inlineData` | `responseModalities` 未含 `IMAGE`，或提示词被安全策略拦截（`finishReason` 非 `STOP`） | 显式传 `[\"IMAGE\"]`；检查 `finishReason` |\n| 参考图未生效 | `fileData.fileUri` 不是公网直链（需鉴权 / 跳转 / 403） | 改用 `inlineData` 或自有 CDN 直链 |\n| 返回 `401` | API Key 无效或未带 `x-goog-api-key` / `Authorization` 头 | 核对 Key |\n","china/zh/models/images/generations.md":"---\ntitle: 图像生成\ndescription: OpenAI 兼容图像生成接口说明。\n---\n\n# 图像生成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\n请求体遵循 OpenAI Images 兼容格式，平台将其透传到支持图像生成的上游 Provider。核心入口是 `POST /v1/images/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\n常见可选字段包括 `size`、`quality`、`n` 等，是否生效取决于实际路由到的上游模型能力。\n\n## 已验证限制（Seedream）\n\n`doubao-seedream-5.0-lite` 在 `size=1024x1024` 时上游拒绝：HTTP 400、`error_class=provider_invalid`，要求像素总数至少 3686400（约 1920×1920）。改用 `2048x2048` 后于 2026-09-10 国内生产返回 200。完整 curl 见[接口清单](../../../quickstart/openapi)。\n","china/zh/models/images/gpt-image-2.md":"---\ntitle: GPT Image（gpt-image-2 / gpt-image-1.5）图像生成 / 编辑（OpenAI Images 原生协议）\ndescription: 按 OpenAI Images API 官方协议调用 gpt-image-2 / gpt-image-1.5：generations 文生图、edits 图生图与蒙版编辑、size / quality 参数、b64_json 响应与按 token 计费口径。OpenAI 官方 SDK 改 base_url 即可直连。\n---\n\n# GPT Image（gpt-image-2 / gpt-image-1.5）图像生成 / 编辑（OpenAI Images 原生协议）\n\n| 模型 | 接口 | 缺省档输出 token（`1024x1024` + `quality: auto`，实测） |\n| --- | --- | --- |\n| `gpt-image-2` | generations / edits | 196 |\n| `gpt-image-1.5` | generations / edits | 4444 |\n\n| 接口 | 能力 | 请求体 | 必填字段 |\n| --- | --- | --- | --- |\n| `POST /v1/images/generations` | 文生图 | JSON | `model`、`prompt` |\n| `POST /v1/images/edits` | 图生图 / 蒙版编辑（多参考图） | `multipart/form-data` | `model`、`prompt`、`image[]` |\n\n两个模型参数集相同、走同一组接口，仅 `model` 字段不同；输出 token 数与单价各不相同（见「计费口径」）。\n\nModelGo 按 OpenAI Images API 的官方路径与请求/响应格式原样接收 `gpt-image-2` / `gpt-image-1.5` 请求，网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。图像**同步返回**，无需轮询。\n\n> 使用 OpenAI 官方 SDK 时，把 `base_url` 指向 `{{ api_endpoint }}/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 1. 创建图像\n\n### 文生图\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-image-2\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    \"size\": \"1536x1024\",\n    \"quality\": \"high\",\n    \"output_format\": \"png\"\n  }'\n```\n\n### 图生图 / 蒙版编辑\n\n`POST {{ api_endpoint }}/v1/images/edits`（`multipart/form-data`）\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=gpt-image-2\" \\\n  -F \"prompt=把背景换成霓虹夜景，保留猫的姿态\" \\\n  -F \"image[]=@./cat.png\" \\\n  -F \"mask=@./mask.png\" \\\n  -F \"size=1024x1024\" \\\n  -F \"quality=medium\" \\\n  -F \"input_fidelity=high\"\n```\n\n- `image[]` 可重复出现，一次传入多张参考图。\n- `mask` 可选，PNG，尺寸必须与第一张 `image[]` 一致；透明区域为需要重绘的区域。\n\n### 响应\n\n```json\n{\n  \"created\": 1757318400,\n  \"data\": [{\"b64_json\": \"iVBORw0KGgoAAAANSUhEUgAA...\"}],\n  \"usage\": {\n    \"input_tokens\": 17,\n    \"input_tokens_details\": {\"text_tokens\": 17, \"image_tokens\": 0},\n    \"output_tokens\": 5488,\n    \"output_tokens_details\": {\"image_tokens\": 5488, \"text_tokens\": 0},\n    \"total_tokens\": 5505\n  }\n}\n```\n\n图像始终以 `data[].b64_json`（base64）返回。保存到文件：\n\n```bash\ncurl -s {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gpt-image-2\",\"prompt\":\"a red ball on a wooden table\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.png\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 全部 | `gpt-image-2` / `gpt-image-1.5` |\n| `prompt` | string | 全部 | 必填。画面内容描述；edits 中描述要如何修改 |\n| `image[]` | file | edits | 必填。一张或多张参考图（png / jpeg / webp） |\n| `mask` | file | edits | 可选。PNG 蒙版，尺寸与图像一致，透明区域为重绘区 |\n| `input_fidelity` | string | edits | 对参考图的保真度，`low` / `high` |\n| `n` | int | 全部 | 生成张数，缺省 `1` |\n| `size` | string | 全部 | `1024x1024` / `1536x1024` / `1024x1536` / `auto`，缺省 `auto`。更大尺寸取决于供应商是否提供 |\n| `quality` | string | 全部 | `low` / `medium` / `high` / `auto`，缺省 `auto`。直接决定输出 token 数 |\n| `output_format` | string | 全部 | `png` / `jpeg` / `webp` |\n| `output_compression` | int | 全部 | `0`–`100`，仅对 `jpeg` / `webp` 生效 |\n| `background` | string | 全部 | `opaque` / `transparent` / `auto` |\n| `moderation` | string | 全部 | 内容审核强度，透传 |\n\n- **`response_format` 不适用于 gpt-image 系列。** 网关会在转发前剥离该字段，不报错；图像始终以 `b64_json` 返回，不提供 `url` 形态。\n- `size` / `quality` 不在上表内、缺 `prompt` → HTTP `400`，不计费。\n- **按可交付档位选路。** 网关只把请求交给能按所声明 `size` / `quality` 交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 输出 token 参考（实测）\n\n| 模型 | `size` | `quality` | `output_tokens_details.image_tokens` |\n| --- | --- | --- | --- |\n| `gpt-image-2` | `1024x1024` | `auto`（缺省） | 196 |\n| `gpt-image-2` | `1536x1024` | `high` | 5488 |\n| `gpt-image-1.5` | `1024x1024` | `auto`（缺省） | 4444 |\n\n输出 token 由模型、尺寸与质量档共同决定：gpt-image-2 的 `high` 档比缺省档高一个数量级以上；同为缺省档，gpt-image-1.5 的输出 token 是 gpt-image-2 的 20 倍以上。两个模型的 token 数与单价都不同，换模型前请核算成本。\n\n## 3. 完整示例（Python，OpenAI 官方 SDK）\n\n```python\nimport base64, os\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/v1\")\n\n# 文生图\nr = client.images.generate(model=\"gpt-image-2\", prompt=\"一只橘猫坐在窗台上，胶片质感\",\n                           size=\"1536x1024\", quality=\"high\", output_format=\"png\")\nopen(\"cat.png\", \"wb\").write(base64.b64decode(r.data[0].b64_json))\nprint(r.usage.output_tokens_details.image_tokens)\n\n# 图生图（蒙版编辑）\nwith open(\"cat.png\", \"rb\") as img, open(\"mask.png\", \"rb\") as mask:\n    e = client.images.edit(model=\"gpt-image-2\", prompt=\"把背景换成霓虹夜景\",\n                           image=[img], mask=mask, size=\"1024x1024\", quality=\"medium\")\nopen(\"cat-neon.png\", \"wb\").write(base64.b64decode(e.data[0].b64_json))\n```\n\n## 4. 计费口径\n\n- **按 token 计费**，三个价目：文本输入（`input`）、图像输入（`image_input`）、图像输出（`image_output`），单位为每百万 token。输出中的图像部分按 `image_output` 单价计。\n- gpt-image-2 与 gpt-image-1.5 各有独立价卡，且同一档位的输出 token 数差异显著（缺省档 196 对 4444），同一请求在两个模型上的费用不可互推。\n- 请求时预授权冻结，响应返回后按 `usage` 中的实际 token 结算：`input_tokens_details.text_tokens` → `input`，`input_tokens_details.image_tokens` → `image_input`，`output_tokens_details.image_tokens` → `image_output`。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- 各价目以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `size` / `quality` 不在参数表内；缺 `prompt`；edits 缺 `image[]` 或 `mask` 尺寸与图像不一致；当前无供应商能出所请求档位 | 按参数表修正或换档位 |\n| 传了 `response_format: \"url\"` 仍返回 `b64_json` | gpt-image 系列不支持该字段，网关静默剥离 | 从 `data[].b64_json` 解码保存 |\n| 返回 `429` | 触发速率限制 | 退避重试；如需更高配额联系平台 |\n| 返回 `401` | API Key 无效或未带 `Authorization` 头 | 核对 Key |\n","china/zh/models/images/qwen-image.md":"---\ntitle: 千问图像生成与编辑 3.0（百炼原生协议）\ndescription: 调用 qwen-image-3.0 / qwen-image-3.0-pro：OpenAI 兼容与百炼 DashScope 原生两条同步入站通道、文生图与图生图（1-3 张参考图）、size 的两种分隔符写法、1k / 2k 分辨率档位与按张计费口径。百炼官方 SDK 改 base_url 即可直连。\n---\n\n# 千问图像生成与编辑 3.0（百炼原生协议）\n\n## 模型\n\n| 模型 | 输出分辨率 | 说明 |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | 总像素 512×512 – 2048×2048 | Pro 系列，2k 档单价高于 1k 档 |\n| `qwen-image-3.0` | 同上 | 标准版，两个档位同价 |\n\n两个模型都同时支持**文生图（T2I）**和**图生图 / 图像编辑（I2I）**：不传参考图是文生图，传 1–3 张参考图是图生图。图像**同步返回**，无需轮询。\n\n> **不支持异步任务通道。** 这一族只在同步接口上服务；打 `/v1/content_generation/tasks` 会被拒。\n\n## 两条入站通道\n\n同一个模型有两种调用写法，能力完全一致，按你现有代码的形状选：\n\n| 通道 | 路径 | 适合谁 |\n| --- | --- | --- |\n| OpenAI 兼容 | `POST /v1/images/generations` | 已按 OpenAI Images 协议或 OpenAI SDK 开发的应用，只改 `base_url` 与 `model` |\n| 百炼原生 | `POST /api/v1/services/aigc/multimodal-generation/generation` | 已在用百炼 DashScope SDK 的应用，只改 `base_url` |\n\n> **两条通道的 `size` 分隔符不同，且互不接受**：OpenAI 兼容通道用字母 `x`（`1024x1024`），百炼原生通道用星号 `*`（`1024*1024`）。写错的那一侧会返回 `400` 并点名正确的分隔符，**不会**被静默改写 —— 这是为了让协议混用尽早显形，而不是在别处出更难查的问题。\n\n## 1. OpenAI 兼容通道\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### 文生图\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，午后光线，胶片质感\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### 图生图 / 图像编辑\n\n不用 multipart，参考图放在请求体顶层的 `image` 字段：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"保留这位女性的面部特征，把服装换成香槟色真丝衬衫与深灰西装外套\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- 图像格式为 PNG，**链接有效期 24 小时**，请及时下载，不要持久化该 URL。\n- `usage` 是**图片张数与档位**，不是 token 用量 —— 这一族的计费完全按张，见「计费口径」。\n- 传 `response_format: \"b64_json\"` 不会报错，但会被忽略，响应中仍是图像 URL。\n\n### 使用 OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # 出图耗时较长，实测单张 40-60 秒\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # 扩展字段走 extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` 不是 OpenAI 官方参数，用 OpenAI SDK 时通过 `extra_body` 传入；直接发 HTTP 请求时放在请求体顶层即可。\n\n## 2. 百炼原生通道\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\n请求与响应两头都是百炼原样的形状，网关不做翻译。\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### 这条通道的约束\n\n- `input.messages` **有且只有一个**对象，`role` 必须是 `user`（仅支持单轮对话）。\n- `content` 里**有且只有一个** `{\"text\": ...}`，不传或传多个都会 `400`。\n- `{\"image\": ...}` 0–3 个：0 个是文生图，1–3 个是图生图。\n- 生成参数放在 `parameters` 下（不是顶层）：`size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`。\n- 使用百炼官方 SDK（`dashscope`）时，把 `dashscope.base_http_api_url` 指向 `{{ api_endpoint }}/api/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 3. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt`（兼容通道）/ `content[].text`（原生通道） | string | 必填，非空。支持中英文，建议不超过 4500 token |\n| `image`（兼容通道）/ `content[].image`（原生通道） | string / string[] | 参考图，1–3 张。**不能传 `null` 或空数组** |\n| `size` | string | 兼容通道 `宽x高`，原生通道 `宽*高`；不传则由模型按提示词自动推荐分辨率 |\n| `n` | int | 输出张数 1–6，缺省 1。**必须是整数**，传字符串形式（如 `\"1\"`）返回 `400` |\n| `negative_prompt` | string | 反向提示词 |\n| `seed` | int | 随机数种子，`0` – `2147483647`。固定种子可让结果相对稳定 |\n| `prompt_extend` | boolean | 是否开启提示词智能改写，缺省 `true`（建议开启） |\n| `prompt_extend_mode` | string | `direct`（缺省，T2I / I2I 均支持）/ `agent`（更精细，**仅文生图**） |\n| `enable_thinking` | boolean | 思考模式，缺省 `true`。提升出图质量但增加耗时。仅在 `prompt_extend=true` 时生效 |\n| `watermark` | boolean | 是否加水印，缺省 `false` |\n\n### 参数校验在调用前完成\n\n下列请求在**创建时**就被拒（HTTP `400`），不会打到上游、不产生费用：\n\n- `n` 不是 1–6 的整数，或写成了字符串 / 小数；\n- `size` 的总像素不在 512×512 – 2048×2048 之间，或宽高比超出 1:8 – 8:1；\n- `size` 用了另一条通道的分隔符（错误信息会点名该用 `x` 还是 `*`）；\n- `image` 为 `null`、空数组，或超过 3 张；\n- `prompt_extend_mode: \"agent\"` 与 `image` 同时出现（APE 仅支持文生图）；\n- `seed` 超出 `0` – `2147483647`；\n- 原生通道上 `messages` 不是恰好一个、或 `content` 里的 `text` 不是恰好一个。\n\n### 参考图的要求\n\n- 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF。\n- 建议宽高均在 384 – 2048 像素之间，单张不超过 10 MB。\n- 支持公网 URL（HTTP / HTTPS）或 Base64（`data:{MIME_type};base64,{base64_data}`）。\n- 公网 URL 必须是上游能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。部分站点对非浏览器抓取返回 403，会导致请求失败。\n\n## 4. 计费口径\n\n**按张计费，不按 token。** 输入（参考图）与输出（生成图）分别计价，各自再分 1k / 2k 两档：\n\n| 模型 | 输出档位 | 输出单价 | 输入单价 |\n| --- | --- | --- | --- |\n| `qwen-image-3.0-pro` | 1k | 0.25 元/张 | 0.02 元/张 |\n| `qwen-image-3.0-pro` | 2k | 0.50 元/张 | 0.02 元/张 |\n| `qwen-image-3.0` | 1k | 0.18 元/张 | 0.02 元/张 |\n| `qwen-image-3.0` | 2k | 0.18 元/张 | 0.02 元/张 |\n\n**档位按「输出」像素面积判定**：面积 ≤ 2,250,000（即 1500×1500）为 `1k`，更大为 `2k`。**输入图的档位同样按输出面积判定**，不是按参考图自己的尺寸 —— 这是上游的口径。响应 `usage` 里的 `output_image_type` / `input_image_type` 就是本次实际命中的档位。\n\n计费金额 = 输出张数 × 该档输出单价 + 输入张数 × 输入单价。几个实测例子（国内生产，2026-09-11）：\n\n| 请求 | `usage` | 结算金额 |\n| --- | --- | --- |\n| `qwen-image-3.0`，`1024x1024`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_1k` | 0.18 元 |\n| `qwen-image-3.0`，`1024x1024`，`n=2`，文生图 | `output_image_count: 2`，`qima_output_1k` | 0.36 元 |\n| `qwen-image-3.0-pro`，`1024x1024`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_1k` | 0.25 元 |\n| `qwen-image-3.0-pro`，`2048x2048`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_2k` | 0.50 元 |\n\n**文生图不产生输入费用**：没有参考图时 `input_image_count` 为 0，只结算输出张数。\n\n## 5. 完整示例（Python，百炼官方 SDK）\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫，背景换成现代简约咖啡店\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","china/zh/models/images/seedream.md":"---\ntitle: Seedream 图像生成（火山方舟原生协议）\ndescription: 按火山引擎方舟 Images API 官方协议调用 Seedream 系列（doubao-seedream-5.0-pro / 5.0-lite / 5.0 / 4.5）：文生图 / 多图参考、各模型 size 档位与像素写法、url / b64_json 响应与按张计费口径。方舟官方 SDK 改 base_url 即可直连。\n---\n\n# Seedream 图像生成（火山方舟原生协议）\n\n## 模型与档位\n\n| 模型 | 缺省 `size` | 可用 `size` | 典型输出（实测） |\n| --- | --- | --- | --- |\n| `doubao-seedream-5.0-pro` | `2K` | `1K` / `1.5K` / `2K`，或 `WxH` | `1K` ≈ 1152×864；`1.5K` ≈ 1792×1344；`2K` + 16:9 提示 → 2816×1584 |\n| `doubao-seedream-5.0-lite` | `2K` | `2K` / `3K` / `4K`，或总像素 ≥ 3,686,400 的 `WxH` | `2K` → 2048×2048；`3K` → 3072×3072；`4K` → 4096×4096 |\n| `doubao-seedream-5.0` | `2K` | 同 5.0 lite | 同 5.0 lite |\n| `doubao-seedream-4.5` | `2K` | `2K` / `4K`，或总像素 ≥ 3,686,400 的 `WxH`（**不提供 `3K`**） | `2K` → 2048×2048；`4K` → 4096×4096 |\n\n- 四个模型走同一入口 `POST /api/v3/images/generations`，能力均为文生图、图生图（单图 / 多图参考），必填 `model`、`prompt`。\n- `doubao-seedream-5.0` 是 `doubao-seedream-5.0-lite` 的别名：方舟没有独立的 5.0 模型，二者档位与单价完全一致。\n- 5.0 pro **不提供** `3K` / `4K`；5.0 lite / 5.0 / 4.5 **不提供** `1K` / `1.5K`（方舟要求总像素 ≥ 3,686,400）；4.5 另外**不提供** `3K`。表外档位在创建时被拒（HTTP `400`），不渲染、不计费。\n- 5.0 pro 的 `1.5K` 与 `1K` 同价（方舟定价），且只有部分供应商能出该档位，可用线路少于其他档位。\n\nModelGo 按火山引擎方舟 **Images API** 的官方路径与请求/响应格式原样接收 Seedream 请求，网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。图像**同步返回**，无需轮询。\n\n> 使用方舟官方 SDK（`volcenginesdkarkruntime`）时，把 `base_url` 指向 `{{ api_endpoint }}/api/v3`、`api_key` 换成 ModelGo API Key 即可。\n\n## 1. 创建图像\n\n`POST {{ api_endpoint }}/api/v3/images/generations`\n\n### 文生图（5.0 pro）\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，16:9 横构图，胶片质感\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### 文生图（5.0 lite）\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### 图生图 / 多图参考\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"把第一张图的猫放到第二张图的霓虹街景里\",\n    \"image\": [\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n    \"size\": \"1280x720\",\n    \"response_format\": \"b64_json\"\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"model\": \"doubao-seedream-5.0-pro\",\n  \"created\": 1757318400,\n  \"data\": [{\"url\": \"https://ark-content-generation.tos-cn-beijing.volces.com/...\", \"size\": \"2816x1584\", \"output_format\": \"jpeg\"}],\n  \"usage\": {\"generated_images\": 1, \"input_images\": 0, \"output_tokens\": 17424, \"total_tokens\": 17424}\n}\n```\n\n- `model` 始终回显你请求的逻辑模型名（如 `doubao-seedream-5.0-lite`），不是方舟内部的版本 id（形如 `doubao-seedream-5-0-260128` / `doubao-seedream-4-5-251128` / `doubao-seedream-5-0-pro-260628`）。\n- `response_format` 缺省 `url`，**链接 24 小时内有效**，请及时下载，不要持久化该 URL。\n- `response_format: \"b64_json\"` 时 `data[].b64_json` 直接给出 base64 图像。\n- `data[].size` 是实际输出像素，`output_format` 是实际编码格式。\n- `usage.output_tokens` / `total_tokens` 为上游回显的参考值，**不参与计费**；结算只看 `usage.generated_images`。\n\n保存到文件：\n\n```bash\ncurl -s {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedream-5.0-lite\",\"prompt\":\"a red ball on a wooden table\",\"size\":\"2K\",\"response_format\":\"b64_json\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.jpg\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `doubao-seedream-5.0-pro` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0` / `doubao-seedream-4.5` |\n| `prompt` | string | 必填。画面内容描述；使用档位写法时在此描述构图比例 |\n| `image` | string / string[] | 参考图 URL（单图）或 URL 数组（多图参考），必须是上游可直接 `GET` 的公网直链 |\n| `size` | string | 分辨率档位（缺省 `2K`；各模型可用档位见「模型与档位」），或显式像素 `WxH`（如 `1280x720`、`2560x1440`） |\n| `seed` | int | 随机种子 |\n| `guidance_scale` | number | 提示词贴合度 |\n| `watermark` | boolean | 是否加水印，缺省 `true` |\n| `response_format` | string | `url`（缺省，24 小时有效）/ `b64_json` |\n| `output_format` | string | 输出编码格式，透传 |\n\n- `sequential_image_generation: \"auto\"`（组图）在 5.0 pro 上不支持 → `400`。\n- `stream: true` → `400`：不支持流式。\n- 请求体中出现上表之外的字段 → `400`，不会被忽略。\n- **按可交付档位选路。** 网关只把请求交给能按所声明 `size` 交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 分辨率档位\n\n| 模型 | `size` 写法 | 输出 | 实测示例 |\n| --- | --- | --- | --- |\n| 5.0 pro | `1K` / `1.5K` / `2K`（缺省） | 档位决定总像素量级，宽高比由 `prompt` 中的构图描述决定 | `\"2K\"` + 16:9 提示 → 2816×1584；`\"1.5K\"` → 1792×1344；`\"1K\"` → 1152×864 |\n| 5.0 lite / 5.0 | `2K`（缺省）/ `3K` / `4K` | 档位决定输出边长 | `\"2K\"` → 2048×2048；`\"3K\"` → 3072×3072；`\"4K\"` → 4096×4096 |\n| 4.5 | `2K`（缺省）/ `4K` | 同上；4.5 不提供 `3K` | `\"2K\"` → 2048×2048；`\"4K\"` → 4096×4096 |\n| 全部 | `WxH` | 精确按指定宽高输出；宽高比在 1/16 – 16 之间。5.0 lite / 5.0 / 4.5 要求总像素 ≥ 3,686,400 | 5.0 pro：`\"1280x720\"` → 1280×720；5.0 lite：`\"2560x1440\"` → 2560×1440 |\n\n- 表外的 `size`（该模型不提供的档位、像素低于下限或宽高比越界）在创建时被拒（HTTP `400`），不会静默降档或升档生成，也不产生费用。\n\n### 参考图的要求\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。\n- 部分站点直链对非浏览器抓取返回 403，会导致请求失败，不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 完整示例（Python，方舟官方 SDK）\n\n```python\nimport os, requests\nfrom volcenginesdkarkruntime import Ark\n\nclient = Ark(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/api/v3\")\n\n# 5.0 pro：档位 + 提示词里的构图比例\nr = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"一只橘猫坐在窗台上，16:9 横构图，胶片质感\",\n                           size=\"2K\", watermark=False)\nimg = r.data[0]\nprint(r.model, img.size, r.usage.generated_images)\nopen(\"cat.jpg\", \"wb\").write(requests.get(img.url, timeout=60).content)\n\n# 5.0 lite：2K 缺省档（2048x2048）\nl = client.images.generate(model=\"doubao-seedream-5.0-lite\",\n                           prompt=\"一只橘猫坐在窗台上，胶片质感\",\n                           size=\"2K\", watermark=False)\nopen(\"cat-lite.jpg\", \"wb\").write(requests.get(l.data[0].url, timeout=60).content)\n\n# 多图参考\ne = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"把第一张图的猫放到第二张图的霓虹街景里\",\n                           image=[\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n                           size=\"1280x720\")\nopen(\"cat-neon.jpg\", \"wb\").write(requests.get(e.data[0].url, timeout=60).content)\n```\n\n## 4. 计费口径\n\n- **按张计费**：以 `usage.generated_images` 为结算数量，每张固定单价，与 `size` 档位无关。\n- **每个模型一个单价**：5.0 pro / 5.0 lite / 5.0 / 4.5 在控制台「模型列表」中各有一张价卡，单价不同（5.0 与 5.0 lite 同价）。\n- 请求时预授权冻结，响应返回后按实际生成张数结算。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- HTTP `200` 但 `data[]` 中没有任何 `url` / `b64_json`（例如各条目均为 `error`）不计费。\n- 内容审核拒绝（如 `OutputImageSensitiveContentDetected`）返回 HTTP `400` 并携带上游错误码，不计费、不重试。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `size` 不在档位表内或 `WxH` 越界；缺 `prompt`；带了 `sequential_image_generation` / `stream` 或其他不支持的字段；当前无供应商能出所请求档位 | 按参数表修正或换档位 |\n| 返回 `400`（5.0 lite / 5.0 / 4.5） | `size` 低于该模型下限：传了 `1K` / `1.5K`，或 `WxH` 总像素 < 3,686,400；4.5 传了 `3K` | 改用 `2K` / `4K`（lite / 5.0 还可用 `3K`），或 `WxH` 总像素 ≥ 3,686,400（如 `2560x1440`） |\n| 返回 `400`（5.0 pro） | 传了 `3K` / `4K`，5.0 pro 不提供该档位 | 改用 `1K` / `1.5K` / `2K` 或 `WxH` |\n| 返回 `400`，`metadata.upstream_error_code` 为 `OutputImageSensitiveContentDetected` 等 | 上游内容审核拒绝，不计费、不重试 | 修改 `prompt` / 参考图后重试 |\n| 生成失败 | 上游无法下载 `image` 中的 URL | 换成公网可直接下载的直链 |\n| `data[].url` 下载 `403` / `404` | 链接已过 24 小时有效期 | 重新生成；或改用 `response_format: \"b64_json\"` |\n| 返回 `401` | API Key 无效或未带 `Authorization` 头 | 核对 Key |\n","china/zh/models/realtime/api.md":"---\ntitle: Realtime API 参考\ndescription: GET /api-ws/v1/realtime（WebSocket）的握手、事件与音频格式说明。\n---\n\n# Realtime API 参考：`GET /api-ws/v1/realtime`\n\n本接口是一个 WebSocket 长连接。网关把百炼 **Qwen-Omni-Realtime** 协议原样双向转发，**不做协议转换**；事件字段的完整定义与工具调用（Function Calling / MCP）事件以百炼官方[客户端事件](https://help.aliyun.com/zh/model-studio/client-events)与[服务端事件](https://help.aliyun.com/zh/model-studio/server-events)为准。本页覆盖接入所需的握手、鉴权、事件清单与音频约定。\n\n## 请求\n\n| 项 | 值 |\n| --- | --- |\n| 方法 | `GET`（WebSocket 升级） |\n| 路径 | `/api-ws/v1/realtime` |\n| 完整地址 | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<逻辑模型名>` |\n| Query | `model`（必填）——平台逻辑模型名，不是上游模型名 |\n| Header | `Authorization: Bearer <mgk_ API Key>`（必填） |\n| Header | `X-Request-ID`（可选）——透传到调用日志，`request_id` 以 `gw_rt_` 开头 |\n\n只有 `public_protocols` 声明了 `dashscope_realtime` 的逻辑模型才能走本入口。\n\n## 握手错误码 {#handshake-errors}\n\n握手（升级为 WebSocket 之前）失败时，以 HTTP 状态码返回，body 为：\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | 触发条件 | 实测 message（cn 生产，2026-10-08） |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | 未携带 API Key | `missing api key` |\n| 401 | `unauthorized` | Key 无效 / 已禁用 | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | 模型不在目录 | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | 模型未声明 `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | 策略（含回落链）中没有该模型的路由 | `no route for model <model>` |\n| 503 | `no_provider` | 有路由但无可用上游实例 | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | 预授权失败（余额/预算不足） | `billing: insufficient funds` |\n\n握手通过（HTTP 101）后再出现的问题，会以带内 `error` 事件下发，然后关闭连接：\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## 会话配置 `session.update`\n\n建连后服务端先发 `session.created`，客户端用 `session.update` 覆盖配置，配置合法则回 `session.updated`。常用字段：\n\n| 字段 | 可选值 | 默认 |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | 见百炼音色列表 | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | 服务端 VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | 任意文本 | 空 |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | 开启 |\n\n`turn_detection: null` 表示关闭服务端 VAD，改由客户端手动提交与触发响应。\n\n## 客户端事件\n\n| 事件 | 作用 |\n| --- | --- |\n| `session.update` | 更新会话配置（模态、音色、音频格式、VAD、instructions 等） |\n| `input_audio_buffer.append` | 追加 Base64 音频到输入缓冲区 |\n| `input_image_buffer.append` | 追加 Base64 图片（JPG/JPEG，需先发过音频） |\n| `input_audio_buffer.commit` | 手动模式下提交音频缓冲区（提交不触发响应） |\n| `input_audio_buffer.clear` | 清空音频缓冲区 |\n| `conversation.item.create` | 创建对话项：纯文本输入、`function_call_output`、`mcp_approval_response` |\n| `response.create` | 触发一次模型响应 |\n| `response.cancel` | 取消正在进行的响应（打断） |\n\n## 服务端事件\n\n| 事件 | 说明 |\n| --- | --- |\n| `session.created` / `session.updated` | 会话建立 / 配置生效 |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD 检测到用户开始 / 停止说话（打断依据） |\n| `input_audio_buffer.committed` / `cleared` | 音频缓冲区提交 / 清空 |\n| `conversation.item.created` | 对话项已创建 |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | 输入语音转写（流式预览 / 最终结果） |\n| `response.created` | 一轮响应开始 |\n| `response.output_item.added` / `response.content_part.added` | 输出项 / 内容片段开始 |\n| `response.text.delta` / `response.text.done` | 仅文本模式的流式 / 完整文本 |\n| `response.audio_transcript.delta` / `.done` | 含音频模式下，音频对应的文本 |\n| `response.audio.delta` / `response.audio.done` | Base64 输出音频（24 kHz PCM）/ 音频结束 |\n| `response.output_item.done` / `response.content_part.done` | 输出项 / 内容片段完成 |\n| `response.done` | 一轮响应结束，`response.usage` 携带分模态 token 用量 |\n\n工具调用（`response.function_call_arguments.delta` / `.done`）与 MCP 相关事件（`mcp_*`）字段见百炼服务端事件文档。\n\n一次完整语音问答的实测事件序（cn 生产，2026-10-08）：\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## 音频格式\n\n| 方向 | 格式 | 事件 / 字段 |\n| --- | --- | --- |\n| 上行（输入） | 16000 Hz、16-bit 小端、单声道 PCM，Base64 | `input_audio_buffer.append` 的 `audio` |\n| 下行（输出） | 24000 Hz、16-bit 小端、单声道 PCM，Base64 | `response.audio.delta` 的 `delta` |\n\n实测满 100 ms 一包推送输入音频（3200 字节 / 帧）最稳。`input_audio_buffer.append` 只入缓冲，不触发响应；是否提交由 VAD 或客户端 `input_audio_buffer.commit` 决定。\n\n## VAD 与打断\n\n- `turn_detection` 非 `null` 时，服务端自动检测语音起止并在静音 `silence_duration_ms`（默认 800ms）后自动提交、触发响应。\n- 用户再次说话：服务端下发 `input_audio_buffer.speech_started` → 客户端**停止播放**并发 `response.cancel` → 收到 `response.done`（cancelled）→ 新一轮。\n- `turn_detection: null` 为手动模式：客户端在录音结束后依次发送 `input_audio_buffer.commit`（等 `input_audio_buffer.committed`）与 `response.create`。\n\n## 用量与计费\n\n每轮响应的 `response.done.response.usage` 携带分模态 token：\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\n网关按整段连接的累计用量在关闭时结算：连接时按会话级预估预授权（当前约 ¥1.2，余额不足则握手 `402`），关闭连接后按实际用量多退少补，无用量则释放预授权。详见[使用指南](./guide#billing)。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 上游限流 | 60 RPM |\n\n## 相关\n\n- [实时语音（Realtime）模型使用指南](./guide)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","china/zh/models/realtime/guide.md":"---\ntitle: 实时语音（Realtime）模型\ndescription: 通过 WebSocket 接入 Qwen-Omni-Realtime，实现实时语音对话、打断与全模态输入。\n---\n\n# 实时语音（Realtime）模型\n\nRealtime 类模型**不走** `/v1/chat/completions`，只能通过 WebSocket 长连接调用。网关把百炼 Qwen-Omni-Realtime 协议**原样双向转发**，不做任何协议转换：你按百炼协议发事件，也按百炼协议收事件。本文给出接入方式、可运行的最小示例与计费口径；逐字段的事件与错误定义见[API 参考](./api)。\n\n## 能做什么\n\n- **实时语音对话**：边说边回，端到端流式返回文本与音频。\n- **语音打断**：用户再次开口时，服务端下发 `input_audio_buffer.speech_started`；客户端停播并发 `response.cancel` 打断当前回复。\n- **全模态输入**：流式音频、图片（可由视频抽帧实时采集）、纯文本。\n- **文本 + 音频输出**：模型同时产出文本与语音。\n\n## 适用模型\n\n一个逻辑模型要能走本入口，必须在模型目录的 `public_protocols` 中声明 `dashscope_realtime`。目前上架的 realtime 模型是 `qwen3.8-omni-flash-realtime`（以模型广场实际上架为准）。可在 [{{ console_endpoint }}]({{ console_endpoint }}) 的模型广场确认某个模型是否提供了该协议。\n\n## 接入\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<逻辑模型名>`（必填） |\n| 鉴权 | `Authorization: Bearer <mgk_ API Key>` |\n| 请求 ID | 可选 `X-Request-ID`；调用日志里 `request_id` 以 `gw_rt_` 开头 |\n\n握手阶段的失败会直接返回 HTTP 状态码（如 Key 无效 `401 unauthorized`、模型未声明 realtime 协议 `403 model_protocol_not_offered`、余额不足 `402`），完整清单见[API 参考](./api#handshake-errors)。\n\n## 最小示例\n\n下面示例在**服务端**运行：用 `mgk_` API Key 建连，配置会话，推送一段 16 kHz PCM 语音，提交后请求回复，并把返回的 24 kHz PCM 写入 `reply.pcm`。\n\n:::note\n- 浏览器原生 `WebSocket` 构造器**不能携带 `Authorization` 头**，所以不能把 API Key 直接放进浏览器连接。\n- 浏览器采集麦克风后，需经你自己的服务端中转（服务端持有 Key 并建连转发），或使用具备鉴权的服务端代理。\n- 下面 Python / Node.js 示例均为服务端代码，可直接复制运行。\n:::\n\n准备输入：把麦克风录音或一段 **16 kHz、16-bit 小端、单声道、无文件头**的 PCM 存为 `input.pcm`。若手上是 WAV，先提取裸 PCM：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython（`pip install websocket-client`）：\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js（`npm install ws`）：\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\n把返回的 `reply.pcm`（24 kHz、16-bit、单声道）封装成可播放的 WAV：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\n只想验证链路时，也可以不传音频：发送一条 `conversation.item.create`（`content` 为 `input_text`），再发 `response.create`，即可只拿文本回复。\n\n## 会话配置\n\n建连后服务端先发 `session.created`（含默认配置），客户端用 `session.update` 覆盖。常用字段：\n\n| 字段 | 说明 |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]`（默认，文本+音频）或 `[\"text\"]`（仅文本） |\n| `voice` | 输出音色，默认 `Tina`；建议使用 `audio.output.voice` |\n| `turn_detection` | 服务端 VAD：`{\"type\":\"server_vad\"}` 或 `{\"type\":\"semantic_vad\"}`；设为 `null` 由客户端手动 commit |\n| `audio.input.format` | 输入音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | 输出音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | 系统人设 |\n| `audio.input.transcription` | 输入转写，服务端会自动开启（模型 `qwen3-asr-flash-realtime`） |\n\n历史兼容字段 `input_audio_format` / `output_audio_format` 仍可用，但新接入建议使用 `audio.input.format` / `audio.output.format`。\n\n## 打断\n\n`turn_detection` 非 `null` 时由服务端 VAD 驱动轮次。用户再次开口会触发：\n\n1. 服务端下发 `input_audio_buffer.speech_started`；\n2. 客户端**停止播放**已缓冲的回复音频，并发送 `response.cancel`；\n3. 服务端随后下发 `response.done`（状态为 cancelled），开始新一轮。\n\n手动模式（`turn_detection: null`）下，客户端负责在录音结束后发送 `input_audio_buffer.commit` 与 `response.create`。\n\n## 计费 {#billing}\n\n- **按 token 分模态计价**：输入分文本/图片/视频与音频两档，输出分文本与音频两档。输出语音时，音频与其对应的文本**分别**计费。\n- **连接时预授权**：建连时按一个会话级预估冻结一笔余额（当前配置约 ¥1.2）。余额不足以覆盖预授权时，握手直接返回 `402`，不建立连接。\n- **关闭连接后按实际用量结算**：按本次连接内所有 `response.done` 的 `usage` 累计结算，多退少补；整段会话没有产生任何用量时释放预授权、不扣费。\n\n价格以控制台模型页为准；例如国内生产 `qwen3.8-omni-flash-realtime` 的单价（元/百万 token）：输入 文本/图片/视频 `1.5`、输入音频 `6`、输出文本 `4.5`、输出音频 `12`。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制；到达上限即关闭连接并结算） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 音频历史 | 最多 100 轮 / 累计 600 秒 |\n| 视频历史 | 最多 50 轮 / 累计 240 秒 |\n| 上游限流 | 60 RPM |\n\n## 下一步\n\n- [API 参考：`GET /api-ws/v1/realtime`](./api)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","china/zh/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: 对候选文档按相关性重排序的 Rerank 接口。\n---\n\n# Rerank\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | 对文档按与查询的相关性重排序 |\n| `POST` | `/v1/reranks` | 同上（别名，等价于 `/v1/rerank`） |\n\nRerank 接口接收一段查询与若干候选文档，按相关性返回排序后的结果，常用于检索增强（RAG）场景的精排。`/v1/rerank` 与 `/v1/reranks` 是同一能力的两条等价路径。\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"ModelGo 支持哪些协议\",\n    \"documents\":[\n      \"兼容 OpenAI 与 Anthropic 协议\",\n      \"今天的天气不错\",\n      \"支持图像、视频、向量、音频能力\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；请求体按上游 Rerank 协议透传，具体字段（如 `top_n`、`return_documents`）是否生效取决于路由到的上游模型。\n- 返回结果通常包含每条文档的相关性得分与排序序号。\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","china/zh/models/text/generation.md":"---\ntitle: 文本生成\ndescription: OpenAI Responses、Chat Completions 兼容入口与 Anthropic Messages 的统一说明。\n---\n\n# 文本生成\n\n文本能力当前覆盖以下公开入口，推荐优先使用 `POST /v1/responses`，其余入口用于兼容已有 SDK 和原生 Claude 客户端。\n\n| 协议 | 方法与路径 | 用途 |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | 新项目优先使用的统一文本生成接口 |\n| OpenAI | `POST /v1/chat/completions` | 兼容大量现有 OpenAI SDK 的对话补全接口 |\n| OpenAI | `POST /v1/completions` | 旧版文本补全接口，仅用于兼容历史调用链 |\n| Anthropic | `POST /v1/messages` | Claude 原生消息格式接口 |\n| OpenAI | `GET /v1/models` | 查询当前路由可用的逻辑模型清单 |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"用三句话介绍 ModelGo。\"\n  }'\n```\n\n适合新接入和统一封装场景。请求体、流式返回和 `usage` 字段遵循 OpenAI Responses 兼容格式。\n\n## OpenAI Chat Completions 兼容入口 {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合已经绑定 OpenAI SDK 或历史对话补全调用链的客户端。推荐新项目优先迁移到 `POST /v1/responses`。\n\n## OpenAI Completions（旧版补全）\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"用三句话介绍 ModelGo。\",\n    \"max_tokens\":256\n  }'\n```\n\n旧版文本补全接口，仅用于兼容仍在使用 `prompt` 的历史调用链，新项目请使用上面的 Responses / Chat Completions。`stream` 同样以 SSE 返回。多数当前对话模型未声明此协议：`qwen3.6-flash` 实测 HTTP 400、`model_protocol_not_offered`。\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合直接复用 Claude 原生消息格式的客户端。该入口保持 `/v1/messages` 的事件流语义，不会在网关侧改造成 OpenAI SSE 帧。\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` 返回该 API Key 绑定策略所允许的逻辑模型（结合平台模型目录），不会在请求时实时探测上游能力，可能与控制台展示略有差异；计费、策略以控制台和绑定策略为准。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名\n- `GET /v1/models` 可用，清单由 API Key 绑定的策略与平台模型目录决定\n- OpenAI 与 Anthropic 协议都可能返回上游原样 `usage`\n- 流式失败时可能不会发送 `data: [DONE]`，请以数据块中的 `error` 判断\n- 如果上游或路由不支持当前协议，平台会返回 `provider_unsupported` 或协议不兼容错误\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","china/zh/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI 兼容向量嵌入接口说明。\n---\n\n# Embeddings\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | 文本向量嵌入 |\n| `POST` | `/v1/embeddings/multimodal` | 多模态（图文等）向量嵌入 |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` 可以是单条字符串，也可以是字符串数组。返回结果遵循 OpenAI Embeddings 兼容格式。\n\n## 多模态 Embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\n面向同时包含文本与图像等内容的向量嵌入场景。`input` 结构与具体模型的多模态能力相关，是否生效取决于路由到的上游模型。\n","china/zh/models/video/ark.md":"---\ntitle: Seedance 视频入站协议\ndescription: 用 Ark 原厂路径调用平台托管的 Seedance 异步视频任务，请求体与响应体都按 Ark 内容生成协议书写。\n---\n\n# Seedance 视频入站协议\n\n豆包 Seedance 系列（`doubao-seedance-*`）除标准视频协议外，还可以用**火山方舟（Ark）原厂路径**调用，\n请求体与响应体按 Ark 内容生成协议书写：\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 创建内容生成任务（视频） |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见下） |\n\n这是**平台托管**通道：路径是 Ark 自己的，但请求走的是网关标准的异步任务流水线，与\n[通用异步内容生成任务](./async-tasks)完全同一条链路，只是换了 Ark 的路径拼写。因此它同样享受\n维度计费、任务落库、产物持久化与预扣/结算的全部保障。\n\n## 创建任务\n\n请求体按 Ark 内容生成协议书写，`model` 填**平台逻辑模型名**（如 `doubao-seedance-2.0-mini`）：\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一只霓虹都市里的猫\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" } }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\n`resolution` / `ratio` / `duration` 的合法取值**随模型而异**（例如 Seedance 2.0 的 Fast 与 Mini 不支持\n`1080p`，`duration` 下限是 4 秒），请以对应模型的能力说明为准；超出范围会在创建时被拒。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与查询返回的就是[通用异步内容生成任务](./async-tasks)那一种 Ark 任务对象——同一条流水线，\n响应报文与字段语义（`status` 取值、`content.video_url`、`error`、`usage` 缺省规则）与那一页完全一致，\n此处不再重复。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消成功后预扣会被退回（void），不产生结算。\n\n**但取消不是所有上游都支持。** 能否取消取决于承接该任务的供应商是否实现了取消能力，而这条通道\n不锁定上游 family，所以同一个逻辑模型的两次调用可能一次能取消、一次不能。两种失败：\n\n| 情况 | 响应 |\n| --- | --- |\n| 承接该任务的供应商不支持取消 | `400` / `4003` `provider_unsupported`，`endpoint not supported by provider` |\n| 任务已到终态（`succeeded` / `failed`） | `409` `task_already_terminal`，`task already finished; nothing to cancel` |\n\n取消失败时预扣不会提前退回，会等任务到终态或预扣过期后按正常结算/释放流程处理。所以**不要把\n「先创建、再取消」当成一种可靠的止损手段**。\n\n## 关键约定\n\n- **`id` 是网关任务 ID，不是上游任务 ID。** 查询、取消都只认这个 ID，请以创建响应里的 `id` 为准。\n- **响应形态是固定的。** 无论实际由哪家上游承接，创建与查询都返回同一种 Ark 任务对象，\n  不会因为路由到不同供应商而变形。\n- **该通道不锁定上游 family。** 路径拼写不参与选路：`model` 对应的逻辑模型路由到谁，就由谁承接。\n  Seedance 在平台上由多家供应商共同承接，同一个逻辑模型的两次调用可能落到不同上游，这是正常的。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），Ark 路径下没有对应端点；\n  直接使用响应里的 `content.video_url` 即可。\n- 该模型是否开放本通道，取决于它在模型目录里声明的 `public_protocols` 是否含\n  `content_generation`；未声明则返回 `4005`。可用 `GET {{ api_endpoint }}/v1/models` 核对。\n\n如果你不需要 Ark 的路径与字段风格，[OpenAI 兼容视频流](./openai-compatible)是更标准化的选择。\n","china/zh/models/video/async-tasks.md":"---\ntitle: 通用异步内容生成任务\ndescription: 平台统一的异步任务入口，覆盖图像、视频等需要任务式处理的内容生成能力。\n---\n\n# 通用异步内容生成任务\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 创建通用异步内容生成任务（图像 / 视频等） |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 轮询通用内容生成任务状态与结果 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见[Seedance 视频入站协议](./ark)的「取消任务」） |\n\n`/v1/content_generation/tasks` 是比标准 OpenAI 视频流更通用的异步任务入口，覆盖图像、视频等需要后台任务执行的生成能力。\n\n## 创建任务\n\n请求体遵循对应上游的通用生成格式，至少需要 `model`：\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\n2026-09-10 国内生产：创建返回 `status=queued`、`id` 形如 `gw_…`；轮询同一 `id` 最终为 `succeeded`，并带 `resolution=720p`、`ratio=16:9`、`duration=5`。同一模型打 `POST /v1/video/generations` 为 `model_protocol_not_offered`。`DELETE` 取消在该上游上返回 `provider_unsupported`。\n\n## 轮询任务\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与轮询都返回**同一种** Ark 形态的任务对象，不随实际承接的上游变化：\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` 取值为 `queued` / `running` / `succeeded` / `failed`；`id` 是**网关任务 ID**，轮询与取消都只认它。\n\n## 三种拼法，同一条流水线\n\n同一条托管异步流水线有三个入站拼写，选哪个只取决于你想按谁的报文风格写客户端：\n\n| 入口 | 请求体 | 响应体 |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | 通用生成格式 | Ark 任务对象（上表） |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark 内容生成原生体 | Ark 任务对象 |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax 视频生成 V2 原生体 | MiniMax 形态（`{\"task_id\"}` / `{\"task\":{…}}`） |\n\n三者的计费、任务落库、产物持久化与预扣/结算行为完全一致。\n\n## 适用场景\n\n- 你要调用的平台能力本身是异步任务，但不走 OpenAI Video 标准形态\n- 你希望统一使用平台托管的「创建任务 → 轮询结果」模型，而不是自行管理厂商原生协议\n- 你调用的是即梦等仅提供托管异步入口的视频模型\n\n## 关键约定\n\n- `model` 仍填写平台逻辑模型名，由平台决定最终路由到哪个上游实现。\n- 请求体字段取决于路由到的具体能力；响应形态则是固定的，见上文。\n- 如果你不想自己处理厂商侧的多种原生轮询协议，优先使用这一入口。\n\n如需标准 OpenAI 视频协议，见[OpenAI 兼容视频流](./openai-compatible)。\n","china/zh/models/video/kling-v3.md":"---\ntitle: 可灵 3.0（kling-v3）文生 / 图生视频（Kling 原生协议）\ndescription: 按可灵官方 API 协议调用 kling-v3：text2video / image2video 创建、mode 档位、sound 音频开关、轮询、下载与计费口径。可灵官方 SDK 改域名即可直连。\n---\n\n# 可灵 3.0（kling-v3）文生 / 图生视频（Kling 原生协议）\n\n| 接口 | 能力 | 必填字段 |\n| --- | --- | --- |\n| `POST /kling/v1/videos/text2video` | 文生视频 | `model_name`、`prompt` |\n| `POST /kling/v1/videos/image2video` | 图生视频（首帧驱动，可选尾帧） | `model_name`、`prompt`、`image` |\n\nModelGo 按可灵官方 API 的路径与请求/响应格式接收请求（`model_name`、`mode`、`sound`、`duration`、`aspect_ratio`……），网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。轮询路径与官方一致：**同一路径 + `/{task_id}`**。\n\n> 使用可灵官方 SDK / 示例代码时，把 API 域名换成 `{{ api_endpoint }}/kling`，鉴权改为 `Authorization: Bearer $MODELGO_API_KEY`（无需可灵的 JWT 签名）。\n\n## 1. 创建任务\n\n### 文生视频\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"一颗红色小球在木桌上缓缓滚动，柔和日光\",\n    \"mode\": \"std\",\n    \"duration\": \"5\",\n    \"aspect_ratio\": \"16:9\",\n    \"sound\": \"on\",\n    \"cfg_scale\": 0.5\n  }'\n```\n\n### 图生视频\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/image2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"小狗缓缓转头\",\n    \"image\": \"https://example-cdn.com/dog.jpg\",\n    \"mode\": \"pro\",\n    \"duration\": \"5\"\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"submitted\",\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773081000\n  }\n}\n```\n\n`data.task_id` 是网关任务 ID，轮询与取内容都用它。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model_name` | string | 全部 | 固定 `kling-v3` |\n| `prompt` | string | 全部 | text2video 必填；image2video 可选（与官方一致）。≤ 2500 字符 |\n| `image` | string | image2video | 必填。首帧图片的**公网可直接下载**的 URL。text2video 请求不得携带 `image` / `image_tail`（会被拒绝，不会静默按文生视频处理） |\n| `image_tail` | string | image2video | 尾帧图片 URL |\n| `mode` | string | 全部 | 档位：`std`（720P）、`pro`（1080P）或 `4k`，**缺省 `pro`** |\n| `duration` | string / int | 全部 | 时长（整数秒）3–15，缺省 `5` |\n| `aspect_ratio` | string | text2video | `16:9` / `9:16` / `1:1`，缺省 `16:9`。图生视频跟随首帧比例 |\n| `sound` | string | 全部 | `on` / `off`，缺省 `off`。**开启会切换到含音频的计费档** |\n| `negative_prompt` | string | 全部 | 反向提示词 |\n| `cfg_scale` | number | 全部 | 提示词遵循度 [0, 1]，缺省 0.5 |\n| `callback_url` / `external_task_id` | string | 全部 | 接受但不生效：网关不回调，任务以 `task_id` 轮询 |\n\n### 档位\n\n| `mode` | 输出 |\n| --- | --- |\n| `std` | 1280×720（按比例） |\n| `pro` | 1920×1080（按比例），缺省 |\n| `4k` | 4K（按比例），仅由支持 4K 的供应商承接，单价另计 |\n\n- **只提供以上三档。** 其他值会在创建时被拒（HTTP `400`）。网关按各供应商可交付档位选路：请求 `4k` 时只会交给能出 4K 的供应商，不会静默降档；若当前没有可用的 4K 供应商，创建返回 `400`，不产生费用。\n\n### 首帧图片的要求（image2video）\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie；JPG / PNG，≤ 10MB，宽高 ≥ 300px，比例 1:2.5–2.5:1。\n- 图片拉取失败会导致任务失败（`task_status=failed`），不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/kling/v1/videos/text2video/{task_id}`（image2video 创建的任务到 `.../image2video/{task_id}` 轮询）\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video/gw_6dce033e-9243-4a64-9c57-73d08a8e379a \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"succeed\",\n    \"task_result\": {\n      \"videos\": [{\"id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"url\": \"{{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content\", \"duration\": \"6\"}]\n    },\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773250000\n  }\n}\n```\n\n- `task_status`：`submitted` → `processing` → `succeed` / `failed`。失败时 `task_status_msg` 给出原因，任务**不计费**。\n- 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。\n- `videos[].url` 指向网关内容接口，需带 API Key 下载；`duration` 为实际交付秒数。\n\n## 4. 下载视频\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o kling.mp4\n```\n\n返回 `video/mp4` 字节流，支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}/kling/v1/videos\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\"}\n\ndef generate(kind: str, body: dict, out: str, timeout: int = 600) -> None:\n    body.setdefault(\"model_name\", \"kling-v3\")\n    r = requests.post(f\"{BASE}/{kind}\", json=body, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"data\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        data = requests.get(f\"{BASE}/{kind}/{task_id}\", headers=H, timeout=30).json()[\"data\"]\n        if data[\"task_status\"] == \"succeed\":\n            break\n        if data[\"task_status\"] == \"failed\":\n            raise RuntimeError(data.get(\"task_status_msg\", \"generation failed\"))\n        time.sleep(8)\n    url = data[\"task_result\"][\"videos\"][0][\"url\"]\n    with requests.get(url, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"text2video\", {\"prompt\": \"一颗红色小球在木桌上缓缓滚动\", \"mode\": \"std\", \"duration\": \"5\", \"sound\": \"on\"}, \"t2v.mp4\")\ngenerate(\"image2video\", {\"prompt\": \"小狗缓缓转头\", \"image\": \"https://example-cdn.com/dog.jpg\", \"mode\": \"pro\", \"duration\": \"5\"}, \"i2v.mp4\")\n```\n\n## 6. 计费口径\n\n- 按**视频秒数 × 单价**计费，单价由三个维度决定：输入方式（文生 / 图生）、档位（`std` 720P / `pro` 1080P / `4k`）、是否生成音频（`sound`）。\n- 创建时按请求的 `duration` 预授权冻结，任务完成后按**实际交付秒数**结算；部分通道多交付约 1 秒（请求 5 秒交付 6 秒），以 `videos[].duration` 为准。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`failed`）不计费，预授权自动释放。\n- 各档单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `mode` 不是 `std`/`pro`/`4k`；`sound` 不是 `on`/`off`；缺 `model_name`；text2video 缺 `prompt`；image2video 缺 `image`；text2video 带了 `image`/`image_tail`；当前无供应商能出所请求档位 | 按参数表修正或换接口/档位 |\n| `task_status=failed` | 上游无法下载首帧图或生成失败 | 换成公网可直接下载的直链 |\n| 轮询 `task_not_found` | `task_id` 不是本 Key 创建的任务，或轮询路径的接口族与创建时不一致 | 用创建时的同一路径轮询 |\n| `/content` 返回 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `succeed`；及时下载 |\n","china/zh/models/video/minimax.md":"---\ntitle: MiniMax 视频入站协议\ndescription: 用 MiniMax 视频生成 V2 的原厂请求体与响应体调用平台托管的异步视频任务，适用于 MiniMax-H3 系列。\n---\n\n# MiniMax 视频入站协议\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | 创建视频生成任务 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 取消未完成的任务并退回预扣 |\n\n这是 **MiniMax 视频生成 V2** 的原厂入站协议，主要面向 MiniMax-H3 系列视频模型。和 Ark 通道一样，\n它跑在平台托管的异步任务流水线上——请求体是 MiniMax 自己的形状，**响应体也按 MiniMax 的形状渲染**，\n所以照着 MiniMax 官方文档写的客户端可以直接解析。\n\n任务落在平台侧，维度计费、产物持久化、预扣/结算都照常生效。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一个男孩在海边打篮球\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\n创建响应就是 MiniMax 文档里的裸任务句柄：\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### 请求体字段\n\n`content[]` 是多模态数组，每项由 `type` 与 `role` 共同决定它的用途：\n\n| `type` | 可用 `role` | 含义 |\n| --- | --- | --- |\n| `text` | —— | 提示词 |\n| `image_url` | `first_frame` / `last_frame` | 首帧 / 尾帧图 |\n| `image_url` | `reference_image` | 参考图 |\n| `video_url` | `reference_video` | 参考视频 |\n| `audio_url` | `reference_audio` | 参考音频 |\n\n- **首尾帧与参考素材不能混用**：带了 `first_frame` / `last_frame` 就不能再带任何 `reference_*`，\n  反之亦然——它们对应上游两种不同的生成任务。\n- `resolution`、`duration`、`ratio` 与 `content` 平级。对 MiniMax-H3，取值范围为\n  `resolution` ∈ `768P` / `2K`，`duration` 为 `4`–`15` 的整数，`ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`；不传时按上游缺省（`2K`、`5` 秒）执行**并按该缺省档计费**。\n- 提示词长度上限约 7000 字符。\n- 具体支持哪些取值仍以 `model` 对应的逻辑模型配置为准。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n查询响应是 `task` 信封，与创建响应**形状不同**：\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` 取值为 `queued` / `running` / `succeeded` / `failed`。\n- 成功后产物地址在 `task.content.url`。\n- `usage` 以**秒**计量（H3 按输出秒数定价），不是 token 数；上游只报告 token 而没有秒数时该字段缺省。\n- 失败时追加 `task.error`（`code` / `message`）。这一项不在 MiniMax 官方成功响应结构里，\n  是为了让失败原因可见而额外补上的，按官方结构解析的客户端会自然忽略它。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消后预扣退回。注意本通道**不会**返回 MiniMax 文档中的 `cancelled` 状态——已取消的任务统一以\n`failed` 呈现，以保证预扣被退回而不是结算。\n\n## 关键约定\n\n- **`id` / `task_id` 都是网关任务 ID**，不是上游任务 ID；查询与取消只认它。\n- 该通道不锁定上游 family，由 `model` 对应逻辑模型的路由决定实际承接方，路径拼写不参与选路。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），MiniMax 路径下没有对应端点。\n\n标准化入口见[OpenAI 兼容视频流](./openai-compatible)。\n","china/zh/models/video/openai-compatible.md":"---\ntitle: OpenAI 兼容视频流\ndescription: 标准 OpenAI Video 兼容接口，包括创建任务、轮询状态与拉取产物内容。\n---\n\n# OpenAI 兼容视频流\n\n> **视频模型只接受厂商官方原生协议**：[万相 2.7（DashScope）](./wan27)、[可灵 3.0（Kling）](./kling-v3)、[Veo 3.1（Google）](./veo31)。`wan2.7-t2v` / `wan2.7-i2v` / `kling-v3` / `veo-3.1` / `veo-3.1-fast` 已不再开放本页的 `POST /v1/video/generations`（对这些模型返回 `400`、`app_error_id=4005 model_protocol_not_offered`）。任务轮询 `GET /v1/videos/{task_id}` 与产物接口 `GET /v1/videos/{task_id}/content` 对原生协议创建的任务仍可用；通用异步任务接口见[异步内容生成任务](./async-tasks)。\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | 创建 OpenAI 兼容视频任务 |\n| `GET` | `/v1/videos/{task_id}` | 轮询视频任务状态与结果 |\n| `GET` | `/v1/videos/{task_id}/content` | 拉取已完成视频任务的产物内容 |\n\n这组接口是平台定义的**标准视频协议**：请求体使用 OpenAI Video 兼容字段，平台负责识别并转换成对应上游的视频异步任务格式。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\n创建成功后返回 `task_id`。后续轮询与产物拉取都围绕该 `task_id` 进行。\n\n## 轮询任务状态\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` 取值为 `queued` / `in_progress` / `completed` / `failed`；为 `completed` 时，`metadata.url` 中会给出产物地址。\n\n## 拉取产物内容\n\n任务完成后，也可以通过内容接口直接拿视频文件。该接口由网关**直接回传 `video/mp4` 字节流**（不再 `302` 跳转到对象存储），支持 `Range` 断点续传，且只有任务所属 API Key（或同租户控制台登录态）可访问：\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\n内容接口的可用性取决于后台「媒体交付」配置：\n\n- 未启用时返回 `404`（`content_delivery_disabled`）\n- 任务尚未完成时返回 `409`（`task_not_completed`）\n- 产物已过期或不存在时返回 `404`（`content_not_available`）\n\n## 关键约定\n\n- 这是标准 OpenAI 兼容视频入口，客户端不需要理解厂商原生协议。\n- 是否支持 `duration`、`size` 等字段，以及最终落到哪个上游，取决于 `model` 对应的逻辑模型配置。\n- 视频任务属于异步模型，轮询时请带退避，避免高频请求触发限流。\n\n如需更通用的异步任务入口，见[通用异步内容生成任务](./async-tasks)；想按厂商原厂报文书写、但仍要平台托管的计费与任务管理，见[Seedance 视频入站协议](./ark)与[MiniMax 视频入站协议](./minimax)。\n","china/zh/models/video/veo31.md":"---\ntitle: Veo 3.1 / Veo 3.1 Fast 文生视频（Google 原生协议）\ndescription: 按 Google Gemini API 官方 Veo 协议调用 veo-3.1 与 veo-3.1-fast：predictLongRunning 创建、operations 轮询、下载与 USD 计费口径。Google GenAI SDK 改 base_url 即可直连。\n---\n\n# Veo 3.1 / Veo 3.1 Fast 文生视频（Google 原生协议）\n\n| 官方模型 ID（路径中使用） | 平台逻辑模型 | 定位 |\n| --- | --- | --- |\n| `veo-3.1-generate-preview` | `veo-3.1` | 质量版，原生音画同出 |\n| `veo-3.1-fast-generate-preview` | `veo-3.1-fast` | 速度优化版，成本更低 |\n\nModelGo 按 Google Gemini API 的 **长时任务（Long-running operation）** 协议原样接收 Veo 请求：`predictLongRunning` 创建 → `operations` 轮询 → 下载。请求体与 Google 文档一致（`instances` + `parameters`）；网关负责路由到供应商并计费。\n\n> 使用 Google GenAI SDK 时，把 `http_options.base_url` 指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key 即可。鉴权头同时接受 `x-goog-api-key: $KEY` 与 `Authorization: Bearer $KEY`。\n\n## 1. 创建任务\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:predictLongRunning`（也接受 `/v1/models/...`）\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"instances\": [{\"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\"}],\n    \"parameters\": {\"aspectRatio\": \"16:9\", \"resolution\": \"1080p\", \"durationSeconds\": 8, \"generateAudio\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\", \"done\": false}\n```\n\n`name` 是官方形态的 operation 名称，最后一段是网关任务 ID；轮询时把 `name` 原样拼到 `/v1beta/` 之后。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `instances[0].prompt` | string | 文生视频必填；图生视频提供了 `image` 时可省略。画面内容与动作描述 |\n| `instances[0].image` | object | 首帧图片（图生视频）。**仅支持 URL 形态** `{\"imageUri\": \"https://...\"}` / `gcsUri`；内联 `bytesBase64Encoded` 会被拒绝 |\n| `instances[0].lastFrame` | object | 尾帧图片，同上 |\n| `parameters.resolution` | string | `720p` 或 `1080p`，**缺省 `720p`** |\n| `parameters.durationSeconds` | int | `4` / `6` / `8`，缺省 `8`。**1080p 需使用 8 秒** |\n| `parameters.aspectRatio` | string | `16:9` 或 `9:16`，缺省 `16:9` |\n| `parameters.generateAudio` | boolean | Veo 3.1 总是生成音轨；计费不区分音频 |\n| `parameters.negativePrompt` | string | 反向提示词 |\n| `parameters.seed` | int | 随机种子 |\n| `parameters.sampleCount` / `numberOfVideos` | int | 只能为 `1`：一个任务一段视频，`>1` 会被拒绝 |\n| `parameters.personGeneration` | string | 透传 |\n\n### 分辨率档位\n\n| 档位 | 输出 |\n| --- | --- |\n| `720p` | 1280×720（16:9）/ 720×1280（9:16），缺省 |\n| `1080p` | 1920×1080 / 1080×1920 |\n\n- **只提供以上两档。** 传 `4k` 会在创建时被拒（HTTP `400`），不会静默降档生成，也不产生费用。\n- 一次只能创建一个视频；只接受一个 `instance`。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/v1beta/{operation.name}`，即 `GET /v1beta/models/{model}/operations/{task_id}`\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\",\n  \"done\": true,\n  \"response\": {\n    \"@type\": \"type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse\",\n    \"generateVideoResponse\": {\n      \"generatedSamples\": [{\"video\": {\"uri\": \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\"}}]\n    }\n  }\n}\n```\n\n- 未完成时 `done=false`；失败时 `done=true` 且带 `error.{code,message}`，任务**不计费**。\n- 8 秒片段通常 1–2 分钟完成，请按 5–10 秒间隔轮询并带退避。\n- 上游偶发临时错误会使创建返回 `502`，不计费，重试即可。\n\n## 4. 下载视频\n\n`generatedSamples[].video.uri` 指向网关内容接口，与 Google 官方一致需带 API Key：\n\n```bash\ncurl \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -o veo.mp4\n```\n\n返回 `video/mp4`（含 AAC 音轨），支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"x-goog-api-key\": os.environ[\"MODELGO_API_KEY\"]}\n\ndef generate(model: str, prompt: str, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/v1beta/models/{model}:predictLongRunning\",\n                      json={\"instances\": [{\"prompt\": prompt}], \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    name = r.json()[\"name\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(name)\n        op = requests.get(f\"{BASE}/v1beta/{name}\", headers=H, timeout=30).json()\n        if op.get(\"done\"):\n            break\n        time.sleep(8)\n    if \"error\" in op:\n        raise RuntimeError(op[\"error\"][\"message\"])\n    uri = op[\"response\"][\"generateVideoResponse\"][\"generatedSamples\"][0][\"video\"][\"uri\"]\n    with requests.get(uri, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"veo-3.1-fast-generate-preview\", \"A small red ball rolling across a wooden table\",\n         {\"resolution\": \"1080p\", \"durationSeconds\": 8, \"aspectRatio\": \"16:9\"}, \"veo-fast.mp4\")\ngenerate(\"veo-3.1-generate-preview\", \"A cinematic drone shot over a misty forest at dawn\",\n         {\"resolution\": \"720p\", \"durationSeconds\": 4}, \"veo.mp4\")\n```\n\n## 6. 计费口径\n\n- **USD 计价**，按**视频秒数 × 分辨率档位单价**计费，结算时按当日汇率折算到账户币种。\n- 创建时按请求的 `durationSeconds` 预授权冻结，任务完成后按实际交付秒数结算。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`done=true` + `error`）不计费，预授权自动释放。\n- 各档单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `resolution` 不在 720p / 1080p；`sampleCount` > 1；多个 `instances`；`image` 用了内联 base64 | 按参数表修正，图片改用 URL |\n| 创建返回 `502` | 上游临时错误 | 重试；不计费 |\n| 轮询 `task_not_found` | operation 名称不是本 Key 创建的任务 | 核对 `name` 与 Key |\n| 下载 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `done=true`；及时下载 |\n","china/zh/models/video/wan27.md":"---\ntitle: 万相 2.7 文生 / 图生视频（DashScope 原生协议）\ndescription: 按阿里百炼 DashScope 官方 video-synthesis 协议调用 wan2.7-t2v / wan2.7-i2v：创建任务、轮询、下载与计费口径。官方 SDK 改 base_url 即可直连。\n---\n\n# 万相 2.7 文生 / 图生视频（DashScope 原生协议）\n\n| 模型 | 能力 | 必填字段 |\n| --- | --- | --- |\n| `wan2.7-t2v` | 文生视频 | `input.prompt` |\n| `wan2.7-i2v` | 图生视频（首帧驱动，可选尾帧） | `input.prompt`、`input.img_url` |\n\n万相 2.7 的官方协议是阿里百炼 DashScope 的 **视频合成异步接口**，ModelGo 网关按官方路径与请求/响应格式原样接收：**创建 → 轮询 → 取内容**。请求体与阿里百炼文档一致，具体由哪家供应商渲染由网关路由决定，对调用方不可见。\n\n> 使用阿里官方 DashScope SDK 时，只需把 `base_url`（`DASHSCOPE_HTTP_BASE_URL`）指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key。\n\n## 1. 创建任务\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis`\n\n请求头：`Authorization: Bearer $MODELGO_API_KEY`、`X-DashScope-Async: enable`、`Content-Type: application/json`。\n\n### 文生视频\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-t2v\",\n    \"input\": {\"prompt\": \"一只毛茸茸的橘猫在阳光下的窗台上玩毛线球\"},\n    \"parameters\": {\"resolution\": \"1080P\", \"duration\": 5, \"prompt_extend\": true}\n  }'\n```\n\n### 图生视频\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-i2v\",\n    \"input\": {\"prompt\": \"猫缓缓转头并眨眼\", \"img_url\": \"https://example-cdn.com/cat.jpg\"},\n    \"parameters\": {\"resolution\": \"720P\", \"duration\": 5}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\", \"task_status\": \"PENDING\", \"submit_time\": \"2026-09-07 17:05:59.000\"},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n`output.task_id` 是网关任务 ID，轮询与取内容都用它。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 全部 | `wan2.7-t2v` 或 `wan2.7-i2v` |\n| `input.prompt` | string | 全部 | 必填。画面内容与动作描述 |\n| `input.img_url` | string | i2v | 必填。首帧图片的**公网可直接下载**的 URL。`wan2.7-t2v` 请求不得携带 `img_url` / `last_frame_url`（会被拒绝，不会静默按文生视频处理） |\n| `input.last_frame_url` | string | i2v | 尾帧图片 URL，与首帧配合生成首尾帧视频 |\n| `input.audio_url` | string | 全部 | 驱动音频 URL（wav/mp3） |\n| `input.negative_prompt` | string | 全部 | 反向提示词 |\n| `parameters.resolution` | string | 全部 | 分辨率档位 `720P` / `1080P`，缺省 `1080P` |\n| `parameters.size` | string | t2v | 与 `resolution` 等价的像素写法，如 `1280*720`、`1920*1080` |\n| `parameters.duration` | int | 全部 | 时长（秒），缺省 `5` |\n| `parameters.prompt_extend` | boolean | 全部 | 是否让上游智能改写提示词 |\n| `parameters.watermark` | boolean | 全部 | 是否加水印 |\n| `parameters.seed` | int | 全部 | 随机种子 |\n| `parameters.audio` | boolean | 全部 | 是否生成音频 |\n\n### 分辨率档位\n\n| 档位 | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 |\n| --- | --- | --- | --- | --- | --- |\n| 720P | `1280*720` | `720*1280` | `960*960` | `1088*832` | `832*1088` |\n| 1080P | `1920*1080` | `1080*1920` | `1440*1440` | `1632*1248` | `1248*1632` |\n\n- **只提供 720P / 1080P。** 传 `4K` 或表外 `size` 会在创建时被拒（HTTP `400`），不会静默降档生成，也不产生费用。\n- **按可交付档位选路。** 网关只把请求交给能按所声明档位交付的供应商（如 `wan2.7-t2v` 的 720P 目前仅由官方百炼通道渲染），不会由其他供应商按 1080P 代出再按 720P 计费；若当前没有能出该档位的供应商，创建返回 `400`，不产生费用。\n- `input` 中除上表字段外的键（如 `first_clip_url`、`ref_images_url`）不被本接口支持，会被拒绝而不是忽略。\n\n### 首帧图片的要求（i2v）\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。\n- 部分站点直链对非浏览器抓取返回 403，会导致任务在生成阶段失败（`task_status=FAILED`），不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/api/v1/tasks/{task_id}`\n\n```bash\ncurl {{ api_endpoint }}/api/v1/tasks/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"output\": {\n    \"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\",\n    \"task_status\": \"SUCCEEDED\",\n    \"submit_time\": \"2026-09-07 17:05:59.000\",\n    \"end_time\": \"2026-09-07 17:09:06.000\",\n    \"video_url\": \"{{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content\"\n  },\n  \"usage\": {\"video_duration\": 6, \"video_count\": 1},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n- `task_status`：`PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`。失败时 `output.code` / `output.message` 给出原因，任务**不计费**。\n- 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。\n- `output.video_url` 指向网关内容接口，需带 API Key 下载；不要持久化，产物有保留期。\n\n## 4. 下载视频\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o cat.mp4\n```\n\n返回 `video/mp4` 字节流，支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python，官方 SDK 风格）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\", \"X-DashScope-Async\": \"enable\"}\n\ndef synthesize(model: str, inp: dict, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/api/v1/services/aigc/video-generation/video-synthesis\",\n                      json={\"model\": model, \"input\": inp, \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"output\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        o = requests.get(f\"{BASE}/api/v1/tasks/{task_id}\", headers=H, timeout=30).json()[\"output\"]\n        if o[\"task_status\"] == \"SUCCEEDED\":\n            break\n        if o[\"task_status\"] == \"FAILED\":\n            raise RuntimeError(o.get(\"message\") or o.get(\"code\"))\n        time.sleep(8)\n    with requests.get(o[\"video_url\"], headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\nsynthesize(\"wan2.7-t2v\", {\"prompt\": \"一只毛茸茸的橘猫在阳光下玩毛线球\"}, {\"resolution\": \"1080P\", \"duration\": 5}, \"t2v.mp4\")\nsynthesize(\"wan2.7-i2v\", {\"prompt\": \"猫缓缓转头并眨眼\", \"img_url\": \"https://example-cdn.com/cat.jpg\"}, {\"resolution\": \"720P\", \"duration\": 5}, \"i2v.mp4\")\n```\n\n## 6. 计费口径\n\n- 按**视频秒数 × 分辨率档位单价**计费；创建时按请求的 `duration` 预授权冻结，任务完成后按**实际交付秒数**结算（`usage.video_duration`）。上游可能多交付 1 秒（请求 5 秒、交付 6 秒），按 6 秒结算。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`FAILED`）不计费，预授权自动释放。\n- 各模型单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `resolution` / `size` 不在 720P / 1080P 内；缺 `input.prompt`；i2v 缺 `input.img_url`；t2v 带了 `input.img_url` / `input.last_frame_url`（图生视频请用 `wan2.7-i2v`）；`input` 含不支持的键；当前无供应商能出所请求档位 | 按参数表修正或换模型/档位 |\n| `task_status=FAILED` | 上游无法下载 `img_url` 或生成失败 | 换成公网可直接下载的直链 |\n| 轮询返回 `task_not_found` | `task_id` 不是本 Key 创建的任务 | 核对 `task_id` 与 Key |\n| `/content` 返回 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `SUCCEEDED`；及时下载 |\n","china/zh/quickstart/agent-clients.md":"---\ntitle: AI 工具接入\ndescription: 选择 AI 客户端或 Agent，通过 ModelGo 调用模型。\n---\n\n# AI 工具接入\n\nModelGo 支持常用的 AI 编程客户端和 Agent。创建 API Key 后，推荐使用 ModelGo CLI 自动完成接入；未接入 CLI 的客户端可通过自定义 Provider 手动配置。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n运行后选择一个或多个工具；如需自动化配置全部支持的工具，可使用：\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n## 支持的 AI 工具\n\n:::agent-tools\n| 工具 | ModelGo CLI自动接入 | 手动接入文档 |\n| --- | --- | --- |\n| Hermes Agent | 支持 | [接入文档](../agents/hermes-agent) |\n| Claude Code | 支持 | [接入文档](../agents/claude-code) |\n| Kilo Code | 暂不支持 | [接入文档](../agents/kilo-code) |\n| Cline | 暂不支持 | [接入文档](../agents/cline) |\n| Codex | 支持 | [接入文档](../agents/codex) |\n| OpenClaw | 支持 | [接入文档](../agents/openclaw) |\n| DeepSeek Harness | 暂不支持 | [接入文档](../agents/deepseek-harness) |\n| ZCode | 暂不支持 | [接入文档](../agents/zcode) |\n| Cursor | 暂不支持 | [接入文档](../agents/cursor) |\n| OpenCode | 支持 | [接入文档](../agents/opencode) |\n| CC Switch | 支持 | [接入文档](../agents/cc-switch) |\n| Cherry Studio | 暂不支持 | [接入文档](../agents/cherry-studio) |\n| Crush | 支持 | [接入文档](../agents/crush) |\n| Factory Droid | 支持 | [接入文档](../agents/factory-droid) |\n| Copilot CLI | 支持 | [接入文档](../agents/copilot-cli) |\n| nanobot | 支持 | [接入文档](../agents/nanobot) |\n| Oh My Pi | 支持 | [接入文档](../agents/oh-my-pi) |\n| CodeBuddy | 支持 | [接入文档](../agents/codebuddy) |\n| Kilo CLI | 暂不支持 | [接入文档](../agents/kilo-cli) |\n:::\n\n## 接入前准备\n\n1. 在[控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n2. 运行上方命令并选择需要接入的客户端或 Agent。\n3. 按终端提示确认站点、Base URL 和脱敏后的 API Key；配置工具会完成连通性验证。\n\n如果你希望用命令行管理 ModelGo 账户、模型、调用和 Skills，继续阅读[命令行工具](cli)。\n\n## 集成指南\n\n大多数工具只需要配置以下信息，即可连接 ModelGo：\n\n1. **API 地址**：OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`；Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n2. **API Key**：在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建的令牌。\n3. **模型名称**：在[模型广场]({{ site_endpoint }}/models)选择的逻辑模型名。\n\n具体配置步骤请参考上方各工具对应的接入文档。\n","china/zh/quickstart/authentication.md":"---\ntitle: 认证鉴权\ndescription: API Key 的获取、传递方式、优先级与常见认证失败处理。\n---\n\n# 认证鉴权\n\n所有模型调用接口都通过 API Key 认证。\n\n## 推荐请求头\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic 风格客户端也可使用：\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini 风格客户端也可使用：\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\n当多个头同时出现时，优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。\n\n## 获取与管理\n\n- 控制台：`{{ console_endpoint }}`\n- API Key 仅在创建时完整展示一次\n- 吊销或停用后会在鉴权缓存失效后生效\n\n## 认证失败\n\n常见错误：\n\n| HTTP | error_class | 说明 |\n| --- | --- | --- |\n| `401` | `auth` | 缺少、无效、停用或过期的 API Key |\n| `403` | `policy` | Key 有效，但不允许调用该模型或未绑定策略 |\n\n更多错误结构见[错误码与限流](errors)。\n","china/zh/quickstart/cli.md":"---\ntitle: 命令行工具\ndescription: 选择适合你的官方命令行工具，完成 ModelGo 配置。\n---\n\n# 命令行工具\n\nModelGo 提供两个官方命令行工具。选择你要完成的任务，运行对应命令即可开始。\n\n:::tools\n@model-go/config | 接入 AI 编程客户端 | 一条命令配置 Claude Code、Codex 等常用客户端。 | npx @model-go/config -r {{ region_flag }} | 查看 npm 包 | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | 使用官方 CLI | 配合官方 ModelGo Skills，让 AI Agent 直接操作 ModelGo。 | npx @model-go/cli@latest install | 查看 npm 包 | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## 接入 AI 编程客户端 `@model-go/config` {#connect-ai-clients}\n\n如果你想在 Claude Code、Codex、OpenCode 等 AI 编程客户端中使用 ModelGo，可以选择引导式配置，也可以通过一条命令完成全部客户端配置。\n\n**引导式配置**\n\n根据终端提示输入 API Key、选择客户端并预览配置，确认后自动写入并验证连接。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**一键式配置（非交互，适合自动化）**\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n### 支持的客户端\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\n引导式配置支持勾选一个或多个客户端；使用 `--only all` 可一次配置全部客户端。\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | 输入你的 [ModelGo API Key]({{ console_endpoint }}/api-keys)。 |\n| `02` | 勾选需要配置的客户端，也可以选择“全部配置”。 |\n| `03` | 预览站点、Base URL、脱敏后的 API Key 和目标客户端。 |\n| `04` | 确认后写入客户端配置，并自动验证连接。 |\n\n> **配置成功：** 终端会显示“配置完成”和“链路验证通过”，并给出启动所选客户端的命令。\n\n[查看 @model-go/config npm 包](https://www.npmjs.com/package/@model-go/config)\n\n## 让 AI Agent 操作 ModelGo `@model-go/cli` {#install-agent-tools}\n\n如果你希望 Claude Code、Codex 等 Agent 直接使用 ModelGo，安装官方 CLI 和 ModelGo Skills。安装向导会完成 CLI 设置、Skills 分发、站点选择和可选登录。\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | npm 首次运行时，确认安装 `@model-go/cli`。 |\n| `02` | 选择安装向导语言，支持中文和英文，后续安装提示将使用所选语言。 |\n| `03` | 安装或升级 ModelGo CLI，并安装 ModelGo Skills。 |\n| `04` | 在向导中选择当前站点环境（`{{ api_endpoint }}`）。 |\n| `05` | 选择是否立即通过浏览器登录；也可以跳过并稍后运行 `modelgo auth login`。 |\n\n### 安装后如何使用\n\n安装完成后，重新启动 AI Agent 或新建会话。ModelGo Skills 会让 AI Agent 直接调用 ModelGo CLI 完成查询和操作，你可以用自然语言向它提问，例如：\n\n- “当前 ModelGo 支持的模型有哪些？”\n- “当前 ModelGo 的账户余额还剩多少？”\n\n如果你希望自己在终端操作，输入 `modelgo` 即可查看全部可用命令和参数说明：\n\n```bash\nmodelgo\n```\n\n常用能力按使用场景分为以下几类：\n\n| 使用场景 | 常用命令 | 说明 |\n| --- | --- | --- |\n| 登录与身份 | `modelgo auth login`、`modelgo auth status`、`modelgo auth logout` | 登录 ModelGo、查看当前登录状态或清除本地登录信息。 |\n| 站点环境 | `modelgo env list`、`modelgo env current`、`modelgo env use <name>` | 查看可用环境、确认当前环境或切换站点；也可以通过 `env add` 和 `env remove` 管理自定义环境。 |\n| 工作空间 | `modelgo tenant list`、`modelgo tenant use <slug>` | 查看当前账号可用的工作空间，并通过工作空间 slug 或 ID 切换 CLI 后续操作使用的工作空间。 |\n| 账户与用量 | `modelgo balance`、`modelgo permissions`、`modelgo logs` | 查看余额和交易记录、账号权限、调用日志及用量统计。 |\n| 模型调用 | `modelgo models`、`modelgo chat`、`modelgo embeddings`、`modelgo call` | 查询可用模型，发起对话或向量请求，或直接调用任意 `/v1/*` 模型接口。 |\n| Key 与支付 | `modelgo key`、`modelgo pay` | 管理当前环境保存的模型 API Key，或管理 x402 按次支付配置。 |\n| CLI 维护 | `modelgo update`、`modelgo --version`、`modelgo --help` | 更新 CLI、查看版本或重新打开完整帮助。 |\n\n需要查看某个命令的参数时，运行 `modelgo <command> --help`。对于 `balance`、`permissions` 和 `logs`，还可以使用全局参数 `--tenant <slug\\|id>` 临时指定本次查询的工作空间。\n\n[查看 @model-go/cli npm 包](https://www.npmjs.com/package/@model-go/cli)\n\n:::note 安全提示\n- 推荐通过交互提示输入 API Key，不要把 Key 直接写进命令。\n- 不要把 API Key 提交到代码仓库或粘贴到共享脚本。\n- 如果安装 CLI 时跳过登录，稍后运行 `modelgo auth login`。\n:::\n\n## 继续探索\n\n- [首次调用](quickstart)：发起第一次模型调用。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n","china/zh/quickstart/errors.md":"---\ntitle: 错误码与限流\ndescription: 统一错误结构、常见错误分类与限流处理建议。\n---\n\n# 错误码与限流\n\n## 错误响应结构\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\n错误响应体除了 `error` 对象外，还带一个与 `X-Trace-ID` 响应头一致的顶层 `trace_id` 字段（链路追踪关闭时省略），便于按日志检索。`metadata.reason` 是可选细分原因（例如 `model_not_in_catalog`）。完整清单与已验证示例见[接口清单](openapi)。\n\n## 常见错误分类\n\n| error_class | HTTP | 含义 |\n| --- | --- | --- |\n| `client_invalid` | 400 | 请求格式或参数无效 |\n| `model_protocol_not_offered` | 400 | 该逻辑模型未声明当前入口对应的 `public_protocols`（`app_error_id=4005`）。换入口或换模型，不要改写请求体撞协议 |\n| `provider_invalid` | 400 | 上游拒绝请求（上游返回非 401/403/408/429 的 4xx） |\n| `provider_unsupported` | 400 | 上游不支持该接口（例如部分视频模型不支持 `DELETE` 取消） |\n| `provider_timeout` | 408 | 上游请求超时 |\n| `auth` | 401 | API Key 认证失败 |\n| `billing_insufficient` | 402 | 余额不足 |\n| `policy` | 403 | 无权调用该模型或未绑定策略 |\n| `quota` | 429 | 触发平台配额或限流 |\n| `provider_rate_limit` | 429 | 上游触发限流（上游返回 429） |\n| `gateway_internal` | 500 | 网关内部错误（兜底分类） |\n| `billing_system` | 502 | 计费系统不可用 |\n| `provider_server` | 502 | 上游服务错误 |\n| `provider_unauthorized` | 502 | 上游凭证被拒（统一归为 5xx，不向调用方暴露上游 Key 问题） |\n| `provider_unavailable` | 503 | 无可用模型供应方 |\n| `route_unconfigured` | 503 | 模型路由未配置上游 |\n\n## 失败请求的计费规则\n\n- 预扣：每次请求受理后按预估用量冻结余额，请求结束后按实际用量结算，多冻结的部分立即释放。\n- 成功请求与已交付部分内容的流式请求：按实际返回的用量结算。\n- **请求已发往上游供应方但最终失败**（上游 4xx/5xx、上游超时、流中途断开，以及客户端在等待响应期间主动断开）：按本次请求的预扣金额结算，不再退回。上游供应方对这类请求已产生实际成本，平台按预扣口径承担并向调用方收取。\n- 请求尚未发往上游即被平台拒绝（参数校验、鉴权、策略、配额、余额不足、网关内部错误）：预扣全额释放，不产生费用。\n- 结算依据可在控制台用量明细的交易记录中查看，按预扣结算的记录会标注失败原因。\n\n## 排障建议\n\n- 保留响应头中的 `X-Request-ID` 与 `X-Trace-ID`；错误响应体也会带同值的顶层 `trace_id` 字段\n- 遇到 `429` 时结合 `Retry-After` 响应头做退避重试（平台限流命中时会下发该头）\n- 流式请求若收到带 `error` 字段的数据块，应按失败处理（此类流中断对应 `provider_stream_broken`，不会再以独立的 HTTP 状态码返回）\n\n能力接口的细节见：\n\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n","china/zh/quickstart/openapi.md":"---\ntitle: 接口清单\ndescription: 客户模型调用面的全量 OpenAPI 清单、鉴权、协议匹配规则与已验证示例。\n---\n\n# 接口清单\n\n本页列出当前对外开放的模型调用 HTTP 接口（`mgk_` API Key，网关 `{{ api_endpoint }}`）。\n\n## 接入前置\n\n1. 在 `{{ console_endpoint }}` 创建 API Key（`mgk_` 前缀），完整明文只展示一次。\n2. `export MODELGO_API_KEY=\"你的-API-Key\"`。\n3. 调用 `GET /v1/models` 确认该 Key 能用的**逻辑模型名**。\n4. 选接口前先确认该模型是否声明了对应协议：打到模型未提供的入口，网关返回 HTTP 400、`error_class=model_protocol_not_offered`（`app_error_id=4005`），而不是帮你改写成别的协议。\n\n## 鉴权\n\n所有下列接口都用同一套 API Key：\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic 客户端可用 `x-api-key`，Gemini 客户端可用 `x-goog-api-key`。多头同时出现时优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。详见[认证鉴权](authentication)。\n\n缺 Key 或 Key 无效时的真实响应（HTTP 401）：\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\n排障请同时保留响应头 `X-Request-ID`、`X-Trace-ID` 与 body 里的 `trace_id`。\n\n## 协议匹配（必读）\n\n平台按模型目录里的 `public_protocols` 决定一个逻辑模型能打哪些入口。文档里的 curl **不能**对任意模型复制粘贴。\n\n| 模型 | 入口 | 结果 |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`、`POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings/multimodal` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`、`POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations`（`size` 至少约 1920×1920） | 200 |\n\n## 全量清单\n\n状态含义：\n\n- **正式对外**：网关已挂载，客户可调；能否对某个模型调通，仍取决于该模型的 `public_protocols` 与 Key 策略。\n- **正式对外 / 别名**：与上一行行为相同。\n\n### 文本与模型目录\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | 正式对外 | 列出当前 Key 策略允许的逻辑模型 |\n| `POST` | `/v1/responses` | 正式对外 | OpenAI Responses，新项目优先 |\n| `POST` | `/v1/chat/completions` | 正式对外 | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | 正式对外 | 旧版 Completions；多数对话模型未声明此协议 |\n| `POST` | `/v1/messages` | 正式对外 | Anthropic Messages |\n\n### 向量 / 图像 / 音频 / 重排\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | 正式对外 | 文本向量 |\n| `POST` | `/v1/embeddings/multimodal` | 正式对外 | 多模态向量；需模型声明对应协议 |\n| `POST` | `/v1/images/generations` | 正式对外 | 图像生成 |\n| `POST` | `/v1/images/edits` | 正式对外 | 图像编辑，`multipart/form-data` |\n| `POST` | `/v1/audio/speech` | 正式对外 | OpenAI TTS；**不是**所有语音模型都提供此协议 |\n| `POST` | `/minimax/v1/t2a_v2` | 正式对外 | MiniMax 原生同步语音合成，见[MiniMax 音频入站协议](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | 正式对外 | 语音转文本，multipart |\n| `POST` | `/v1/audio/translations` | 正式对外 | 语音翻译，multipart |\n| `POST` | `/v1/rerank` | 正式对外 | 重排序 |\n| `POST` | `/v1/reranks` | 正式对外 / 别名 | 与 `/v1/rerank` 等价 |\n\n### 视频与异步任务（托管）\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 正式对外 | 通用异步任务创建 |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 取消；上游不支持时返回 `provider_unsupported` |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 正式对外 | 与上一组同一托管流水线，Ark 路径拼写 |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上轮询 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上取消 |\n| `POST` | `/minimax/v2/video_generation` | 正式对外 | MiniMax 视频 V2 托管入口，请求需带齐计费维度 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 取消 |\n| `POST` | `/v1/video/generations` | 正式对外 | OpenAI 兼容视频创建；需模型声明该协议 |\n| `GET` | `/v1/videos/{task_id}` | 正式对外 | 轮询 |\n| `GET` | `/v1/videos/{task_id}/content` | 正式对外 | 302 拉产物 |\n| `DELETE` | `/v1/videos/{task_id}` | 正式对外 | 取消 |\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n真实响应形态（条目已截断）：\n\n```json\n{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"claude-fable-5\",\n      \"object\": \"model\",\n      \"created\": 1735689600,\n      \"context_length\": 1000000,\n      \"input_modalities\": [\"file\", \"image\", \"text\"],\n      \"output_modalities\": [\"text\"]\n    }\n  ]\n}\n```\n\n`id` 就是请求里的 `model`。清单**不包含** `public_protocols`；某个模型能不能打某个入口，以实际调用结果和控制台模型页为准。\n\n## 文本调用（已验证）\n\n### `POST /v1/chat/completions`\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}],\n    \"max_tokens\": 64\n  }'\n```\n\n成功时 HTTP 200，`object` 为 `chat.completion`，含 `choices[0].message` 与 `usage`。部分推理模型会额外返回 `reasoning_content`，且 `usage.completion_tokens` 可能远大于 `max_tokens`（实测 `max_tokens: 64` 时 completion 仍可达上千）。\n\n流式：同一路径加 `\"stream\": true`，响应 `Content-Type: text/event-stream`，每行 `data: {chunk}`，以 `data: [DONE]` 结束。\n\n空 body `{}` 的真实错误（HTTP 400）：\n\n```json\n{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"invalid request\",\n    \"metadata\": {\n      \"app_error_id\": 4001,\n      \"error_class\": \"client_invalid\",\n      \"request_id\": \"gw_a542461f-fe16-4f72-88d7-4c67b4bc9d7c\"\n    }\n  },\n  \"trace_id\": \"d6630b36c387a9e1e2d7bc9b6aa89020\"\n}\n```\n\n模型不在目录（HTTP 403）：\n\n```json\n{\n  \"error\": {\n    \"code\": 403,\n    \"message\": \"model is not registered or enabled in catalog\",\n    \"metadata\": {\n      \"app_error_id\": 4031,\n      \"error_class\": \"policy\",\n      \"reason\": \"model_not_in_catalog\",\n      \"request_id\": \"gw_ecc21066-c4a9-4eb1-97e7-799c4b1290\"\n    }\n  }\n}\n```\n\n### `POST /v1/responses`\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"input\": \"用一句话介绍 ModelGo。\",\n    \"max_output_tokens\": 64\n  }'\n```\n\n成功时 `object` 为 `response`，`output` 为数组（可能含 `reasoning` 与 `message`），并带 `output_text`。\n\n### `POST /v1/messages`\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"claude-fable-5\",\n    \"max_tokens\": 64,\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}]\n  }'\n```\n\n成功时 Anthropic 消息形态：`type: \"message\"`，`content[].type: \"text\"`。响应里的 `model` 可能是上游内部名（实测为 `pa/venus-cathedral-5`），与请求里的逻辑名不同，请以请求 `model` 和控制台为准。\n\n## 向量 / 图像 / 语音（已验证）\n\n### `POST /v1/embeddings`\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"text-embedding-3-small\",\"input\":\"hello ModelGo\"}'\n```\n\n成功：`data[0].embedding` 为浮点数组（`text-embedding-3-small` 实测维度 1536），`usage.prompt_tokens` 为计费 token。\n\n### `POST /v1/images/generations`\n\n`doubao-seedream-5.0-lite` 拒绝过小的 `size`。`1024x1024` 实测 HTTP 400、`error_class=provider_invalid`，上游要求像素总数至少 3686400（约 1920×1920）。用 `2048x2048` 可通过：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"a tiny red apple on white background, simple\",\n    \"size\": \"2048x2048\"\n  }'\n```\n\n成功响应含 `data[0].url`（对象存储地址，有时效）和 `usage.generated_images`。响应 `model` 可能是上游名（实测 `doubao-seedream-5-0-260128`）。\n\n### `POST /minimax/v1/t2a_v2`\n\n见[MiniMax 音频入站协议](../models/audio/minimax)。`speech-2.8-turbo` / `speech-2.8-hd` 当前声明的是这条 MiniMax 原生协议，不是 OpenAI `/v1/audio/speech`。\n\n## 异步视频（已验证）\n\nSeedance 类模型走托管异步任务，而不是 OpenAI `/v1/video/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedance-2.0-mini\",\n    \"content\": [{\"type\": \"text\", \"text\": \"a red apple on a table\"}]\n  }'\n```\n\n创建成功（HTTP 200）：\n\n```json\n{\n  \"id\": \"gw_c731f504-5a53-4e37-a972-30653a8ee390\",\n  \"model\": \"doubao-seedance-2.0-mini\",\n  \"status\": \"queued\",\n  \"created_at\": 1789012940,\n  \"error\": null\n}\n```\n\n同一 `id` 也可在 `GET /ark/api/v3/contents/generations/tasks/{id}` 轮询，状态会变为 `running`，完成后为 **`succeeded`**（实测 `resolution=720p`、`ratio=16:9`、`duration=5`）。`DELETE` 取消在该上游上实测返回 HTTP 400、`error_class=provider_unsupported`、`endpoint not supported by provider`——不要假设所有视频模型都支持取消。\n\n`POST /minimax/v2/video_generation` 若缺少计费维度，返回 HTTP 400、`client_invalid`（`billing_error_code=4223`）。按 MiniMax 视频文档补齐 `duration` / `resolution` 等字段后再试。\n\n## 流式约定\n\n- 文本流式接口（`/v1/chat/completions`、`/v1/responses`、`/v1/messages`）在请求体设 `stream: true`（Anthropic 为 `stream: true`）。\n- OpenAI 形态：`Content-Type: text/event-stream`，帧为 `data: <json>`，正常结束带 `data: [DONE]`。\n- Anthropic `/v1/messages` 保持原生 `event:` 帧，网关不会改写成 OpenAI SSE。\n- 流中若出现带 `error` 的数据块，按失败处理；此时可能没有独立的 HTTP 错误状态码。\n\n## 限流、超时、幂等、分页\n\n- 限流：HTTP 429，`error_class` 为 `quota` 或 `provider_rate_limit`；平台限流时会带 `Retry-After`。\n- 超时：客户端自行设置；上游超时为 `provider_timeout`（408）。\n- 幂等：同步文本/图像/语音请求没有客户侧幂等键。异步视频任务以返回的 `id` / `task_id` 为后续轮询主键；重复 POST 会再创建新任务。\n- 分页：模型调用面没有 cursor/page 列表接口。`GET /v1/models` 一次返回当前 Key 可见的全部逻辑模型。\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [错误码与限流](errors)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [MiniMax 音频入站协议](../models/audio/minimax)\n- [通用异步内容生成任务](../models/video/async-tasks)\n","china/zh/quickstart/overview.md":"---\ntitle: 平台概览\ndescription: 了解 ModelGo 的统一模型 API、兼容协议、模型能力与生产调用管理方式。\n---\n\n# 平台概览\n\n## ModelGo 概述\n\nModelGo 是面向生产环境的 AI 模型聚合网关。通过一个 API Key 和统一的 API，你可以调用文本、图像、视频、音频、向量与重排模型，无需为不同模型重复维护接入代码。\n\n无论你是在验证模型效果、开发 AI 功能，还是将模型调用投入生产，都可以通过相同的开发流程完成接入，并在一个平台内管理权限、用量、日志和安全策略。\n\n## 一个 API，调用多种模型\n\nModelGo 将不同类型的模型能力接入到同一套开发流程中。你可以根据业务场景选择对应能力，并进入详细文档查看接口、参数与调用示例。\n\n| 模型类别 | 模型能力 | 查看文档 |\n| --- | --- | --- |\n| 文本 | 对话、内容生成、推理与工具调用 | [文本生成](../models/text/generation) |\n| 图像 | 根据文本生成图像，或编辑已有图像 | [图像生成](../models/images/generations) · [图像编辑](../models/images/edits) |\n| 视频 | 生成视频，并通过异步任务查询进度与结果 | [标准视频接口](../models/video/openai-compatible) · [异步任务](../models/video/async-tasks) |\n| 向量 | 生成文本或多模态 Embeddings，用于语义检索与 RAG | [Embeddings](../models/vectors/embeddings) |\n| 音频 | 语音合成、语音识别与语音翻译 | [语音合成](../models/audio/speech) · [MiniMax 音频](../models/audio/minimax) · [语音转文本](../models/audio/transcriptions) · [语音翻译](../models/audio/translations) |\n| 重排 | 对候选结果重新排序，提升搜索和 RAG 的检索效果 | [Rerank](../models/rerank/rerank) |\n\n你也可以在模型广场查看可用模型，在模型体验中测试模型效果，或通过 `GET /v1/models` 获取当前 API Key 可调用的模型列表。\n\n## 使用熟悉的协议与工具\n\nModelGo 兼容 OpenAI 与 Anthropic 文本协议。已经使用相关 SDK 或客户端的项目，通常只需要替换 Base URL 和 API Key，即可沿用现有调用方式。\n\n根据客户端使用的协议选择对应地址：\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n所有请求使用同一套 ModelGo API Key 进行鉴权。你可以在[控制台]({{ console_endpoint }})创建 API Key，具体请求头与安全建议请查看[认证鉴权](authentication)。\n\n## 为生产调用而设计\n\nModelGo 不只提供统一接口，也提供模型调用进入真实业务后需要的管理能力：\n\n- **稳定调用**：在接入层统一处理模型路由与故障回退，减少单一路径异常对业务的影响。\n- **权限与安全**：通过工作空间、成员和 API Key 划分调用权限，并限制预算、可用模型与调用来源。\n- **用量与成本**：按时间、工作空间、模型、成员和 API Key 查看请求数、Token 用量与消费金额。\n- **调用追踪**：通过 Request ID、调用状态、延迟和错误信息定位同步调用与异步任务问题。\n\n## 开始使用\n\n如果是第一次接入 ModelGo，建议按以下顺序开始：\n\n- [首次调用](quickstart)：获取 API Key，并完成第一次模型调用。\n- [接口清单](openapi)：全量对外路径、协议匹配规则与已验证示例。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的调用示例。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n\n:::note 开发前请注意\n- 请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名，而不是上游厂商的原始模型 ID。\n- 通过 `GET /v1/models` 可以查询当前 API Key 有权调用的逻辑模型。返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。\n- 文本流式响应使用 SSE 传输，并以 `data: [DONE]` 表示响应结束。\n- 视频等异步生成接口会先返回 `task_id`，需要使用该 ID 查询任务进度和结果。\n- 排查调用问题时，请保留响应中的 `X-Request-ID`，方便定位具体请求。\n:::\n","china/zh/quickstart/quickstart.md":"---\ntitle: 首次调用\ndescription: 获取 API Key、选择模型，并通过 Responses API 完成第一次调用。\n---\n\n# 首次调用\n\n你可以复用现有 OpenAI 或 Anthropic SDK 接入 ModelGo，也可以按下面三步完成第一次 Responses API 调用。\n\n## 使用标准协议接入\n\nModelGo 同时兼容 OpenAI 与 Anthropic 标准协议。如果项目已经使用对应 SDK，通常只需替换 Base URL 和 API Key，无需重写调用逻辑。\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## 三步完成第一次 API 调用\n\n如果是第一次接入 ModelGo，完成下面三步即可发起请求并获得生成结果。\n\n### 第 1 步：获取 API Key\n\n- 登录[控制台]({{ console_endpoint }})。\n- 进入「API Key」页面，创建一个新的 API Key。\n- 将 API Key 写入环境变量，避免直接放进代码：\n\n```bash\nexport MODELGO_API_KEY=\"你的-API-Key\"\n```\n\n### 第 2 步：选择模型\n\n请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名。你可以在[模型广场]({{ site_endpoint }}/models)查看模型，也可以通过以下请求查询当前 API Key 有权调用的逻辑模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。选择一个模型名，在下一步中替换 `<model>`。\n\n### 第 3 步：发起第一次调用\n\n推荐使用 `POST /v1/responses`。选择你熟悉的方式运行下面的请求：\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"用三句话介绍 ModelGo。\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"用三句话介绍 ModelGo。\",\n)\n\nprint(response.output_text)\n```\n\n请求成功后会返回模型生成结果。Python SDK 可以通过 `response.output_text` 直接读取文本内容。\n\n## 使用其他兼容协议\n\n如果你的项目已经使用其他兼容接口，可以继续沿用原有请求结构：\n\n- [使用 Chat Completions](../models/text/generation#chat-completions)：适合已有 OpenAI Chat Completions 项目。\n- [使用 Anthropic Messages](../models/text/generation#anthropic-messages)：适合已有 Claude SDK 或 Anthropic Messages 项目。\n\n## 继续探索\n\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的完整说明。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n","international/en/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: Configure CC Switch and Claude Code with ModelGo.\n---\n\n# CC Switch\n\nCC Switch is a desktop provider manager for Claude Code, Codex, Gemini, OpenCode, OpenClaw, and more. This guide uses Claude Code as an example and shows how to add and enable ModelGo.\n\n## Before you start\n\n- Install [CC Switch](https://github.com/farion1231/cc-switch/releases) and make sure it opens normally.\n- Install Claude Code and launch it at least once.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open the Claude Code configuration\n\nOpen CC Switch, select **Claude** at the top, and click **+** to add a configuration.\n\n![CC Switch overview](/images/agents/cc-switch/overview.webp)\n\n![Add a Claude configuration in CC Switch](/images/agents/cc-switch/claude-add.webp)\n\n## 2. Add a ModelGo provider\n\nPaste the following JSON into the configuration editor. Replace `your-model-id` with a logical model name from the model catalog and `sk-your-token` with your ModelGo API key:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-your-token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"your-model-id\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"your-model-id\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![Edit the ModelGo configuration in CC Switch](/images/agents/cc-switch/config-global.webp)\n\nIf your CC Switch version supports environment placeholders, you can use `{env:MODELGO_API_KEY}` for the token and set it in the terminal where you start Claude Code:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | API key created in the ModelGo console |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A logical model name from the model catalog |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable logical model name |\n\n:::note\n- Use the ModelGo root URL for the Anthropic base URL. Do not append `/v1/messages`; Claude Code adds that path.\n- Keep the API key in the local CC Switch configuration or an environment variable. Do not commit it to a repository.\n- Name the provider **ModelGo** so it is easy to identify and switch later.\n:::\n\n## 3. Save and enable the provider\n\nSet the provider name to **ModelGo**, then click **Add** or **Save**. Return to the Claude configuration list and enable the ModelGo entry.\n\n![Add the ModelGo provider in CC Switch](/images/agents/cc-switch/provider-global.webp)\n\n![Enable the ModelGo profile in CC Switch](/images/agents/cc-switch/use-global.webp)\n\nStart Claude Code:\n\n```bash\nclaude\n```\n\nEnter a simple task such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n## 4. Verify the configuration\n\nTo verify the API key and model access separately:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse an `id` from the response as the logical model name for `ANTHROPIC_MODEL` and `ANTHROPIC_SMALL_FAST_MODEL`.\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nConfirm that the token is a valid ModelGo API key and that the CC Switch profile does not contain an old token. Remove extra spaces or line breaks.\n\n### 404 or endpoint errors\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`. Do not use `{{ api_endpoint }}/v1/messages` or a full request path.\n\n### Model unavailable\n\nMake sure the model name exactly matches a logical model in the [model catalog]({{ site_endpoint }}/models) and is enabled for the API key.\n\n### Claude Code still uses the old profile\n\nConfirm that the ModelGo profile is enabled in CC Switch. Fully restart the terminal, then run `claude` again.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [CC Switch Quick Start](https://cc-switch.cc/docs/getting-started/quick-start/): learn the interface and profile switching flow.\n- [CC Switch Provider Setup](https://cc-switch.cc/en/tutorials/provider-setup): learn custom provider fields and credential management.\n","international/en/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: Connect Cherry Studio to the international ModelGo endpoint through a custom provider.\n---\n\n# Cherry Studio\n\nCherry Studio includes several built-in providers, but ModelGo is not one of them. Use Cherry Studio's **Custom Provider** flow to create a ModelGo provider, then fetch and add the models you need. ModelGo exposes both OpenAI-compatible and Anthropic-compatible endpoints.\n\n## Prerequisites\n\n- Cherry Studio is installed and you can open its Settings page.\n- You have created or copied an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- You have confirmed the logical model ID to use in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open model service settings\n\nOpen Cherry Studio **Settings**, go to **Model Services**, and click **+ Add Provider** at the bottom of the provider list.\n\n![Open the provider picker in Cherry Studio](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. Add a custom provider\n\nIn the **Add Custom Provider** dialog, enter:\n\n| Setting | Value for international ModelGo |\n| --- | --- |\n| Provider name | `ModelGo` |\n| API key | The API key created in the ModelGo console |\n| OpenAI endpoint | `{{ api_endpoint }}/v1` |\n| Anthropic endpoint | `{{ api_endpoint }}` (only for Anthropic-compatible models or Agent mode) |\n\nClick **Add** to save the provider. Use the OpenAI endpoint for regular chats and model discovery. Do not append `/v1` to the Anthropic endpoint; Cherry Studio builds the protocol path for you.\n\n![Add the ModelGo custom provider](/images/agents/cherry-studio/custom-provider-global.webp)\n\n:::note\n- Do not enter a full `/chat/completions` or `/messages` URL.\n- Use `{{ api_endpoint }}/v1` for OpenAI-compatible requests and `{{ api_endpoint }}` for Anthropic-compatible requests.\n:::\n\n## 3. Fetch and add models\n\nReturn to the ModelGo provider page and click **Get Models**. Cherry Studio reads the logical models available to the current API key.\n\n![Fetch ModelGo models in Cherry Studio](/images/agents/cherry-studio/fetch-models-global.webp)\n\nIn the model picker, click **+** next to individual models or choose **Add All Models**.\n\n![Add all ModelGo models in Cherry Studio](/images/agents/cherry-studio/model-picker.webp)\n\nAdded models appear in the ModelGo provider's model section. Adding only the models you use keeps the model picker easier to navigate.\n\n![ModelGo models in the provider list](/images/agents/cherry-studio/model-list-global.webp)\n\n## 4. Enable the provider and start chatting\n\nTurn on the switch in the upper-right corner of the ModelGo provider page and run the API key check. Start a new chat, select **ModelGo** and one of the models you added, then send a short message.\n\nFor OpenAI-compatible models, the OpenAI endpoint is enough. For Claude or Cherry Studio Agent mode, configure the Anthropic endpoint and add an Anthropic-compatible model as well.\n\n## Verify the configuration\n\nYou can verify model discovery from a terminal:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical ModelGo model IDs to add in Cherry Studio.\n\n## Troubleshooting\n\n### 401 or authentication failure\n\nCheck that the API key was copied in full with no extra spaces, and that the provider switch is enabled.\n\n### 404 or an invalid endpoint path\n\nSet the OpenAI endpoint to `{{ api_endpoint }}/v1` and the Anthropic endpoint to `{{ api_endpoint }}`. Do not enter the complete `/v1/chat/completions` or `/v1/messages` path.\n\n### The model list is empty\n\nFirst verify `/v1/models` with the `curl` command above, then confirm the model is enabled for your API key in the model catalog. After fetching, click **+** or **Add All Models**; fetching alone does not add models to the picker.\n\n### Agent mode cannot send a request\n\nSet the Anthropic endpoint to `{{ api_endpoint }}` and add a model that supports the Anthropic-compatible protocol. The Anthropic endpoint is not required for ordinary OpenAI-compatible chats.\n\n## Related documentation\n\n- [First call](../quickstart/quickstart): Create an API key, inspect models, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): Learn how to keep API keys safe.\n- [Cherry Studio custom providers](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang): Follow Cherry Studio's official custom-provider flow.\n- [Cherry Studio provider settings](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers): Learn how Base URLs, model management, and connection checks work.\n","international/en/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: Configure Claude Code with ModelGo's Anthropic-compatible API.\n---\n\n# Claude Code\n\nClaude Code is a terminal-based AI coding assistant. Configure its Anthropic-compatible endpoint to use ModelGo models and API keys.\n\n## Before you start\n\n- Install Node.js.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Claude Code\n\nRun:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nVerify the installation:\n\n```bash\nclaude --version\n```\n\n## 2. Configure ModelGo\n\n### macOS / Linux\n\nCreate and edit the Claude Code settings file:\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\nRun these commands in PowerShell:\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\nPaste the following into `settings.json`. Replace `YOUR_MODELGO_API_KEY` and `YOUR_MODELGO_MODEL` with a real ModelGo API key and logical model name:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\nUse the ModelGo root URL for `ANTHROPIC_BASE_URL`; do not append `/v1/messages`. Claude Code adds the path and calls ModelGo's `POST /v1/messages` endpoint.\n\n:::note\n- If you use one model only, set all five model variables to the same ModelGo logical model so an unavailable auxiliary model does not prevent startup.\n- Keep the API key in your local settings. Do not commit `settings.json` or share it with others.\n:::\n\n## 3. Optional: skip official account onboarding\n\nIf the first `claude` launch stops at the official account login flow, create `.claude.json` in your user directory with the completed-onboarding flag.\n\nmacOS / Linux:\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell:\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. Start Claude Code\n\nChange to your project directory and start Claude Code:\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\nOn the first visit, choose **Trust This Folder** to allow Claude Code to access project files. Send a simple coding request; a normal response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A ModelGo logical model name |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The same callable ModelGo logical model name |\n\nFind a model in the [Model Gallery]({{ site_endpoint }}/models), or query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that `ANTHROPIC_AUTH_TOKEN` is a valid ModelGo API key and contains no extra spaces.\n\n### 403 or model unavailable\n\nMake sure all five model variables use ModelGo logical model names allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`, not `{{ api_endpoint }}/v1/messages`; Claude Code adds `/v1/messages` itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code): see the latest installation and configuration guidance.\n","international/en/agents/cline.md":"---\ntitle: Cline\ndescription: Configure Cline with ModelGo's OpenAI-compatible API.\n---\n\n# Cline\n\nCline is an AI coding assistant for VS Code. Select the `OpenAI Compatible` provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install VS Code.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cline\n\nOpen the VS Code Extensions marketplace, search for **Cline**, and install the extension.\n\n![Install Cline from the VS Code Extensions marketplace](/images/agents/cline/cline-market.webp)\n\n## 2. Configure ModelGo\n\nAfter installation, click the Cline icon in the VS Code activity bar and open **API Configuration**.\n\n![Open Cline API Configuration](/images/agents/cline/cline-config-global.webp)\n\nFill in the following values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | Your ModelGo API key |\n| Model ID | A ModelGo logical model name |\n\nClick **Done** to save.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL. Do not include `/chat/completions`; Cline appends the endpoint path.\n- Use a logical model name available to the current API key in the Model Catalog rather than copying the example from the screenshot.\n- Keep the API key in your local Cline settings. Do not commit it or share screenshots containing it.\n:::\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. Start using Cline\n\nOpen the Cline panel and send a simple coding request, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Complete a conversation in Cline](/images/agents/cline/cline-chat.webp)\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in the API Key field.\n\n### 403 or model unavailable\n\nMake sure Model ID is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`; do not paste a full `/chat/completions` URL.\n\n### The model list is empty\n\nRequest `GET {{ api_endpoint }}/v1/models` to verify the endpoint. If Cline does not show the model in its list, enter Model ID manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Cline OpenAI Compatible docs](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx): see Cline's official provider configuration guidance.\n","international/en/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: Connect CodeBuddy to ModelGo.\n---\n\n# CodeBuddy\n\nCodeBuddy Code is Tencent Cloud's terminal coding assistant. Environment variables override its API endpoint, key, and model so requests can use ModelGo.\n\n## Prerequisites\n\n- Node.js 18+ and CodeBuddy CLI are installed; `codebuddy --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. Configure ModelGo variables\n\nSet these variables in the shell that starts CodeBuddy:\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-your-token\"\nexport CODEBUDDY_MODEL=\"your-model-id\"\n```\n\n`CODEBUDDY_AUTH_TOKEN` is CodeBuddy platform login, not the ModelGo model key.\n\n:::note\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Non-interactive `codebuddy -p` requires `CODEBUDDY_API_KEY`.\n- Keep keys and model IDs in a local profile or secret manager.\n:::\n\n## 3. Start and verify\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\ncodebuddy -p \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### CodeBuddy still uses its default model\n\nConfirm variables are visible in the current shell, then fully restart `codebuddy`.\n\n### 401 or 404 responses\n\nCheck `CODEBUDDY_API_KEY`, `CODEBUDDY_MODEL`, and `CODEBUDDY_BASE_URL`; do not put a full endpoint path in the Base URL.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [CodeBuddy CLI quickstart](https://www.codebuddy.ai/docs/cli/quickstart): Review installation, login, and first run.\n- [CodeBuddy CLI environment variables](https://www.codebuddy.ai/docs/cli/env-vars): Review endpoint, key, and model variables.\n","international/en/agents/codex.md":"---\ntitle: Codex\ndescription: Configure Codex CLI with ModelGo's Responses API.\n---\n\n# Codex\n\nCodex is OpenAI's command-line AI coding assistant. With a custom `model_provider`, Codex CLI can send Responses API requests to ModelGo.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Codex\n\nRun this command in macOS, Linux, or Windows:\n\n```bash\nnpm install -g @openai/codex\n```\n\nVerify the installation:\n\n```bash\ncodex --version\n```\n\nIf Codex shows an upgrade prompt on first launch, choose **Skip** and finish the ModelGo setup first.\n\n![Skip the Codex upgrade prompt](/images/agents/codex/codex-start.webp)\n\n## 2. Configure ModelGo\n\nCodex reads its user-level model and provider settings from `~/.codex/config.toml`. Create the file first:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\nPaste the following into `config.toml`, replacing `YOUR_MODELGO_MODEL` with a logical model name allowed for the current API key:\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\nThe `base_url` is ModelGo's OpenAI-compatible API root. Codex appends `/v1/responses` when it sends a request.\n\n## 3. Set the API key\n\nStore your ModelGo API key in the `MODELGO_API_KEY` environment variable. Do not put the real key directly in `config.toml`.\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\nCheck that the variable is set without printing the key:\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- Keep `MODELGO_API_KEY` in your local environment. Do not commit it or share terminal screenshots containing it.\n- `model` must be a ModelGo logical model name. The `gpt-5.6-sol` shown in the screenshot is only an example; replace it with a model you can call.\n- `wire_api = \"responses\"` is required by current Codex configurations. Do not use the deprecated `wire_api = \"chat\"`.\n:::\n\n:::note Start a new conversation after changing the API key or endpoint\n- In a multi-turn conversation, Codex continues to send prior Responses context. That context may include encrypted reasoning data that can only be handled by the original upstream account.\n- If you change `MODELGO_API_KEY` or `base_url`, or a proxy or account pool routes the same conversation to another upstream account, start a new Codex conversation. Do not continue or resume the existing conversation, or the request may fail with `400 invalid_encrypted_content`.\n:::\n\n## 4. Start and verify\n\nChange to a local project directory and run:\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\nWhen Codex asks for permission to work in the project, trust the directory as appropriate. After the welcome screen appears, send a simple coding request such as “Describe this project in three sentences.”\n\n![Codex project welcome screen](/images/agents/codex/codex-skip.webp)\n\nA normal model response confirms that ModelGo is connected.\n\n![Start a conversation in Codex](/images/agents/codex/codex-chat.webp)\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### Provider not found at startup\n\nMake sure the file is the user-level `~/.codex/config.toml`, and that `model_provider = \"modelgo\"` matches `[model_providers.modelgo]`.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces or newlines.\n\n### 403 or model unavailable\n\nMake sure `model` is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `base_url` to `{{ api_endpoint }}/v1`. Do not include `/responses` or `/v1/responses`; Codex appends the path.\n\n### Chat wire API deprecation warning\n\nAdd `wire_api = \"responses\"` under `[model_providers.modelgo]`, then upgrade Codex CLI:\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### `400 invalid_encrypted_content`\n\nThis usually means the conversation contains encrypted context created by the original upstream account, but the current request was handled by a different upstream account.\n\nCheck whether the API key or Base URL changed, or whether a proxy or account pool switched upstream accounts. If a switch occurred, start a new conversation instead of continuing or resuming the existing one.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Codex configuration reference](https://developers.openai.com/codex/config-reference/): see current `config.toml` fields.\n","international/en/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: Connect Copilot CLI to ModelGo.\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI supports BYOK. Provider environment variables can route model requests to ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Copilot CLI is installed and `copilot --help` works.\n- GitHub/Copilot authentication is complete.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know a logical model ID that supports tool calling and streaming.\n\n## 1. Configure ModelGo BYOK\n\nSet these variables in the shell that starts Copilot CLI:\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"your-model-id\"\ncopilot\n```\n\nIf needed, define the key first:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nThe `openai` provider type targets OpenAI Chat Completions-compatible services.\n\n:::note\n- GitHub login and the ModelGo API key are separate credentials.\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Prefer a model with tool calling, streaming, and a large context window.\n:::\n\n## 2. Verify the model\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\nAsk Copilot CLI to perform a small read-only task, such as listing project entry points.\n\n## Troubleshooting\n\n### Copilot still uses its default model\n\nConfirm `COPILOT_MODEL` and `COPILOT_PROVIDER_BASE_URL` are visible in the current shell, then restart `copilot`.\n\n### 401, 404, or tool-call errors\n\nCheck the key, Base URL, and logical model ID. Choose a model with the required streaming and tool-calling capabilities.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models): Review provider variables and model requirements.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","international/en/agents/crush.md":"---\ntitle: Crush\ndescription: Connect Crush to ModelGo.\n---\n\n# Crush\n\nCrush is Charmbracelet's terminal coding agent. Its OpenAI-compatible provider support lets you route requests through ModelGo.\n\n## Prerequisites\n\n- Node.js 18+, Go, or Homebrew is available; `crush --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\nYou can also use `npm install -g @charmland/crush`, `go install github.com/charmbracelet/crush@latest`, or `winget install charmbracelet.crush` on Windows.\n\n## 2. Add a ModelGo provider\n\nCrush reads project `.crushrc`/`crushrc` files and the global `~/.config/crush/crushrc` (Windows: `%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`).\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/your-model-id --name \"your-model-id\"\n```\n\nReplace `your-model-id` with a ModelGo logical model ID.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL; do not append `/chat/completions`.\n- Keep the API key in `MODELGO_API_KEY` instead of committing it to a config file.\n- `modelgo/your-model-id` is Crush's provider/model identifier.\n:::\n\n## 3. Start and verify\n\n```bash\ncrush\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck the `crushrc` filename and path, then restart Crush. Project configuration takes precedence over global configuration.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is available in the same shell and that the Base URL is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n- [Crush repository](https://github.com/charmbracelet/crush): Read installation, provider, and command references.\n- [Crush config schema](https://github.com/charmbracelet/crush/blob/main/schema.json): Check `crushrc` fields.\n","international/en/agents/cursor.md":"---\ntitle: Cursor\ndescription: Configure Cursor with ModelGo's OpenAI-compatible API.\n---\n\n# Cursor\n\nCursor is an AI coding editor. With a custom OpenAI Base URL, Cursor can call ModelGo logical models.\n\n## Before you start\n\n- Install [Cursor](https://www.cursor.com/).\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cursor\n\nVisit the [Cursor website](https://www.cursor.com/) and download the build for your operating system.\n\n![Cursor download page](/images/agents/cursor/install.webp)\n\n## 2. Open Cursor model settings\n\nOpen Cursor settings and go to **Models**.\n\n![Open Models in Cursor Settings](/images/agents/cursor/settings.webp)\n\n## 3. Add and enable a model\n\nClick **Add model**, enter a logical model name from the [model catalog]({{ site_endpoint }}/models), and save it.\n\n![Add a model in Cursor](/images/agents/cursor/add-model.webp)\n\nIn **Model Names**, keep the models you want to use and disable the rest.\n\n![Enable the target model in Cursor](/images/agents/cursor/model-list.webp)\n\n## 4. Configure the ModelGo endpoint\n\nIn **Settings → Models → API Keys**, configure the OpenAI-compatible endpoint:\n\n| Setting | ModelGo value |\n| --- | --- |\n| OpenAI API Key | Your ModelGo API key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | A logical model name from the ModelGo catalog |\n\n![Configure the ModelGo endpoint in Cursor](/images/agents/cursor/config-global.webp)\n\nIf your Cursor release uses the alternate settings layout, enter the same ModelGo values there.\n\n![Alternate Cursor settings layout](/images/agents/cursor/config-cn.webp)\n\nClick **Verify** or **Save**. Cursor may use slightly different labels in different releases, but the API key, Base URL, and model name have the same meaning.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- Use a logical model name from the ModelGo catalog instead of copying the example in the screenshot.\n- If Verify fails, send a test message in chat or use the command below to check the endpoint and key.\n:::\n\n## 5. Test the connection\n\nReturn to the Cursor chat, select the model you added, and send a simple message. A normal response confirms the integration.\n\n![Test a ModelGo model in Cursor](/images/agents/cursor/chat.webp)\n\nYou can also list the models available to the API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nMake sure the API key is complete, has no extra spaces, and is entered in **OpenAI API Key**.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions` to it.\n\n### Verify fails or the model is unavailable\n\nCheck that the model name is a logical ModelGo model and that the model is enabled for the API key.\n\n### The chat returns no content\n\nRun `GET {{ api_endpoint }}/v1/models` to verify connectivity and the key, then confirm the target model is enabled in Model Names.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [Cursor documentation](https://docs.cursor.com/): see Cursor settings, models, and custom API configuration.\n","international/en/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: Configure DeepSeek Harness with ModelGo's OpenAI-compatible API.\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness (DSH) is an open-source agent framework from DeepSeek AI. It combines models, tools, filesystems, terminals, sessions, and a Web UI into a runnable agent. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22 or later.\n- Install pnpm 11 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start DeepSeek Harness\n\nThe current source-install path is:\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![Start DeepSeek Harness from source](/images/agents/deepseek-harness/install.webp)\n\nThe terminal prints the Web UI address. The default is `http://127.0.0.1:3080`; use the address printed by your terminal if the port is already in use.\n\nFor a quick preview, you can also run:\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. Configure ModelGo\n\nOpen the address printed by the terminal, click the sidebar button in the upper-left corner, and then click **Settings**.\n\n![Open DeepSeek Harness settings](/images/agents/deepseek-harness/settings.webp)\n\nSelect **Models** and click **Add custom provider**.\n\n![Add a custom provider](/images/agents/deepseek-harness/model-picker.webp)\n\nUse these values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider ID | `modelgo` |\n| Display name | `ModelGo` |\n| API URL | `{{ api_endpoint }}/v1` |\n| API protocol | `openai-completions` |\n| API key | ModelGo API key |\n| Model ID | A logical model name from the Model Catalog |\n| Display name | You can use the same value as the model ID |\n\n![Fill in the ModelGo custom provider](/images/agents/deepseek-harness/provider-config.webp)\n\nClick **Create provider** to save the configuration. Keep these points in mind:\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the API URL. Do not append `/chat/completions`; DSH builds the request path for the `openai-completions` protocol.\n- The model ID must be a logical ModelGo model name allowed by the API key. Do not copy the example model from the screenshot.\n- Keep the API key in your local configuration. Do not commit it or share it in screenshots.\n:::\n\n## 3. Start a session\n\nReturn to the main view, choose a workspace, and then select the ModelGo model you just added.\n\n![Select the ModelGo model](/images/agents/deepseek-harness/session.webp)\n\nSend a simple task such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### The Web UI does not open\n\nMake sure `pnpm dsh web` is still running and open the port printed by the terminal. The default is `3080`; DSH may choose another port when it is occupied.\n\n### 401 or authentication failed\n\nCheck that the API key is complete, has no extra spaces, and was created in the ModelGo Console.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet the API URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Select `openai-completions` as the API protocol.\n\n### The model list is empty\n\nCheck that a model ID is present and that the custom provider was saved. You can verify the ModelGo endpoint first:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [DeepSeek Harness official website](https://www.deepseek.com/harness/): see the latest installation and product information.\n- [DeepSeek Harness GitHub repository](https://github.com/deepseek-ai/deepseek-harness): view source and releases.\n","international/en/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: Connect Factory Droid to ModelGo.\n---\n\n# Factory Droid\n\nFactory Droid is Factory's terminal agent. Its BYOK custom model settings can point Droid at ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Node.js 18+ and the Droid CLI are installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\nInside Droid, `/settings` opens the settings screen.\n\n## 2. Configure a ModelGo custom model\n\nMerge this `customModels` entry into `~/.factory/settings.json` (Windows: `%USERPROFILE%\\\\.factory\\\\settings.json`):\n\n```json\n{\n  \"customModels\": [{\n    \"model\": \"your-model-id\",\n    \"displayName\": \"ModelGo / your-model-id\",\n    \"baseUrl\": \"{{ api_endpoint }}/v1\",\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"provider\": \"openai\"\n  }]\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nRestart Droid and choose the custom model from `/models` or the model picker.\n\n:::note\n- Set `baseUrl` to `{{ api_endpoint }}/v1`; do not add `/chat/completions`.\n- `model` must be a ModelGo logical model ID.\n- Merge `customModels` into the existing file so other settings remain intact.\n:::\n\n## 3. Verify a request\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"your-model-id\" \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### The model is not listed\n\nValidate the JSON, keep `customModels` at the top level, and fully restart Droid.\n\n### Authentication or endpoint errors\n\nCheck the environment variable in the shell that launches Droid and remove duplicate `/v1` or full paths from `baseUrl`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Factory Droid settings](https://docs.factory.ai/droid-cli/settings): Find `settings.json` and settings entry points.\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok): Review custom model fields.\n","international/en/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: Configure Hermes Agent with ModelGo's OpenAI-compatible API.\n---\n\n# Hermes Agent\n\nHermes Agent is a terminal-based AI agent. With a custom provider, Hermes can use ModelGo's OpenAI-compatible API to call models.\n\n## Before you start\n\n- Install Node.js 22 or newer.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm the ModelGo logical model name you want to use in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Hermes Agent\n\nmacOS or Linux:\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\nReopen your terminal and verify the installation:\n\n```bash\nhermes --version\n```\n\n## 2. Configure ModelGo\n\nPut your API key in an environment variable for the current shell. Never commit a real key to a repository or public script:\n\n```bash\nexport MODELGO_API_KEY=\"your-ModelGo-API-key\"\nexport MODELGO_MODEL=\"your-ModelGo-logical-model-name\"\n```\n\nIf you are not sure which model name to use, query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse `hermes config set` to create a custom provider. Replace `<model>` with a logical model name from the Model Gallery or the `GET /v1/models` response:\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\nIf your Hermes version includes the interactive setup wizard, you can run:\n\n```bash\nhermes model\n```\n\nChoose **Custom endpoint**, enter the ModelGo Base URL, API key, and model name, and select **Chat Completions** as the protocol.\n\n:::note\n- Some older Hermes releases label the Chat Completions protocol as `openai_messages`. If `chat_completions` is rejected, upgrade Hermes or select Chat Completions in the `hermes model` wizard.\n:::\n\n## 3. Check the configuration and start a session\n\nCheck the Hermes configuration:\n\n```bash\nhermes config check\n```\n\nStart Hermes after the check passes:\n\n```bash\nhermes\n```\n\nSend a message such as “Introduce ModelGo in three sentences.” A model response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API mode | `chat_completions` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model ID | A ModelGo logical model name, not the upstream provider's raw model ID |\n\nHermes stores non-sensitive settings in `~/.hermes/config.yaml` and API keys and other secrets in `~/.hermes/.env`. Do not share or commit files under `~/.hermes/` that contain credentials.\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nMake sure the API key is valid and has not been revoked or expired, then run:\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 403 or model unavailable\n\nCheck that `model.default` is a ModelGo logical model allowed by the policy attached to your API key.\n\n### 404 or endpoint not found\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions`; Hermes adds the request path itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs): see the latest installer, configuration, and CLI reference.\n","international/en/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: Connect Kilo CLI to ModelGo.\n---\n\n# Kilo CLI\n\nKilo CLI is a terminal coding agent with custom OpenAI-compatible providers. Because ModelGo CLI automation is not available for Kilo CLI, use `/connect` or a `kilo.jsonc` file.\n\n## Prerequisites\n\n- Node.js 18+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\nRun `kilo` in a project; `/connect` opens the interactive provider setup.\n\n## 2. Add a ModelGo provider\n\nCreate `kilo.jsonc` in the project root (or edit the global config):\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/your-model-id\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"ModelGo / your-model-id\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nAlternatively choose `/connect` → `OpenAI Compatible` and enter the same Base URL, key, and model ID.\n\n:::note\n- Use lowercase provider ID `modelgo`; select `modelgo/your-model-id`.\n- `baseURL` is `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- The model ID must match a ModelGo logical model.\n:::\n\n## 3. Verify the configuration\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck JSONC syntax, the provider ID, and the `model` path, then restart Kilo.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is exported and `baseURL` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Kilo CLI documentation](https://kilo.ai/docs/code-with-ai/platforms/cli): Review installation, `/connect`, and CLI commands.\n- [Kilo custom models](https://kilo.ai/docs/code-with-ai/agents/custom-models): Review OpenAI Compatible provider fields.\n","international/en/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: Configure Kilo Code with ModelGo's OpenAI-compatible API.\n---\n\n# Kilo Code\n\nKilo Code is an AI coding assistant for VS Code and JetBrains. Use its OpenAI-compatible provider to connect Kilo Code to ModelGo models and API keys.\n\n## Before you start\n\n- Install VS Code or a JetBrains IDE.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Kilo Code\n\n### VS Code\n\nOpen the VS Code Marketplace, search for **Kilo Code**, verify the publisher, and install the extension. Then open the Kilo Code panel from the activity bar.\n\n![Install Kilo Code from the VS Code Marketplace](/images/agents/kilo-code/vscode-market.webp)\n\nOn the first install, VS Code asks you to confirm the publisher. Verify that it is Kilo Code, then click **Trust Publisher & Install**.\n\n![Trust the Kilo Code publisher](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\nOpen Settings / Preferences → Plugins, search the Marketplace for **Kilo Code**, and install the plugin. Restart the IDE after installation so the plugin takes effect.\n\n![Install Kilo Code from the JetBrains Marketplace](/images/agents/kilo-code/jetbrains-market.webp)\n\nWhen installing a third-party plugin, JetBrains displays its plugin notice. Confirm it and click **Accept** to finish the installation.\n\n![Confirm the JetBrains third-party plugin notice](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. Configure ModelGo in VS Code\n\nOpen Kilo Code settings, go to **Providers**, select **OpenAI Compatible**, and enter:\n\nFrom the Kilo Code welcome screen, first choose **Bring my own Key**:\n\n![Choose Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model | A ModelGo logical model name |\n\n![Kilo Code VS Code configuration](/images/agents/kilo-code/vscode-config-global.webp)\n\nAfter saving, Kilo Code attempts to load models from the compatible `/v1/models` endpoint. If the target model is not in the picker, choose **Use custom** and enter the logical model name from the Model Gallery.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append `/chat/completions`. Kilo Code adds the standard path when it sends a request.\n- The model shown in the screenshot is only an interface example. Replace it with a ModelGo logical model allowed for the API key.\n- Keep the API key in Kilo Code's local settings. Do not commit it to a repository or include it in screenshots.\n:::\n\n## 3. Configure ModelGo in JetBrains\n\nOpen Kilo Code settings, click **Bring my own Key**, select **OpenAI Compatible**, and use the same values as in VS Code:\n\n![Choose Bring my own Key in JetBrains](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**: `{{ api_endpoint }}/v1`\n2. **API key**: your ModelGo API key\n3. **Model**: a ModelGo logical model name\n4. Click **Save**.\n\n![ModelGo provider settings in JetBrains](/images/agents/kilo-code/jetbrains-config-global.webp)\n\nIf the model picker is empty, verify that the Base URL is reachable, then choose the custom-model option and enter the logical model name manually.\n\n![Kilo Code completing a task in JetBrains](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. Verify the connection\n\nOpen a local project and send a simple coding request in the Kilo Code panel, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Kilo Code completing a coding task](/images/agents/kilo-code/vscode-start.webp)\n\nTo inspect the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in **API key**, not the Base URL field.\n\n### 403 or model unavailable\n\nMake sure **Model** is a logical model listed in the ModelGo Model Gallery and allowed by the policy attached to the API key. Do not use an upstream provider's raw model ID unless the gallery explicitly lists it.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Kilo Code appends the endpoint path when it sends the request.\n\n### The model picker is empty\n\nUse `GET {{ api_endpoint }}/v1/models` to check the API key and endpoint. If the endpoint works, choose **Use custom** and enter the logical model name manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Kilo Code documentation](https://kilo.ai/docs): see the latest extension installation and provider setup guidance.\n","international/en/agents/nanobot.md":"---\ntitle: nanobot\ndescription: Connect nanobot to ModelGo.\n---\n\n# nanobot\n\nnanobot is a lightweight terminal agent that configures providers and model presets in JSON. It can call ModelGo through its OpenAI-compatible API.\n\n## Prerequisites\n\n- Python 3.11+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\nThe default config is `~/.nanobot/config.json`.\n\n## 2. Configure a ModelGo provider\n\nMerge these fields into `~/.nanobot/config.json`:\n\n```json\n{\n  \"providers\": {\"modelgo\": {\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"apiBase\": \"{{ api_endpoint }}/v1\"\n  }},\n  \"modelPresets\": {\"ModelGo\": {\n    \"provider\": \"modelgo\",\n    \"model\": \"your-model-id\",\n    \"maxTokens\": 4096,\n    \"contextWindowTokens\": 65536,\n    \"temperature\": 0.1\n  }},\n  \"agents\": {\"defaults\": {\"modelPreset\": \"ModelGo\"}}\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nLeave `apiType` unset for a custom OpenAI-compatible endpoint.\n\n:::note\n- Preserve existing channels and tools fields when merging the JSON.\n- Keep the key in `MODELGO_API_KEY`, not in a committed config file.\n- The model must be a ModelGo logical model ID.\n:::\n\n## 3. Verify the connection\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### nanobot cannot find the model\n\nMake sure `modelPresets.ModelGo.provider` matches `providers.modelgo` and that the JSON is valid.\n\n### 401 or endpoint errors\n\nConfirm the key is exported and `apiBase` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [nanobot OpenAI-compatible provider guide](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md): Review the JSON configuration.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","international/en/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: Connect Oh My Pi to ModelGo.\n---\n\n# Oh My Pi\n\nOh My Pi (`omp`) is a terminal coding agent. Declare an OpenAI-compatible provider in `models.yml`, then select models as `provider-id/model-id`.\n\n## Prerequisites\n\n- Bun or the official installer is available.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux can also use the official installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. Add a ModelGo provider\n\nEdit `~/.omp/agent/models.yml`:\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: your-model-id\n        name: ModelGo / your-model-id\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` is the environment variable name:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\n:::note\n- Use `openai-completions` and `{{ api_endpoint }}/v1` for the endpoint.\n- Select models as `modelgo/your-model-id`.\n- Keep the real API key out of `models.yml` and source control.\n:::\n\n## 3. Select and verify\n\n```bash\nomp --list-models\nomp --model modelgo/your-model-id\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSend a small read-only task in the session.\n\n## Troubleshooting\n\n### ModelGo is missing from the model list\n\nCheck `~/.omp/agent/models.yml`, YAML indentation, and restart `omp`.\n\n### 401 or endpoint errors\n\nConfirm `MODELGO_API_KEY` is exported and `baseUrl` has no duplicate `/v1` or full endpoint path.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Oh My Pi providers](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md): Review provider, API, and key settings.\n- [Oh My Pi models](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md): Review model selection and `models.yml`.\n","international/en/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: Configure OpenClaw with ModelGo's OpenAI-compatible API.\n---\n\n# OpenClaw\n\nOpenClaw is an open-source, self-hosted personal AI assistant. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22.22.3 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\nVerify the installation:\n\n```bash\nopenclaw --version\n```\n\n## 2. Set the API key\n\nOpenClaw can read a provider API key from an environment variable. Set your ModelGo API key as `MODELGO_API_KEY`:\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. Configure the ModelGo provider\n\nCreate and open the OpenClaw configuration file:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\nPaste the following into `openclaw.json`, replacing `YOUR_MODELGO_MODEL` with a logical model name from the Model Catalog:\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | A ModelGo logical model name |\n| `agents.defaults.model.primary` | `modelgo/<logical-model-name>` |\n\n:::note\n- Use `{{ api_endpoint }}/v1` as `baseUrl`; do not append `/chat/completions`.\n- Set `contextWindow` and `maxTokens` to values supported by the selected model. The values above are generic examples; use the Model Catalog as the source of truth.\n- Set `reasoning` to `true` when the selected model supports reasoning.\n- Inject the API key through the environment. Do not write a real key into the config file or commit it.\n:::\n\n## 4. Start and verify\n\nSave the configuration and run:\n\n```bash\nopenclaw onboard --install-daemon\n```\n\nCheck the active provider and model:\n\n```bash\nopenclaw models status\n```\n\nIf the status is healthy, start the Gateway:\n\n```bash\nopenclaw gateway start\n```\n\nSend a simple message in OpenClaw, such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### Model not found\n\nMake sure `models.providers.modelgo.models[].id` matches the model name in `agents.defaults.model.primary`, which must use the `modelgo/<model-name>` format.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` exists in the current terminal and that `apiKey` is `${MODELGO_API_KEY}` with no extra spaces.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `baseUrl` to `{{ api_endpoint }}/v1`; do not use a full `/chat/completions` URL. OpenClaw appends the path for `openai-completions`.\n\n### Gateway did not load the new configuration\n\nRestart the Gateway after editing the file:\n\n```bash\nopenclaw gateway restart\n```\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [OpenClaw custom provider docs](https://docs.openclaw.ai/gateway/config-tools): see provider, Base URL, and model list configuration.\n","international/en/agents/opencode.md":"---\ntitle: OpenCode\ndescription: Configure OpenCode with ModelGo's OpenAI-compatible API.\n---\n\n# OpenCode\n\nOpenCode is an open-source terminal AI coding agent. Its custom provider support lets you connect any OpenAI-compatible endpoint, including ModelGo, from a terminal, IDE, or desktop client.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Install OpenCode and confirm that `opencode -v` works in your terminal.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenCode\n\nRun:\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nYou can also use the installation method provided by the OpenCode project. A version printed by `opencode -v` confirms a successful installation.\n\n## 2. Configure the ModelGo provider\n\nOpenCode reads user configuration from:\n\n- macOS/Linux: `~/.config/opencode/opencode.json`\n- Windows: `%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\nCreate or edit `opencode.json`. Replace `your-model-id` with a logical model name from the model catalog:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"your-model-id\"\n        }\n      }\n    }\n  }\n}\n```\n\nSet the environment variable:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `name` | `ModelGo`, the display name in OpenCode |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | A logical model ID and display name from the model catalog |\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- `modelgo` is a local provider ID and can be changed. Use the new ID when selecting a model.\n- Keep the API key in an environment variable instead of committing it to a config file.\n- Model IDs must exactly match logical model names from the ModelGo catalog.\n:::\n\n## 3. Select a model and start a chat\n\nStart OpenCode:\n\n```bash\nopencode\n```\n\nEnter `/models` to open the model picker, then select a model under the **ModelGo** provider.\n\n![Open the model picker in OpenCode](/images/agents/opencode/model-search.webp)\n\nThe **ModelGo** provider label confirms that OpenCode recognized the provider.\n\n![Identify ModelGo in the OpenCode model list](/images/agents/opencode/provider-name.webp)\n\nYou can also type `ModelGo` in the picker to filter the list:\n\n![Filter ModelGo models in OpenCode](/images/agents/opencode/provider-filter.webp)\n\nSelect the model and enter a simple task such as “Describe this project in three sentences.”\n\n![Start a chat with ModelGo in OpenCode](/images/agents/opencode/chat.webp)\n\n## 4. Verify the configuration\n\nIf the model list is empty, confirm that the API key can reach ModelGo:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical model names to use in `models`.\n\n## Troubleshooting\n\n### OpenCode cannot find the config file\n\nCheck that the file is named `opencode.json` and is in `~/.config/opencode/` (or `%USERPROFILE%\\\\.config\\\\opencode\\\\` on Windows). A project-level file with the same name can override user settings.\n\n### 401 or authentication errors\n\nConfirm that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces. Restart OpenCode after changing the variable.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as `baseURL`; do not append `/chat/completions`.\n\n### Empty model list or unavailable model\n\nMake sure the ID in `models` exactly matches a logical ModelGo model and that the model is enabled for the API key.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [OpenCode Providers documentation](https://opencode.ai/docs/providers): configure providers, credentials, and custom Base URLs.\n- [OpenCode configuration documentation](https://opencode.ai/docs/config/): learn the config file structure and model options.\n","international/en/agents/zcode.md":"---\ntitle: ZCode\ndescription: Configure ZCode with ModelGo's OpenAI-compatible API.\n---\n\n# ZCode\n\nZCode is a desktop AI coding environment from Zhipu AI for Windows, macOS, and Linux. It supports custom OpenAI-compatible providers, so you can use ModelGo models and API keys directly in ZCode.\n\n## Before you start\n\n- Install the ZCode desktop app.\n- Create an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name that the API key can call in the [Model catalog]({{ site_endpoint }}/models).\n\n## 1. Install ZCode\n\nOpen the [ZCode download page](https://zcode.z.ai/en/docs/install) and download the package for your operating system. ZCode provides macOS, Windows, and Linux builds; Linux users can choose `.deb`, `.rpm`, or AppImage.\n\n![ZCode download page](/images/agents/zcode/install.webp)\n\nComplete the installation and launch ZCode. On first launch, choose a workspace and finish the onboarding flow to reach the main interface.\n\n![ZCode platform installers](/images/agents/zcode/setup.webp)\n\n## 2. Add the ModelGo provider\n\nClick the settings icon in the lower-left corner, open **Model settings**, then click **Add provider** at the bottom of the provider list.\n\n![Open ZCode Model settings and add a provider](/images/agents/zcode/provider-fields.webp)\n\nEnter the following values:\n\n| Setting | ModelGo value |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | A ModelGo API key created in the [console]({{ console_endpoint }}/api-keys) |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | Click **Add model** and enter a logical model name from the model catalog |\n| Context window | Use the model's actual context length; if unsure, start with `200000` |\n\n![ModelGo provider settings](/images/agents/zcode/provider-saved-global.webp)\n\nClick **Add provider** to save. Keep these details in mind:\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not enter the full `/chat/completions` URL. ZCode appends the request path based on the API format.\n- Name is only the local display name. Use `ModelGo`; do not enter an upstream vendor name.\n- Model IDs must be logical model names from the ModelGo catalog. Do not copy the example model in the screenshot.\n- Keep the API key in the local ZCode settings and out of repositories or public screenshots.\n:::\n\n## 3. Add a model and start a chat\n\nClick **Add model**, enter a ModelGo logical model name, and save it. You can add multiple models as needed.\n\n![Select a ModelGo model in ZCode](/images/agents/zcode/chat.webp)\n\nReturn to the chat view, select **ModelGo** and the model you added, then enter a simple task such as “Describe this project in three sentences.” A successful response confirms the integration.\n\nTo verify which models the API key can call, run:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nCheck that the API key is complete, has no extra spaces, and is entered in the **API Key** field.\n\n### 403 or model unavailable\n\nConfirm that the Model list uses a logical model name from the ModelGo catalog and that the API key is allowed to call it.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL and choose **Chat completions (/chat/completions)**. Do not paste a complete endpoint path into Base URL.\n\n### Empty model list or provider cannot be saved\n\nMake sure at least one model has been added and the Base URL is reachable. If needed, verify the API key and endpoint with `GET {{ api_endpoint }}/v1/models`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): learn how to use API keys safely.\n- [ZCode installation docs](https://zcode.z.ai/en/docs/install): see the latest installation instructions.\n- [ZCode model connection docs](https://zcode.z.ai/en/docs/configuration): see custom provider and model settings.\n","international/en/models/audio/minimax.md":"---\ntitle: MiniMax Audio Inbound Protocol\ndescription: Drive platform-managed synchronous speech synthesis with MiniMax T2A request and response bodies.\n---\n\n# MiniMax Audio Inbound Protocol\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | Catalog-advertised MiniMax T2A inbound |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK alias with the same semantics |\n\nThis is **MiniMax synchronous speech synthesis (T2A V2)** as an inbound protocol. The gateway accepts a MiniMax `T2aV2Req` body as-is (`model`, `text`, `voice_setting`, `audio_setting`, `stream`, and other MiniMax fields) and **renders a MiniMax `T2aV2Resp`**, so a client written against MiniMax's own documentation can decode this surface directly.\n\n`model` is the platform logical model name; policy, routing, and billing apply as usual. The logical model must advertise `minimax_t2a` in `public_protocols`, or the gateway rejects the call as a protocol mismatch.\n\nFor OpenAI-shaped binary audio, see [Speech](./speech).\n\n## Synthesize\n\nThe two paths are equivalent:\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"Hello from ModelGo.\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\nA successful non-stream response is MiniMax JSON. Audio lives in `data.audio` as a **hexadecimal string** (not a raw `audio/mpeg` body):\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\nVerified 2026-09-10 on domestic production with `speech-2.8-turbo` against `POST /minimax/v1/t2a_v2` (hex truncated). The same model on `POST /v1/audio/speech` returns `model_protocol_not_offered`.\n\nOnly numeric `base_resp.status_code` **`0`** is success. HTTP 200 with a non-zero `status_code` is still a failed invoke.\n\n### Streaming\n\nSet `\"stream\": true`. The response is SSE whose events are MiniMax JSON (incremental hex audio), not OpenAI chat `choices[].delta` chunks.\n\n### Failures and HTTP status\n\nIn-band MiniMax errors are echoed to the caller. The gateway maps `status_code` to HTTP:\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| any other non-`0` | `502` |\n\n### Billing\n\nUsage is the upstream **character** count (`usage.characters`, else `extra_info.usage_characters`). The gateway does not bill `len(text)`.\n\n## Conventions\n\n- `model` is the platform logical model name; whether this lane is allowed is the model's `public_protocols`.\n- The path does not pick the upstream family. Routing on the logical model decides MiniMax-direct vs a Bailian adaptor.\n- Providers on the route must declare MiniMax T2A. An OpenAI-compatible relay alone returns `provider_unsupported`.\n","international/en/models/audio/speech.md":"---\ntitle: Speech\ndescription: OpenAI-compatible text-to-speech endpoint.\n---\n\n# Speech\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\nThe request is JSON (OpenAI `{input, voice}`) and the response body is binary audio returned with the upstream `Content-Type`.\n\n**Check `public_protocols` first.** Domestic `speech-2.8-hd` / `speech-2.8-turbo` currently offer MiniMax T2A, not this endpoint (`model_protocol_not_offered`). Use [MiniMax Audio Inbound Protocol](./minimax).\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"Hello from ModelGo.\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\nFor MiniMax-native fields (voice mix, subtitles, hex JSON, SSE), see [MiniMax Audio Inbound Protocol](./minimax).\n","international/en/models/audio/transcriptions.md":"---\ntitle: Transcriptions\ndescription: OpenAI-compatible speech-to-text endpoint.\n---\n\n# Transcriptions\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\nThis endpoint typically uploads audio as `multipart/form-data` and returns JSON with recognized `text`.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/en/models/audio/translations.md":"---\ntitle: Translations\ndescription: OpenAI-compatible audio translation endpoint.\n---\n\n# Translations\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\nUploads follow the same shape as transcriptions and return translated text in JSON.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/en/models/images/edits.md":"---\ntitle: Image Edits\ndescription: OpenAI-compatible image edit endpoint.\n---\n\n# Image Edits\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\nThis endpoint uses `multipart/form-data` and forwards the original body and `Content-Type` upstream, so clients should call `POST /v1/images/edits` with multipart upload semantics.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\nIf the routed upstream model does not support image editing, the gateway returns `provider_unsupported`.\n","international/en/models/images/generations.md":"---\ntitle: Image Generation\ndescription: OpenAI-compatible image generation endpoint.\n---\n\n# Image Generation\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\nThe request body follows the OpenAI Images-compatible shape and is forwarded to an upstream provider that supports image generation. The main entrypoint is `POST /v1/images/generations`.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\nCommon optional fields include `size`, `quality`, and `n`, subject to upstream model support.\n\n## Verified Seedream limit\n\n`doubao-seedream-5.0-lite` rejects `size=1024x1024` (HTTP 400 `provider_invalid`, at least 3686400 pixels). `2048x2048` succeeded on 2026-09-10. Full curl: [API catalog](../../../quickstart/openapi).\n","international/en/models/images/qwen-image.md":"---\ntitle: Qwen Image Generation and Editing 3.0 (Bailian native protocol)\ndescription: Call qwen-image-3.0 / qwen-image-3.0-pro on either of two synchronous inbound lanes — OpenAI-compatible and Bailian DashScope native — with text to image and image to image (1-3 reference images), the two spellings of size, and the 1k / 2k resolution tiers. The official Bailian SDK works by changing base_url.\n---\n\n# Qwen Image Generation and Editing 3.0 (Bailian native protocol)\n\n## Models\n\n| Model | Output resolution | Notes |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | Total pixels 512×512 – 2048×2048 | Pro tier; the 2k tier costs more than 1k |\n| `qwen-image-3.0` | Same | Standard tier; both tiers priced the same |\n\n> **Availability and pricing differ by region.** Check the model list for this endpoint before integrating — see the [API catalog](../../../quickstart/openapi).\n\nBoth models serve **text to image (T2I)** and **image to image / editing (I2I)**: no reference image means T2I, 1–3 reference images mean I2I. Images are returned **synchronously** — no polling.\n\n> **The async task lane is not supported.** This family is served only on the synchronous endpoints; a call to `/v1/content_generation/tasks` is refused.\n\n## Two inbound lanes\n\nOne model, two spellings, identical capability. Pick whichever matches the code you already have:\n\n| Lane | Path | Who it is for |\n| --- | --- | --- |\n| OpenAI-compatible | `POST /v1/images/generations` | Apps already written against the OpenAI Images protocol or SDK — change `base_url` and `model` only |\n| Bailian native | `POST /api/v1/services/aigc/multimodal-generation/generation` | Apps already using the Bailian DashScope SDK — change `base_url` only |\n\n> **The two lanes spell `size` differently and neither accepts the other's spelling**: the OpenAI-compatible lane uses the letter `x` (`1024x1024`), the Bailian native lane uses an asterisk (`1024*1024`). The wrong one returns `400` naming the separator it expects; it is **not** silently rewritten — mixing the two protocols should surface here rather than as a harder problem further down.\n\n## 1. OpenAI-compatible lane\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### Text to image\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"A fluffy ginger cat on a sunlit windowsill, afternoon light, film grain\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### Image to image / editing\n\nNo multipart: the reference images go in the top-level `image` field.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"Keep her facial features; change the outfit to a champagne silk shirt and a dark grey blazer\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### Response\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- Images are PNG, and the **link is valid for 24 hours** — download promptly and do not persist the URL.\n- `usage` carries **image counts and tiers, not token usage**: this family bills purely per image (see Billing).\n- `response_format: \"b64_json\"` does not error but is ignored; the response still carries an image URL.\n\n### Using the OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # Generation is slow; 40-60s for a single image in practice\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"A fluffy ginger cat on a sunlit windowsill, film grain\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # extensions go through extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` are not OpenAI parameters: pass them via `extra_body` with the OpenAI SDK, or at the top level of the request body over plain HTTP.\n\n## 2. Bailian native lane\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\nRequest and response are Bailian's own shapes in both directions — the gateway does not translate.\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### Constraints of this lane\n\n- `input.messages` carries **exactly one** object and `role` must be `user` (single-turn only).\n- `content` carries **exactly one** `{\"text\": ...}`; omitting it or passing several returns `400`.\n- `{\"image\": ...}` 0–3 entries: 0 is text to image, 1–3 is image to image.\n- Generation parameters live under `parameters` (not at the top level): `size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`.\n- With the official Bailian SDK (`dashscope`), point `dashscope.base_http_api_url` at `{{ api_endpoint }}/api/v1` and use your ModelGo API key.\n\n## 3. Parameters\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt` (compat lane) / `content[].text` (native lane) | string | Required, non-empty. Chinese and English; up to about 4500 tokens recommended |\n| `image` (compat lane) / `content[].image` (native lane) | string / string[] | Reference images, 1–3. **`null` and an empty array are refused** |\n| `size` | string | `WxH` on the compat lane, `W*H` on the native lane. Omitted means the model picks a resolution from the prompt |\n| `n` | int | 1–6 output images, default 1. **Must be an integer**; the string form (e.g. `\"1\"`) returns `400` |\n| `negative_prompt` | string | What to keep out of the picture |\n| `seed` | int | `0` – `2147483647`. A fixed seed makes results relatively stable |\n| `prompt_extend` | boolean | Prompt rewriting, default `true` (recommended) |\n| `prompt_extend_mode` | string | `direct` (default, T2I and I2I) / `agent` (finer, **text to image only**) |\n| `enable_thinking` | boolean | Thinking mode, default `true`. Better images, longer latency. Only effective when `prompt_extend=true` |\n| `watermark` | boolean | Watermark, default `false` |\n\n### Validation happens before the call\n\nThe following are refused at creation (HTTP `400`) — nothing reaches the upstream and nothing is charged:\n\n- `n` is not an integer in 1–6, or is written as a string or a decimal;\n- `size` total pixels fall outside 512×512 – 2048×2048, or the aspect ratio is outside 1:8 – 8:1;\n- `size` uses the other lane's separator (the error names whether `x` or `*` is expected);\n- `image` is `null`, an empty array, or more than 3 entries;\n- `prompt_extend_mode: \"agent\"` is combined with `image` (APE is text to image only);\n- `seed` is outside `0` – `2147483647`;\n- on the native lane, `messages` is not exactly one, or `content` does not carry exactly one `text`.\n\n### Reference image requirements\n\n- Formats: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF.\n- Width and height between 384 and 2048 pixels recommended; at most 10 MB each.\n- Public URLs (HTTP / HTTPS) or Base64 (`data:{MIME_type};base64,{base64_data}`).\n- A public URL must be directly `GET`-able by the upstream: no auth, no redirect, no Referer / Cookie dependency. Some sites return 403 to non-browser clients, which fails the request.\n\n## 4. Metering\n\n**This family is metered per image, not per token.** The `usage` block carries image counts and tiers rather than token counts:\n\n| Field | Meaning |\n| --- | --- |\n| `output_image_count` | How many images were delivered |\n| `output_image_type` | The output tier this call hit: `qima_output_1k` or `qima_output_2k` |\n| `input_image_count` | How many reference images the request supplied (0 for text to image) |\n| `input_image_type` | The input tier, `qima_input_1k` or `qima_input_2k` |\n\n**The tier is decided by the OUTPUT pixel area**: an area of 2,250,000 (that is, 1500×1500) or less is `1k`, anything larger is `2k`. **The input tier is judged by the output area too**, not by the size of the reference image — that is the upstream's own rule.\n\nText to image supplies no reference image, so `input_image_count` is 0 and only the delivered images are metered. Requesting `n` images meters `n`, not one.\n\n## 5. Full example (Python, official Bailian SDK)\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt; modern minimalist cafe background\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","international/en/models/realtime/api.md":"---\ntitle: Realtime API reference\ndescription: Handshake, events, and audio formats for GET /api-ws/v1/realtime (WebSocket).\n---\n\n# Realtime API reference: `GET /api-ws/v1/realtime`\n\nThis endpoint is a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol verbatim in both directions with **no protocol translation**; the full field definitions and the tool-calling (Function Calling / MCP) events follow Bailian's official [client events](https://help.aliyun.com/zh/model-studio/client-events) and [server events](https://help.aliyun.com/zh/model-studio/server-events). This page covers the handshake, auth, event list, and audio conventions needed to integrate.\n\n## Request\n\n| Item | Value |\n| --- | --- |\n| Method | `GET` (WebSocket upgrade) |\n| Path | `/api-ws/v1/realtime` |\n| Full URL | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<logical model>` |\n| Query | `model` (required) — the platform logical model, not the upstream model |\n| Header | `Authorization: Bearer <mgk_ API Key>` (required) |\n| Header | `X-Request-ID` (optional) — propagated to the call log; the `request_id` starts with `gw_rt_` |\n\nOnly a logical model whose `public_protocols` includes `dashscope_realtime` can use this surface.\n\n## Handshake errors {#handshake-errors}\n\nFailures before the WebSocket upgrade are returned as HTTP status codes with a body of:\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | Trigger | Observed message (cn production, 2026-10-08) |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | no API key | `missing api key` |\n| 401 | `unauthorized` | invalid / disabled key | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | model not in catalog | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | model does not advertise `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | no route for the model in the policy (including its fallback chain) | `no route for model <model>` |\n| 503 | `no_provider` | a route exists but no provider instance is available | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | preauthorization failed (balance / budget) | `billing: insufficient funds` |\n\nAfter a successful upgrade (HTTP 101), later problems are delivered as an in-band `error` event, then the connection closes:\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## Session configuration `session.update`\n\nAfter connecting, the server first sends `session.created`; the client overrides with `session.update`, and a valid update is acknowledged with `session.updated`. Common fields:\n\n| Field | Values | Default |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | see Bailian's voice list | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | server VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | any text | empty |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | enabled |\n\n`turn_detection: null` disables the server VAD so the client commits and triggers responses manually.\n\n## Client events\n\n| Event | Purpose |\n| --- | --- |\n| `session.update` | Update session config (modalities, voice, audio format, VAD, instructions, …) |\n| `input_audio_buffer.append` | Append Base64 audio to the input buffer |\n| `input_image_buffer.append` | Append a Base64 image (JPG/JPEG; audio must have been sent first) |\n| `input_audio_buffer.commit` | Commit the audio buffer in manual mode (does not trigger a response) |\n| `input_audio_buffer.clear` | Clear the audio buffer |\n| `conversation.item.create` | Create an item: plain text input, `function_call_output`, `mcp_approval_response` |\n| `response.create` | Trigger one model response |\n| `response.cancel` | Cancel the in-progress response (interruption) |\n\n## Server events\n\n| Event | Meaning |\n| --- | --- |\n| `session.created` / `session.updated` | Session created / config applied |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD detected the user starting / stopping (interruption trigger) |\n| `input_audio_buffer.committed` / `cleared` | Audio buffer committed / cleared |\n| `conversation.item.created` | An item was created |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | Input speech transcription (streaming preview / final) |\n| `response.created` | A response turn began |\n| `response.output_item.added` / `response.content_part.added` | Output item / content part began |\n| `response.text.delta` / `response.text.done` | Text-only streaming / full text |\n| `response.audio_transcript.delta` / `.done` | Transcript of the audio output |\n| `response.audio.delta` / `response.audio.done` | Base64 output audio (24 kHz PCM) / end of audio |\n| `response.output_item.done` / `response.content_part.done` | Output item / content part completed |\n| `response.done` | Response turn ended; `response.usage` carries per-modality token usage |\n\nTool-calling events (`response.function_call_arguments.delta` / `.done`) and the MCP events (`mcp_*`) are documented in Bailian's server-events reference.\n\nObserved event order for one voice turn (cn production, 2026-10-08):\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## Audio formats\n\n| Direction | Format | Field |\n| --- | --- | --- |\n| Uplink (input) | 16000 Hz, 16-bit little-endian, mono PCM, Base64 | `audio` of `input_audio_buffer.append` |\n| Downlink (output) | 24000 Hz, 16-bit little-endian, mono PCM, Base64 | `delta` of `response.audio.delta` |\n\nSending input audio in full 100 ms frames (3200 bytes per frame) proved most reliable. `input_audio_buffer.append` only buffers; whether it is committed is decided by VAD or by a client `input_audio_buffer.commit`.\n\n## VAD and interruption\n\n- With a non-`null` `turn_detection`, the server auto-detects speech boundaries and, after `silence_duration_ms` of silence (default 800 ms), auto-commits and triggers a response.\n- When the user speaks again: the server emits `input_audio_buffer.speech_started` → the client **stops playback** and sends `response.cancel` → `response.done` (cancelled) arrives → a new turn begins.\n- `turn_detection: null` is manual mode: after recording, the client sends `input_audio_buffer.commit` (wait for `input_audio_buffer.committed`) then `response.create`.\n\n## Usage and billing\n\nEach turn's `response.done.response.usage` carries per-modality tokens:\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\nThe gateway settles the accumulated session usage at close: a session-level estimate is held at connect (currently about ¥1.2; insufficient balance fails the handshake with `402`), then refund/top-up applies based on actual usage; a session with no usage releases the hold. See the [guide](./guide#billing).\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Upstream rate limit | 60 RPM |\n\n## Related\n\n- [Realtime (WebSocket) models guide](./guide)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","international/en/models/realtime/guide.md":"---\ntitle: Realtime (WebSocket) models\ndescription: Call Qwen-Omni-Realtime over WebSocket for live voice chat, interruption, and omni-modal input.\n---\n\n# Realtime (WebSocket) models\n\nRealtime models do **not** use `/v1/chat/completions`; they are called over a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol **verbatim in both directions** — there is no protocol translation: you send Bailian events and receive Bailian events. This page covers connection, a runnable minimal example, and billing; the exact event and error schema is in the [API reference](./api).\n\n## What it does\n\n- **Live voice chat**: speak and get streamed text and audio back as you go.\n- **Interruption**: when the user speaks again the server emits `input_audio_buffer.speech_started`; the client stops playback and sends `response.cancel` to interrupt the current reply.\n- **Omni-modal input**: streaming audio, images (frames sampled from video), and plain text.\n- **Text + audio output**: the model produces both text and speech.\n\n## Supported models\n\nA logical model can use this surface only if its catalog `public_protocols` includes `dashscope_realtime`. The realtime model currently available is `qwen3.8-omni-flash-realtime` (check the marketplace for what is actually listed). Check the model marketplace at [{{ console_endpoint }}]({{ console_endpoint }}) to confirm whether a model offers this protocol.\n\n## Connecting\n\n| Item | Value |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<logical model>` (required) |\n| Auth | `Authorization: Bearer <mgk_ API Key>` |\n| Request ID | optional `X-Request-ID`; the call-log `request_id` starts with `gw_rt_` |\n\nHandshake failures are returned as HTTP status codes (e.g. an invalid key is `401 unauthorized`, a model without the realtime protocol is `403 model_protocol_not_offered`, insufficient balance is `402`); see the full list in the [API reference](./api#handshake-errors).\n\n## Minimal example\n\nThe examples below run **server-side**: connect with an `mgk_` API key, configure the session, push 16 kHz PCM audio, commit, request a reply, and write the returned 24 kHz PCM to `reply.pcm`.\n\n:::note\n- A browser's native `WebSocket` constructor **cannot set an `Authorization` header**, so the API key must not be placed in a browser connection.\n- For browser microphone capture, relay through your own server (which holds the key and opens the connection), or use an authenticated server-side proxy.\n- The Python / Node.js examples below are server-side and run as-is.\n:::\n\nPrepare input: capture the microphone, or save 16 kHz, 16-bit little-endian, mono, **headerless** PCM as `input.pcm`. If you have a WAV, extract the raw PCM first:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython (`pip install websocket-client`):\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js (`npm install ws`):\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\nWrap the returned `reply.pcm` (24 kHz, 16-bit, mono) into a playable WAV:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\nTo smoke-test connectivity without audio, send one `conversation.item.create` with an `input_text` content item, then `response.create`, to get a text-only reply.\n\n## Session configuration\n\nRight after connecting, the server sends `session.created` (with defaults); the client overrides with `session.update`. Common fields:\n\n| Field | Meaning |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` (default) or `[\"text\"]` |\n| `voice` | output voice, default `Tina`; prefer `audio.output.voice` |\n| `turn_detection` | server VAD: `{\"type\":\"server_vad\"}` or `{\"type\":\"semantic_vad\"}`; `null` = client-side manual commit |\n| `audio.input.format` | input format, e.g. `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | output format, e.g. `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | system persona |\n| `audio.input.transcription` | input transcription; the server enables it automatically (model `qwen3-asr-flash-realtime`) |\n\nThe legacy `input_audio_format` / `output_audio_format` fields still work, but new integrations should use `audio.input.format` / `audio.output.format`.\n\n## Interruption\n\nWith a non-`null` `turn_detection`, the server VAD drives turns. When the user speaks again:\n\n1. the server emits `input_audio_buffer.speech_started`;\n2. the client **stops playing** buffered reply audio and sends `response.cancel`;\n3. the server then emits `response.done` (status cancelled) and starts a new turn.\n\nIn manual mode (`turn_detection: null`) the client sends `input_audio_buffer.commit` and `response.create` after recording.\n\n## Billing {#billing}\n\n- **Token-based, per modality**: input is split into text/image/video and audio; output into text and audio. When the model produces speech, the audio **and** its transcript text are billed separately.\n- **Preauthorization at connect**: a session-level estimate is held when the connection opens (currently about ¥1.2). If the balance cannot cover it, the handshake returns `402` and no connection is established.\n- **Settled after close on actual usage**: the total of every `response.done` `usage` over the connection is settled at close — refund or top-up applies. A session that meters nothing releases the hold and charges nothing.\n\nCheck the console model page for current prices; for example, domestic `qwen3.8-omni-flash-realtime` (CNY / million tokens) is priced at input text/image/video `1.5`, input audio `6`, output text `4.5`, output audio `12`.\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced; the socket is closed and settled at the cap) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Audio history | up to 100 turns / 600 s |\n| Video history | up to 50 turns / 240 s |\n| Upstream rate limit | 60 RPM |\n\n## Next steps\n\n- [API reference: `GET /api-ws/v1/realtime`](./api)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","international/en/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: Re-order candidate documents by relevance to a query.\n---\n\n# Rerank\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | Re-rank documents by relevance to a query |\n| `POST` | `/v1/reranks` | Alias, equivalent to `/v1/rerank` |\n\nThe Rerank endpoint takes a query and a set of candidate documents and returns them ordered by relevance. It is commonly used for the re-ranking stage in retrieval-augmented (RAG) pipelines. `/v1/rerank` and `/v1/reranks` are two equivalent paths to the same capability.\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"Which protocols does ModelGo support\",\n    \"documents\":[\n      \"OpenAI and Anthropic compatible protocols\",\n      \"The weather is nice today\",\n      \"Supports image, video, vector, and audio capabilities\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## Key conventions\n\n- `model` must be the platform logical model name; the body is forwarded per the upstream Rerank protocol, and whether specific fields (e.g. `top_n`, `return_documents`) take effect depends on the routed upstream model.\n- The response typically contains a relevance score and rank index for each document.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","international/en/models/text/generation.md":"---\ntitle: Text Generation\ndescription: Unified guidance for OpenAI Responses, Chat Completions compatibility, and Anthropic Messages.\n---\n\n# Text Generation\n\nThe gateway exposes the following public text entrypoints. Prefer `POST /v1/responses` for new integrations, and use the others for SDK compatibility or native Claude clients.\n\n| Protocol | Method and path | Use |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | Preferred unified text generation API for new projects |\n| OpenAI | `POST /v1/chat/completions` | Widely compatible chat completion endpoint |\n| OpenAI | `POST /v1/completions` | Legacy text completions, only for compatibility |\n| Anthropic | `POST /v1/messages` | Claude native message format |\n| OpenAI | `GET /v1/models` | List logical models available under the current routing |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"Introduce ModelGo in three sentences.\"\n  }'\n```\n\nUse this entrypoint when you want a single OpenAI-compatible response API with a forward-looking request shape.\n\n## OpenAI Chat Completions compatibility {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this for existing OpenAI SDK flows that still depend on chat completions. New projects should usually start from `POST /v1/responses`.\n\n## OpenAI Completions (legacy)\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"Introduce ModelGo in three sentences.\",\n    \"max_tokens\":256\n  }'\n```\n\nThe legacy text-completions endpoint, only for call chains that still use a `prompt`. New projects should use Responses or Chat Completions above. `stream` is likewise delivered over SSE. Most current chat models do not offer this protocol: `qwen3.6-flash` returned HTTP 400 `model_protocol_not_offered` on 2026-09-10.\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this when the client already speaks Claude's native `/v1/messages` schema. The gateway preserves the native event-stream framing for streamed Anthropic responses.\n\n## Listing models\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` returns the logical models allowed by the API key's bound policy (resolved against the platform model catalog). It does not probe upstream capabilities at request time and may differ from the console; billing and policy follow the console and bound policies.\n\n## Key conventions\n\n- `model` must be the platform logical model name.\n- `GET /v1/models` is available; the list is derived from the API key's bound policy and the platform model catalog.\n- Both OpenAI and Anthropic style endpoints may return upstream-native `usage`.\n- Stream failures may arrive as error chunks; do not rely only on `data: [DONE]`.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","international/en/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI-compatible embedding endpoint.\n---\n\n# Embeddings\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Multimodal (image/text) embeddings |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` may be a single string or an array of strings. The response follows the OpenAI-compatible embeddings shape.\n\n## Multimodal embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\nFor embedding inputs that mix text and image content. The `input` shape depends on the routed model's multimodal capabilities; whether it takes effect is determined by the upstream model.\n","international/en/models/video/ark.md":"---\ntitle: Seedance Video Inbound Protocol\ndescription: Drive platform-managed async Seedance video tasks over Ark's own paths, with Ark-shaped request and response bodies.\n---\n\n# Seedance Video Inbound Protocol\n\nBeyond the standard video protocols, the Doubao Seedance series (`doubao-seedance-*`) can also be\ncalled over **Volcengine Ark's own paths**, with request and response bodies following Ark's\ncontent-generation protocol:\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | Create a content generation (video) task |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Poll task status and result |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent**, see below) |\n\nThis is a **platform-managed** lane: the path is Ark's own, but the request runs on the gateway's\nstandard async task pipeline — the very same one behind\n[Generic Async Content Generation Tasks](./async-tasks), just spelled with Ark's path. It therefore\nkeeps per-dimension metering, task persistence, artifact delivery, and preauthorize/settle intact.\n\n## Create a task\n\nThe body follows Ark's content-generation protocol, and `model` is the **platform logical model\nname** (e.g. `doubao-seedance-2.0-mini`):\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a neon city cat\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" } }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\nValid values for `resolution` / `ratio` / `duration` **vary by model** — the Fast and Mini variants of\nSeedance 2.0, for instance, do not support `1080p`, and `duration` has a floor of 4 seconds. Follow the\ncapability notes for the model you are calling; out-of-range values are rejected at create time.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll answer with exactly the Ark task object documented under\n[Generic Async Content Generation Tasks](./async-tasks) — it is the same pipeline, so the response\npayload and every field's meaning (`status` values, `content.video_url`, `error`, when `usage` is\nomitted) are identical to that page and are not repeated here.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nA successful cancel voids the preauthorization; nothing is settled.\n\n**Not every upstream supports cancelling, though.** Whether a task can be cancelled depends on\nwhether the supplier serving it implements cancellation, and because this lane does not pin an\nupstream family, two calls on the same logical model may differ — one cancellable, one not. Two\nfailure shapes:\n\n| Case | Response |\n| --- | --- |\n| The supplier serving the task cannot cancel | `400` / `4003` `provider_unsupported`, `endpoint not supported by provider` |\n| The task already reached a terminal state (`succeeded` / `failed`) | `409` `task_already_terminal`, `task already finished; nothing to cancel` |\n\nWhen a cancel fails the preauthorization is not released early — it follows the normal\nsettle/expiry path once the task reaches a terminal state. So **do not treat \"create then cancel\"\nas a reliable way to back out of a charge.**\n\n## Key conventions\n\n- **`id` is the gateway task id, not the upstream one.** Polling and cancelling only accept that id,\n  so hold on to the `id` returned by create.\n- **The response shape is fixed.** Whichever upstream actually serves the request, create and poll\n  both answer with the same Ark task object — it does not change when routing changes.\n- **The lane does not pin an upstream family.** The URL spelling plays no part in routing: whoever\n  the logical model behind `model` routes to serves it. Seedance is carried by several suppliers on\n  the platform, so two calls on the same logical model may land on different upstreams — that is\n  expected.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the Ark paths — use `content.video_url` from the response.\n- Whether a model is offered on this lane depends on its catalog `public_protocols` including\n  `content_generation`; without it the call is refused with `4005`. Check with\n  `GET {{ api_endpoint }}/v1/models`.\n\nIf you do not need Ark's path and field style, [OpenAI-Compatible Video Flow](./openai-compatible) is\nthe more standardized choice.\n","international/en/models/video/async-tasks.md":"---\ntitle: Generic Async Content Generation Tasks\ndescription: A platform-managed async task entrypoint for image, video, and other content generation capabilities.\n---\n\n# Generic Async Content Generation Tasks\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | Create a generic async content generation task (image / video / ...) |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | Poll a generic content generation task |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent** — see \"Cancel a task\" in [Seedance Video Inbound Protocol](./ark)) |\n\n`/v1/content_generation/tasks` is a more general async task entrypoint than the standard OpenAI-compatible video flow. It covers image, video, and other generation capabilities that must run as backend tasks.\n\n## Create a task\n\nThe body follows the upstream generic generation shape and must include at least `model`:\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\nVerified 2026-09-10 on domestic production: create returned `status=queued` with a `gw_…` id; polling the same id ended at `succeeded` with `resolution=720p`, `ratio=16:9`, `duration=5`. The same model on `POST /v1/video/generations` is `model_protocol_not_offered`. `DELETE` cancel returned `provider_unsupported` on that upstream.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll both answer with the **same** Ark-shaped task object, regardless of which upstream served the request:\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` is one of `queued` / `running` / `succeeded` / `failed`; `id` is the **gateway task id**, and it is the only id polling and cancelling accept.\n\n## Three spellings, one pipeline\n\nThe same managed async pipeline has three inbound spellings. Which one you pick depends only on whose payload style you want to write your client against:\n\n| Entry point | Request body | Response body |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | Generic generation shape | Ark task object (above) |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark content-generation native body | Ark task object |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax video-generation V2 native body | MiniMax shapes (`{\"task_id\"}` / `{\"task\":{…}}`) |\n\nBilling, task persistence, artifact delivery, and preauthorize/settle behave identically across all three.\n\n## When to use it\n\n- The platform capability is asynchronous but does not use the OpenAI Video-standard request / response shape\n- You want a unified platform-managed create-and-poll flow instead of handling each vendor's native protocol yourself\n- You are calling a video model such as Jimeng that is exposed only through the managed async lane\n\n## Key conventions\n\n- `model` is still the platform logical model name; the platform decides which upstream implementation handles the task.\n- Request fields depend on the routed capability; the response shape, by contrast, is fixed — see above.\n- If you do not want to manage multiple vendor-specific polling styles, prefer this entrypoint.\n\nFor the standard OpenAI-compatible video protocol, see [OpenAI-Compatible Video Flow](./openai-compatible).\n","international/en/models/video/minimax.md":"---\ntitle: MiniMax Video Inbound Protocol\ndescription: Drive platform-managed async video tasks with MiniMax video-generation V2 request and response bodies, for the MiniMax-H3 family.\n---\n\n# MiniMax Video Inbound Protocol\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | Create a video generation task |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | Poll task status and result |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | Cancel an unfinished task and release its preauthorization |\n\nThis is **MiniMax video generation V2** as an inbound protocol, aimed mainly at the MiniMax-H3 family.\nLike the Ark lane it runs on the platform-managed async pipeline — the request body is MiniMax's own\nshape, and **the responses are rendered in MiniMax's shape too**, so a client written against\nMiniMax's own documentation can decode this surface directly.\n\nThe task lives on the platform, so per-dimension metering, artifact\ndelivery, and preauthorize/settle all apply as usual.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a boy playing basketball by the sea\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\nCreate answers the bare task handle from MiniMax's documentation:\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### Request fields\n\n`content[]` is a multimodal array; `type` and `role` together decide what each part is:\n\n| `type` | Valid `role` | Meaning |\n| --- | --- | --- |\n| `text` | — | Prompt |\n| `image_url` | `first_frame` / `last_frame` | First / last frame image |\n| `image_url` | `reference_image` | Reference image |\n| `video_url` | `reference_video` | Reference video |\n| `audio_url` | `reference_audio` | Reference audio |\n\n- **Frames and references cannot be mixed**: a request carrying `first_frame` / `last_frame` may not\n  also carry any `reference_*` part, and vice versa — they map to two different upstream jobs.\n- `resolution`, `duration`, and `ratio` are flat siblings of `content`. For MiniMax-H3 the accepted\n  values are `resolution` ∈ `768P` / `2K`, `duration` an integer in `4`–`15`, and `ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`. Omitting one applies the upstream default\n  (`2K`, 5 seconds) — **and bills at that default tier**.\n- Prompt length is capped at roughly 7000 characters.\n- Which values are actually supported still depends on the logical model behind `model`.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nPoll answers a `task` envelope — a **different shape** from create:\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` is one of `queued` / `running` / `succeeded` / `failed`.\n- On success the artifact URL is in `task.content.url`.\n- `usage` is denominated in **seconds** (H3 is quoted per second of output), not tokens; it is\n  omitted when the upstream reports only token counts and no seconds.\n- On failure a `task.error` (`code` / `message`) is added. That field is not part of MiniMax's\n  documented success schema — it is included so a failure reason is visible at all, and a client\n  decoding the documented struct simply ignores it.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCancelling voids the preauthorization. Note that this lane never reports MiniMax's documented\n`cancelled` status — a cancelled task is surfaced as `failed`, which is what makes its\npreauthorization be released rather than settled.\n\n## Key conventions\n\n- **`id` / `task_id` are the gateway task id**, not the upstream one; polling and cancelling only\n  accept that id.\n- The lane does not pin an upstream family; the logical model behind `model` decides who serves the\n  request, and the URL spelling plays no part in it.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the MiniMax paths.\n\nFor the most standardized experience, use [OpenAI-Compatible Video Flow](./openai-compatible).\n","international/en/models/video/openai-compatible.md":"---\ntitle: OpenAI-Compatible Video Flow\ndescription: Standard OpenAI Video-compatible endpoints for task creation, polling, and asset retrieval.\n---\n\n# OpenAI-Compatible Video Flow\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | Create an OpenAI-compatible video task |\n| `GET` | `/v1/videos/{task_id}` | Poll video task status and result |\n| `GET` | `/v1/videos/{task_id}/content` | Fetch the produced content of a finished video task |\n\nThis set of endpoints is the platform's **standard video protocol**: the request uses OpenAI Video-compatible fields, and the platform translates it into the upstream vendor's async video task format.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\nA successful create returns a `task_id`. Subsequent polling and content fetches are all keyed by that `task_id`.\n\n## Poll task status\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` is one of `queued` / `in_progress` / `completed` / `failed`; on `completed`, the produced asset URL appears in `metadata.url`.\n\n## Fetch the asset\n\nOnce the task is done, you can fetch the asset bytes through the content endpoint. The gateway **streams the `video/mp4` bytes directly** (no `302` redirect to object storage), supports `Range` requests, and only the API key that owns the task (or a console session in the same tenant) may read it:\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\nContent availability depends on the backend \"media delivery\" setting:\n\n- `404` (`content_delivery_disabled`) when delivery is disabled\n- `409` (`task_not_completed`) when the task is still running\n- `404` (`content_not_available`) when the asset has expired or is missing\n\n## Key conventions\n\n- This is the standard OpenAI-compatible video entrypoint; clients do not need to understand vendor-native protocols.\n- Whether fields such as `duration` or `size` are supported, and which upstream vendor is selected, depends on the logical model referenced by `model`.\n- Video generation is asynchronous. Poll with backoff to avoid unnecessary rate-limit pressure.\n\nFor the more generic async task entrypoint, see [Generic Async Content Generation Tasks](./async-tasks). To write against a vendor's own payload style while keeping platform-managed billing and task handling, see the [Seedance Video Inbound Protocol](./ark) and the [MiniMax Video Inbound Protocol](./minimax).\n","international/en/quickstart/agent-clients.md":"---\ntitle: AI Tool Setup\ndescription: Choose an AI client or Agent and use it with ModelGo models.\n---\n\n# AI Tool Setup\n\nModelGo supports common AI coding clients and Agents. After you create an API key, use the official configuration tool for one-click setup; clients not covered by that tool can be configured manually through a custom provider.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\nSelect one or more tools when prompted. To configure every supported tool in an automated workflow, use:\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n## Supported AI tools\n\n:::agent-tools\n| Tool | Official config tool | Manual setup docs |\n| --- | --- | --- |\n| Hermes Agent | Supported | [Setup guide](../agents/hermes-agent) |\n| Claude Code | Supported | [Setup guide](../agents/claude-code) |\n| Kilo Code | Not supported | [Setup guide](../agents/kilo-code) |\n| Cline | Not supported | [Setup guide](../agents/cline) |\n| Codex | Supported | [Setup guide](../agents/codex) |\n| OpenClaw | Supported | [Setup guide](../agents/openclaw) |\n| DeepSeek Harness | Not supported | [Setup guide](../agents/deepseek-harness) |\n| ZCode | Not supported | [Setup guide](../agents/zcode) |\n| Cursor | Not supported | [Setup guide](../agents/cursor) |\n| OpenCode | Supported | [Setup guide](../agents/opencode) |\n| CC Switch | Supported | [Setup guide](../agents/cc-switch) |\n| Cherry Studio | Not supported | [Setup guide](../agents/cherry-studio) |\n| Crush | Supported | [Setup guide](../agents/crush) |\n| Factory Droid | Supported | [Setup guide](../agents/factory-droid) |\n| Copilot CLI | Supported | [Setup guide](../agents/copilot-cli) |\n| nanobot | Supported | [Setup guide](../agents/nanobot) |\n| Oh My Pi | Supported | [Setup guide](../agents/oh-my-pi) |\n| CodeBuddy | Supported | [Setup guide](../agents/codebuddy) |\n| Kilo CLI | Not supported | [Setup guide](../agents/kilo-cli) |\n:::\n\n## Before you connect\n\n1. Create an API key in the [console]({{ console_endpoint }}/api-keys).\n2. Run the command above and select the clients or Agents you want to configure.\n3. Confirm the site, Base URL, and masked API key when prompted. The configuration tool verifies the connection automatically.\n\nTo manage your ModelGo account, models, calls, and Skills from the terminal, continue to [CLI Tools](cli).\n\n## Integration guide\n\nMost tools only need the following information to connect to ModelGo:\n\n1. **API address**: Use `{{ api_endpoint }}/v1` for OpenAI-compatible APIs, or `{{ api_endpoint }}` for Anthropic-compatible APIs.\n2. **API key**: The token created in [ModelGo Console]({{ console_endpoint }}/api-keys).\n3. **Model name**: The logical model ID selected from the [Model Catalog]({{ site_endpoint }}/models).\n\nSee the setup guide for each tool above for the exact configuration steps.\n","international/en/quickstart/authentication.md":"---\ntitle: Authentication\ndescription: API key handling, supported headers, precedence, and common auth failures.\n---\n\n# Authentication\n\nAll model endpoints authenticate with an API key.\n\n## Recommended header\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic-style clients may also use:\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini-style clients may also use:\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nWhen several are present, precedence is `Authorization` > `x-api-key` > `x-goog-api-key`.\n\n## Get & manage\n\n- Console: `{{ console_endpoint }}`\n- An API key is shown in full only once, at creation time\n- Revoking or disabling a key takes effect after the auth cache expires\n\n## Common failures\n\n| HTTP | error_class | Meaning |\n| --- | --- | --- |\n| `401` | `auth` | Missing, invalid, disabled, or expired API key |\n| `403` | `policy` | Key is valid but not allowed to call the model |\n\nSee [Errors & Rate Limits](errors) for the unified error shape.\n","international/en/quickstart/cli.md":"---\ntitle: CLI Tools\ndescription: Choose the official command-line tool for your task and complete your ModelGo setup.\n---\n\n# CLI Tools\n\nModelGo provides two official command-line tools. Choose the task you want to complete and run the corresponding command.\n\n:::tools\n@model-go/config | Connect AI coding clients | Configure Claude Code, Codex, and other common clients with one command. | npx @model-go/config -r {{ region_flag }} | View npm package | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | Use the official CLI | Pair it with official ModelGo Skills so an AI agent can operate ModelGo directly. | npx @model-go/cli@latest install | View npm package | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## Connect AI coding clients `@model-go/config` {#connect-ai-clients}\n\nTo use ModelGo in Claude Code, Codex, OpenCode, or another supported AI coding client, choose guided setup or configure all clients with a single command.\n\n**Guided setup**\n\nFollow the terminal prompts to enter your API key, select clients, review the configuration, and verify connectivity after the changes are written.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**One-command setup (non-interactive, suitable for automation)**\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n### Supported clients\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\nGuided setup lets you select one or more clients; use `--only all` to configure every supported client at once.\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Enter your [ModelGo API key]({{ console_endpoint }}/api-keys). |\n| `02` | Select one or more clients, or choose “Configure all.” |\n| `03` | Review the site, Base URL, masked API key, and selected clients. |\n| `04` | Confirm the changes, write the client configuration, and verify connectivity. |\n\n> **Setup succeeded:** the terminal reports that configuration is complete and the connectivity check passes, then shows how to start the selected client.\n\n[View @model-go/config on npm](https://www.npmjs.com/package/@model-go/config)\n\n## Let an AI agent operate ModelGo `@model-go/cli` {#install-agent-tools}\n\nInstall the official CLI and ModelGo Skills when you want an agent such as Claude Code or Codex to use ModelGo directly. The installer sets up the CLI, distributes Skills, selects the site, and optionally signs you in.\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Confirm installation of `@model-go/cli` when npm asks. |\n| `02` | Choose Simplified Chinese or English. The rest of the installation prompts will use your selected language. |\n| `03` | Install or upgrade the ModelGo CLI and install ModelGo Skills. |\n| `04` | Select the environment for this site (`{{ api_endpoint }}`). |\n| `05` | Choose whether to sign in through the browser now, or skip and run `modelgo auth login` later. |\n\n### Using the CLI after installation\n\nAfter installation, restart your AI agent or open a new session. ModelGo Skills lets the agent call the ModelGo CLI directly to perform queries and operations, so you can ask in natural language, for example:\n\n- “Which models does ModelGo currently support?”\n- “What is my current ModelGo account balance?”\n\nTo use the CLI yourself, run `modelgo` in your terminal to see every available command and option:\n\n```bash\nmodelgo\n```\n\nThe most common commands are grouped by task:\n\n| Task | Common commands | What they do |\n| --- | --- | --- |\n| Authentication | `modelgo auth login`, `modelgo auth status`, `modelgo auth logout` | Sign in to ModelGo, inspect the current authentication state, or clear local credentials. |\n| Environments | `modelgo env list`, `modelgo env current`, `modelgo env use <name>` | List environments, show the active environment, or switch sites. Use `env add` and `env remove` to manage custom environments. |\n| Workspaces | `modelgo tenant list`, `modelgo tenant use <slug>` | List the workspaces available to your account and use a workspace slug or ID to select the workspace for subsequent CLI commands. |\n| Account and usage | `modelgo balance`, `modelgo permissions`, `modelgo logs` | View balances and transactions, account permissions, call logs, and usage statistics. |\n| Model calls | `modelgo models`, `modelgo chat`, `modelgo embeddings`, `modelgo call` | List available models, make chat or embedding requests, or call any `/v1/*` model endpoint directly. |\n| Keys and payments | `modelgo key`, `modelgo pay` | Manage the model API key stored for the active environment or configure x402 pay-per-call payments. |\n| CLI maintenance | `modelgo update`, `modelgo --version`, `modelgo --help` | Update the CLI, print its version, or reopen the complete help output. |\n\nRun `modelgo <command> --help` to inspect the options for a specific command. For `balance`, `permissions`, and `logs`, you can also use the global `--tenant <slug\\|id>` option to target a workspace for that command only.\n\n[View @model-go/cli on npm](https://www.npmjs.com/package/@model-go/cli)\n\n:::note Security\n- Prefer the interactive API-key prompt instead of putting a key directly in a command.\n- Never commit an API key to source control or paste it into a shared script.\n- If you skipped login during CLI installation, run `modelgo auth login` later.\n:::\n\n## Continue exploring\n\n- [First API Call](quickstart): make your first model call.\n- [Authentication](authentication): learn how to use and protect your API key.\n","international/en/quickstart/errors.md":"---\ntitle: Errors & Rate Limits\ndescription: Unified error shape, common categories, and rate-limit handling.\n---\n\n# Errors & Rate Limits\n\n## Error shape\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\nBesides the `error` object, the body carries a top-level `trace_id` field (matching the `X-Trace-ID` response header; omitted when tracing is disabled) so you can grep logs by it. `metadata.reason` is an optional subtype (for example `model_not_in_catalog`). Full catalog and verified examples: [API catalog](openapi).\n\n## Common categories\n\n| error_class | HTTP | Meaning |\n| --- | --- | --- |\n| `client_invalid` | 400 | Bad request shape or parameters |\n| `model_protocol_not_offered` | 400 | The logical model does not declare this inbound protocol (`app_error_id=4005`). Switch endpoint or model |\n| `provider_invalid` | 400 | Upstream rejected the request (upstream returned a 4xx other than 401/403/408/429) |\n| `provider_unsupported` | 400 | The upstream does not support this endpoint (for example some video models reject `DELETE` cancel) |\n| `provider_timeout` | 408 | Upstream request timed out |\n| `auth` | 401 | API key authentication failed |\n| `billing_insufficient` | 402 | Insufficient balance |\n| `policy` | 403 | Model not allowed or no policy bound |\n| `quota` | 429 | Platform quota or limit hit |\n| `provider_rate_limit` | 429 | Upstream rate limit (upstream returned 429) |\n| `gateway_internal` | 500 | Gateway internal error (catch-all) |\n| `billing_system` | 502 | Billing system unavailable |\n| `provider_server` | 502 | Upstream server error |\n| `provider_unauthorized` | 502 | Upstream credential rejected (bucketed as 5xx; upstream-key issues are not exposed to callers) |\n| `provider_unavailable` | 503 | No available provider |\n| `route_unconfigured` | 503 | Model route has no upstream configured |\n\n## Billing of failed requests\n\n- Pre-authorization: every accepted request freezes balance based on an estimate; after the request ends it is settled by actual usage and any excess is released immediately.\n- Successful requests, and streaming requests that already delivered content, are settled by the usage actually returned.\n- **Requests that were dispatched to the upstream provider but ultimately failed** (upstream 4xx/5xx, upstream timeout, mid-stream disconnect, or the client closing the connection while waiting for the response) are settled at the pre-authorized amount and are not refunded. The upstream provider has already incurred cost for such requests; the platform bears it at the pre-authorized figure and bills the caller accordingly.\n- Requests rejected before reaching an upstream provider (validation, authentication, policy, quota, insufficient balance, gateway internal errors) release the full pre-authorization and incur no charge.\n- The settlement basis is visible in the console's usage transactions; records settled at the pre-authorized amount carry the failure reason.\n\n## Troubleshooting\n\n- Keep `X-Request-ID` and `X-Trace-ID` from the response headers; the error body also carries a top-level `trace_id` with the same value.\n- On `429`, honor the `Retry-After` response header and back off exponentially (the platform sets it when a platform rate limit is hit).\n- If a streaming response delivers a chunk with an `error` field, treat it as a failure (such a mid-stream break maps to `provider_stream_broken` and is not returned as a separate HTTP status).\n\nFor endpoint details see:\n\n- [Text Generation](../models/text/generation)\n- [Image Generation](../models/images/generations)\n- [OpenAI-Compatible Video Flow](../models/video/openai-compatible)\n- [Generic Async Content Generation Tasks](../models/video/async-tasks)\n- [Seedance Video Inbound Protocol](../models/video/ark)\n- [MiniMax Video Inbound Protocol](../models/video/minimax)\n","international/en/quickstart/openapi.md":"---\ntitle: API catalog\ndescription: Full customer-facing OpenAPI list, auth, protocol matching, and verified examples.\n---\n\n# API catalog\n\nThis page lists the public model-calling HTTP APIs (`mgk_` API Key, gateway `{{ api_endpoint }}`).\n\n## Before you call\n\n1. Create an API key (`mgk_`) at `{{ console_endpoint }}`. The full secret is shown once.\n2. `export MODELGO_API_KEY=\"your-key\"`.\n3. Call `GET /v1/models` for logical model names.\n4. A model only accepts endpoints listed in its `public_protocols`. Hitting any other path returns HTTP 400, `error_class=model_protocol_not_offered` (`app_error_id=4005`).\n\n## Auth\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic clients may send `x-api-key`; Gemini clients may send `x-goog-api-key`. Priority: `Authorization` > `x-api-key` > `x-goog-api-key`. See [Authentication](authentication).\n\nMissing or invalid key (HTTP 401):\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\nKeep `X-Request-ID`, `X-Trace-ID`, and body `trace_id`.\n\n## Protocol matching\n\n| Model | Endpoint | Result |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`, `POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`, `POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations` with `size` ≥ ~1920×1920 | 200 |\n\n## Catalog\n\n**Public** means the gateway mounts the route. Whether a given model accepts it still depends on `public_protocols` and the key's policy.\n\n### Text and model list\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | Public | Logical models allowed for this key |\n| `POST` | `/v1/responses` | Public | OpenAI Responses (preferred) |\n| `POST` | `/v1/chat/completions` | Public | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | Public | Legacy; most chat models do not offer it |\n| `POST` | `/v1/messages` | Public | Anthropic Messages |\n\n### Vectors / images / audio / rerank\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | Public | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Public | Needs a multimodal-embedding protocol |\n| `POST` | `/v1/images/generations` | Public | Image generation |\n| `POST` | `/v1/images/edits` | Public | Multipart image edits |\n| `POST` | `/v1/audio/speech` | Public | OpenAI TTS; not every speech model offers it |\n| `POST` | `/minimax/v1/t2a_v2` | Public | MiniMax native TTS; see [MiniMax audio inbound](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | Public | Multipart STT |\n| `POST` | `/v1/audio/translations` | Public | Multipart translation |\n| `POST` | `/v1/rerank` | Public | Rerank |\n| `POST` | `/v1/reranks` | Public / alias | Same as `/v1/rerank` |\n\n### Managed async video\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST`/`GET`/`DELETE` | `/v1/content_generation/tasks` and `.../{task_id}` | Public | Generic async tasks |\n| `POST`/`GET`/`DELETE` | `/ark/api/v3/contents/generations/tasks` and `.../{task_id}` | Public | Same pipeline, Ark spelling |\n| `POST`/`GET`/`DELETE` | `/minimax/v2/video_generation` and `.../{task_id}` | Public | MiniMax video V2; pricing dimensions required |\n| `POST`/`GET`/`DELETE` | `/v1/video/generations`, `/v1/videos/{task_id}`, `/v1/videos/{task_id}/content` | Public | OpenAI-compatible video; model must offer it |\n\nCancel (`DELETE`) may return `provider_unsupported` if the upstream has no cancel API.\n\n## Verified calls\n\nList models:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nChat Completions:\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":64}'\n```\n\nEmpty `{}` → HTTP 400 `client_invalid`. Unknown model → HTTP 403 `policy` / `model_not_in_catalog`.\n\nResponses: `POST /v1/responses` with `input` + `max_output_tokens`. Messages: `POST /v1/messages` with `x-api-key` and `max_tokens`. The Messages response `model` field may be an upstream id, not the logical name.\n\nEmbeddings: `text-embedding-3-small` returned 1536-d vectors.\n\nImages: `doubao-seedream-5.0-lite` rejects `1024x1024` (`provider_invalid`, min 3686400 pixels). `2048x2048` succeeded.\n\nSpeech: use [MiniMax audio inbound](../models/audio/minimax) for `speech-2.8-*`.\n\nVideo: Seedance uses `/v1/content_generation/tasks` (create returns `{\"id\",\"model\",\"status\":\"queued\"}`; poll later returns `status=succeeded`, plus `resolution` / `ratio` / `duration`). `/v1/video/generations` is `model_protocol_not_offered` for `doubao-seedance-2.0-mini`.\n\n## Streaming\n\nSet `stream: true`. OpenAI-shaped endpoints use `text/event-stream` frames `data: {json}` ending with `data: [DONE]`. `/v1/messages` keeps native Anthropic `event:` frames. A chunk with `error` is a failure even if HTTP status was 200.\n\n## Limits\n\n- Rate limits: HTTP 429 (`quota` or `provider_rate_limit`); honor `Retry-After`.\n- No client idempotency key on sync calls. Each async POST creates a new task; poll by returned `id`.\n- No pagination on this surface; `GET /v1/models` returns the full list for the key.\n\nSee [Errors](errors), [Text generation](../models/text/generation), [MiniMax audio inbound](../models/audio/minimax), [Async tasks](../models/video/async-tasks).\n","international/en/quickstart/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [First API Call](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","international/en/quickstart/quickstart.md":"---\ntitle: First API Call\ndescription: Create an API key, choose a model, and make your first request with the Responses API.\n---\n\n# First API Call\n\nYou can reuse an existing OpenAI or Anthropic SDK with ModelGo, or follow the three steps below to make your first request with the Responses API.\n\n## Connect with standard protocols\n\nModelGo supports both OpenAI and Anthropic standard protocols. If your project already uses either SDK, you can usually keep the existing integration and replace only the Base URL and API key.\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## Make your first API call in three steps\n\nIf this is your first ModelGo integration, complete these three steps to send a request and receive a generated result.\n\n### 1. Create an API key\n\n- Sign in to the [console]({{ console_endpoint }}).\n- Open the API Keys page and create a new API key.\n- Store it in an environment variable instead of placing it directly in your code:\n\n```bash\nexport MODELGO_API_KEY=\"your-api-key\"\n```\n\n### 2. Choose a model\n\nThe `model` request field must use a ModelGo logical model name. Browse models in the [Model Catalog]({{ site_endpoint }}/models) or use the following request to list the logical models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative. Choose a model name and replace `<model>` in the next step.\n\n### 3. Send your first request\n\nWe recommend starting with `POST /v1/responses`. Run the example in your preferred language:\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"Introduce ModelGo in three sentences.\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"Introduce ModelGo in three sentences.\",\n)\n\nprint(response.output_text)\n```\n\nA successful request returns the model-generated result. With the Python SDK, read the generated text from `response.output_text`.\n\n## Use other compatible protocols\n\nIf your project already uses another compatible interface, you can keep its existing request shape:\n\n- [Use Chat Completions](../models/text/generation#chat-completions): For existing OpenAI Chat Completions integrations.\n- [Use Anthropic Messages](../models/text/generation#anthropic-messages): For existing Claude SDK or Anthropic Messages integrations.\n\n## Continue exploring\n\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See the complete Responses, Chat Completions, and Anthropic Messages documentation.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n","international/zh/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: 使用 ModelGo 配置 CC Switch 和 Claude Code。\n---\n\n# CC Switch\n\nCC Switch 是桌面端配置管理工具，可以统一管理 Claude Code、Codex、Gemini、OpenCode、OpenClaw 等工具的 Provider。下面以 Claude Code 为例，将 ModelGo 添加到 CC Switch 并启用。\n\n## 接入前准备\n\n- 已安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)，并能正常打开。\n- 已安装 Claude Code，并至少启动过一次。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 打开 Claude Code 配置\n\n打开 CC Switch，在顶部选择 **Claude**，点击右侧的 **+** 新增配置。\n\n![CC Switch 主界面](/images/agents/cc-switch/overview.webp)\n\n![在 CC Switch 中添加 Claude 配置](/images/agents/cc-switch/claude-add.webp)\n\n## 2. 添加 ModelGo Provider\n\n在配置编辑器中粘贴下面的 JSON。将 `你的模型名` 替换为模型广场中的逻辑模型名，将 `sk-你的token` 替换为 ModelGo API Key：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-你的token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"你的模型名\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"你的模型名\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![在 CC Switch 中编辑 ModelGo 配置](/images/agents/cc-switch/config-global.webp)\n\n如果你的 CC Switch 版本支持环境变量占位符，可以将 Token 改为 `{env:MODELGO_API_KEY}`，并在启动 Claude Code 的终端中设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | ModelGo 控制台创建的 API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | 模型广场中的逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的逻辑模型名 |\n\n:::note\n- Anthropic Base URL 填写 ModelGo 根地址，不要追加 `/v1/messages`；Claude Code 会自动请求 `/v1/messages`。\n- API Key 只保存在本机 CC Switch 配置或环境变量中，不要提交到代码仓库。\n- CC Switch 的 Provider 名称可以填写 `ModelGo`，方便后续识别和切换。\n:::\n\n## 3. 保存并启用\n\n填写 Provider 名称 **ModelGo** 后点击 **Add** 或 **Save**。回到 Claude 配置列表，选中 ModelGo 配置并启用。\n\n![在 CC Switch 中添加 ModelGo Provider](/images/agents/cc-switch/provider-global.webp)\n\n![在 CC Switch 中启用 ModelGo 配置](/images/agents/cc-switch/use-global.webp)\n\n启动 Claude Code：\n\n```bash\nclaude\n```\n\n输入一条简单任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n## 4. 验证配置\n\n如果需要单独验证 API Key 和模型，可执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果中的 `id` 即可作为 `ANTHROPIC_MODEL` 和 `ANTHROPIC_SMALL_FAST_MODEL` 的逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 Token 是有效的 ModelGo API Key，且当前 CC Switch 配置没有残留的旧 Token。复制 Token 时不要带空格或换行。\n\n### 返回 404 或找不到接口\n\n确认 `ANTHROPIC_BASE_URL` 为 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages` 或完整请求路径。\n\n### 模型不可用\n\n确认模型名与[模型广场]({{ site_endpoint }}/models)中的逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n### 修改后 Claude Code 仍使用旧配置\n\n在 CC Switch 中确认 ModelGo 配置已启用，然后完全退出并重新打开终端，再运行 `claude`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [CC Switch 官方快速开始](https://cc-switch.cc/docs/getting-started/quick-start/)：了解界面和配置切换流程。\n- [CC Switch Provider 配置教程](https://cc-switch.cc/en/tutorials/provider-setup)：了解自定义 Provider 字段和凭据管理。\n","international/zh/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: 通过自定义服务商将 Cherry Studio 接入 ModelGo 国际站。\n---\n\n# Cherry Studio\n\nCherry Studio 已内置多个官方服务商，但 ModelGo 不在预置列表中。请使用“自定义服务商”创建一个 ModelGo Provider，再获取并添加模型。ModelGo 同时提供 OpenAI 兼容接口和 Anthropic 兼容接口，可按使用场景选择。\n\n## 接入前准备\n\n- 已安装 Cherry Studio，并能打开设置页面。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的逻辑模型名。\n\n## 1. 打开模型服务设置\n\n打开 Cherry Studio 的“设置”，进入“模型服务”，点击左侧底部的“+ 添加服务商”。\n\n![在 Cherry Studio 中打开添加服务商](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. 添加自定义服务商\n\n在“添加自定义提供商”窗口中填写：\n\n| 配置项 | ModelGo 国际站填写内容 |\n| --- | --- |\n| 提供商名称 | `ModelGo` |\n| API 密钥 | ModelGo 控制台创建的 API Key |\n| OpenAI 地址 | `{{ api_endpoint }}/v1` |\n| Anthropic 地址 | `{{ api_endpoint }}`（仅在使用 Anthropic 兼容模型或 Agent 模式时填写） |\n\n点击“添加”保存。OpenAI 地址用于普通聊天和模型列表；Anthropic 地址不要追加 `/v1`，Cherry Studio 会按协议补全请求路径。\n\n![添加 ModelGo 自定义提供商](/images/agents/cherry-studio/custom-provider-global.webp)\n\n:::note\n- 不要把完整的 `/chat/completions` 或 `/messages` 写进地址。\n- OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`，Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n:::\n\n## 3. 获取并添加模型\n\n回到 ModelGo 服务商页面，点击“获取模型列表”。Cherry Studio 会从 ModelGo 的模型接口读取当前 API Key 可用的逻辑模型。\n\n![在 Cherry Studio 中获取 ModelGo 模型列表](/images/agents/cherry-studio/fetch-models-global.webp)\n\n模型列表弹窗打开后，可以按需点击单个模型右侧的“+”，也可以点击“添加全部模型”。\n\n![在 Cherry Studio 中添加全部 ModelGo 模型](/images/agents/cherry-studio/model-picker.webp)\n\n添加完成后，模型会出现在 ModelGo 服务商的模型区域。只添加自己需要的模型可以让选择器更简洁。\n\n![ModelGo 服务商中的模型列表](/images/agents/cherry-studio/model-list-global.webp)\n\n## 4. 启用并开始对话\n\n在 ModelGo 服务商右上角打开开关，确认 API 密钥检测通过。新建对话时选择 **ModelGo** 及刚添加的模型，然后发送一条简单消息验证调用。\n\n如果只使用 OpenAI 兼容模型，保留 OpenAI 地址即可；使用 Claude 等 Anthropic 兼容模型或 Cherry Studio Agent 模式时，再配置 Anthropic 地址并添加对应模型。\n\n## 验证配置\n\n可以在终端检查 API Key 是否能读取模型列表：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是 Cherry Studio 中应添加的 ModelGo 逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认服务商右上角开关已打开。\n\n### 返回 404 或接口路径错误\n\nOpenAI 地址应为 `{{ api_endpoint }}/v1`，Anthropic 地址应为 `{{ api_endpoint }}`。不要填写完整的 `/v1/chat/completions` 或 `/v1/messages`。\n\n### 获取模型列表为空\n\n先用上面的 `curl` 验证 `/v1/models`，再确认模型已在模型广场开通。获取列表后还要点击模型右侧的“+”或“添加全部模型”，仅获取列表不会自动加入选择器。\n\n### Agent 模式无法调用\n\n确认已填写 Anthropic 地址 `{{ api_endpoint }}`，并添加支持 Anthropic 兼容协议的模型。普通 OpenAI 兼容聊天不需要填写该地址。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cherry Studio 自定义服务商文档](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang)：查看官方的自定义服务商流程。\n- [Cherry Studio Provider 设置说明](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers)：了解 Base URL、模型管理和连通性检测规则。\n","international/zh/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: 使用 ModelGo 的 Anthropic 兼容接口配置 Claude Code。\n---\n\n# Claude Code\n\nClaude Code 是运行在终端中的 AI 编程助手。通过配置 Anthropic 兼容接口，你可以让 Claude Code 使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 Node.js。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Claude Code\n\n在终端执行：\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n安装完成后检查版本：\n\n```bash\nclaude --version\n```\n\n## 2. 配置 ModelGo\n\n### macOS / Linux\n\n创建并编辑 Claude Code 配置文件：\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\n在 PowerShell 中执行：\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\n将下面内容写入 `settings.json`。把 `YOUR_MODELGO_API_KEY` 和 `YOUR_MODELGO_MODEL` 替换为真实的 ModelGo API Key 与逻辑模型名：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n`ANTHROPIC_BASE_URL` 填写 ModelGo 的根地址，不要追加 `/v1/messages`。Claude Code 会自动请求 ModelGo 的 `POST /v1/messages` 接口。\n\n:::note\n- 如果你只使用一个模型，建议将五个模型变量都设置为同一个 ModelGo 逻辑模型名，避免辅助模型未授权导致启动失败。\n- API Key 仅写入本机配置，不要将 `settings.json` 提交到代码仓库或分享给他人。\n:::\n\n## 3. 可选：跳过官方账号初始化\n\n如果首次输入 `claude` 时卡在官方账号登录引导，可以在用户目录创建 `.claude.json`，写入已完成初始化标识。\n\nmacOS / Linux：\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell：\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. 启动 Claude Code\n\n进入你的项目目录并启动：\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\n首次进入项目时，选择 **Trust This Folder**，允许 Claude Code 访问项目文件。然后输入一条简单的编码需求，能够正常返回结果即表示接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | ModelGo 平台逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n\n模型名可以通过[模型广场]({{ site_endpoint }}/models)确认，也可以查询当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的 ModelGo API Key，复制时不要带多余空格。\n\n### 返回 403 或模型不可用\n\n确认五个模型变量使用的都是当前 API Key 策略允许调用的 ModelGo 逻辑模型名。\n\n### 返回 404 或找不到接口\n\n`ANTHROPIC_BASE_URL` 应填写 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages`；Claude Code 会自动补充 `/v1/messages`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)：查看最新安装与配置说明。\n","international/zh/agents/cline.md":"---\ntitle: Cline\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cline。\n---\n\n# Cline\n\nCline 是 VS Code 中的 AI 编程助手。选择 `OpenAI Compatible` Provider 后，可以通过 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 VS Code。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cline\n\n打开 VS Code 扩展市场，搜索 **Cline** 并安装扩展。\n\n![在 VS Code 扩展市场安装 Cline](/images/agents/cline/cline-market.webp)\n\n## 2. 配置 ModelGo\n\n安装完成后，点击 VS Code 左侧工具栏中的 Cline 图标，打开 **API Configuration**。\n\n![打开 Cline API Configuration](/images/agents/cline/cline-config-global.webp)\n\n按下表填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | ModelGo API Key |\n| Model ID | ModelGo 平台逻辑模型名 |\n\n点击 **Done** 保存。\n\n:::note\n- Base URL 使用 `{{ api_endpoint }}/v1`，不要填写 `/chat/completions`；Cline 会自动拼接接口路径。\n- Model ID 使用模型广场中当前 API Key 可调用的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 只保存在本机 Cline 设置中，不要提交到代码仓库或截图分享。\n:::\n\n如需先确认当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. 开始使用\n\n在 Cline 面板输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n![Cline 完成一次对话](/images/agents/cline/cline-chat.webp)\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写在 API Key 字段。\n\n### 返回 403 或模型不可用\n\n确认 Model ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应为 `{{ api_endpoint }}/v1`，不要粘贴完整的 `/chat/completions` URL。\n\n### 模型列表为空\n\n先请求 `GET {{ api_endpoint }}/v1/models` 验证接口；若 Cline 下拉列表不显示模型，可直接手动输入 Model ID。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Cline OpenAI Compatible 文档](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx)：查看 Cline 官方 Provider 配置说明。\n","international/zh/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: 通过 ModelGo 接入 CodeBuddy。\n---\n\n# CodeBuddy\n\nCodeBuddy Code 是腾讯云的终端 AI 编程工具。它支持用环境变量覆盖 API 地址、Key 和模型，因此无需修改项目代码即可接入 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已安装 CodeBuddy CLI，并能执行 `codebuddy --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. 配置 ModelGo 环境变量\n\n在启动 CodeBuddy 的同一终端设置：\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-你的token\"\nexport CODEBUDDY_MODEL=\"你的模型名\"\n```\n\n`CODEBUDDY_BASE_URL` 覆盖请求地址，`CODEBUDDY_API_KEY` 用于模型调用，`CODEBUDDY_MODEL` 指定 ModelGo 逻辑模型。不要将 `CODEBUDDY_AUTH_TOKEN` 与 ModelGo API Key 混用；前者是 CodeBuddy 平台登录凭据。\n\n:::note\n- Base URL 填 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- 若使用非交互模式 `codebuddy -p`，必须设置 `CODEBUDDY_API_KEY`。\n- API Key 和模型名建议写进本地 shell profile 或密钥管理器，不要提交到仓库。\n:::\n\n## 3. 启动并验证\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\n```\n\n在会话中让 CodeBuddy 执行一个只读任务；非交互调用示例：\n\n```bash\ncodebuddy -p \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 仍然使用默认模型或地址\n\n确认环境变量在当前终端可见，并完全退出后重新启动 `codebuddy`。检查变量名拼写是否为大写形式。\n\n### 401 或 404\n\n检查 `CODEBUDDY_API_KEY`、`CODEBUDDY_MODEL` 和 `CODEBUDDY_BASE_URL`，不要把完整接口路径写进 Base URL。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [CodeBuddy CLI 快速开始](https://www.codebuddy.ai/docs/cli/quickstart)：查看安装、登录和首次运行流程。\n- [CodeBuddy CLI 环境变量](https://www.codebuddy.ai/docs/cli/env-vars)：查看 `CODEBUDDY_BASE_URL`、`CODEBUDDY_API_KEY` 和模型变量。\n","international/zh/agents/codex.md":"---\ntitle: Codex\ndescription: 使用 ModelGo 的 Responses API 配置 Codex CLI。\n---\n\n# Codex\n\nCodex 是 OpenAI 的命令行 AI 编程助手。通过自定义 `model_provider`，可以将 Codex CLI 的 Responses API 请求发送到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Codex\n\n在 macOS、Linux 或 Windows 终端中执行：\n\n```bash\nnpm install -g @openai/codex\n```\n\n安装完成后检查版本：\n\n```bash\ncodex --version\n```\n\n首次启动时，如果 Codex 提示有新版本可用，可以选择 **Skip**，先完成 ModelGo 配置。\n\n![跳过 Codex 升级提示](/images/agents/codex/codex-start.webp)\n\n## 2. 配置 ModelGo\n\nCodex 从用户目录下的 `~/.codex/config.toml` 读取模型和 Provider 配置。先创建目录和配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\n将下面内容粘贴到 `config.toml`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中当前 API Key 可调用的逻辑模型名：\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\n其中，`base_url` 使用 ModelGo 的 OpenAI 兼容根地址，Codex 会自动请求 `/v1/responses`。\n\n## 3. 设置 API Key\n\n将 ModelGo API Key 保存到系统环境变量 `MODELGO_API_KEY`。不要把真实 API Key 直接写入 `config.toml`。\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n检查变量是否已生效（只输出是否存在，不要打印 Key 内容）：\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- `MODELGO_API_KEY` 只应保存在本机环境变量中，不要提交到代码仓库或分享终端截图。\n- `model` 必须填写 ModelGo 逻辑模型名；截图中的 `gpt-5.6-sol` 仅为示例，请替换为你实际可调用的模型。\n- `wire_api = \"responses\"` 是当前 Codex 配置要求；不要使用已经弃用的 `wire_api = \"chat\"`。\n:::\n\n:::note 切换 API Key 或服务地址后请新建会话\n- Codex 在多轮对话中会继续携带之前的 Responses 上下文，其中可能包含只能由原上游账号继续处理的加密推理内容。\n- 如果你更换了 `MODELGO_API_KEY`、`base_url`，或者代理、号池将同一会话切换到其他上游账号，请新建 Codex 会话，不要继续或恢复原会话，否则请求可能返回 `400 invalid_encrypted_content`。\n:::\n\n## 4. 启动并验证\n\n进入一个本地项目目录，执行：\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\n首次进入项目时，按提示选择信任当前目录。看到 Codex 欢迎界面后，输入一条简单的编码需求，例如“用三句话介绍这个项目”。\n\n![Codex 首次进入项目的欢迎界面](/images/agents/codex/codex-skip.webp)\n\n能够正常返回模型结果，即表示 ModelGo 接入成功。\n\n![Codex 开始对话](/images/agents/codex/codex-chat.webp)\n\n如需先确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 启动后提示找不到 Provider\n\n确认配置文件路径是用户目录下的 `~/.codex/config.toml`，并检查 `model_provider = \"modelgo\"` 与 `[model_providers.modelgo]` 的名称一致。\n\n### 返回 401 或认证失败\n\n检查当前终端是否已设置 `MODELGO_API_KEY`，并确认 API Key 没有多余空格或换行。\n\n### 返回 403 或模型不可用\n\n确认 `model` 使用模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`base_url` 应填写 `{{ api_endpoint }}/v1`。不要填写完整的 `/responses` 或 `/v1/responses`，Codex 会自动拼接路径。\n\n### 出现 Chat wire API 弃用提示\n\n在 `[model_providers.modelgo]` 中加入 `wire_api = \"responses\"`，并升级到最新 Codex CLI：\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### 返回 `400 invalid_encrypted_content`\n\n这通常说明当前会话携带了原上游账号生成的加密上下文，但本轮请求被另一个上游账号处理。\n\n先检查是否更换过 API Key、Base URL，或者代理、号池是否切换了上游账号。发生过切换时，请新建会话，不要继续或恢复原会话。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Codex 配置参考](https://developers.openai.com/codex/config-reference/)：查看当前 Codex 的 `config.toml` 字段说明。\n","international/zh/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: 通过 ModelGo 接入 Copilot CLI。\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI 支持 BYOK（Bring Your Own Key）。设置 Provider 环境变量后，Copilot CLI 会把模型请求发送到 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 GitHub Copilot CLI，并能执行 `copilot --help`。\n- 已完成 GitHub 登录或组织要求的 Copilot 认证。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认支持工具调用和流式输出的逻辑模型。\n\n## 1. 配置 ModelGo BYOK\n\n在启动 Copilot CLI 的同一终端设置：\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"你的模型名\"\ncopilot\n```\n\n如果还没有通用环境变量，可直接设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\n```\n\n`openai` Provider 类型用于 OpenAI Chat Completions 兼容服务；`COPILOT_MODEL` 填 ModelGo 逻辑模型 ID。\n\n:::note\n- Copilot CLI 仍可能需要 GitHub 登录；登录身份与模型请求所用的 ModelGo Key 是两套凭据。\n- Base URL 填 `{{ api_endpoint }}/v1`，不要写 `/chat/completions`。\n- 建议选择支持 tool calling、streaming 且上下文窗口较大的模型。\n:::\n\n## 2. 验证模型\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\n在会话中让 Copilot CLI 执行一个只读任务，例如“列出项目入口文件”，确认能正常返回结果。\n\n## 常见问题\n\n### Copilot CLI 仍调用默认模型\n\n确认 `COPILOT_MODEL` 与 `COPILOT_PROVIDER_BASE_URL` 在当前终端可见，并重新启动 `copilot`。\n\n### 返回 401、404 或不支持工具调用\n\n检查 API Key、Base URL 和逻辑模型名；如果模型不支持工具调用或流式响应，请在模型广场更换模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)：查看 Provider 环境变量和模型要求。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","international/zh/agents/crush.md":"---\ntitle: Crush\ndescription: 通过 ModelGo 接入 Crush。\n---\n\n# Crush\n\nCrush 是 Charmbracelet 提供的终端 AI 编程 Agent。它支持 OpenAI 兼容 Provider，可通过 `crushrc` 将请求转发到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+、Go 或 Homebrew。\n- 已安装 Crush，并能执行 `crush --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\n也可以使用 `npm install -g @charmland/crush`、`go install github.com/charmbracelet/crush@latest`，Windows 用户可执行 `winget install charmbracelet.crush`。\n\n## 2. 添加 ModelGo Provider\n\nCrush 的项目配置放在项目根目录的 `.crushrc` 或 `crushrc`，全局配置放在 `~/.config/crush/crushrc`（Windows：`%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`）。推荐使用 CLI 写入配置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/你的模型名 --name \"你的模型名\"\n```\n\n将 `你的模型名` 替换为模型广场中的逻辑模型 ID。`openai-compat` 表示使用 OpenAI Chat Completions 兼容协议。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- API Key 建议通过 `MODELGO_API_KEY` 环境变量提供，不要写入仓库。\n- `modelgo/你的模型名` 是 Crush 的 Provider/模型标识，Provider ID 可按需修改。\n:::\n\n## 3. 启动并验证\n\n```bash\ncrush\n```\n\n在模型选择器中选择 ModelGo 模型，发送一条简单请求。也可先验证目录接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 找不到 Provider\n\n确认 `crushrc` 路径和文件名正确，并重新启动 Crush。项目配置会覆盖全局配置。\n\n### 返回 401 或 404\n\n检查 `MODELGO_API_KEY` 是否生效，Base URL 是否为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Crush 官方仓库](https://github.com/charmbracelet/crush)：查看安装、Provider 和命令参考。\n- [Crush 配置 Schema](https://github.com/charmbracelet/crush/blob/main/schema.json)：查看 `crushrc` 字段定义。\n","international/zh/agents/cursor.md":"---\ntitle: Cursor\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cursor。\n---\n\n# Cursor\n\nCursor 是一款 AI 编程编辑器。通过自定义 OpenAI Base URL，Cursor 可以调用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 [Cursor](https://www.cursor.com/)。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cursor\n\n访问 [Cursor 官网](https://www.cursor.com/)，下载并安装适合你操作系统的版本。\n\n![Cursor 官网下载页面](/images/agents/cursor/install.webp)\n\n## 2. 打开 Cursor 模型设置\n\n打开 Cursor 设置，进入 **Models** 页面。\n\n![打开 Cursor Settings 的 Models](/images/agents/cursor/settings.webp)\n\n## 3. 添加并启用模型\n\n点击 **Add model**，输入[模型广场]({{ site_endpoint }}/models)中的逻辑模型名，然后保存。\n\n![在 Cursor 中添加模型](/images/agents/cursor/add-model.webp)\n\n在 **Model Names** 列表中保留需要使用的模型，并关闭不需要的模型。\n\n![在 Cursor 中启用目标模型](/images/agents/cursor/model-list.webp)\n\n## 4. 配置 ModelGo 接口\n\n在 **Settings → Models → API Keys** 中配置 OpenAI 兼容接口：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| OpenAI API Key | ModelGo API Key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | ModelGo 模型广场中的逻辑模型名 |\n\n![在 Cursor 中配置 ModelGo 接口](/images/agents/cursor/config-global.webp)\n\n如果你的 Cursor 使用另一版设置界面，可参考下面的布局，填写相同的 ModelGo 参数。\n\n![Cursor 另一版设置界面](/images/agents/cursor/config-cn.webp)\n\n点击 **Verify** 或 **Save** 保存配置。Cursor 的不同版本可能会调整设置项名称，但 Base URL、API Key 和模型名的含义不变。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- 模型名必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图里的示例。\n- 如果 Verify 无法完成，可先在聊天窗口直接发送请求，或用下方命令检查接口和 Key。\n:::\n\n## 5. 测试连接\n\n回到 Cursor 聊天窗口，选择刚添加的模型，发送一条简单消息。能够正常返回结果，即表示接入成功。\n\n![在 Cursor 中测试 ModelGo 模型](/images/agents/cursor/chat.webp)\n\n也可以在终端查看当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 API Key 复制完整且没有多余空格，并检查是否填入 **OpenAI API Key** 字段。\n\n### 返回 404 或接口路径错误\n\n确认 Base URL 为 `{{ api_endpoint }}/v1`，不要把 `/chat/completions` 拼到 Base URL 后面。\n\n### Verify 失败或模型不可用\n\n确认模型名是 ModelGo 模型广场中的逻辑模型名，并检查该模型是否已对当前 API Key 开通。\n\n### 聊天窗口没有返回内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 验证网络和 Key，再确认 Cursor 的 Model Names 列表中已启用目标模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cursor 官方文档](https://docs.cursor.com/)：查看 Cursor 设置、模型和自定义 API 配置说明。\n","international/zh/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 DeepSeek Harness。\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness（DSH）是 DeepSeek AI 开源的智能体框架，可以将模型、工具、文件系统、终端、会话和 Web UI 组合成可运行的 Agent。通过自定义提供方，DSH 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已安装 pnpm 11 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装并启动 DeepSeek Harness\n\nDeepSeek Harness 当前推荐从源码安装：\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![从源码启动 DeepSeek Harness](/images/agents/deepseek-harness/install.webp)\n\n终端会打印 Web UI 地址，默认是 `http://127.0.0.1:3080`。如果端口已被占用，请以终端实际打印的地址为准。\n\n如果只想快速体验，也可以直接运行：\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. 配置 ModelGo\n\n在浏览器打开终端打印的地址，点击左上角侧边栏按钮，然后点击 **设置**。\n\n![打开 DeepSeek Harness 设置](/images/agents/deepseek-harness/settings.webp)\n\n在设置中选择 **模型**，点击 **添加自定义提供方**。\n\n![添加自定义提供方](/images/agents/deepseek-harness/model-picker.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider ID | `modelgo` |\n| 显示名称 | `ModelGo` |\n| API 地址 | `{{ api_endpoint }}/v1` |\n| API 协议 | `openai-completions` |\n| API 密钥 | ModelGo API Key |\n| 模型 ID | 模型广场中的逻辑模型名 |\n| 显示名称 | 可填写与模型 ID 相同的名称 |\n\n![填写 ModelGo 自定义提供方](/images/agents/deepseek-harness/provider-config.webp)\n\n点击 **创建提供方** 保存配置。配置时请注意：\n\n:::note\n- API 地址填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`；DSH 会根据 `openai-completions` 协议拼接请求路径。\n- 模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例模型。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 开始会话\n\n回到主界面，选择一个工作区，再选择刚刚添加的 ModelGo 模型。\n\n![选择 ModelGo 模型开始会话](/images/agents/deepseek-harness/session.webp)\n\n输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 已接入成功。\n\n## 常见问题\n\n### Web UI 无法打开\n\n确认 `pnpm dsh web` 进程仍在运行，并访问终端打印的实际端口。默认端口是 `3080`，端口冲突时 DSH 可能会自动使用其他端口。\n\n### 返回 401 或认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写的是 ModelGo 控制台创建的 API Key。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\nAPI 地址应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。API 协议请选择 `openai-completions`。\n\n### 模型列表为空\n\n检查模型 ID 是否填写，并确认 DSH 的自定义提供方已保存。必要时可以先用下面的命令验证 ModelGo 接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [DeepSeek Harness 官方网站](https://www.deepseek.com/harness/)：查看最新安装方式和产品说明。\n- [DeepSeek Harness GitHub 仓库](https://github.com/deepseek-ai/deepseek-harness)：查看源码和版本信息。\n","international/zh/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: 通过 ModelGo 接入 Factory Droid。\n---\n\n# Factory Droid\n\nFactory Droid 是 Factory 的终端 Agent。通过 BYOK 自定义模型，可以让 Droid 使用 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 Node.js 18+ 和 Droid CLI。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装并启动 Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\n也可以使用 Factory 官方安装器。进入 Droid 后输入 `/settings` 可打开设置。\n\n## 2. 配置 ModelGo 自定义模型\n\n编辑 `~/.factory/settings.json`（Windows：`%USERPROFILE%\\\\.factory\\\\settings.json`），合并以下 `customModels` 配置：\n\n```json\n{\n  \"customModels\": [\n    {\n      \"model\": \"你的模型名\",\n      \"displayName\": \"ModelGo / 你的模型名\",\n      \"baseUrl\": \"{{ api_endpoint }}/v1\",\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"provider\": \"openai\"\n    }\n  ]\n}\n```\n\n先设置 Key：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n重新启动 Droid，在 `/models` 或模型选择器中选择 `ModelGo / 你的模型名`。\n\n:::note\n- `baseUrl` 填 `{{ api_endpoint }}/v1`，不要附加 `/chat/completions`。\n- `model` 必须使用 ModelGo 模型广场中的逻辑模型 ID。\n- 保留原有 `settings.json` 字段，只合并 `customModels`，不要覆盖其他个人设置。\n:::\n\n## 3. 验证请求\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"你的模型名\" \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 模型没有出现在列表中\n\n检查 JSON 是否有效、`customModels` 是否位于文件顶层，并完全退出后重新启动 Droid。\n\n### 认证失败或接口路径错误\n\n确认环境变量已在启动 Droid 的同一终端中设置，且 `baseUrl` 没有重复的 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Factory Droid 设置](https://docs.factory.ai/droid-cli/settings)：查看 `settings.json` 的位置和设置入口。\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok)：了解自定义模型字段和模型独立性。\n","international/zh/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Hermes Agent。\n---\n\n# Hermes Agent\n\nHermes Agent 是一款运行在终端中的 AI Agent。通过自定义 Provider，Hermes 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的 ModelGo 逻辑模型名。\n\n## 1. 安装 Hermes Agent\n\nmacOS 或 Linux：\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell：\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\n重新打开终端后，检查安装是否成功：\n\n```bash\nhermes --version\n```\n\n## 2. 配置 ModelGo\n\n先把 API Key 放入当前终端的环境变量。不要把真实 Key 提交到代码仓库或公开脚本中：\n\n```bash\nexport MODELGO_API_KEY=\"你的-ModelGo-API-Key\"\nexport MODELGO_MODEL=\"你的-ModelGo-逻辑模型名\"\n```\n\n如果还不确定模型名，可以先查询当前 API Key 可用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n然后使用 `hermes config set` 写入自定义 Provider。将 `<model>` 替换为模型广场或 `GET /v1/models` 返回的逻辑模型名：\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\n如果你的 Hermes 版本通过 `hermes model` 提供配置向导，也可以运行：\n\n```bash\nhermes model\n```\n\n选择 **Custom endpoint**，依次填写下方配置表中的 ModelGo Base URL、API Key 和模型名，并选择 **Chat Completions** 协议。\n\n:::note\n- 部分旧版本将 Chat Completions 协议显示为 `openai_messages`。如果 `chat_completions` 被提示为无效，请升级 Hermes，或在 `hermes model` 向导中选择 Chat Completions。\n:::\n\n## 3. 检查配置并开始对话\n\n检查 Hermes 配置：\n\n```bash\nhermes config check\n```\n\n检查通过后启动 Hermes：\n\n```bash\nhermes\n```\n\n输入一条消息，例如“用三句话介绍 ModelGo”。如果能返回模型结果，说明接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API 模式 | `chat_completions` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model ID | ModelGo 的平台逻辑模型名，不是上游厂商原始模型 ID |\n\nHermes 会将非敏感配置保存到 `~/.hermes/config.yaml`，API Key 等敏感信息保存到 `~/.hermes/.env`。不要分享或提交 `~/.hermes/` 下包含密钥的文件。\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n确认 API Key 没有被撤销或过期，并重新执行：\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 返回 403 或模型不可用\n\n确认 `model.default` 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要再拼接 `/chat/completions`；Hermes 会在请求时补充具体路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs)：查看安装器、配置项和 CLI 的最新说明。\n","international/zh/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: 通过 ModelGo 接入 Kilo CLI。\n---\n\n# Kilo CLI\n\nKilo CLI 是终端 AI 编程 Agent。它支持自定义 OpenAI 兼容 Provider；由于 ModelGo CLI 尚未提供官方自动配置，本文采用 Kilo 的 `/connect` 与配置文件方式。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\n进入项目目录后运行 `kilo`，首次启动可使用 `/connect` 添加 Provider。\n\n## 2. 添加 ModelGo Provider\n\n在项目根目录创建 `kilo.jsonc`（或编辑全局配置），加入 OpenAI 兼容 Provider：\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/你的模型名\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"ModelGo / 你的模型名\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n也可以在 TUI 中选择 `/connect` → `OpenAI Compatible`，填写同样的 Base URL、API Key 和模型 ID。\n\n:::note\n- Provider ID 使用小写 `modelgo`；模型选择格式为 `modelgo/你的模型名`。\n- `baseURL` 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- Kilo CLI 的模型 ID 必须与 ModelGo 模型广场逻辑模型名一致。\n:::\n\n## 3. 验证配置\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\n在模型选择器中选中 ModelGo 模型，发送一条只读任务确认连接。\n\n## 常见问题\n\n### Provider 没有出现在选择器\n\n检查 `kilo.jsonc` 的 JSONC 格式、Provider ID 和 `model` 路径，并重新启动 Kilo。\n\n### 401 或 404\n\n确认 `MODELGO_API_KEY` 已导出，`baseURL` 为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Kilo CLI 官方文档](https://kilo.ai/docs/code-with-ai/platforms/cli)：查看安装、`/connect` 和 CLI 命令。\n- [Kilo 自定义模型](https://kilo.ai/docs/code-with-ai/agents/custom-models)：查看 OpenAI Compatible Provider 字段和模型格式。\n","international/zh/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Kilo Code。\n---\n\n# Kilo Code\n\nKilo Code 是一款支持 VS Code 和 JetBrains 的 AI 编程助手。通过 OpenAI 兼容 Provider，你可以在 Kilo Code 中使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 VS Code 或 JetBrains IDE。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Kilo Code\n\n### VS Code\n\n打开 VS Code 扩展市场，搜索 **Kilo Code**，确认发布者后安装扩展。安装完成后，打开左侧 Kilo Code 面板。\n\n![在 VS Code 扩展市场安装 Kilo Code](/images/agents/kilo-code/vscode-market.webp)\n\n首次安装时，VS Code 会要求确认是否信任发布者。确认发布者为 Kilo Code 后，点击 **Trust Publisher & Install**。\n\n![确认信任 Kilo Code 发布者](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\n打开 Settings / Preferences → Plugins，在 Marketplace 搜索 **Kilo Code** 并安装。安装完成后重启 IDE，使扩展生效。\n\n![在 JetBrains Marketplace 安装 Kilo Code](/images/agents/kilo-code/jetbrains-market.webp)\n\n安装第三方插件时，JetBrains 会显示插件声明。确认后点击 **接受**，完成安装。\n\n![确认 JetBrains 第三方插件声明](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. 在 VS Code 中配置 ModelGo\n\n打开 Kilo Code 的设置，进入 **Providers**，选择 **OpenAI Compatible**，填写以下信息：\n\n先在 Kilo Code 的欢迎页选择 **Bring my own Key**：\n\n![选择 Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model | ModelGo 平台逻辑模型名 |\n\n![Kilo Code VS Code 配置界面](/images/agents/kilo-code/vscode-config-global.webp)\n\n保存后，Kilo Code 会尝试从兼容的 `/v1/models` 接口获取模型。如果下拉列表中没有目标模型，可以选择 **Use custom**，手动输入模型广场中的逻辑模型名。\n\n:::note\n- Base URL 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。Kilo Code 会自动拼接标准路径。\n- 截图中的模型名仅为界面示例，请替换为当前 API Key 可调用的 ModelGo 逻辑模型名。\n- API Key 只填写在本机的 Kilo Code 设置中，不要提交到代码仓库或截图分享。\n:::\n\n## 3. 在 JetBrains 中配置 ModelGo\n\n打开 Kilo Code 设置，点击 **Bring my own Key**，选择 **OpenAI Compatible**，然后填写与 VS Code 相同的配置：\n\n![在 JetBrains 中选择 Bring my own Key](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**：`{{ api_endpoint }}/v1`\n2. **API Key**：ModelGo API Key\n3. **Model**：ModelGo 逻辑模型名\n4. 点击 **Save** 保存。\n\n![JetBrains 中的 ModelGo Provider 配置](/images/agents/kilo-code/jetbrains-config-global.webp)\n\n如果模型下拉列表为空，先确认 Base URL 可访问，再选择自定义模型并手动输入逻辑模型名。\n\n![在 JetBrains 中完成一次编码任务](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. 检查配置并开始对话\n\n进入一个本地项目，在 Kilo Code 面板中输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回模型结果，即表示接入成功。\n\n![Kilo Code 完成一次编码任务](/images/agents/kilo-code/vscode-start.webp)\n\n如需检查当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整，确认没有多余空格，并确认填写在 **API Key** 而不是 Base URL 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 **Model** 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。不要直接填写上游厂商原始模型 ID，除非模型广场明确提供该名称。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。Kilo Code 会在请求时补充具体接口路径。\n\n### 模型下拉列表没有内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 检查 API Key 和接口是否可用；如果接口正常，使用 **Use custom** 手动输入逻辑模型名。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Kilo Code 官方文档](https://kilo.ai/docs)：查看最新的扩展安装和 Provider 配置说明。\n","international/zh/agents/nanobot.md":"---\ntitle: nanobot\ndescription: 通过 ModelGo 接入 nanobot。\n---\n\n# nanobot\n\nnanobot 是轻量级终端 Agent。它通过 JSON 配置 Provider 和模型预设，可直接使用 ModelGo 的 OpenAI 兼容 API。\n\n## 接入前准备\n\n- 已安装 Python 3.11+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\n配置文件默认位于 `~/.nanobot/config.json`。\n\n## 2. 配置 ModelGo Provider\n\n编辑 `~/.nanobot/config.json`，合并以下字段：\n\n```json\n{\n  \"providers\": {\n    \"modelgo\": {\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"apiBase\": \"{{ api_endpoint }}/v1\"\n    }\n  },\n  \"modelPresets\": {\n    \"ModelGo\": {\n      \"provider\": \"modelgo\",\n      \"model\": \"你的模型名\",\n      \"maxTokens\": 4096,\n      \"contextWindowTokens\": 65536,\n      \"temperature\": 0.1\n    }\n  },\n  \"agents\": { \"defaults\": { \"modelPreset\": \"ModelGo\" } }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nnanobot 对 OpenAI 兼容自定义端点无需额外填写 `apiType`；`apiBase` 使用带 `/v1` 的根地址。\n\n:::note\n- 保留原配置中的 channels、tools 等字段，只合并 providers、modelPresets 和 agents.defaults。\n- API Key 使用环境变量，不要把真实 Key 写进 JSON 或提交到仓库。\n- 模型名必须是 ModelGo 模型广场中的逻辑模型 ID。\n:::\n\n## 3. 验证连接\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### `nanobot` 找不到模型\n\n确认 `modelPresets.ModelGo.provider` 与 `providers.modelgo` 的 ID 一致，并检查 JSON 格式。\n\n### 401 或请求地址错误\n\n确认 API Key 环境变量已导出，`apiBase` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [nanobot OpenAI 兼容 Provider 指南](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md)：查看完整 JSON 配置说明。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","international/zh/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: 通过 ModelGo 接入 Oh My Pi。\n---\n\n# Oh My Pi\n\nOh My Pi（命令 `omp`）是终端 AI 编程 Agent。它支持在 `models.yml` 中声明 OpenAI 兼容 Provider，并按 `provider-id/model-id` 选择模型。\n\n## 接入前准备\n\n- 已安装 Bun 或使用官方安装脚本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux 也可以执行官方安装脚本：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. 添加 ModelGo Provider\n\n编辑 `~/.omp/agent/models.yml`，加入：\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: 你的模型名\n        name: ModelGo / 你的模型名\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` 填环境变量名，而不是 Key 本身：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n:::note\n- `api` 使用 `openai-completions`，`baseUrl` 使用 `{{ api_endpoint }}/v1`。\n- 模型选择格式为 `modelgo/你的模型名`。\n- 不要把真实 API Key 写入 `models.yml`，并确认文件权限仅当前用户可读。\n:::\n\n## 3. 选择模型并验证\n\n```bash\nomp --list-models\nomp --model modelgo/你的模型名\n```\n\n进入会话后发送一条简单任务；也可先检查 ModelGo 模型目录：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 模型列表没有 ModelGo\n\n确认文件路径为 `~/.omp/agent/models.yml`，YAML 缩进正确，并重新启动 `omp`。\n\n### 401 或接口路径错误\n\n确认 `MODELGO_API_KEY` 已导出，`baseUrl` 没有重复 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Oh My Pi Provider 文档](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md)：查看 Provider、API 类型和密钥配置。\n- [Oh My Pi 模型文档](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md)：查看模型选择和 `models.yml` 结构。\n","international/zh/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenClaw。\n---\n\n# OpenClaw\n\nOpenClaw 是一款开源、自托管的个人 AI 助手。通过自定义 Provider，可以让 OpenClaw 使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22.22.3 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\n检查安装是否成功：\n\n```bash\nopenclaw --version\n```\n\n## 2. 设置 API Key\n\nOpenClaw 配置支持从环境变量读取 Provider API Key。将 ModelGo API Key 设置为 `MODELGO_API_KEY`：\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. 配置 ModelGo Provider\n\n创建并打开 OpenClaw 配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\n将下面内容粘贴到 `openclaw.json`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | ModelGo 逻辑模型名 |\n| `agents.defaults.model.primary` | `modelgo/<逻辑模型名>` |\n\n:::note\n- `baseUrl` 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- `contextWindow` 和 `maxTokens` 应与所选模型的限制匹配；上方数值是通用示例，请以模型广场信息为准。\n- 如果模型支持推理，可将对应模型的 `reasoning` 改为 `true`。\n- API Key 通过环境变量注入，不要把真实 Key 写入配置文件或提交到仓库。\n:::\n\n## 4. 启动并验证\n\n保存配置后，在终端执行：\n\n```bash\nopenclaw onboard --install-daemon\n```\n\n查看当前模型和 Provider 状态：\n\n```bash\nopenclaw models status\n```\n\n如果状态正常，启动 Gateway：\n\n```bash\nopenclaw gateway start\n```\n\n在 OpenClaw 对话界面发送一条简单消息，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 接入成功。\n\n## 常见问题\n\n### 找不到模型\n\n确认 `models.providers.modelgo.models[].id` 与 `agents.defaults.model.primary` 中的模型名一致，并使用 `modelgo/<模型名>` 格式。\n\n### 返回 401 或认证失败\n\n检查当前终端是否存在 `MODELGO_API_KEY`，并确认 `apiKey` 使用 `${MODELGO_API_KEY}`，没有多余空格。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`baseUrl` 应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；OpenClaw 会按 `openai-completions` 协议拼接路径。\n\n### Gateway 没有加载新配置\n\n修改配置后重启 Gateway：\n\n```bash\nopenclaw gateway restart\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [OpenClaw 自定义 Provider 文档](https://docs.openclaw.ai/gateway/config-tools)：查看 Provider、Base URL 和模型列表配置说明。\n","international/zh/agents/opencode.md":"---\ntitle: OpenCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenCode。\n---\n\n# OpenCode\n\nOpenCode 是一个开源终端 AI 编程 Agent，支持通过自定义 Provider 接入 OpenAI 兼容接口。配置 ModelGo 后，可以在终端、IDE 或桌面端使用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已安装 OpenCode，并能在终端执行 `opencode -v`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenCode\n\n在终端执行：\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nWindows 用户也可以使用 OpenCode 官方提供的安装方式。安装完成后，执行 `opencode -v`，看到版本号即表示安装成功。\n\n## 2. 配置 ModelGo Provider\n\nOpenCode 默认从以下位置读取用户配置：\n\n- macOS/Linux：`~/.config/opencode/opencode.json`\n- Windows：`%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\n创建或编辑 `opencode.json`，将 `你的模型名` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"你的模型名\"\n        }\n      }\n    }\n  }\n}\n```\n\n设置环境变量：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `name` | `ModelGo`，用于界面显示 |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | 模型广场中的逻辑模型 ID 和显示名称 |\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- `modelgo` 是本地 Provider ID，可以按需修改；修改后选择模型时使用新的 Provider ID。\n- API Key 通过环境变量读取，不要把真实 Key 直接写入配置文件或提交到仓库。\n- 模型 ID 必须是 ModelGo 模型广场中的逻辑模型名，不要直接照抄示例。\n:::\n\n## 3. 选择模型并开始对话\n\n启动 OpenCode：\n\n```bash\nopencode\n```\n\n输入 `/models` 打开模型选择器，搜索并选择 **ModelGo** Provider 下的模型。\n\n![在 OpenCode 中打开模型选择器](/images/agents/opencode/model-search.webp)\n\n模型列表中显示 **ModelGo** 的条目，即表示 Provider 已被识别。\n\n![在 OpenCode 模型列表中识别 ModelGo](/images/agents/opencode/provider-name.webp)\n\n也可以在模型选择器中输入 `ModelGo` 进行筛选：\n\n![在 OpenCode 中筛选 ModelGo 模型](/images/agents/opencode/provider-filter.webp)\n\n选择模型后输入一条简单任务，例如“用三句话介绍这个项目”。\n\n![在 OpenCode 中使用 ModelGo 开始对话](/images/agents/opencode/chat.webp)\n\n## 4. 验证配置\n\n如果模型列表为空，可以先确认 API Key 能访问 ModelGo：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是可填入 `models` 配置的逻辑模型名。\n\n## 常见问题\n\n### OpenCode 找不到配置文件\n\n确认文件名为 `opencode.json`，并放在 `~/.config/opencode/`（Windows 为 `%USERPROFILE%\\\\.config\\\\opencode\\\\`）目录下。也可以在项目目录放置同名配置覆盖用户配置。\n\n### 返回 401 或认证失败\n\n确认当前终端已设置 `MODELGO_API_KEY`，且 API Key 没有多余空格。重新打开终端后再启动 OpenCode。\n\n### 返回 404 或接口路径错误\n\n确认 `baseURL` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n### 模型列表为空或模型不可用\n\n确认 `models` 中的 ID 与模型广场逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [OpenCode 官方 Providers 文档](https://opencode.ai/docs/providers)：查看 Provider、凭据和自定义 Base URL 的配置方式。\n- [OpenCode 官方配置文档](https://opencode.ai/docs/config/)：了解配置文件结构及模型选项。\n","international/zh/agents/zcode.md":"---\ntitle: ZCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 ZCode。\n---\n\n# ZCode\n\nZCode 是智谱 AI 推出的桌面 AI 编程工具，支持 Windows、macOS 和 Linux。ZCode 支持自定义 OpenAI 兼容供应商，配置后可以直接使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 ZCode 桌面客户端。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 ZCode\n\n访问 [ZCode 官方下载页](https://zcode.z.ai/cn/docs/install)，根据操作系统下载对应安装包。ZCode 提供 macOS、Windows 和 Linux 版本，Linux 用户可以选择 `.deb`、`.rpm` 或 AppImage。\n\n![ZCode 官方下载页](/images/agents/zcode/install.webp)\n\n下载完成后，按系统提示完成安装并启动 ZCode。首次启动时可以选择工作区；完成引导后进入主界面。\n\n![ZCode 全平台安装包](/images/agents/zcode/setup.webp)\n\n## 2. 添加 ModelGo 供应商\n\n在 ZCode 左下角点击设置图标，进入 **Model settings**，然后在供应商列表底部点击 **Add provider**。\n\n![打开 ZCode Model settings 并添加供应商](/images/agents/zcode/provider-fields.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在 [控制台]({{ console_endpoint }}/api-keys) 创建的 ModelGo API Key |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | 点击 **Add model**，填写模型广场中的逻辑模型名 |\n| Context window | 按模型实际上下文长度填写；不确定时可先填 `200000` |\n\n![ModelGo 供应商配置示例](/images/agents/zcode/provider-saved-global.webp)\n\n点击 **Add provider** 保存。配置时请注意：\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；ZCode 会根据 API format 自动拼接路径。\n- Name 是本机显示名称，填写 `ModelGo` 即可，不需要填写上游厂商名称。\n- Model list 中的模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 添加模型并开始对话\n\n点击 **Add model**，输入一个 ModelGo 逻辑模型名并保存。可以按需添加多个模型。\n\n![ZCode 中选择 ModelGo 模型](/images/agents/zcode/chat.webp)\n\n回到对话界面，在模型下拉菜单中选择 **ModelGo** 和刚添加的模型，输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n如需确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认填写在 **API Key** 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 Model list 中填写的是模型广场中的逻辑模型名，且当前 API Key 策略允许调用该模型。\n\n### 返回 404 或接口路径错误\n\nBase URL 应为 `{{ api_endpoint }}/v1`，API format 请选择 **Chat completions (/chat/completions)**，不要把完整接口路径填入 Base URL。\n\n### 模型列表为空或无法保存\n\n确认至少添加了一个模型，并检查 Base URL 是否可以访问。必要时先用 `GET {{ api_endpoint }}/v1/models` 验证 API Key 和接口。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [ZCode 安装文档](https://zcode.z.ai/cn/docs/install)：查看最新安装说明。\n- [ZCode 连接模型文档](https://zcode.z.ai/cn/docs/configuration)：查看自定义供应商和模型配置说明。\n","international/zh/models/audio/minimax.md":"---\ntitle: MiniMax 音频入站协议\ndescription: 用 MiniMax T2A 原厂请求体与响应体做平台托管的同步语音合成。\n---\n\n# MiniMax 音频入站协议\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | 目录公示的 MiniMax T2A 入站 |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK 别名，语义相同 |\n\n这是 **MiniMax 同步语音合成（T2A V2）** 的原厂入站协议。请求体按 MiniMax `T2aV2Req` 原样接收（`model`、`text`、`voice_setting`、`audio_setting`、`stream` 等），**响应体也按 MiniMax `T2aV2Resp` 渲染**，照 MiniMax 官方文档写的客户端可以直接解析。\n\n`model` 填写平台逻辑模型名，策略、路由与计费照常生效。逻辑模型必须在 `public_protocols` 中声明 `minimax_t2a`，否则网关返回协议不匹配。\n\n只需要 OpenAI 形态的二进制音频时，见[语音合成](./speech)。\n\n## 合成\n\n两条路径等价，任选其一：\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"你好，欢迎使用 ModelGo。\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\n非流式成功响应是 MiniMax JSON，音频在 `data.audio`，为**十六进制字符串**（不是 `audio/mpeg` 直出）：\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\n2026-09-10 国内生产用 `speech-2.8-turbo` 打 `POST /minimax/v1/t2a_v2` 得到上述形态（hex 已截断）。同一模型打 `POST /v1/audio/speech` 返回 `model_protocol_not_offered`。\n\n`base_resp.status_code` **只有数字 `0` 表示成功**。HTTP 200 但 `status_code != 0` 仍按调用失败处理。\n\n### 流式\n\n请求里加 `\"stream\": true`，响应为 SSE，每帧仍是 MiniMax JSON（含增量 hex 音频），不是 OpenAI chat 的 `choices[].delta`。\n\n### 失败与 HTTP\n\n带内错误会把 MiniMax JSON 回传给调用方，并按 `status_code` 映射 HTTP 状态：\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| 其余非 `0` | `502` |\n\n### 计费\n\n按上游报告的 **字符数** 计量（`usage.characters`，否则 `extra_info.usage_characters`），不会用 `text` 的字符串长度估算。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；是否可走本通道以该模型的 `public_protocols` 为准。\n- 路径不参与选路：由逻辑模型的路由决定 MiniMax 直连或百炼等 adaptor。\n- 路由上的 Provider 必须声明支持 MiniMax T2A；仅 OpenAI 兼容中继时会返回 `provider_unsupported`。\n","international/zh/models/audio/speech.md":"---\ntitle: 语音合成\ndescription: OpenAI 兼容 text-to-speech 接口说明。\n---\n\n# 语音合成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\n请求体为 JSON（OpenAI `{input, voice}`），响应体为二进制音频，`Content-Type` 由上游决定并原样返回。\n\n**先确认模型声明了 OpenAI TTS 协议。** 国内生产上的 `speech-2.8-hd` / `speech-2.8-turbo` 当前走 MiniMax T2A，打本接口会返回 `model_protocol_not_offered`。这两款模型请用 [MiniMax 音频入站协议](./minimax)。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"你好，欢迎使用 ModelGo。\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\n需要 MiniMax 原厂字段（音色、字幕、hex JSON、SSE）时，见[MiniMax 音频入站协议](./minimax)。\n","international/zh/models/audio/transcriptions.md":"---\ntitle: 语音转文本\ndescription: OpenAI 兼容 speech-to-text 接口说明。\n---\n\n# 语音转文本\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\n该接口通常以 `multipart/form-data` 上传音频文件和 `model` 字段，响应为 JSON，包含识别出的 `text`。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/zh/models/audio/translations.md":"---\ntitle: 语音翻译\ndescription: OpenAI 兼容语音翻译接口说明。\n---\n\n# 语音翻译\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\n上传方式与语音转文本一致，响应为 JSON。适合把音频内容翻译为目标文本输出。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/zh/models/images/edits.md":"---\ntitle: 图像编辑\ndescription: OpenAI 兼容图像编辑接口说明。\n---\n\n# 图像编辑\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\n该接口使用 `multipart/form-data` 上传原图和 `model` 字段。网关会保留原始 body 与 `Content-Type` 向上游透传，因此调用时应直接使用 `POST /v1/images/edits` 的 multipart 方式。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\n如果上游模型不支持图像编辑，平台会返回 `provider_unsupported`。\n","international/zh/models/images/generations.md":"---\ntitle: 图像生成\ndescription: OpenAI 兼容图像生成接口说明。\n---\n\n# 图像生成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\n请求体遵循 OpenAI Images 兼容格式，平台将其透传到支持图像生成的上游 Provider。核心入口是 `POST /v1/images/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\n常见可选字段包括 `size`、`quality`、`n` 等，是否生效取决于实际路由到的上游模型能力。\n\n## 已验证限制（Seedream）\n\n`doubao-seedream-5.0-lite` 在 `size=1024x1024` 时上游拒绝：HTTP 400、`error_class=provider_invalid`，要求像素总数至少 3686400（约 1920×1920）。改用 `2048x2048` 后于 2026-09-10 国内生产返回 200。完整 curl 见[接口清单](../../../quickstart/openapi)。\n","international/zh/models/images/qwen-image.md":"---\ntitle: 千问图像生成与编辑 3.0（百炼原生协议）\ndescription: 调用 qwen-image-3.0 / qwen-image-3.0-pro：OpenAI 兼容与百炼 DashScope 原生两条同步入站通道、文生图与图生图（1-3 张参考图）、size 的两种分隔符写法与 1k / 2k 分辨率档位。百炼官方 SDK 改 base_url 即可直连。\n---\n\n# 千问图像生成与编辑 3.0（百炼原生协议）\n\n## 模型\n\n| 模型 | 输出分辨率 | 说明 |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | 总像素 512×512 – 2048×2048 | Pro 系列，2k 档单价高于 1k 档 |\n| `qwen-image-3.0` | 同上 | 标准版，两个档位同价 |\n\n> **可用性与价格按区域不同。** 接入前请先确认该区域是否提供这两个模型 —— 见[接口清单](../../../quickstart/openapi)。\n\n两个模型都同时支持**文生图（T2I）**和**图生图 / 图像编辑（I2I）**：不传参考图是文生图，传 1–3 张参考图是图生图。图像**同步返回**，无需轮询。\n\n> **不支持异步任务通道。** 这一族只在同步接口上服务；打 `/v1/content_generation/tasks` 会被拒。\n\n## 两条入站通道\n\n同一个模型有两种调用写法，能力完全一致，按你现有代码的形状选：\n\n| 通道 | 路径 | 适合谁 |\n| --- | --- | --- |\n| OpenAI 兼容 | `POST /v1/images/generations` | 已按 OpenAI Images 协议或 OpenAI SDK 开发的应用，只改 `base_url` 与 `model` |\n| 百炼原生 | `POST /api/v1/services/aigc/multimodal-generation/generation` | 已在用百炼 DashScope SDK 的应用，只改 `base_url` |\n\n> **两条通道的 `size` 分隔符不同，且互不接受**：OpenAI 兼容通道用字母 `x`（`1024x1024`），百炼原生通道用星号 `*`（`1024*1024`）。写错的那一侧会返回 `400` 并点名正确的分隔符，**不会**被静默改写 —— 这是为了让协议混用尽早显形，而不是在别处出更难查的问题。\n\n## 1. OpenAI 兼容通道\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### 文生图\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，午后光线，胶片质感\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### 图生图 / 图像编辑\n\n不用 multipart，参考图放在请求体顶层的 `image` 字段：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"保留这位女性的面部特征，把服装换成香槟色真丝衬衫与深灰西装外套\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- 图像格式为 PNG，**链接有效期 24 小时**，请及时下载，不要持久化该 URL。\n- `usage` 是**图片张数与档位**，不是 token 用量 —— 这一族的计费完全按张，见「计费口径」。\n- 传 `response_format: \"b64_json\"` 不会报错，但会被忽略，响应中仍是图像 URL。\n\n### 使用 OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # 出图耗时较长，实测单张 40-60 秒\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # 扩展字段走 extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` 不是 OpenAI 官方参数，用 OpenAI SDK 时通过 `extra_body` 传入；直接发 HTTP 请求时放在请求体顶层即可。\n\n## 2. 百炼原生通道\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\n请求与响应两头都是百炼原样的形状，网关不做翻译。\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### 这条通道的约束\n\n- `input.messages` **有且只有一个**对象，`role` 必须是 `user`（仅支持单轮对话）。\n- `content` 里**有且只有一个** `{\"text\": ...}`，不传或传多个都会 `400`。\n- `{\"image\": ...}` 0–3 个：0 个是文生图，1–3 个是图生图。\n- 生成参数放在 `parameters` 下（不是顶层）：`size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`。\n- 使用百炼官方 SDK（`dashscope`）时，把 `dashscope.base_http_api_url` 指向 `{{ api_endpoint }}/api/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 3. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt`（兼容通道）/ `content[].text`（原生通道） | string | 必填，非空。支持中英文，建议不超过 4500 token |\n| `image`（兼容通道）/ `content[].image`（原生通道） | string / string[] | 参考图，1–3 张。**不能传 `null` 或空数组** |\n| `size` | string | 兼容通道 `宽x高`，原生通道 `宽*高`；不传则由模型按提示词自动推荐分辨率 |\n| `n` | int | 输出张数 1–6，缺省 1。**必须是整数**，传字符串形式（如 `\"1\"`）返回 `400` |\n| `negative_prompt` | string | 反向提示词 |\n| `seed` | int | 随机数种子，`0` – `2147483647`。固定种子可让结果相对稳定 |\n| `prompt_extend` | boolean | 是否开启提示词智能改写，缺省 `true`（建议开启） |\n| `prompt_extend_mode` | string | `direct`（缺省，T2I / I2I 均支持）/ `agent`（更精细，**仅文生图**） |\n| `enable_thinking` | boolean | 思考模式，缺省 `true`。提升出图质量但增加耗时。仅在 `prompt_extend=true` 时生效 |\n| `watermark` | boolean | 是否加水印，缺省 `false` |\n\n### 参数校验在调用前完成\n\n下列请求在**创建时**就被拒（HTTP `400`），不会打到上游、不产生费用：\n\n- `n` 不是 1–6 的整数，或写成了字符串 / 小数；\n- `size` 的总像素不在 512×512 – 2048×2048 之间，或宽高比超出 1:8 – 8:1；\n- `size` 用了另一条通道的分隔符（错误信息会点名该用 `x` 还是 `*`）；\n- `image` 为 `null`、空数组，或超过 3 张；\n- `prompt_extend_mode: \"agent\"` 与 `image` 同时出现（APE 仅支持文生图）；\n- `seed` 超出 `0` – `2147483647`；\n- 原生通道上 `messages` 不是恰好一个、或 `content` 里的 `text` 不是恰好一个。\n\n### 参考图的要求\n\n- 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF。\n- 建议宽高均在 384 – 2048 像素之间，单张不超过 10 MB。\n- 支持公网 URL（HTTP / HTTPS）或 Base64（`data:{MIME_type};base64,{base64_data}`）。\n- 公网 URL 必须是上游能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。部分站点对非浏览器抓取返回 403，会导致请求失败。\n\n## 4. 计量口径\n\n**这一族按张计量，不按 token。** `usage` 里给的是图片张数与档位，不是 token 用量：\n\n| 字段 | 含义 |\n| --- | --- |\n| `output_image_count` | 本次实际交付的图片张数 |\n| `output_image_type` | 本次命中的输出档位：`qima_output_1k` 或 `qima_output_2k` |\n| `input_image_count` | 请求提供的参考图张数（文生图为 0） |\n| `input_image_type` | 输入档位：`qima_input_1k` 或 `qima_input_2k` |\n\n**档位按「输出」像素面积判定**：面积 ≤ 2,250,000（即 1500×1500）为 `1k`，更大为 `2k`。**输入图的档位同样按输出面积判定**，不是按参考图自己的尺寸 —— 这是上游的口径。\n\n文生图没有参考图，`input_image_count` 为 0，只计量交付的图片。请求 `n` 张就计量 `n` 张，不是一张。\n\n## 5. 完整示例（Python，百炼官方 SDK）\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫，背景换成现代简约咖啡店\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","international/zh/models/realtime/api.md":"---\ntitle: Realtime API 参考\ndescription: GET /api-ws/v1/realtime（WebSocket）的握手、事件与音频格式说明。\n---\n\n# Realtime API 参考：`GET /api-ws/v1/realtime`\n\n本接口是一个 WebSocket 长连接。网关把百炼 **Qwen-Omni-Realtime** 协议原样双向转发，**不做协议转换**；事件字段的完整定义与工具调用（Function Calling / MCP）事件以百炼官方[客户端事件](https://help.aliyun.com/zh/model-studio/client-events)与[服务端事件](https://help.aliyun.com/zh/model-studio/server-events)为准。本页覆盖接入所需的握手、鉴权、事件清单与音频约定。\n\n## 请求\n\n| 项 | 值 |\n| --- | --- |\n| 方法 | `GET`（WebSocket 升级） |\n| 路径 | `/api-ws/v1/realtime` |\n| 完整地址 | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<逻辑模型名>` |\n| Query | `model`（必填）——平台逻辑模型名，不是上游模型名 |\n| Header | `Authorization: Bearer <mgk_ API Key>`（必填） |\n| Header | `X-Request-ID`（可选）——透传到调用日志，`request_id` 以 `gw_rt_` 开头 |\n\n只有 `public_protocols` 声明了 `dashscope_realtime` 的逻辑模型才能走本入口。\n\n## 握手错误码 {#handshake-errors}\n\n握手（升级为 WebSocket 之前）失败时，以 HTTP 状态码返回，body 为：\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | 触发条件 | 实测 message（cn 生产，2026-10-08） |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | 未携带 API Key | `missing api key` |\n| 401 | `unauthorized` | Key 无效 / 已禁用 | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | 模型不在目录 | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | 模型未声明 `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | 策略（含回落链）中没有该模型的路由 | `no route for model <model>` |\n| 503 | `no_provider` | 有路由但无可用上游实例 | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | 预授权失败（余额/预算不足） | `billing: insufficient funds` |\n\n握手通过（HTTP 101）后再出现的问题，会以带内 `error` 事件下发，然后关闭连接：\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## 会话配置 `session.update`\n\n建连后服务端先发 `session.created`，客户端用 `session.update` 覆盖配置，配置合法则回 `session.updated`。常用字段：\n\n| 字段 | 可选值 | 默认 |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | 见百炼音色列表 | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | 服务端 VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | 任意文本 | 空 |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | 开启 |\n\n`turn_detection: null` 表示关闭服务端 VAD，改由客户端手动提交与触发响应。\n\n## 客户端事件\n\n| 事件 | 作用 |\n| --- | --- |\n| `session.update` | 更新会话配置（模态、音色、音频格式、VAD、instructions 等） |\n| `input_audio_buffer.append` | 追加 Base64 音频到输入缓冲区 |\n| `input_image_buffer.append` | 追加 Base64 图片（JPG/JPEG，需先发过音频） |\n| `input_audio_buffer.commit` | 手动模式下提交音频缓冲区（提交不触发响应） |\n| `input_audio_buffer.clear` | 清空音频缓冲区 |\n| `conversation.item.create` | 创建对话项：纯文本输入、`function_call_output`、`mcp_approval_response` |\n| `response.create` | 触发一次模型响应 |\n| `response.cancel` | 取消正在进行的响应（打断） |\n\n## 服务端事件\n\n| 事件 | 说明 |\n| --- | --- |\n| `session.created` / `session.updated` | 会话建立 / 配置生效 |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD 检测到用户开始 / 停止说话（打断依据） |\n| `input_audio_buffer.committed` / `cleared` | 音频缓冲区提交 / 清空 |\n| `conversation.item.created` | 对话项已创建 |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | 输入语音转写（流式预览 / 最终结果） |\n| `response.created` | 一轮响应开始 |\n| `response.output_item.added` / `response.content_part.added` | 输出项 / 内容片段开始 |\n| `response.text.delta` / `response.text.done` | 仅文本模式的流式 / 完整文本 |\n| `response.audio_transcript.delta` / `.done` | 含音频模式下，音频对应的文本 |\n| `response.audio.delta` / `response.audio.done` | Base64 输出音频（24 kHz PCM）/ 音频结束 |\n| `response.output_item.done` / `response.content_part.done` | 输出项 / 内容片段完成 |\n| `response.done` | 一轮响应结束，`response.usage` 携带分模态 token 用量 |\n\n工具调用（`response.function_call_arguments.delta` / `.done`）与 MCP 相关事件（`mcp_*`）字段见百炼服务端事件文档。\n\n一次完整语音问答的实测事件序（cn 生产，2026-10-08）：\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## 音频格式\n\n| 方向 | 格式 | 事件 / 字段 |\n| --- | --- | --- |\n| 上行（输入） | 16000 Hz、16-bit 小端、单声道 PCM，Base64 | `input_audio_buffer.append` 的 `audio` |\n| 下行（输出） | 24000 Hz、16-bit 小端、单声道 PCM，Base64 | `response.audio.delta` 的 `delta` |\n\n实测满 100 ms 一包推送输入音频（3200 字节 / 帧）最稳。`input_audio_buffer.append` 只入缓冲，不触发响应；是否提交由 VAD 或客户端 `input_audio_buffer.commit` 决定。\n\n## VAD 与打断\n\n- `turn_detection` 非 `null` 时，服务端自动检测语音起止并在静音 `silence_duration_ms`（默认 800ms）后自动提交、触发响应。\n- 用户再次说话：服务端下发 `input_audio_buffer.speech_started` → 客户端**停止播放**并发 `response.cancel` → 收到 `response.done`（cancelled）→ 新一轮。\n- `turn_detection: null` 为手动模式：客户端在录音结束后依次发送 `input_audio_buffer.commit`（等 `input_audio_buffer.committed`）与 `response.create`。\n\n## 用量与计费\n\n每轮响应的 `response.done.response.usage` 携带分模态 token：\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\n网关按整段连接的累计用量在关闭时结算：连接时按会话级预估预授权（当前约 ¥1.2，余额不足则握手 `402`），关闭连接后按实际用量多退少补，无用量则释放预授权。详见[使用指南](./guide#billing)。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 上游限流 | 60 RPM |\n\n## 相关\n\n- [实时语音（Realtime）模型使用指南](./guide)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","international/zh/models/realtime/guide.md":"---\ntitle: 实时语音（Realtime）模型\ndescription: 通过 WebSocket 接入 Qwen-Omni-Realtime，实现实时语音对话、打断与全模态输入。\n---\n\n# 实时语音（Realtime）模型\n\nRealtime 类模型**不走** `/v1/chat/completions`，只能通过 WebSocket 长连接调用。网关把百炼 Qwen-Omni-Realtime 协议**原样双向转发**，不做任何协议转换：你按百炼协议发事件，也按百炼协议收事件。本文给出接入方式、可运行的最小示例与计费口径；逐字段的事件与错误定义见[API 参考](./api)。\n\n## 能做什么\n\n- **实时语音对话**：边说边回，端到端流式返回文本与音频。\n- **语音打断**：用户再次开口时，服务端下发 `input_audio_buffer.speech_started`；客户端停播并发 `response.cancel` 打断当前回复。\n- **全模态输入**：流式音频、图片（可由视频抽帧实时采集）、纯文本。\n- **文本 + 音频输出**：模型同时产出文本与语音。\n\n## 适用模型\n\n一个逻辑模型要能走本入口，必须在模型目录的 `public_protocols` 中声明 `dashscope_realtime`。目前上架的 realtime 模型是 `qwen3.8-omni-flash-realtime`（以模型广场实际上架为准）。可在 [{{ console_endpoint }}]({{ console_endpoint }}) 的模型广场确认某个模型是否提供了该协议。\n\n## 接入\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<逻辑模型名>`（必填） |\n| 鉴权 | `Authorization: Bearer <mgk_ API Key>` |\n| 请求 ID | 可选 `X-Request-ID`；调用日志里 `request_id` 以 `gw_rt_` 开头 |\n\n握手阶段的失败会直接返回 HTTP 状态码（如 Key 无效 `401 unauthorized`、模型未声明 realtime 协议 `403 model_protocol_not_offered`、余额不足 `402`），完整清单见[API 参考](./api#handshake-errors)。\n\n## 最小示例\n\n下面示例在**服务端**运行：用 `mgk_` API Key 建连，配置会话，推送一段 16 kHz PCM 语音，提交后请求回复，并把返回的 24 kHz PCM 写入 `reply.pcm`。\n\n:::note\n- 浏览器原生 `WebSocket` 构造器**不能携带 `Authorization` 头**，所以不能把 API Key 直接放进浏览器连接。\n- 浏览器采集麦克风后，需经你自己的服务端中转（服务端持有 Key 并建连转发），或使用具备鉴权的服务端代理。\n- 下面 Python / Node.js 示例均为服务端代码，可直接复制运行。\n:::\n\n准备输入：把麦克风录音或一段 **16 kHz、16-bit 小端、单声道、无文件头**的 PCM 存为 `input.pcm`。若手上是 WAV，先提取裸 PCM：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython（`pip install websocket-client`）：\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js（`npm install ws`）：\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\n把返回的 `reply.pcm`（24 kHz、16-bit、单声道）封装成可播放的 WAV：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\n只想验证链路时，也可以不传音频：发送一条 `conversation.item.create`（`content` 为 `input_text`），再发 `response.create`，即可只拿文本回复。\n\n## 会话配置\n\n建连后服务端先发 `session.created`（含默认配置），客户端用 `session.update` 覆盖。常用字段：\n\n| 字段 | 说明 |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]`（默认，文本+音频）或 `[\"text\"]`（仅文本） |\n| `voice` | 输出音色，默认 `Tina`；建议使用 `audio.output.voice` |\n| `turn_detection` | 服务端 VAD：`{\"type\":\"server_vad\"}` 或 `{\"type\":\"semantic_vad\"}`；设为 `null` 由客户端手动 commit |\n| `audio.input.format` | 输入音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | 输出音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | 系统人设 |\n| `audio.input.transcription` | 输入转写，服务端会自动开启（模型 `qwen3-asr-flash-realtime`） |\n\n历史兼容字段 `input_audio_format` / `output_audio_format` 仍可用，但新接入建议使用 `audio.input.format` / `audio.output.format`。\n\n## 打断\n\n`turn_detection` 非 `null` 时由服务端 VAD 驱动轮次。用户再次开口会触发：\n\n1. 服务端下发 `input_audio_buffer.speech_started`；\n2. 客户端**停止播放**已缓冲的回复音频，并发送 `response.cancel`；\n3. 服务端随后下发 `response.done`（状态为 cancelled），开始新一轮。\n\n手动模式（`turn_detection: null`）下，客户端负责在录音结束后发送 `input_audio_buffer.commit` 与 `response.create`。\n\n## 计费 {#billing}\n\n- **按 token 分模态计价**：输入分文本/图片/视频与音频两档，输出分文本与音频两档。输出语音时，音频与其对应的文本**分别**计费。\n- **连接时预授权**：建连时按一个会话级预估冻结一笔余额（当前配置约 ¥1.2）。余额不足以覆盖预授权时，握手直接返回 `402`，不建立连接。\n- **关闭连接后按实际用量结算**：按本次连接内所有 `response.done` 的 `usage` 累计结算，多退少补；整段会话没有产生任何用量时释放预授权、不扣费。\n\n价格以控制台模型页为准；例如国内生产 `qwen3.8-omni-flash-realtime` 的单价（元/百万 token）：输入 文本/图片/视频 `1.5`、输入音频 `6`、输出文本 `4.5`、输出音频 `12`。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制；到达上限即关闭连接并结算） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 音频历史 | 最多 100 轮 / 累计 600 秒 |\n| 视频历史 | 最多 50 轮 / 累计 240 秒 |\n| 上游限流 | 60 RPM |\n\n## 下一步\n\n- [API 参考：`GET /api-ws/v1/realtime`](./api)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","international/zh/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: 对候选文档按相关性重排序的 Rerank 接口。\n---\n\n# Rerank\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | 对文档按与查询的相关性重排序 |\n| `POST` | `/v1/reranks` | 同上（别名，等价于 `/v1/rerank`） |\n\nRerank 接口接收一段查询与若干候选文档，按相关性返回排序后的结果，常用于检索增强（RAG）场景的精排。`/v1/rerank` 与 `/v1/reranks` 是同一能力的两条等价路径。\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"ModelGo 支持哪些协议\",\n    \"documents\":[\n      \"兼容 OpenAI 与 Anthropic 协议\",\n      \"今天的天气不错\",\n      \"支持图像、视频、向量、音频能力\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；请求体按上游 Rerank 协议透传，具体字段（如 `top_n`、`return_documents`）是否生效取决于路由到的上游模型。\n- 返回结果通常包含每条文档的相关性得分与排序序号。\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","international/zh/models/text/generation.md":"---\ntitle: 文本生成\ndescription: OpenAI Responses、Chat Completions 兼容入口与 Anthropic Messages 的统一说明。\n---\n\n# 文本生成\n\n文本能力当前覆盖以下公开入口，推荐优先使用 `POST /v1/responses`，其余入口用于兼容已有 SDK 和原生 Claude 客户端。\n\n| 协议 | 方法与路径 | 用途 |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | 新项目优先使用的统一文本生成接口 |\n| OpenAI | `POST /v1/chat/completions` | 兼容大量现有 OpenAI SDK 的对话补全接口 |\n| OpenAI | `POST /v1/completions` | 旧版文本补全接口，仅用于兼容历史调用链 |\n| Anthropic | `POST /v1/messages` | Claude 原生消息格式接口 |\n| OpenAI | `GET /v1/models` | 查询当前路由可用的逻辑模型清单 |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"用三句话介绍 ModelGo。\"\n  }'\n```\n\n适合新接入和统一封装场景。请求体、流式返回和 `usage` 字段遵循 OpenAI Responses 兼容格式。\n\n## OpenAI Chat Completions 兼容入口 {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合已经绑定 OpenAI SDK 或历史对话补全调用链的客户端。推荐新项目优先迁移到 `POST /v1/responses`。\n\n## OpenAI Completions（旧版补全）\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"用三句话介绍 ModelGo。\",\n    \"max_tokens\":256\n  }'\n```\n\n旧版文本补全接口，仅用于兼容仍在使用 `prompt` 的历史调用链，新项目请使用上面的 Responses / Chat Completions。`stream` 同样以 SSE 返回。多数当前对话模型未声明此协议：`qwen3.6-flash` 实测 HTTP 400、`model_protocol_not_offered`。\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合直接复用 Claude 原生消息格式的客户端。该入口保持 `/v1/messages` 的事件流语义，不会在网关侧改造成 OpenAI SSE 帧。\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` 返回该 API Key 绑定策略所允许的逻辑模型（结合平台模型目录），不会在请求时实时探测上游能力，可能与控制台展示略有差异；计费、策略以控制台和绑定策略为准。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名\n- `GET /v1/models` 可用，清单由 API Key 绑定的策略与平台模型目录决定\n- OpenAI 与 Anthropic 协议都可能返回上游原样 `usage`\n- 流式失败时可能不会发送 `data: [DONE]`，请以数据块中的 `error` 判断\n- 如果上游或路由不支持当前协议，平台会返回 `provider_unsupported` 或协议不兼容错误\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","international/zh/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI 兼容向量嵌入接口说明。\n---\n\n# Embeddings\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | 文本向量嵌入 |\n| `POST` | `/v1/embeddings/multimodal` | 多模态（图文等）向量嵌入 |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` 可以是单条字符串，也可以是字符串数组。返回结果遵循 OpenAI Embeddings 兼容格式。\n\n## 多模态 Embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\n面向同时包含文本与图像等内容的向量嵌入场景。`input` 结构与具体模型的多模态能力相关，是否生效取决于路由到的上游模型。\n","international/zh/models/video/ark.md":"---\ntitle: Seedance 视频入站协议\ndescription: 用 Ark 原厂路径调用平台托管的 Seedance 异步视频任务，请求体与响应体都按 Ark 内容生成协议书写。\n---\n\n# Seedance 视频入站协议\n\n豆包 Seedance 系列（`doubao-seedance-*`）除标准视频协议外，还可以用**火山方舟（Ark）原厂路径**调用，\n请求体与响应体按 Ark 内容生成协议书写：\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 创建内容生成任务（视频） |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见下） |\n\n这是**平台托管**通道：路径是 Ark 自己的，但请求走的是网关标准的异步任务流水线，与\n[通用异步内容生成任务](./async-tasks)完全同一条链路，只是换了 Ark 的路径拼写。因此它同样享受\n维度计费、任务落库、产物持久化与预扣/结算的全部保障。\n\n## 创建任务\n\n请求体按 Ark 内容生成协议书写，`model` 填**平台逻辑模型名**（如 `doubao-seedance-2.0-mini`）：\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一只霓虹都市里的猫\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" } }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\n`resolution` / `ratio` / `duration` 的合法取值**随模型而异**（例如 Seedance 2.0 的 Fast 与 Mini 不支持\n`1080p`，`duration` 下限是 4 秒），请以对应模型的能力说明为准；超出范围会在创建时被拒。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与查询返回的就是[通用异步内容生成任务](./async-tasks)那一种 Ark 任务对象——同一条流水线，\n响应报文与字段语义（`status` 取值、`content.video_url`、`error`、`usage` 缺省规则）与那一页完全一致，\n此处不再重复。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消成功后预扣会被退回（void），不产生结算。\n\n**但取消不是所有上游都支持。** 能否取消取决于承接该任务的供应商是否实现了取消能力，而这条通道\n不锁定上游 family，所以同一个逻辑模型的两次调用可能一次能取消、一次不能。两种失败：\n\n| 情况 | 响应 |\n| --- | --- |\n| 承接该任务的供应商不支持取消 | `400` / `4003` `provider_unsupported`，`endpoint not supported by provider` |\n| 任务已到终态（`succeeded` / `failed`） | `409` `task_already_terminal`，`task already finished; nothing to cancel` |\n\n取消失败时预扣不会提前退回，会等任务到终态或预扣过期后按正常结算/释放流程处理。所以**不要把\n「先创建、再取消」当成一种可靠的止损手段**。\n\n## 关键约定\n\n- **`id` 是网关任务 ID，不是上游任务 ID。** 查询、取消都只认这个 ID，请以创建响应里的 `id` 为准。\n- **响应形态是固定的。** 无论实际由哪家上游承接，创建与查询都返回同一种 Ark 任务对象，\n  不会因为路由到不同供应商而变形。\n- **该通道不锁定上游 family。** 路径拼写不参与选路：`model` 对应的逻辑模型路由到谁，就由谁承接。\n  Seedance 在平台上由多家供应商共同承接，同一个逻辑模型的两次调用可能落到不同上游，这是正常的。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），Ark 路径下没有对应端点；\n  直接使用响应里的 `content.video_url` 即可。\n- 该模型是否开放本通道，取决于它在模型目录里声明的 `public_protocols` 是否含\n  `content_generation`；未声明则返回 `4005`。可用 `GET {{ api_endpoint }}/v1/models` 核对。\n\n如果你不需要 Ark 的路径与字段风格，[OpenAI 兼容视频流](./openai-compatible)是更标准化的选择。\n","international/zh/models/video/async-tasks.md":"---\ntitle: 通用异步内容生成任务\ndescription: 平台统一的异步任务入口，覆盖图像、视频等需要任务式处理的内容生成能力。\n---\n\n# 通用异步内容生成任务\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 创建通用异步内容生成任务（图像 / 视频等） |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 轮询通用内容生成任务状态与结果 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见[Seedance 视频入站协议](./ark)的「取消任务」） |\n\n`/v1/content_generation/tasks` 是比标准 OpenAI 视频流更通用的异步任务入口，覆盖图像、视频等需要后台任务执行的生成能力。\n\n## 创建任务\n\n请求体遵循对应上游的通用生成格式，至少需要 `model`：\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\n2026-09-10 国内生产：创建返回 `status=queued`、`id` 形如 `gw_…`；轮询同一 `id` 最终为 `succeeded`，并带 `resolution=720p`、`ratio=16:9`、`duration=5`。同一模型打 `POST /v1/video/generations` 为 `model_protocol_not_offered`。`DELETE` 取消在该上游上返回 `provider_unsupported`。\n\n## 轮询任务\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与轮询都返回**同一种** Ark 形态的任务对象，不随实际承接的上游变化：\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` 取值为 `queued` / `running` / `succeeded` / `failed`；`id` 是**网关任务 ID**，轮询与取消都只认它。\n\n## 三种拼法，同一条流水线\n\n同一条托管异步流水线有三个入站拼写，选哪个只取决于你想按谁的报文风格写客户端：\n\n| 入口 | 请求体 | 响应体 |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | 通用生成格式 | Ark 任务对象（上表） |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark 内容生成原生体 | Ark 任务对象 |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax 视频生成 V2 原生体 | MiniMax 形态（`{\"task_id\"}` / `{\"task\":{…}}`） |\n\n三者的计费、任务落库、产物持久化与预扣/结算行为完全一致。\n\n## 适用场景\n\n- 你要调用的平台能力本身是异步任务，但不走 OpenAI Video 标准形态\n- 你希望统一使用平台托管的「创建任务 → 轮询结果」模型，而不是自行管理厂商原生协议\n- 你调用的是即梦等仅提供托管异步入口的视频模型\n\n## 关键约定\n\n- `model` 仍填写平台逻辑模型名，由平台决定最终路由到哪个上游实现。\n- 请求体字段取决于路由到的具体能力；响应形态则是固定的，见上文。\n- 如果你不想自己处理厂商侧的多种原生轮询协议，优先使用这一入口。\n\n如需标准 OpenAI 视频协议，见[OpenAI 兼容视频流](./openai-compatible)。\n","international/zh/models/video/minimax.md":"---\ntitle: MiniMax 视频入站协议\ndescription: 用 MiniMax 视频生成 V2 的原厂请求体与响应体调用平台托管的异步视频任务，适用于 MiniMax-H3 系列。\n---\n\n# MiniMax 视频入站协议\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | 创建视频生成任务 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 取消未完成的任务并退回预扣 |\n\n这是 **MiniMax 视频生成 V2** 的原厂入站协议，主要面向 MiniMax-H3 系列视频模型。和 Ark 通道一样，\n它跑在平台托管的异步任务流水线上——请求体是 MiniMax 自己的形状，**响应体也按 MiniMax 的形状渲染**，\n所以照着 MiniMax 官方文档写的客户端可以直接解析。\n\n任务落在平台侧，维度计费、产物持久化、预扣/结算都照常生效。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一个男孩在海边打篮球\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\n创建响应就是 MiniMax 文档里的裸任务句柄：\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### 请求体字段\n\n`content[]` 是多模态数组，每项由 `type` 与 `role` 共同决定它的用途：\n\n| `type` | 可用 `role` | 含义 |\n| --- | --- | --- |\n| `text` | —— | 提示词 |\n| `image_url` | `first_frame` / `last_frame` | 首帧 / 尾帧图 |\n| `image_url` | `reference_image` | 参考图 |\n| `video_url` | `reference_video` | 参考视频 |\n| `audio_url` | `reference_audio` | 参考音频 |\n\n- **首尾帧与参考素材不能混用**：带了 `first_frame` / `last_frame` 就不能再带任何 `reference_*`，\n  反之亦然——它们对应上游两种不同的生成任务。\n- `resolution`、`duration`、`ratio` 与 `content` 平级。对 MiniMax-H3，取值范围为\n  `resolution` ∈ `768P` / `2K`，`duration` 为 `4`–`15` 的整数，`ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`；不传时按上游缺省（`2K`、`5` 秒）执行**并按该缺省档计费**。\n- 提示词长度上限约 7000 字符。\n- 具体支持哪些取值仍以 `model` 对应的逻辑模型配置为准。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n查询响应是 `task` 信封，与创建响应**形状不同**：\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` 取值为 `queued` / `running` / `succeeded` / `failed`。\n- 成功后产物地址在 `task.content.url`。\n- `usage` 以**秒**计量（H3 按输出秒数定价），不是 token 数；上游只报告 token 而没有秒数时该字段缺省。\n- 失败时追加 `task.error`（`code` / `message`）。这一项不在 MiniMax 官方成功响应结构里，\n  是为了让失败原因可见而额外补上的，按官方结构解析的客户端会自然忽略它。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消后预扣退回。注意本通道**不会**返回 MiniMax 文档中的 `cancelled` 状态——已取消的任务统一以\n`failed` 呈现，以保证预扣被退回而不是结算。\n\n## 关键约定\n\n- **`id` / `task_id` 都是网关任务 ID**，不是上游任务 ID；查询与取消只认它。\n- 该通道不锁定上游 family，由 `model` 对应逻辑模型的路由决定实际承接方，路径拼写不参与选路。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），MiniMax 路径下没有对应端点。\n\n标准化入口见[OpenAI 兼容视频流](./openai-compatible)。\n","international/zh/models/video/openai-compatible.md":"---\ntitle: OpenAI 兼容视频流\ndescription: 标准 OpenAI Video 兼容接口，包括创建任务、轮询状态与拉取产物内容。\n---\n\n# OpenAI 兼容视频流\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | 创建 OpenAI 兼容视频任务 |\n| `GET` | `/v1/videos/{task_id}` | 轮询视频任务状态与结果 |\n| `GET` | `/v1/videos/{task_id}/content` | 拉取已完成视频任务的产物内容 |\n\n这组接口是平台定义的**标准视频协议**：请求体使用 OpenAI Video 兼容字段，平台负责识别并转换成对应上游的视频异步任务格式。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\n创建成功后返回 `task_id`。后续轮询与产物拉取都围绕该 `task_id` 进行。\n\n## 轮询任务状态\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` 取值为 `queued` / `in_progress` / `completed` / `failed`；为 `completed` 时，`metadata.url` 中会给出产物地址。\n\n## 拉取产物内容\n\n任务完成后，也可以通过内容接口直接拿视频文件。该接口由网关**直接回传 `video/mp4` 字节流**（不再 `302` 跳转到对象存储），支持 `Range` 断点续传，且只有任务所属 API Key（或同租户控制台登录态）可访问：\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\n内容接口的可用性取决于后台「媒体交付」配置：\n\n- 未启用时返回 `404`（`content_delivery_disabled`）\n- 任务尚未完成时返回 `409`（`task_not_completed`）\n- 产物已过期或不存在时返回 `404`（`content_not_available`）\n\n## 关键约定\n\n- 这是标准 OpenAI 兼容视频入口，客户端不需要理解厂商原生协议。\n- 是否支持 `duration`、`size` 等字段，以及最终落到哪个上游，取决于 `model` 对应的逻辑模型配置。\n- 视频任务属于异步模型，轮询时请带退避，避免高频请求触发限流。\n\n如需更通用的异步任务入口，见[通用异步内容生成任务](./async-tasks)；想按厂商原厂报文书写、但仍要平台托管的计费与任务管理，见[Seedance 视频入站协议](./ark)与[MiniMax 视频入站协议](./minimax)。\n","international/zh/quickstart/agent-clients.md":"---\ntitle: AI 工具接入\ndescription: 选择 AI 客户端或 Agent，通过 ModelGo 调用模型。\n---\n\n# AI 工具接入\n\nModelGo 支持常用的 AI 编程客户端和 Agent。创建 API Key 后，推荐使用 ModelGo CLI 自动完成接入；未接入 CLI 的客户端可通过自定义 Provider 手动配置。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n运行后选择一个或多个工具；如需自动化配置全部支持的工具，可使用：\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n## 支持的 AI 工具\n\n:::agent-tools\n| 工具 | ModelGo CLI自动接入 | 手动接入文档 |\n| --- | --- | --- |\n| Hermes Agent | 支持 | [接入文档](../agents/hermes-agent) |\n| Claude Code | 支持 | [接入文档](../agents/claude-code) |\n| Kilo Code | 暂不支持 | [接入文档](../agents/kilo-code) |\n| Cline | 暂不支持 | [接入文档](../agents/cline) |\n| Codex | 支持 | [接入文档](../agents/codex) |\n| OpenClaw | 支持 | [接入文档](../agents/openclaw) |\n| DeepSeek Harness | 暂不支持 | [接入文档](../agents/deepseek-harness) |\n| ZCode | 暂不支持 | [接入文档](../agents/zcode) |\n| Cursor | 暂不支持 | [接入文档](../agents/cursor) |\n| OpenCode | 支持 | [接入文档](../agents/opencode) |\n| CC Switch | 支持 | [接入文档](../agents/cc-switch) |\n| Cherry Studio | 暂不支持 | [接入文档](../agents/cherry-studio) |\n| Crush | 支持 | [接入文档](../agents/crush) |\n| Factory Droid | 支持 | [接入文档](../agents/factory-droid) |\n| Copilot CLI | 支持 | [接入文档](../agents/copilot-cli) |\n| nanobot | 支持 | [接入文档](../agents/nanobot) |\n| Oh My Pi | 支持 | [接入文档](../agents/oh-my-pi) |\n| CodeBuddy | 支持 | [接入文档](../agents/codebuddy) |\n| Kilo CLI | 暂不支持 | [接入文档](../agents/kilo-cli) |\n:::\n\n## 接入前准备\n\n1. 在[控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n2. 运行上方命令并选择需要接入的客户端或 Agent。\n3. 按终端提示确认站点、Base URL 和脱敏后的 API Key；配置工具会完成连通性验证。\n\n如果你希望用命令行管理 ModelGo 账户、模型、调用和 Skills，继续阅读[命令行工具](cli)。\n\n## 集成指南\n\n大多数工具只需要配置以下信息，即可连接 ModelGo：\n\n1. **API 地址**：OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`；Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n2. **API Key**：在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建的令牌。\n3. **模型名称**：在[模型广场]({{ site_endpoint }}/models)选择的逻辑模型名。\n\n具体配置步骤请参考上方各工具对应的接入文档。\n","international/zh/quickstart/authentication.md":"---\ntitle: 认证鉴权\ndescription: API Key 的获取、传递方式、优先级与常见认证失败处理。\n---\n\n# 认证鉴权\n\n所有模型调用接口都通过 API Key 认证。\n\n## 推荐请求头\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic 风格客户端也可使用：\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini 风格客户端也可使用：\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\n当多个头同时出现时，优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。\n\n## 获取与管理\n\n- 控制台：`{{ console_endpoint }}`\n- API Key 仅在创建时完整展示一次\n- 吊销或停用后会在鉴权缓存失效后生效\n\n## 认证失败\n\n常见错误：\n\n| HTTP | error_class | 说明 |\n| --- | --- | --- |\n| `401` | `auth` | 缺少、无效、停用或过期的 API Key |\n| `403` | `policy` | Key 有效，但不允许调用该模型或未绑定策略 |\n\n更多错误结构见[错误码与限流](errors)。\n","international/zh/quickstart/cli.md":"---\ntitle: 命令行工具\ndescription: 选择适合你的官方命令行工具，完成 ModelGo 配置。\n---\n\n# 命令行工具\n\nModelGo 提供两个官方命令行工具。选择你要完成的任务，运行对应命令即可开始。\n\n:::tools\n@model-go/config | 接入 AI 编程客户端 | 一条命令配置 Claude Code、Codex 等常用客户端。 | npx @model-go/config -r {{ region_flag }} | 查看 npm 包 | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | 使用官方 CLI | 配合官方 ModelGo Skills，让 AI Agent 直接操作 ModelGo。 | npx @model-go/cli@latest install | 查看 npm 包 | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## 接入 AI 编程客户端 `@model-go/config` {#connect-ai-clients}\n\n如果你想在 Claude Code、Codex、OpenCode 等 AI 编程客户端中使用 ModelGo，可以选择引导式配置，也可以通过一条命令完成全部客户端配置。\n\n**引导式配置**\n\n根据终端提示输入 API Key、选择客户端并预览配置，确认后自动写入并验证连接。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**一键式配置（非交互，适合自动化）**\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n### 支持的客户端\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\n引导式配置支持勾选一个或多个客户端；使用 `--only all` 可一次配置全部客户端。\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | 输入你的 [ModelGo API Key]({{ console_endpoint }}/api-keys)。 |\n| `02` | 勾选需要配置的客户端，也可以选择“全部配置”。 |\n| `03` | 预览站点、Base URL、脱敏后的 API Key 和目标客户端。 |\n| `04` | 确认后写入客户端配置，并自动验证连接。 |\n\n> **配置成功：** 终端会显示“配置完成”和“链路验证通过”，并给出启动所选客户端的命令。\n\n[查看 @model-go/config npm 包](https://www.npmjs.com/package/@model-go/config)\n\n## 让 AI Agent 操作 ModelGo `@model-go/cli` {#install-agent-tools}\n\n如果你希望 Claude Code、Codex 等 Agent 直接使用 ModelGo，安装官方 CLI 和 ModelGo Skills。安装向导会完成 CLI 设置、Skills 分发、站点选择和可选登录。\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | npm 首次运行时，确认安装 `@model-go/cli`。 |\n| `02` | 选择安装向导语言，支持中文和英文，后续安装提示将使用所选语言。 |\n| `03` | 安装或升级 ModelGo CLI，并安装 ModelGo Skills。 |\n| `04` | 在向导中选择当前站点环境（`{{ api_endpoint }}`）。 |\n| `05` | 选择是否立即通过浏览器登录；也可以跳过并稍后运行 `modelgo auth login`。 |\n\n### 安装后如何使用\n\n安装完成后，重新启动 AI Agent 或新建会话。ModelGo Skills 会让 AI Agent 直接调用 ModelGo CLI 完成查询和操作，你可以用自然语言向它提问，例如：\n\n- “当前 ModelGo 支持的模型有哪些？”\n- “当前 ModelGo 的账户余额还剩多少？”\n\n如果你希望自己在终端操作，输入 `modelgo` 即可查看全部可用命令和参数说明：\n\n```bash\nmodelgo\n```\n\n常用能力按使用场景分为以下几类：\n\n| 使用场景 | 常用命令 | 说明 |\n| --- | --- | --- |\n| 登录与身份 | `modelgo auth login`、`modelgo auth status`、`modelgo auth logout` | 登录 ModelGo、查看当前登录状态或清除本地登录信息。 |\n| 站点环境 | `modelgo env list`、`modelgo env current`、`modelgo env use <name>` | 查看可用环境、确认当前环境或切换站点；也可以通过 `env add` 和 `env remove` 管理自定义环境。 |\n| 工作空间 | `modelgo tenant list`、`modelgo tenant use <slug>` | 查看当前账号可用的工作空间，并通过工作空间 slug 或 ID 切换 CLI 后续操作使用的工作空间。 |\n| 账户与用量 | `modelgo balance`、`modelgo permissions`、`modelgo logs` | 查看余额和交易记录、账号权限、调用日志及用量统计。 |\n| 模型调用 | `modelgo models`、`modelgo chat`、`modelgo embeddings`、`modelgo call` | 查询可用模型，发起对话或向量请求，或直接调用任意 `/v1/*` 模型接口。 |\n| Key 与支付 | `modelgo key`、`modelgo pay` | 管理当前环境保存的模型 API Key，或管理 x402 按次支付配置。 |\n| CLI 维护 | `modelgo update`、`modelgo --version`、`modelgo --help` | 更新 CLI、查看版本或重新打开完整帮助。 |\n\n需要查看某个命令的参数时，运行 `modelgo <command> --help`。对于 `balance`、`permissions` 和 `logs`，还可以使用全局参数 `--tenant <slug\\|id>` 临时指定本次查询的工作空间。\n\n[查看 @model-go/cli npm 包](https://www.npmjs.com/package/@model-go/cli)\n\n:::note 安全提示\n- 推荐通过交互提示输入 API Key，不要把 Key 直接写进命令。\n- 不要把 API Key 提交到代码仓库或粘贴到共享脚本。\n- 如果安装 CLI 时跳过登录，稍后运行 `modelgo auth login`。\n:::\n\n## 继续探索\n\n- [首次调用](quickstart)：发起第一次模型调用。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n","international/zh/quickstart/errors.md":"---\ntitle: 错误码与限流\ndescription: 统一错误结构、常见错误分类与限流处理建议。\n---\n\n# 错误码与限流\n\n## 错误响应结构\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\n错误响应体除了 `error` 对象外，还带一个与 `X-Trace-ID` 响应头一致的顶层 `trace_id` 字段（链路追踪关闭时省略），便于按日志检索。`metadata.reason` 是可选细分原因（例如 `model_not_in_catalog`）。完整清单与已验证示例见[接口清单](openapi)。\n\n## 常见错误分类\n\n| error_class | HTTP | 含义 |\n| --- | --- | --- |\n| `client_invalid` | 400 | 请求格式或参数无效 |\n| `model_protocol_not_offered` | 400 | 该逻辑模型未声明当前入口对应的 `public_protocols`（`app_error_id=4005`）。换入口或换模型，不要改写请求体撞协议 |\n| `provider_invalid` | 400 | 上游拒绝请求（上游返回非 401/403/408/429 的 4xx） |\n| `provider_unsupported` | 400 | 上游不支持该接口（例如部分视频模型不支持 `DELETE` 取消） |\n| `provider_timeout` | 408 | 上游请求超时 |\n| `auth` | 401 | API Key 认证失败 |\n| `billing_insufficient` | 402 | 余额不足 |\n| `policy` | 403 | 无权调用该模型或未绑定策略 |\n| `quota` | 429 | 触发平台配额或限流 |\n| `provider_rate_limit` | 429 | 上游触发限流（上游返回 429） |\n| `gateway_internal` | 500 | 网关内部错误（兜底分类） |\n| `billing_system` | 502 | 计费系统不可用 |\n| `provider_server` | 502 | 上游服务错误 |\n| `provider_unauthorized` | 502 | 上游凭证被拒（统一归为 5xx，不向调用方暴露上游 Key 问题） |\n| `provider_unavailable` | 503 | 无可用模型供应方 |\n| `route_unconfigured` | 503 | 模型路由未配置上游 |\n\n## 失败请求的计费规则\n\n- 预扣：每次请求受理后按预估用量冻结余额，请求结束后按实际用量结算，多冻结的部分立即释放。\n- 成功请求与已交付部分内容的流式请求：按实际返回的用量结算。\n- **请求已发往上游供应方但最终失败**（上游 4xx/5xx、上游超时、流中途断开，以及客户端在等待响应期间主动断开）：按本次请求的预扣金额结算，不再退回。上游供应方对这类请求已产生实际成本，平台按预扣口径承担并向调用方收取。\n- 请求尚未发往上游即被平台拒绝（参数校验、鉴权、策略、配额、余额不足、网关内部错误）：预扣全额释放，不产生费用。\n- 结算依据可在控制台用量明细的交易记录中查看，按预扣结算的记录会标注失败原因。\n\n## 排障建议\n\n- 保留响应头中的 `X-Request-ID` 与 `X-Trace-ID`；错误响应体也会带同值的顶层 `trace_id` 字段\n- 遇到 `429` 时结合 `Retry-After` 响应头做退避重试（平台限流命中时会下发该头）\n- 流式请求若收到带 `error` 字段的数据块，应按失败处理（此类流中断对应 `provider_stream_broken`，不会再以独立的 HTTP 状态码返回）\n\n能力接口的细节见：\n\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n","international/zh/quickstart/openapi.md":"---\ntitle: 接口清单\ndescription: 客户模型调用面的全量 OpenAPI 清单、鉴权、协议匹配规则与已验证示例。\n---\n\n# 接口清单\n\n本页列出当前对外开放的模型调用 HTTP 接口（`mgk_` API Key，网关 `{{ api_endpoint }}`）。\n\n## 接入前置\n\n1. 在 `{{ console_endpoint }}` 创建 API Key（`mgk_` 前缀），完整明文只展示一次。\n2. `export MODELGO_API_KEY=\"你的-API-Key\"`。\n3. 调用 `GET /v1/models` 确认该 Key 能用的**逻辑模型名**。\n4. 选接口前先确认该模型是否声明了对应协议：打到模型未提供的入口，网关返回 HTTP 400、`error_class=model_protocol_not_offered`（`app_error_id=4005`），而不是帮你改写成别的协议。\n\n## 鉴权\n\n所有下列接口都用同一套 API Key：\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic 客户端可用 `x-api-key`，Gemini 客户端可用 `x-goog-api-key`。多头同时出现时优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。详见[认证鉴权](authentication)。\n\n缺 Key 或 Key 无效时的真实响应（HTTP 401）：\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\n排障请同时保留响应头 `X-Request-ID`、`X-Trace-ID` 与 body 里的 `trace_id`。\n\n## 协议匹配（必读）\n\n平台按模型目录里的 `public_protocols` 决定一个逻辑模型能打哪些入口。文档里的 curl **不能**对任意模型复制粘贴。\n\n| 模型 | 入口 | 结果 |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`、`POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings/multimodal` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`、`POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations`（`size` 至少约 1920×1920） | 200 |\n\n## 全量清单\n\n状态含义：\n\n- **正式对外**：网关已挂载，客户可调；能否对某个模型调通，仍取决于该模型的 `public_protocols` 与 Key 策略。\n- **正式对外 / 别名**：与上一行行为相同。\n\n### 文本与模型目录\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | 正式对外 | 列出当前 Key 策略允许的逻辑模型 |\n| `POST` | `/v1/responses` | 正式对外 | OpenAI Responses，新项目优先 |\n| `POST` | `/v1/chat/completions` | 正式对外 | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | 正式对外 | 旧版 Completions；多数对话模型未声明此协议 |\n| `POST` | `/v1/messages` | 正式对外 | Anthropic Messages |\n\n### 向量 / 图像 / 音频 / 重排\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | 正式对外 | 文本向量 |\n| `POST` | `/v1/embeddings/multimodal` | 正式对外 | 多模态向量；需模型声明对应协议 |\n| `POST` | `/v1/images/generations` | 正式对外 | 图像生成 |\n| `POST` | `/v1/images/edits` | 正式对外 | 图像编辑，`multipart/form-data` |\n| `POST` | `/v1/audio/speech` | 正式对外 | OpenAI TTS；**不是**所有语音模型都提供此协议 |\n| `POST` | `/minimax/v1/t2a_v2` | 正式对外 | MiniMax 原生同步语音合成，见[MiniMax 音频入站协议](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | 正式对外 | 语音转文本，multipart |\n| `POST` | `/v1/audio/translations` | 正式对外 | 语音翻译，multipart |\n| `POST` | `/v1/rerank` | 正式对外 | 重排序 |\n| `POST` | `/v1/reranks` | 正式对外 / 别名 | 与 `/v1/rerank` 等价 |\n\n### 视频与异步任务（托管）\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 正式对外 | 通用异步任务创建 |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 取消；上游不支持时返回 `provider_unsupported` |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 正式对外 | 与上一组同一托管流水线，Ark 路径拼写 |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上轮询 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上取消 |\n| `POST` | `/minimax/v2/video_generation` | 正式对外 | MiniMax 视频 V2 托管入口，请求需带齐计费维度 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 取消 |\n| `POST` | `/v1/video/generations` | 正式对外 | OpenAI 兼容视频创建；需模型声明该协议 |\n| `GET` | `/v1/videos/{task_id}` | 正式对外 | 轮询 |\n| `GET` | `/v1/videos/{task_id}/content` | 正式对外 | 302 拉产物 |\n| `DELETE` | `/v1/videos/{task_id}` | 正式对外 | 取消 |\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n真实响应形态（条目已截断）：\n\n```json\n{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"claude-fable-5\",\n      \"object\": \"model\",\n      \"created\": 1735689600,\n      \"context_length\": 1000000,\n      \"input_modalities\": [\"file\", \"image\", \"text\"],\n      \"output_modalities\": [\"text\"]\n    }\n  ]\n}\n```\n\n`id` 就是请求里的 `model`。清单**不包含** `public_protocols`；某个模型能不能打某个入口，以实际调用结果和控制台模型页为准。\n\n## 文本调用（已验证）\n\n### `POST /v1/chat/completions`\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}],\n    \"max_tokens\": 64\n  }'\n```\n\n成功时 HTTP 200，`object` 为 `chat.completion`，含 `choices[0].message` 与 `usage`。部分推理模型会额外返回 `reasoning_content`，且 `usage.completion_tokens` 可能远大于 `max_tokens`（实测 `max_tokens: 64` 时 completion 仍可达上千）。\n\n流式：同一路径加 `\"stream\": true`，响应 `Content-Type: text/event-stream`，每行 `data: {chunk}`，以 `data: [DONE]` 结束。\n\n空 body `{}` 的真实错误（HTTP 400）：\n\n```json\n{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"invalid request\",\n    \"metadata\": {\n      \"app_error_id\": 4001,\n      \"error_class\": \"client_invalid\",\n      \"request_id\": \"gw_a542461f-fe16-4f72-88d7-4c67b4bc9d7c\"\n    }\n  },\n  \"trace_id\": \"d6630b36c387a9e1e2d7bc9b6aa89020\"\n}\n```\n\n模型不在目录（HTTP 403）：\n\n```json\n{\n  \"error\": {\n    \"code\": 403,\n    \"message\": \"model is not registered or enabled in catalog\",\n    \"metadata\": {\n      \"app_error_id\": 4031,\n      \"error_class\": \"policy\",\n      \"reason\": \"model_not_in_catalog\",\n      \"request_id\": \"gw_ecc21066-c4a9-4eb1-97e7-799c4b1290\"\n    }\n  }\n}\n```\n\n### `POST /v1/responses`\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"input\": \"用一句话介绍 ModelGo。\",\n    \"max_output_tokens\": 64\n  }'\n```\n\n成功时 `object` 为 `response`，`output` 为数组（可能含 `reasoning` 与 `message`），并带 `output_text`。\n\n### `POST /v1/messages`\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"claude-fable-5\",\n    \"max_tokens\": 64,\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}]\n  }'\n```\n\n成功时 Anthropic 消息形态：`type: \"message\"`，`content[].type: \"text\"`。响应里的 `model` 可能是上游内部名（实测为 `pa/venus-cathedral-5`），与请求里的逻辑名不同，请以请求 `model` 和控制台为准。\n\n## 向量 / 图像 / 语音（已验证）\n\n### `POST /v1/embeddings`\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"text-embedding-3-small\",\"input\":\"hello ModelGo\"}'\n```\n\n成功：`data[0].embedding` 为浮点数组（`text-embedding-3-small` 实测维度 1536），`usage.prompt_tokens` 为计费 token。\n\n### `POST /v1/images/generations`\n\n`doubao-seedream-5.0-lite` 拒绝过小的 `size`。`1024x1024` 实测 HTTP 400、`error_class=provider_invalid`，上游要求像素总数至少 3686400（约 1920×1920）。用 `2048x2048` 可通过：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"a tiny red apple on white background, simple\",\n    \"size\": \"2048x2048\"\n  }'\n```\n\n成功响应含 `data[0].url`（对象存储地址，有时效）和 `usage.generated_images`。响应 `model` 可能是上游名（实测 `doubao-seedream-5-0-260128`）。\n\n### `POST /minimax/v1/t2a_v2`\n\n见[MiniMax 音频入站协议](../models/audio/minimax)。`speech-2.8-turbo` / `speech-2.8-hd` 当前声明的是这条 MiniMax 原生协议，不是 OpenAI `/v1/audio/speech`。\n\n## 异步视频（已验证）\n\nSeedance 类模型走托管异步任务，而不是 OpenAI `/v1/video/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedance-2.0-mini\",\n    \"content\": [{\"type\": \"text\", \"text\": \"a red apple on a table\"}]\n  }'\n```\n\n创建成功（HTTP 200）：\n\n```json\n{\n  \"id\": \"gw_c731f504-5a53-4e37-a972-30653a8ee390\",\n  \"model\": \"doubao-seedance-2.0-mini\",\n  \"status\": \"queued\",\n  \"created_at\": 1789012940,\n  \"error\": null\n}\n```\n\n同一 `id` 也可在 `GET /ark/api/v3/contents/generations/tasks/{id}` 轮询，状态会变为 `running`，完成后为 **`succeeded`**（实测 `resolution=720p`、`ratio=16:9`、`duration=5`）。`DELETE` 取消在该上游上实测返回 HTTP 400、`error_class=provider_unsupported`、`endpoint not supported by provider`——不要假设所有视频模型都支持取消。\n\n`POST /minimax/v2/video_generation` 若缺少计费维度，返回 HTTP 400、`client_invalid`（`billing_error_code=4223`）。按 MiniMax 视频文档补齐 `duration` / `resolution` 等字段后再试。\n\n## 流式约定\n\n- 文本流式接口（`/v1/chat/completions`、`/v1/responses`、`/v1/messages`）在请求体设 `stream: true`（Anthropic 为 `stream: true`）。\n- OpenAI 形态：`Content-Type: text/event-stream`，帧为 `data: <json>`，正常结束带 `data: [DONE]`。\n- Anthropic `/v1/messages` 保持原生 `event:` 帧，网关不会改写成 OpenAI SSE。\n- 流中若出现带 `error` 的数据块，按失败处理；此时可能没有独立的 HTTP 错误状态码。\n\n## 限流、超时、幂等、分页\n\n- 限流：HTTP 429，`error_class` 为 `quota` 或 `provider_rate_limit`；平台限流时会带 `Retry-After`。\n- 超时：客户端自行设置；上游超时为 `provider_timeout`（408）。\n- 幂等：同步文本/图像/语音请求没有客户侧幂等键。异步视频任务以返回的 `id` / `task_id` 为后续轮询主键；重复 POST 会再创建新任务。\n- 分页：模型调用面没有 cursor/page 列表接口。`GET /v1/models` 一次返回当前 Key 可见的全部逻辑模型。\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [错误码与限流](errors)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [MiniMax 音频入站协议](../models/audio/minimax)\n- [通用异步内容生成任务](../models/video/async-tasks)\n","international/zh/quickstart/overview.md":"---\ntitle: 平台概览\ndescription: ModelGo 模型网关的能力范围、兼容协议、接入地址与认证方式总览。\n---\n\n# 平台概览\n\n{{ platform_name }} 模型网关提供统一的模型调用入口，对外兼容 OpenAI 与 Anthropic 文本协议，并补齐图像、视频、向量和音频等能力页。客户端通常只需要替换 `base_url` 和 API Key，就能沿用现有 SDK 或 HTTP 调用逻辑。\n\n## 接入地址\n\n```text\n{{ api_endpoint }}/v1\n```\n\n控制台地址：\n\n```text\n{{ console_endpoint }}\n```\n\n## 当前公开能力\n\n| 一级分类 | 能力页 | 主要接口 |\n| --- | --- | --- |\n| 快速开始 | 平台概览 / 首次调用 / AI 工具接入 / 认证鉴权 / 错误码与限流 | 接入与排障说明 |\n| 模型 / 文本 | 文本生成 | `POST /v1/responses` `POST /v1/chat/completions` `POST /v1/completions` `POST /v1/messages` `GET /v1/models` |\n| 模型 / 图像 | 图像生成 / 图像编辑 | `POST /v1/images/generations` `POST /v1/images/edits` |\n| 模型 / 视频 | OpenAI 兼容视频流 / 通用异步内容生成任务 / Seedance 与 MiniMax 入站 | `POST /v1/video/generations` `GET /v1/videos/{task_id}` `GET /v1/videos/{task_id}/content` `POST /v1/content_generation/tasks` `GET /v1/content_generation/tasks/{task_id}` |\n| 模型 / 向量 | Embeddings | `POST /v1/embeddings` `POST /v1/embeddings/multimodal` |\n| 模型 / 音频 | 语音合成 / MiniMax 音频 / 语音转文本 / 语音翻译 | `POST /v1/audio/speech` `POST /minimax/v1/t2a_v2` `POST /v1/t2a_v2` `POST /v1/audio/transcriptions` `POST /v1/audio/translations` |\n| 模型 / 重排 | Rerank | `POST /v1/rerank` `POST /v1/reranks` |\n\n## 关键约定\n\n- `model` 必须填写平台逻辑模型名，而不是上游厂商原始模型 ID。\n- 平台提供 `GET /v1/models` 查询入口，返回的清单由该 API Key 绑定的策略所允许的逻辑模型（结合平台模型目录）决定，并非实时探测上游能力，最终以控制台模型页与策略配置为准。\n- 流式文本接口通过 SSE 返回，以 `data: [DONE]` 结束。\n- 视频 / 异步内容生成走异步任务模型，创建任务后需按 `task_id` 轮询。\n- 错误响应使用统一结构，排障时请保留 `X-Request-ID`。\n\n## 下一步\n\n- [首次调用](quickstart)\n- [接口清单](openapi)\n- [认证鉴权](authentication)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n- [MiniMax 音频](../models/audio/minimax)\n- [Rerank](../models/rerank/rerank)\n- [错误码与限流](errors)\n","international/zh/quickstart/quickstart.md":"---\ntitle: 首次调用\ndescription: 获取 API Key、确认模型名并完成第一次调用。\n---\n\n# 首次调用\n\n你可以复用现有 OpenAI 或 Anthropic SDK 接入 ModelGo，也可以按下面三步完成第一次 Responses API 调用。\n\n## 使用标准协议接入\n\nModelGo 同时兼容 OpenAI 与 Anthropic 标准协议。如果项目已经使用对应 SDK，通常只需替换 Base URL 和 API Key，无需重写调用逻辑。\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## 三步完成第一次 API 调用\n\n如果是第一次接入 ModelGo，完成下面三步即可发起请求并获得生成结果。\n\n### 第 1 步：获取 API Key\n\n1. 登录控制台：`{{ console_endpoint }}`。\n2. 在「API Key」页面创建新的 Key。\n3. 使用环境变量注入：\n\n```bash\nexport MODELGO_API_KEY=\"你的-API-Key\"\n```\n\n### 第 2 步：确认模型名称\n\n请求中的 `model` 使用平台逻辑模型名。可调用 `GET /v1/models` 查询当前可用的逻辑模型清单，返回结果由该 API Key 绑定的策略所允许的逻辑模型（结合平台模型目录）决定，请以[模型广场]({{ site_endpoint }}/models)和已绑定策略为准。\n\n### 第 3 步：发起第一次调用\n\n推荐把第一次调用落在 `POST /v1/responses`：\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"用三句话介绍 ModelGo。\"\n  }'\n```\n\n如果你已经接入旧版 OpenAI Chat Completions SDK，也可以继续调用 `POST /v1/chat/completions`：\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"messages\": [\n      {\"role\": \"system\", \"content\": \"你是一个简洁的助手。\"},\n      {\"role\": \"user\", \"content\": \"用三句话介绍 ModelGo。\"}\n    ]\n  }'\n```\n\nPython（OpenAI SDK，推荐走 Responses）：\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"用三句话介绍 ModelGo。\",\n)\n\nprint(response.output_text)\n```\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [文本生成](../models/text/generation)\n- [错误码与限流](errors)\n"}
+export const DOCS_PAGES = {"china/en/about/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [Quickstart](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","china/en/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: Configure CC Switch and Claude Code with ModelGo.\n---\n\n# CC Switch\n\nCC Switch is a desktop provider manager for Claude Code, Codex, Gemini, OpenCode, OpenClaw, and more. This guide uses Claude Code as an example and shows how to add and enable ModelGo.\n\n## Before you start\n\n- Install [CC Switch](https://github.com/farion1231/cc-switch/releases) and make sure it opens normally.\n- Install Claude Code and launch it at least once.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open the Claude Code configuration\n\nOpen CC Switch, select **Claude** at the top, and click **+** to add a configuration.\n\n![CC Switch overview](/images/agents/cc-switch/overview.webp)\n\n![Add a Claude configuration in CC Switch](/images/agents/cc-switch/claude-add.webp)\n\n## 2. Add a ModelGo provider\n\nPaste the following JSON into the configuration editor. Replace `your-model-id` with a logical model name from the model catalog and `sk-your-token` with your ModelGo API key:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-your-token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"your-model-id\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"your-model-id\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![Edit the ModelGo configuration in CC Switch](/images/agents/cc-switch/config-cn.webp)\n\nIf your CC Switch version supports environment placeholders, you can use `{env:MODELGO_API_KEY}` for the token and set it in the terminal where you start Claude Code:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | API key created in the ModelGo console |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A logical model name from the model catalog |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable logical model name |\n\n:::note\n- Use the ModelGo root URL for the Anthropic base URL. Do not append `/v1/messages`; Claude Code adds that path.\n- Keep the API key in the local CC Switch configuration or an environment variable. Do not commit it to a repository.\n- Name the provider **ModelGo** so it is easy to identify and switch later.\n:::\n\n## 3. Save and enable the provider\n\nSet the provider name to **ModelGo**, then click **Add** or **Save**. Return to the Claude configuration list and enable the ModelGo entry.\n\n![Add the ModelGo provider in CC Switch](/images/agents/cc-switch/provider-cn.webp)\n\n![Enable the ModelGo profile in CC Switch](/images/agents/cc-switch/use-cn.webp)\n\nStart Claude Code:\n\n```bash\nclaude\n```\n\nEnter a simple task such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n## 4. Verify the configuration\n\nTo verify the API key and model access separately:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse an `id` from the response as the logical model name for `ANTHROPIC_MODEL` and `ANTHROPIC_SMALL_FAST_MODEL`.\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nConfirm that the token is a valid ModelGo API key and that the CC Switch profile does not contain an old token. Remove extra spaces or line breaks.\n\n### 404 or endpoint errors\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`. Do not use `{{ api_endpoint }}/v1/messages` or a full request path.\n\n### Model unavailable\n\nMake sure the model name exactly matches a logical model in the [model catalog]({{ site_endpoint }}/models) and is enabled for the API key.\n\n### Claude Code still uses the old profile\n\nConfirm that the ModelGo profile is enabled in CC Switch. Fully restart the terminal, then run `claude` again.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [CC Switch Quick Start](https://cc-switch.cc/docs/getting-started/quick-start/): learn the interface and profile switching flow.\n- [CC Switch Provider Setup](https://cc-switch.cc/en/tutorials/provider-setup): learn custom provider fields and credential management.\n","china/en/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: Connect Cherry Studio to ModelGo through a custom provider.\n---\n\n# Cherry Studio\n\nCherry Studio includes several built-in providers, but ModelGo is not one of them. Use Cherry Studio's **Custom Provider** flow to create a ModelGo provider, then fetch and add the models you need. ModelGo exposes both OpenAI-compatible and Anthropic-compatible endpoints.\n\n## Prerequisites\n\n- Cherry Studio is installed and you can open its Settings page.\n- You have created or copied an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- You have confirmed the logical model ID to use in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open model service settings\n\nOpen Cherry Studio **Settings**, go to **Model Services**, and click **+ Add Provider** at the bottom of the provider list.\n\n![Open the provider picker in Cherry Studio](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. Add a custom provider\n\nIn the **Add Custom Provider** dialog, enter:\n\n| Setting | Value for ModelGo |\n| --- | --- |\n| Provider name | `ModelGo` |\n| API key | The API key created in the ModelGo console |\n| OpenAI endpoint | `{{ api_endpoint }}/v1` |\n| Anthropic endpoint | `{{ api_endpoint }}` (only for Anthropic-compatible models or Agent mode) |\n\nClick **Add** to save the provider. Use the OpenAI endpoint for regular chats and model discovery. Do not append `/v1` to the Anthropic endpoint; Cherry Studio builds the protocol path for you.\n\n![Add the ModelGo custom provider](/images/agents/cherry-studio/custom-provider.webp)\n\n:::note\n- Do not enter a full `/chat/completions` or `/messages` URL.\n- Use `{{ api_endpoint }}/v1` for OpenAI-compatible requests and `{{ api_endpoint }}` for Anthropic-compatible requests.\n:::\n\n## 3. Fetch and add models\n\nReturn to the ModelGo provider page and click **Get Models**. Cherry Studio reads the logical models available to the current API key.\n\n![Fetch ModelGo models in Cherry Studio](/images/agents/cherry-studio/fetch-models.webp)\n\nIn the model picker, click **+** next to individual models or choose **Add All Models**.\n\n![Add all ModelGo models in Cherry Studio](/images/agents/cherry-studio/model-picker.webp)\n\nAdded models appear in the ModelGo provider's model section. Adding only the models you use keeps the model picker easier to navigate.\n\n![ModelGo models in the provider list](/images/agents/cherry-studio/model-list.webp)\n\n## 4. Enable the provider and start chatting\n\nTurn on the switch in the upper-right corner of the ModelGo provider page and run the API key check. Start a new chat, select **ModelGo** and one of the models you added, then send a short message.\n\nFor OpenAI-compatible models, the OpenAI endpoint is enough. For Claude or Cherry Studio Agent mode, configure the Anthropic endpoint and add an Anthropic-compatible model as well.\n\n## Verify the configuration\n\nYou can verify model discovery from a terminal:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical ModelGo model IDs to add in Cherry Studio.\n\n## Troubleshooting\n\n### 401 or authentication failure\n\nCheck that the API key was copied in full with no extra spaces, and that the provider switch is enabled.\n\n### 404 or an invalid endpoint path\n\nSet the OpenAI endpoint to `{{ api_endpoint }}/v1` and the Anthropic endpoint to `{{ api_endpoint }}`. Do not enter the complete `/v1/chat/completions` or `/v1/messages` path.\n\n### The model list is empty\n\nFirst verify `/v1/models` with the `curl` command above, then confirm the model is enabled for your API key in the model catalog. After fetching, click **+** or **Add All Models**; fetching alone does not add models to the picker.\n\n### Agent mode cannot send a request\n\nSet the Anthropic endpoint to `{{ api_endpoint }}` and add a model that supports the Anthropic-compatible protocol. The Anthropic endpoint is not required for ordinary OpenAI-compatible chats.\n\n## Related documentation\n\n- [First call](../quickstart/quickstart): Create an API key, inspect models, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): Learn how to keep API keys safe.\n- [Cherry Studio custom providers](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang): Follow Cherry Studio's official custom-provider flow.\n- [Cherry Studio provider settings](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers): Learn how Base URLs, model management, and connection checks work.\n","china/en/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: Configure Claude Code with ModelGo's Anthropic-compatible API.\n---\n\n# Claude Code\n\nClaude Code is a terminal-based AI coding assistant. Configure its Anthropic-compatible endpoint to use ModelGo models and API keys.\n\n## Before you start\n\n- Install Node.js.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Claude Code\n\nRun:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nVerify the installation:\n\n```bash\nclaude --version\n```\n\n## 2. Configure ModelGo\n\n### macOS / Linux\n\nCreate and edit the Claude Code settings file:\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\nRun these commands in PowerShell:\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\nPaste the following into `settings.json`. Replace `YOUR_MODELGO_API_KEY` and `YOUR_MODELGO_MODEL` with a real ModelGo API key and logical model name:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\nUse the ModelGo root URL for `ANTHROPIC_BASE_URL`; do not append `/v1/messages`. Claude Code adds the path and calls ModelGo's `POST /v1/messages` endpoint.\n\n:::note\n- If you use one model only, set all five model variables to the same ModelGo logical model so an unavailable auxiliary model does not prevent startup.\n- Keep the API key in your local settings. Do not commit `settings.json` or share it with others.\n:::\n\n## 3. Optional: skip official account onboarding\n\nIf the first `claude` launch stops at the official account login flow, create `.claude.json` in your user directory with the completed-onboarding flag.\n\nmacOS / Linux:\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell:\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. Start Claude Code\n\nChange to your project directory and start Claude Code:\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\nOn the first visit, choose **Trust This Folder** to allow Claude Code to access project files. Send a simple coding request; a normal response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A ModelGo logical model name |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The same callable ModelGo logical model name |\n\nFind a model in the [Model Gallery]({{ site_endpoint }}/models), or query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that `ANTHROPIC_AUTH_TOKEN` is a valid ModelGo API key and contains no extra spaces.\n\n### 403 or model unavailable\n\nMake sure all five model variables use ModelGo logical model names allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`, not `{{ api_endpoint }}/v1/messages`; Claude Code adds `/v1/messages` itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code): see the latest installation and configuration guidance.\n","china/en/agents/cline.md":"---\ntitle: Cline\ndescription: Configure Cline with ModelGo's OpenAI-compatible API.\n---\n\n# Cline\n\nCline is an AI coding assistant for VS Code. Select the `OpenAI Compatible` provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install VS Code.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cline\n\nOpen the VS Code Extensions marketplace, search for **Cline**, and install the extension.\n\n![Install Cline from the VS Code Extensions marketplace](/images/agents/cline/cline-market.webp)\n\n## 2. Configure ModelGo\n\nAfter installation, click the Cline icon in the VS Code activity bar and open **API Configuration**.\n\n![Open Cline API Configuration](/images/agents/cline/cline-config-cn.webp)\n\nFill in the following values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | Your ModelGo API key |\n| Model ID | A ModelGo logical model name |\n\nClick **Done** to save.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL. Do not include `/chat/completions`; Cline appends the endpoint path.\n- Use a logical model name available to the current API key in the Model Catalog rather than copying the example from the screenshot.\n- Keep the API key in your local Cline settings. Do not commit it or share screenshots containing it.\n:::\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. Start using Cline\n\nOpen the Cline panel and send a simple coding request, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Complete a conversation in Cline](/images/agents/cline/cline-chat.webp)\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in the API Key field.\n\n### 403 or model unavailable\n\nMake sure Model ID is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`; do not paste a full `/chat/completions` URL.\n\n### The model list is empty\n\nRequest `GET {{ api_endpoint }}/v1/models` to verify the endpoint. If Cline does not show the model in its list, enter Model ID manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Cline OpenAI Compatible docs](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx): see Cline's official provider configuration guidance.\n","china/en/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: Connect CodeBuddy to ModelGo.\n---\n\n# CodeBuddy\n\nCodeBuddy Code is Tencent Cloud's terminal coding assistant. Environment variables override its API endpoint, key, and model so requests can use ModelGo.\n\n## Prerequisites\n\n- Node.js 18+ and CodeBuddy CLI are installed; `codebuddy --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. Configure ModelGo variables\n\nSet these variables in the shell that starts CodeBuddy:\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-your-token\"\nexport CODEBUDDY_MODEL=\"your-model-id\"\n```\n\n`CODEBUDDY_AUTH_TOKEN` is CodeBuddy platform login, not the ModelGo model key.\n\n:::note\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Non-interactive `codebuddy -p` requires `CODEBUDDY_API_KEY`.\n- Keep keys and model IDs in a local profile or secret manager.\n:::\n\n## 3. Start and verify\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\ncodebuddy -p \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### CodeBuddy still uses its default model\n\nConfirm variables are visible in the current shell, then fully restart `codebuddy`.\n\n### 401 or 404 responses\n\nCheck `CODEBUDDY_API_KEY`, `CODEBUDDY_MODEL`, and `CODEBUDDY_BASE_URL`; do not put a full endpoint path in the Base URL.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [CodeBuddy CLI quickstart](https://www.codebuddy.ai/docs/cli/quickstart): Review installation, login, and first run.\n- [CodeBuddy CLI environment variables](https://www.codebuddy.ai/docs/cli/env-vars): Review endpoint, key, and model variables.\n","china/en/agents/codex.md":"---\ntitle: Codex\ndescription: Configure Codex CLI with ModelGo's Responses API.\n---\n\n# Codex\n\nCodex is OpenAI's command-line AI coding assistant. With a custom `model_provider`, Codex CLI can send Responses API requests to ModelGo.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Codex\n\nRun this command in macOS, Linux, or Windows:\n\n```bash\nnpm install -g @openai/codex\n```\n\nVerify the installation:\n\n```bash\ncodex --version\n```\n\nIf Codex shows an upgrade prompt on first launch, choose **Skip** and finish the ModelGo setup first.\n\n![Skip the Codex upgrade prompt](/images/agents/codex/codex-start.webp)\n\n## 2. Configure ModelGo\n\nCodex reads its user-level model and provider settings from `~/.codex/config.toml`. Create the file first:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\nPaste the following into `config.toml`, replacing `YOUR_MODELGO_MODEL` with a logical model name allowed for the current API key:\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\nThe `base_url` is ModelGo's OpenAI-compatible API root. Codex appends `/v1/responses` when it sends a request.\n\n## 3. Set the API key\n\nStore your ModelGo API key in the `MODELGO_API_KEY` environment variable. Do not put the real key directly in `config.toml`.\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\nCheck that the variable is set without printing the key:\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- Keep `MODELGO_API_KEY` in your local environment. Do not commit it or share terminal screenshots containing it.\n- `model` must be a ModelGo logical model name. The `gpt-5.6-sol` shown in the screenshot is only an example; replace it with a model you can call.\n- `wire_api = \"responses\"` is required by current Codex configurations. Do not use the deprecated `wire_api = \"chat\"`.\n:::\n\n:::note Start a new conversation after changing the API key or endpoint\n- In a multi-turn conversation, Codex continues to send prior Responses context. That context may include encrypted reasoning data that can only be handled by the original upstream account.\n- If you change `MODELGO_API_KEY` or `base_url`, or a proxy or account pool routes the same conversation to another upstream account, start a new Codex conversation. Do not continue or resume the existing conversation, or the request may fail with `400 invalid_encrypted_content`.\n:::\n\n## 4. Start and verify\n\nChange to a local project directory and run:\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\nWhen Codex asks for permission to work in the project, trust the directory as appropriate. After the welcome screen appears, send a simple coding request such as “Describe this project in three sentences.”\n\n![Codex project welcome screen](/images/agents/codex/codex-skip.webp)\n\nA normal model response confirms that ModelGo is connected.\n\n![Start a conversation in Codex](/images/agents/codex/codex-chat.webp)\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### Provider not found at startup\n\nMake sure the file is the user-level `~/.codex/config.toml`, and that `model_provider = \"modelgo\"` matches `[model_providers.modelgo]`.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces or newlines.\n\n### 403 or model unavailable\n\nMake sure `model` is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `base_url` to `{{ api_endpoint }}/v1`. Do not include `/responses` or `/v1/responses`; Codex appends the path.\n\n### Chat wire API deprecation warning\n\nAdd `wire_api = \"responses\"` under `[model_providers.modelgo]`, then upgrade Codex CLI:\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### `400 invalid_encrypted_content`\n\nThis usually means the conversation contains encrypted context created by the original upstream account, but the current request was handled by a different upstream account.\n\nCheck whether the API key or Base URL changed, or whether a proxy or account pool switched upstream accounts. If a switch occurred, start a new conversation instead of continuing or resuming the existing one.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Codex configuration reference](https://developers.openai.com/codex/config-reference/): see current `config.toml` fields.\n","china/en/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: Connect Copilot CLI to ModelGo.\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI supports BYOK. Provider environment variables can route model requests to ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Copilot CLI is installed and `copilot --help` works.\n- GitHub/Copilot authentication is complete.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know a logical model ID that supports tool calling and streaming.\n\n## 1. Configure ModelGo BYOK\n\nSet these variables in the shell that starts Copilot CLI:\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"your-model-id\"\ncopilot\n```\n\nIf needed, define the key first:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nThe `openai` provider type targets OpenAI Chat Completions-compatible services.\n\n:::note\n- GitHub login and the ModelGo API key are separate credentials.\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Prefer a model with tool calling, streaming, and a large context window.\n:::\n\n## 2. Verify the model\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\nAsk Copilot CLI to perform a small read-only task, such as listing project entry points.\n\n## Troubleshooting\n\n### Copilot still uses its default model\n\nConfirm `COPILOT_MODEL` and `COPILOT_PROVIDER_BASE_URL` are visible in the current shell, then restart `copilot`.\n\n### 401, 404, or tool-call errors\n\nCheck the key, Base URL, and logical model ID. Choose a model with the required streaming and tool-calling capabilities.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models): Review provider variables and model requirements.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","china/en/agents/crush.md":"---\ntitle: Crush\ndescription: Connect Crush to ModelGo.\n---\n\n# Crush\n\nCrush is Charmbracelet's terminal coding agent. Its OpenAI-compatible provider support lets you route requests through ModelGo.\n\n## Prerequisites\n\n- Node.js 18+, Go, or Homebrew is available; `crush --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\nYou can also use `npm install -g @charmland/crush`, `go install github.com/charmbracelet/crush@latest`, or `winget install charmbracelet.crush` on Windows.\n\n## 2. Add a ModelGo provider\n\nCrush reads project `.crushrc`/`crushrc` files and the global `~/.config/crush/crushrc` (Windows: `%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`).\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/your-model-id --name \"your-model-id\"\n```\n\nReplace `your-model-id` with a ModelGo logical model ID.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL; do not append `/chat/completions`.\n- Keep the API key in `MODELGO_API_KEY` instead of committing it to a config file.\n- `modelgo/your-model-id` is Crush's provider/model identifier.\n:::\n\n## 3. Start and verify\n\n```bash\ncrush\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck the `crushrc` filename and path, then restart Crush. Project configuration takes precedence over global configuration.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is available in the same shell and that the Base URL is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n- [Crush repository](https://github.com/charmbracelet/crush): Read installation, provider, and command references.\n- [Crush config schema](https://github.com/charmbracelet/crush/blob/main/schema.json): Check `crushrc` fields.\n","china/en/agents/cursor.md":"---\ntitle: Cursor\ndescription: Configure Cursor with ModelGo's OpenAI-compatible API.\n---\n\n# Cursor\n\nCursor is an AI coding editor. With a custom OpenAI Base URL, Cursor can call ModelGo logical models.\n\n## Before you start\n\n- Install [Cursor](https://www.cursor.com/).\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cursor\n\nVisit the [Cursor website](https://www.cursor.com/) and download the build for your operating system.\n\n![Cursor download page](/images/agents/cursor/install.webp)\n\n## 2. Open Cursor model settings\n\nOpen Cursor settings and go to **Models**.\n\n![Open Models in Cursor Settings](/images/agents/cursor/settings.webp)\n\n## 3. Add and enable a model\n\nClick **Add model**, enter a logical model name from the [model catalog]({{ site_endpoint }}/models), and save it.\n\n![Add a model in Cursor](/images/agents/cursor/add-model.webp)\n\nIn **Model Names**, keep the models you want to use and disable the rest.\n\n![Enable the target model in Cursor](/images/agents/cursor/model-list.webp)\n\n## 4. Configure the ModelGo endpoint\n\nIn **Settings → Models → API Keys**, configure the OpenAI-compatible endpoint:\n\n| Setting | ModelGo value |\n| --- | --- |\n| OpenAI API Key | Your ModelGo API key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | A logical model name from the ModelGo catalog |\n\n![Configure the ModelGo endpoint in Cursor](/images/agents/cursor/config-cn.webp)\n\nIf your Cursor release uses the alternate settings layout, enter the same ModelGo values there.\n\n![Alternate Cursor settings layout](/images/agents/cursor/config-global.webp)\n\nClick **Verify** or **Save**. Cursor may use slightly different labels in different releases, but the API key, Base URL, and model name have the same meaning.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- Use a logical model name from the ModelGo catalog instead of copying the example in the screenshot.\n- If Verify fails, send a test message in chat or use the command below to check the endpoint and key.\n:::\n\n## 5. Test the connection\n\nReturn to the Cursor chat, select the model you added, and send a simple message. A normal response confirms the integration.\n\n![Test a ModelGo model in Cursor](/images/agents/cursor/chat.webp)\n\nYou can also list the models available to the API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nMake sure the API key is complete, has no extra spaces, and is entered in **OpenAI API Key**.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions` to it.\n\n### Verify fails or the model is unavailable\n\nCheck that the model name is a logical ModelGo model and that the model is enabled for the API key.\n\n### The chat returns no content\n\nRun `GET {{ api_endpoint }}/v1/models` to verify connectivity and the key, then confirm the target model is enabled in Model Names.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [Cursor documentation](https://docs.cursor.com/): see Cursor settings, models, and custom API configuration.\n","china/en/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: Configure DeepSeek Harness with ModelGo's OpenAI-compatible API.\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness (DSH) is an open-source agent framework from DeepSeek AI. It combines models, tools, filesystems, terminals, sessions, and a Web UI into a runnable agent. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22 or later.\n- Install pnpm 11 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start DeepSeek Harness\n\nThe current source-install path is:\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![Start DeepSeek Harness from source](/images/agents/deepseek-harness/install.webp)\n\nThe terminal prints the Web UI address. The default is `http://127.0.0.1:3080`; use the address printed by your terminal if the port is already in use.\n\nFor a quick preview, you can also run:\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. Configure ModelGo\n\nOpen the address printed by the terminal, click the sidebar button in the upper-left corner, and then click **Settings**.\n\n![Open DeepSeek Harness settings](/images/agents/deepseek-harness/settings.webp)\n\nSelect **Models** and click **Add custom provider**.\n\n![Add a custom provider](/images/agents/deepseek-harness/model-picker.webp)\n\nUse these values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider ID | `modelgo` |\n| Display name | `ModelGo` |\n| API URL | `{{ api_endpoint }}/v1` |\n| API protocol | `openai-completions` |\n| API key | ModelGo API key |\n| Model ID | A logical model name from the Model Catalog |\n| Display name | You can use the same value as the model ID |\n\n![Fill in the ModelGo custom provider](/images/agents/deepseek-harness/provider-config.webp)\n\nClick **Create provider** to save the configuration. Keep these points in mind:\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the API URL. Do not append `/chat/completions`; DSH builds the request path for the `openai-completions` protocol.\n- The model ID must be a logical ModelGo model name allowed by the API key. Do not copy the example model from the screenshot.\n- Keep the API key in your local configuration. Do not commit it or share it in screenshots.\n:::\n\n## 3. Start a session\n\nReturn to the main view, choose a workspace, and then select the ModelGo model you just added.\n\n![Select the ModelGo model](/images/agents/deepseek-harness/session.webp)\n\nSend a simple task such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### The Web UI does not open\n\nMake sure `pnpm dsh web` is still running and open the port printed by the terminal. The default is `3080`; DSH may choose another port when it is occupied.\n\n### 401 or authentication failed\n\nCheck that the API key is complete, has no extra spaces, and was created in the ModelGo Console.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet the API URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Select `openai-completions` as the API protocol.\n\n### The model list is empty\n\nCheck that a model ID is present and that the custom provider was saved. You can verify the ModelGo endpoint first:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [DeepSeek Harness official website](https://www.deepseek.com/harness/): see the latest installation and product information.\n- [DeepSeek Harness GitHub repository](https://github.com/deepseek-ai/deepseek-harness): view source and releases.\n","china/en/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: Connect Factory Droid to ModelGo.\n---\n\n# Factory Droid\n\nFactory Droid is Factory's terminal agent. Its BYOK custom model settings can point Droid at ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Node.js 18+ and the Droid CLI are installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\nInside Droid, `/settings` opens the settings screen.\n\n## 2. Configure a ModelGo custom model\n\nMerge this `customModels` entry into `~/.factory/settings.json` (Windows: `%USERPROFILE%\\\\.factory\\\\settings.json`):\n\n```json\n{\n  \"customModels\": [{\n    \"model\": \"your-model-id\",\n    \"displayName\": \"ModelGo / your-model-id\",\n    \"baseUrl\": \"{{ api_endpoint }}/v1\",\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"provider\": \"openai\"\n  }]\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nRestart Droid and choose the custom model from `/models` or the model picker.\n\n:::note\n- Set `baseUrl` to `{{ api_endpoint }}/v1`; do not add `/chat/completions`.\n- `model` must be a ModelGo logical model ID.\n- Merge `customModels` into the existing file so other settings remain intact.\n:::\n\n## 3. Verify a request\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"your-model-id\" \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### The model is not listed\n\nValidate the JSON, keep `customModels` at the top level, and fully restart Droid.\n\n### Authentication or endpoint errors\n\nCheck the environment variable in the shell that launches Droid and remove duplicate `/v1` or full paths from `baseUrl`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Factory Droid settings](https://docs.factory.ai/droid-cli/settings): Find `settings.json` and settings entry points.\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok): Review custom model fields.\n","china/en/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: Configure Hermes Agent with ModelGo's OpenAI-compatible API.\n---\n\n# Hermes Agent\n\nHermes Agent is a terminal-based AI agent. With a custom provider, Hermes can use ModelGo's OpenAI-compatible API to call models.\n\n## Before you start\n\n- Install Node.js 22 or newer.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm the ModelGo logical model name you want to use in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Hermes Agent\n\nmacOS or Linux:\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\nReopen your terminal and verify the installation:\n\n```bash\nhermes --version\n```\n\n## 2. Configure ModelGo\n\nPut your API key in an environment variable for the current shell. Never commit a real key to a repository or public script:\n\n```bash\nexport MODELGO_API_KEY=\"your-ModelGo-API-key\"\nexport MODELGO_MODEL=\"your-ModelGo-logical-model-name\"\n```\n\nIf you are not sure which model name to use, query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse `hermes config set` to create a custom provider. Replace `<model>` with a logical model name from the Model Gallery or the `GET /v1/models` response:\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\nIf your Hermes version includes the interactive setup wizard, you can run:\n\n```bash\nhermes model\n```\n\nChoose **Custom endpoint**, enter the ModelGo Base URL, API key, and model name, and select **Chat Completions** as the protocol.\n\n:::note\n- Some older Hermes releases label the Chat Completions protocol as `openai_messages`. If `chat_completions` is rejected, upgrade Hermes or select Chat Completions in the `hermes model` wizard.\n:::\n\n## 3. Check the configuration and start a session\n\nCheck the Hermes configuration:\n\n```bash\nhermes config check\n```\n\nStart Hermes after the check passes:\n\n```bash\nhermes\n```\n\nSend a message such as “Introduce ModelGo in three sentences.” A model response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API mode | `chat_completions` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model ID | A ModelGo logical model name, not the upstream provider's raw model ID |\n\nHermes stores non-sensitive settings in `~/.hermes/config.yaml` and API keys and other secrets in `~/.hermes/.env`. Do not share or commit files under `~/.hermes/` that contain credentials.\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nMake sure the API key is valid and has not been revoked or expired, then run:\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 403 or model unavailable\n\nCheck that `model.default` is a ModelGo logical model allowed by the policy attached to your API key.\n\n### 404 or endpoint not found\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions`; Hermes adds the request path itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs): see the latest installer, configuration, and CLI reference.\n","china/en/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: Connect Kilo CLI to ModelGo.\n---\n\n# Kilo CLI\n\nKilo CLI is a terminal coding agent with custom OpenAI-compatible providers. Because ModelGo CLI automation is not available for Kilo CLI, use `/connect` or a `kilo.jsonc` file.\n\n## Prerequisites\n\n- Node.js 18+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\nRun `kilo` in a project; `/connect` opens the interactive provider setup.\n\n## 2. Add a ModelGo provider\n\nCreate `kilo.jsonc` in the project root (or edit the global config):\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/your-model-id\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"ModelGo / your-model-id\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nAlternatively choose `/connect` → `OpenAI Compatible` and enter the same Base URL, key, and model ID.\n\n:::note\n- Use lowercase provider ID `modelgo`; select `modelgo/your-model-id`.\n- `baseURL` is `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- The model ID must match a ModelGo logical model.\n:::\n\n## 3. Verify the configuration\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck JSONC syntax, the provider ID, and the `model` path, then restart Kilo.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is exported and `baseURL` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Kilo CLI documentation](https://kilo.ai/docs/code-with-ai/platforms/cli): Review installation, `/connect`, and CLI commands.\n- [Kilo custom models](https://kilo.ai/docs/code-with-ai/agents/custom-models): Review OpenAI Compatible provider fields.\n","china/en/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: Configure Kilo Code with ModelGo's OpenAI-compatible API.\n---\n\n# Kilo Code\n\nKilo Code is an AI coding assistant for VS Code and JetBrains. Use its OpenAI-compatible provider to connect Kilo Code to ModelGo models and API keys.\n\n## Before you start\n\n- Install VS Code or a JetBrains IDE.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Kilo Code\n\n### VS Code\n\nOpen the VS Code Marketplace, search for **Kilo Code**, verify the publisher, and install the extension. Then open the Kilo Code panel from the activity bar.\n\n![Install Kilo Code from the VS Code Marketplace](/images/agents/kilo-code/vscode-market.webp)\n\nOn the first install, VS Code asks you to confirm the publisher. Verify that it is Kilo Code, then click **Trust Publisher & Install**.\n\n![Trust the Kilo Code publisher](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\nOpen Settings / Preferences → Plugins, search the Marketplace for **Kilo Code**, and install the plugin. Restart the IDE after installation so the plugin takes effect.\n\n![Install Kilo Code from the JetBrains Marketplace](/images/agents/kilo-code/jetbrains-market.webp)\n\nWhen installing a third-party plugin, JetBrains displays its plugin notice. Confirm it and click **Accept** to finish the installation.\n\n![Confirm the JetBrains third-party plugin notice](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. Configure ModelGo in VS Code\n\nOpen Kilo Code settings, go to **Providers**, select **OpenAI Compatible**, and enter:\n\nFrom the Kilo Code welcome screen, first choose **Bring my own Key**:\n\n![Choose Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model | A ModelGo logical model name |\n\n![Kilo Code VS Code configuration](/images/agents/kilo-code/vscode-config-cn.webp)\n\nAfter saving, Kilo Code attempts to load models from the compatible `/v1/models` endpoint. If the target model is not in the picker, choose **Use custom** and enter the logical model name from the Model Gallery.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append `/chat/completions`. Kilo Code adds the standard path when it sends a request.\n- The model shown in the screenshot is only an interface example. Replace it with a ModelGo logical model allowed for the API key.\n- Keep the API key in Kilo Code's local settings. Do not commit it to a repository or include it in screenshots.\n:::\n\n## 3. Configure ModelGo in JetBrains\n\nOpen Kilo Code settings, click **Bring my own Key**, select **OpenAI Compatible**, and use the same values as in VS Code:\n\n![Choose Bring my own Key in JetBrains](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**: `{{ api_endpoint }}/v1`\n2. **API key**: your ModelGo API key\n3. **Model**: a ModelGo logical model name\n4. Click **Save**.\n\n![ModelGo provider settings in JetBrains](/images/agents/kilo-code/jetbrains-config-cn.webp)\n\nIf the model picker is empty, verify that the Base URL is reachable, then choose the custom-model option and enter the logical model name manually.\n\n![Kilo Code completing a task in JetBrains](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. Verify the connection\n\nOpen a local project and send a simple coding request in the Kilo Code panel, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Kilo Code completing a coding task](/images/agents/kilo-code/vscode-start.webp)\n\nTo inspect the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in **API key**, not the Base URL field.\n\n### 403 or model unavailable\n\nMake sure **Model** is a logical model listed in the ModelGo Model Gallery and allowed by the policy attached to the API key. Do not use an upstream provider's raw model ID unless the gallery explicitly lists it.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Kilo Code appends the endpoint path when it sends the request.\n\n### The model picker is empty\n\nUse `GET {{ api_endpoint }}/v1/models` to check the API key and endpoint. If the endpoint works, choose **Use custom** and enter the logical model name manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Kilo Code documentation](https://kilo.ai/docs): see the latest extension installation and provider setup guidance.\n","china/en/agents/nanobot.md":"---\ntitle: nanobot\ndescription: Connect nanobot to ModelGo.\n---\n\n# nanobot\n\nnanobot is a lightweight terminal agent that configures providers and model presets in JSON. It can call ModelGo through its OpenAI-compatible API.\n\n## Prerequisites\n\n- Python 3.11+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\nThe default config is `~/.nanobot/config.json`.\n\n## 2. Configure a ModelGo provider\n\nMerge these fields into `~/.nanobot/config.json`:\n\n```json\n{\n  \"providers\": {\"modelgo\": {\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"apiBase\": \"{{ api_endpoint }}/v1\"\n  }},\n  \"modelPresets\": {\"ModelGo\": {\n    \"provider\": \"modelgo\",\n    \"model\": \"your-model-id\",\n    \"maxTokens\": 4096,\n    \"contextWindowTokens\": 65536,\n    \"temperature\": 0.1\n  }},\n  \"agents\": {\"defaults\": {\"modelPreset\": \"ModelGo\"}}\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nLeave `apiType` unset for a custom OpenAI-compatible endpoint.\n\n:::note\n- Preserve existing channels and tools fields when merging the JSON.\n- Keep the key in `MODELGO_API_KEY`, not in a committed config file.\n- The model must be a ModelGo logical model ID.\n:::\n\n## 3. Verify the connection\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### nanobot cannot find the model\n\nMake sure `modelPresets.ModelGo.provider` matches `providers.modelgo` and that the JSON is valid.\n\n### 401 or endpoint errors\n\nConfirm the key is exported and `apiBase` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [nanobot OpenAI-compatible provider guide](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md): Review the JSON configuration.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","china/en/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: Connect Oh My Pi to ModelGo.\n---\n\n# Oh My Pi\n\nOh My Pi (`omp`) is a terminal coding agent. Declare an OpenAI-compatible provider in `models.yml`, then select models as `provider-id/model-id`.\n\n## Prerequisites\n\n- Bun or the official installer is available.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux can also use the official installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. Add a ModelGo provider\n\nEdit `~/.omp/agent/models.yml`:\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: your-model-id\n        name: ModelGo / your-model-id\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` is the environment variable name:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\n:::note\n- Use `openai-completions` and `{{ api_endpoint }}/v1` for the endpoint.\n- Select models as `modelgo/your-model-id`.\n- Keep the real API key out of `models.yml` and source control.\n:::\n\n## 3. Select and verify\n\n```bash\nomp --list-models\nomp --model modelgo/your-model-id\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSend a small read-only task in the session.\n\n## Troubleshooting\n\n### ModelGo is missing from the model list\n\nCheck `~/.omp/agent/models.yml`, YAML indentation, and restart `omp`.\n\n### 401 or endpoint errors\n\nConfirm `MODELGO_API_KEY` is exported and `baseUrl` has no duplicate `/v1` or full endpoint path.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Oh My Pi providers](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md): Review provider, API, and key settings.\n- [Oh My Pi models](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md): Review model selection and `models.yml`.\n","china/en/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: Configure OpenClaw with ModelGo's OpenAI-compatible API.\n---\n\n# OpenClaw\n\nOpenClaw is an open-source, self-hosted personal AI assistant. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22.22.3 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\nVerify the installation:\n\n```bash\nopenclaw --version\n```\n\n## 2. Set the API key\n\nOpenClaw can read a provider API key from an environment variable. Set your ModelGo API key as `MODELGO_API_KEY`:\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. Configure the ModelGo provider\n\nCreate and open the OpenClaw configuration file:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\nPaste the following into `openclaw.json`, replacing `YOUR_MODELGO_MODEL` with a logical model name from the Model Catalog:\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | A ModelGo logical model name |\n| `agents.defaults.model.primary` | `modelgo/<logical-model-name>` |\n\n:::note\n- Use `{{ api_endpoint }}/v1` as `baseUrl`; do not append `/chat/completions`.\n- Set `contextWindow` and `maxTokens` to values supported by the selected model. The values above are generic examples; use the Model Catalog as the source of truth.\n- Set `reasoning` to `true` when the selected model supports reasoning.\n- Inject the API key through the environment. Do not write a real key into the config file or commit it.\n:::\n\n## 4. Start and verify\n\nSave the configuration and run:\n\n```bash\nopenclaw onboard --install-daemon\n```\n\nCheck the active provider and model:\n\n```bash\nopenclaw models status\n```\n\nIf the status is healthy, start the Gateway:\n\n```bash\nopenclaw gateway start\n```\n\nSend a simple message in OpenClaw, such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### Model not found\n\nMake sure `models.providers.modelgo.models[].id` matches the model name in `agents.defaults.model.primary`, which must use the `modelgo/<model-name>` format.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` exists in the current terminal and that `apiKey` is `${MODELGO_API_KEY}` with no extra spaces.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `baseUrl` to `{{ api_endpoint }}/v1`; do not use a full `/chat/completions` URL. OpenClaw appends the path for `openai-completions`.\n\n### Gateway did not load the new configuration\n\nRestart the Gateway after editing the file:\n\n```bash\nopenclaw gateway restart\n```\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [OpenClaw custom provider docs](https://docs.openclaw.ai/gateway/config-tools): see provider, Base URL, and model list configuration.\n","china/en/agents/opencode.md":"---\ntitle: OpenCode\ndescription: Configure OpenCode with ModelGo's OpenAI-compatible API.\n---\n\n# OpenCode\n\nOpenCode is an open-source terminal AI coding agent. Its custom provider support lets you connect any OpenAI-compatible endpoint, including ModelGo, from a terminal, IDE, or desktop client.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Install OpenCode and confirm that `opencode -v` works in your terminal.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenCode\n\nRun:\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nYou can also use the installation method provided by the OpenCode project. A version printed by `opencode -v` confirms a successful installation.\n\n## 2. Configure the ModelGo provider\n\nOpenCode reads user configuration from:\n\n- macOS/Linux: `~/.config/opencode/opencode.json`\n- Windows: `%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\nCreate or edit `opencode.json`. Replace `your-model-id` with a logical model name from the model catalog:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"your-model-id\"\n        }\n      }\n    }\n  }\n}\n```\n\nSet the environment variable:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `name` | `ModelGo`, the display name in OpenCode |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | A logical model ID and display name from the model catalog |\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- `modelgo` is a local provider ID and can be changed. Use the new ID when selecting a model.\n- Keep the API key in an environment variable instead of committing it to a config file.\n- Model IDs must exactly match logical model names from the ModelGo catalog.\n:::\n\n## 3. Select a model and start a chat\n\nStart OpenCode:\n\n```bash\nopencode\n```\n\nEnter `/models` to open the model picker, then select a model under the **ModelGo** provider.\n\n![Open the model picker in OpenCode](/images/agents/opencode/model-search.webp)\n\nThe **ModelGo** provider label confirms that OpenCode recognized the provider.\n\n![Identify ModelGo in the OpenCode model list](/images/agents/opencode/provider-name.webp)\n\nYou can also type `ModelGo` in the picker to filter the list:\n\n![Filter ModelGo models in OpenCode](/images/agents/opencode/provider-filter.webp)\n\nSelect the model and enter a simple task such as “Describe this project in three sentences.”\n\n![Start a chat with ModelGo in OpenCode](/images/agents/opencode/chat.webp)\n\n## 4. Verify the configuration\n\nIf the model list is empty, confirm that the API key can reach ModelGo:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical model names to use in `models`.\n\n## Troubleshooting\n\n### OpenCode cannot find the config file\n\nCheck that the file is named `opencode.json` and is in `~/.config/opencode/` (or `%USERPROFILE%\\\\.config\\\\opencode\\\\` on Windows). A project-level file with the same name can override user settings.\n\n### 401 or authentication errors\n\nConfirm that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces. Restart OpenCode after changing the variable.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as `baseURL`; do not append `/chat/completions`.\n\n### Empty model list or unavailable model\n\nMake sure the ID in `models` exactly matches a logical ModelGo model and that the model is enabled for the API key.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [OpenCode Providers documentation](https://opencode.ai/docs/providers): configure providers, credentials, and custom Base URLs.\n- [OpenCode configuration documentation](https://opencode.ai/docs/config/): learn the config file structure and model options.\n","china/en/agents/zcode.md":"---\ntitle: ZCode\ndescription: Configure ZCode with ModelGo's OpenAI-compatible API.\n---\n\n# ZCode\n\nZCode is a desktop AI coding environment from Zhipu AI for Windows, macOS, and Linux. It supports custom OpenAI-compatible providers, so you can use ModelGo models and API keys directly in ZCode.\n\n## Before you start\n\n- Install the ZCode desktop app.\n- Create an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name that the API key can call in the [Model catalog]({{ site_endpoint }}/models).\n\n## 1. Install ZCode\n\nOpen the [ZCode download page](https://zcode.z.ai/en/docs/install) and download the package for your operating system. ZCode provides macOS, Windows, and Linux builds; Linux users can choose `.deb`, `.rpm`, or AppImage.\n\n![ZCode download page](/images/agents/zcode/install.webp)\n\nComplete the installation and launch ZCode. On first launch, choose a workspace and finish the onboarding flow to reach the main interface.\n\n![ZCode platform installers](/images/agents/zcode/setup.webp)\n\n## 2. Add the ModelGo provider\n\nClick the settings icon in the lower-left corner, open **Model settings**, then click **Add provider** at the bottom of the provider list.\n\n![Open ZCode Model settings and add a provider](/images/agents/zcode/provider-fields.webp)\n\nEnter the following values:\n\n| Setting | ModelGo value |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | A ModelGo API key created in the [console]({{ console_endpoint }}/api-keys) |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | Click **Add model** and enter a logical model name from the model catalog |\n| Context window | Use the model's actual context length; if unsure, start with `200000` |\n\n![ModelGo provider settings](/images/agents/zcode/provider-saved-global.webp)\n\nClick **Add provider** to save. Keep these details in mind:\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not enter the full `/chat/completions` URL. ZCode appends the request path based on the API format.\n- Name is only the local display name. Use `ModelGo`; do not enter an upstream vendor name.\n- Model IDs must be logical model names from the ModelGo catalog. Do not copy the example model in the screenshot.\n- Keep the API key in the local ZCode settings and out of repositories or public screenshots.\n:::\n\n## 3. Add a model and start a chat\n\nClick **Add model**, enter a ModelGo logical model name, and save it. You can add multiple models as needed.\n\n![Select a ModelGo model in ZCode](/images/agents/zcode/chat.webp)\n\nReturn to the chat view, select **ModelGo** and the model you added, then enter a simple task such as “Describe this project in three sentences.” A successful response confirms the integration.\n\nTo verify which models the API key can call, run:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nCheck that the API key is complete, has no extra spaces, and is entered in the **API Key** field.\n\n### 403 or model unavailable\n\nConfirm that the Model list uses a logical model name from the ModelGo catalog and that the API key is allowed to call it.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL and choose **Chat completions (/chat/completions)**. Do not paste a complete endpoint path into Base URL.\n\n### Empty model list or provider cannot be saved\n\nMake sure at least one model has been added and the Base URL is reachable. If needed, verify the API key and endpoint with `GET {{ api_endpoint }}/v1/models`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): learn how to use API keys safely.\n- [ZCode installation docs](https://zcode.z.ai/en/docs/install): see the latest installation instructions.\n- [ZCode model connection docs](https://zcode.z.ai/en/docs/configuration): see custom provider and model settings.\n","china/en/models/audio/minimax.md":"---\ntitle: MiniMax Audio\ndescription: Drive platform-managed synchronous speech synthesis with MiniMax T2A request and response bodies.\n---\n\n# MiniMax Audio\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | Catalog-advertised MiniMax T2A inbound |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK alias with the same semantics |\n\nThis is **MiniMax synchronous speech synthesis (T2A V2)** as an inbound protocol. The gateway accepts a MiniMax `T2aV2Req` body as-is (`model`, `text`, `voice_setting`, `audio_setting`, `stream`, and other MiniMax fields) and **renders a MiniMax `T2aV2Resp`**, so a client written against MiniMax's own documentation can decode this surface directly.\n\n`model` is the platform logical model name; policy, routing, and billing apply as usual. The logical model must advertise `minimax_t2a` in `public_protocols`, or the gateway rejects the call as a protocol mismatch.\n\nFor OpenAI-shaped binary audio, see [Speech](./speech).\n\n## Synthesize\n\nThe two paths are equivalent:\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"Hello from ModelGo.\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\nA successful non-stream response is MiniMax JSON. Audio lives in `data.audio` as a **hexadecimal string** (not a raw `audio/mpeg` body):\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\nVerified 2026-09-10 on domestic production with `speech-2.8-turbo` against `POST /minimax/v1/t2a_v2` (hex truncated). The same model on `POST /v1/audio/speech` returns `model_protocol_not_offered`.\n\nOnly numeric `base_resp.status_code` **`0`** is success. HTTP 200 with a non-zero `status_code` is still a failed invoke.\n\n### Streaming\n\nSet `\"stream\": true`. The response is SSE whose events are MiniMax JSON (incremental hex audio), not OpenAI chat `choices[].delta` chunks.\n\n### Failures and HTTP status\n\nIn-band MiniMax errors are echoed to the caller. The gateway maps `status_code` to HTTP:\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| any other non-`0` | `502` |\n\n### Billing\n\nUsage is the upstream **character** count (`usage.characters`, else `extra_info.usage_characters`). The gateway does not bill `len(text)`.\n\n## Conventions\n\n- `model` is the platform logical model name; whether this lane is allowed is the model's `public_protocols`.\n- The path does not pick the upstream family. Routing on the logical model decides MiniMax-direct vs a Bailian adaptor.\n- Providers on the route must declare MiniMax T2A. An OpenAI-compatible relay alone returns `provider_unsupported`.\n","china/en/models/audio/speech.md":"---\ntitle: Speech\ndescription: OpenAI-compatible text-to-speech endpoint.\n---\n\n# Speech\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\nThe request is JSON (OpenAI `{input, voice}`) and the response body is binary audio returned with the upstream `Content-Type`.\n\n**Check `public_protocols` first.** Domestic `speech-2.8-hd` / `speech-2.8-turbo` currently offer MiniMax T2A, not this endpoint (`model_protocol_not_offered`). Use [MiniMax Audio Inbound Protocol](./minimax).\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"Hello from ModelGo.\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\nFor MiniMax-native fields (voice mix, subtitles, hex JSON, SSE), see [MiniMax Audio Inbound Protocol](./minimax).\n","china/en/models/audio/transcriptions.md":"---\ntitle: Transcriptions\ndescription: OpenAI-compatible speech-to-text endpoint.\n---\n\n# Transcriptions\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\nThis endpoint typically uploads audio as `multipart/form-data` and returns JSON with recognized `text`.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/en/models/audio/translations.md":"---\ntitle: Translations\ndescription: OpenAI-compatible audio translation endpoint.\n---\n\n# Translations\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\nUploads follow the same shape as transcriptions and return translated text in JSON.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/en/models/images/edits.md":"---\ntitle: Image Edits\ndescription: OpenAI-compatible image edit endpoint.\n---\n\n# Image Edits\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\nThis endpoint uses `multipart/form-data` and forwards the original body and `Content-Type` upstream, so clients should call `POST /v1/images/edits` with multipart upload semantics.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\nIf the routed upstream model does not support image editing, the gateway returns `provider_unsupported`.\n","china/en/models/images/gemini-image.md":"---\ntitle: Gemini Image\ndescription: Call gemini-3-pro-image, gemini-3.1-flash-image and gemini-3.1-flash-lite-image on the official Gemini API generateContent protocol — responseModalities, aspectRatio / imageSize tiers, inlineData responses and token-based billing. The Google GenAI SDK works by changing base_url.\n---\n\n# Gemini Image\n\n| Model (used in the path) | Positioning | Available `imageSize` |\n| --- | --- | --- |\n| `gemini-3-pro-image` | Quality tier | `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-image` | Speed / cost balance | `512px` / `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-lite-image` | Lowest cost | `1K` only |\n\nThe ModelGo gateway accepts image generation requests on the Gemini API **`generateContent`** protocol unchanged: `contents` + `generationConfig`, returning `candidates[].content.parts[].inlineData` synchronously. The gateway routes to a supplier and bills the call; which supplier renders the image is invisible to the caller. **The model name in the URL path is authoritative** — the body does not carry a model.\n\n> With the Google GenAI SDK, point `http_options.base_url` at `{{ api_endpoint }}` and use your ModelGo API key as `api_key`. Both `x-goog-api-key: $KEY` and `Authorization: Bearer $KEY` are accepted.\n>\n> Google's newer Interactions API is not yet supported; use `generateContent`.\n\n## 1. Create an image\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:generateContent` (also accepted under `/v1/models/...`)\n\n### Text to image\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [{\"text\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\"}]}],\n    \"generationConfig\": {\n      \"responseModalities\": [\"IMAGE\"],\n      \"imageConfig\": {\"aspectRatio\": \"16:9\", \"imageSize\": \"2K\"}\n    }\n  }'\n```\n\n### Image to image\n\nPut reference images into `parts` as `inlineData` (base64) or `fileData` (public URL):\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3-pro-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [\n      {\"text\": \"Replace the background with a neon night street, keep the cat's pose\"},\n      {\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"<base64>\"}}\n    ]}],\n    \"generationConfig\": {\"responseModalities\": [\"IMAGE\"], \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}}\n  }'\n```\n\n`fileData` form: `{\"fileData\": {\"fileUri\": \"https://example-cdn.com/cat.png\"}}` — must be a direct link the upstream can `GET`.\n\n### Response\n\n```json\n{\n  \"candidates\": [{\n    \"content\": {\n      \"role\": \"model\",\n      \"parts\": [{\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"iVBORw0KGgo...\"}}]\n    },\n    \"finishReason\": \"STOP\",\n    \"index\": 0\n  }],\n  \"usageMetadata\": {\n    \"promptTokenCount\": 18,\n    \"candidatesTokenCount\": 1680,\n    \"totalTokenCount\": 1698,\n    \"promptTokensDetails\": [{\"modality\": \"TEXT\", \"tokenCount\": 18}],\n    \"candidatesTokensDetails\": [{\"modality\": \"IMAGE\", \"tokenCount\": 1680}]\n  },\n  \"modelVersion\": \"gemini-3.1-flash-image\"\n}\n```\n\n- The image is in `parts[].inlineData.data` (base64). When `responseModalities` includes `TEXT`, `parts` may also contain a `{\"text\": ...}` part.\n- `modelVersion` echoes the model name from the request path.\n\nSave to a file:\n\n```bash\ncurl -s \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"contents\":[{\"parts\":[{\"text\":\"a red ball on a wooden table\"}]}],\"generationConfig\":{\"responseModalities\":[\"IMAGE\"]}}' \\\n  | python3 -c '\nimport sys, json, base64\nfor p in json.load(sys.stdin)[\"candidates\"][0][\"content\"][\"parts\"]:\n    if \"inlineData\" in p:\n        open(\"out.png\", \"wb\").write(base64.b64decode(p[\"inlineData\"][\"data\"])); break'\n```\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `contents[].role` | string | `user` |\n| `contents[].parts[].text` | string | The prompt. Describes the image; for image-to-image, describes the change |\n| `contents[].parts[].inlineData` | object | Reference image, `{\"mimeType\": \"image/png\", \"data\": \"<base64>\"}` |\n| `contents[].parts[].fileData` | object | Reference image URL, `{\"fileUri\": \"https://...\"}` |\n| `systemInstruction` | object | Optional system instruction, same as Gemini text calls |\n| `generationConfig.responseModalities` | string[] | `[\"IMAGE\"]` for image only; `[\"TEXT\",\"IMAGE\"]` for interleaved text and image |\n| `generationConfig.imageConfig.aspectRatio` | string | `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` |\n| `generationConfig.imageConfig.imageSize` | string | Resolution tier; per-model values in the first table, default `1K` |\n\n- `candidateCount` > 1 → `400`: one image per request.\n- `tools`, `responseSchema` / `responseMimeType` → `400`: image models do not support tool calls or structured output.\n- `:streamGenerateContent` → `400`: image generation does not stream.\n- An `imageSize` the model does not offer (e.g. `2K` on `gemini-3.1-flash-lite-image`) → `400`; it is **never silently downgraded**, and nothing is charged.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared tier; if no supplier can currently produce it the request returns `400` and nothing is charged.\n\n### Resolution tiers\n\n| Tier | Pixel budget | Measured output (example) |\n| --- | --- | --- |\n| `512px` | ~0.25 MP | — |\n| `1K` (default) | ~1 MP | default → 1408×768 |\n| `2K` | ~4 MP | `16:9` → 2752×1536 |\n| `4K` | ~16 MP | `9:16` → 3072×5504 |\n\nThe tier sets the total pixel budget; **exact width and height are determined by `aspectRatio`**. Without an `aspectRatio` the default is the supplier's roughly 16:9 output.\n\n## 3. Full example (Python, Google GenAI SDK)\n\n```python\nimport os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(api_key=os.environ[\"MODELGO_API_KEY\"],\n                      http_options={\"base_url\": \"{{ api_endpoint }}\"})\n\nresp = client.models.generate_content(\n    model=\"gemini-3.1-flash-image\",\n    contents=\"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    config=types.GenerateContentConfig(\n        response_modalities=[\"IMAGE\"],\n        image_config=types.ImageConfig(aspect_ratio=\"16:9\", image_size=\"2K\"),\n    ),\n)\nfor part in resp.candidates[0].content.parts:\n    if part.inline_data:\n        open(\"cat.png\", \"wb\").write(part.inline_data.data)\nprint(resp.usage_metadata.candidates_token_count)\n```\n\nFor image-to-image, pass a list as `contents`: `[\"Replace the background with a neon night street\", types.Part.from_bytes(data=open(\"cat.png\",\"rb\").read(), mime_type=\"image/png\")]`.\n\n## 4. Billing\n\n- **Token-based**: text in `promptTokensDetails` at `input`, images at `image_input`; in `candidatesTokensDetails`, `IMAGE` at `image_output` and `TEXT` at `output`.\n- Output image tokens grow with the tier (measured): `1K` ≈ 1120, `2K` ≈ 1680, `4K` ≈ 2000.\n- A reservation is frozen at request time and settled from the actual `usageMetadata` values.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- Prices are those shown in the console's model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `imageSize` not offered by the model; `aspectRatio` outside the table; `candidateCount` > 1; `tools` / `responseSchema` / `responseMimeType` present; `:streamGenerateContent` called; no supplier can currently produce the requested tier | Fix per the parameter table; use `generateContent` |\n| No `inlineData` in `parts` | `responseModalities` did not include `IMAGE`, or the prompt was blocked by safety policy (`finishReason` other than `STOP`) | Pass `[\"IMAGE\"]` explicitly; check `finishReason` |\n| Reference image ignored | `fileData.fileUri` is not a public direct link (auth / redirect / 403) | Use `inlineData` or a direct link on your own CDN |\n| `401` | Invalid API key or missing `x-goog-api-key` / `Authorization` header | Check the key |\n","china/en/models/images/generations.md":"---\ntitle: Image Generation\ndescription: OpenAI-compatible image generation endpoint.\n---\n\n# Image Generation\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\nThe request body follows the OpenAI Images-compatible shape and is forwarded to an upstream provider that supports image generation. The main entrypoint is `POST /v1/images/generations`.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\nCommon optional fields include `size`, `quality`, and `n`, subject to upstream model support.\n\n## Verified Seedream limit\n\n`doubao-seedream-5.0-lite` rejects `size=1024x1024` (HTTP 400 `provider_invalid`, at least 3686400 pixels). `2048x2048` succeeded on 2026-09-10. Full curl: [API catalog](../../../quickstart/openapi).\n","china/en/models/images/gpt-image-2.md":"---\ntitle: GPT Image\ndescription: Call gpt-image-2 / gpt-image-1.5 on the official OpenAI Images API — generations for text-to-image, edits for image-to-image and mask editing, size / quality parameters, b64_json responses and token-based billing. The official OpenAI SDK works by changing base_url.\n---\n\n# GPT Image\n\n| Model | Endpoints | Default-tier output tokens (`1024x1024` + `quality: auto`, measured) |\n| --- | --- | --- |\n| `gpt-image-2` | generations / edits | 196 |\n| `gpt-image-1.5` | generations / edits | 4444 |\n\n| Endpoint | Capability | Body | Required fields |\n| --- | --- | --- | --- |\n| `POST /v1/images/generations` | Text to image | JSON | `model`, `prompt` |\n| `POST /v1/images/edits` | Image to image / mask editing (multiple references) | `multipart/form-data` | `model`, `prompt`, `image[]` |\n\nBoth models share the same parameter set and the same endpoints; only the `model` field differs. Their output token counts and prices differ (see \"Billing\").\n\nThe ModelGo gateway accepts `gpt-image-2` / `gpt-image-1.5` requests on the official OpenAI Images API paths with the official request/response shapes unchanged; the gateway routes to a supplier and bills the call. Which supplier renders the image is invisible to the caller. Images are returned **synchronously** — there is no polling.\n\n> With the official OpenAI SDK, point `base_url` at `{{ api_endpoint }}/v1` and use your ModelGo API key as `api_key`.\n\n## 1. Create an image\n\n### Text to image\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-image-2\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    \"size\": \"1536x1024\",\n    \"quality\": \"high\",\n    \"output_format\": \"png\"\n  }'\n```\n\n### Image to image / mask editing\n\n`POST {{ api_endpoint }}/v1/images/edits` (`multipart/form-data`)\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=gpt-image-2\" \\\n  -F \"prompt=Replace the background with a neon night street, keep the cat's pose\" \\\n  -F \"image[]=@./cat.png\" \\\n  -F \"mask=@./mask.png\" \\\n  -F \"size=1024x1024\" \\\n  -F \"quality=medium\" \\\n  -F \"input_fidelity=high\"\n```\n\n- `image[]` may be repeated to send several reference images in one request.\n- Text fields such as `model`, `prompt`, `size`, `quality` and `n` must appear once, as plain form fields (not file parts); otherwise the request gets a 400.\n- `mask` is optional: a PNG with the same dimensions as the first `image[]`; transparent areas are repainted.\n\n### Response\n\n```json\n{\n  \"created\": 1757318400,\n  \"data\": [{\"b64_json\": \"iVBORw0KGgoAAAANSUhEUgAA...\"}],\n  \"usage\": {\n    \"input_tokens\": 17,\n    \"input_tokens_details\": {\"text_tokens\": 17, \"image_tokens\": 0},\n    \"output_tokens\": 5488,\n    \"output_tokens_details\": {\"image_tokens\": 5488, \"text_tokens\": 0},\n    \"total_tokens\": 5505\n  }\n}\n```\n\nImages are always returned as `data[].b64_json` (base64). Save to a file:\n\n```bash\ncurl -s {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gpt-image-2\",\"prompt\":\"a red ball on a wooden table\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.png\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model` | string | all | `gpt-image-2` / `gpt-image-1.5` |\n| `prompt` | string | all | Required. Describes the image; for edits, describes the change to make |\n| `image[]` | file | edits | Required. One or more reference images (png / jpeg / webp) |\n| `mask` | file | edits | Optional. PNG mask with the same dimensions as the image; transparent areas are repainted |\n| `input_fidelity` | string | edits | How closely to follow the reference image, `low` / `high` |\n| `n` | int | all | Number of images, default `1` |\n| `size` | string | all | Default `auto`. **gpt-image-2**: any `WxH` where width and height are multiples of 16 and width × height is between 655,360 and 8,294,400 (e.g. `1248x832`, `1248x1248`, `3840x2160`); finer limits such as aspect ratio are decided by the upstream, and its reason is returned in the 400 message. **gpt-image-1.5**: `1024x1024` / `1536x1024` / `1024x1536` / `auto` only |\n| `quality` | string | all | `low` / `medium` / `high` / `auto`, default `auto`. Directly determines the output token count |\n| `output_format` | string | all | `png` / `jpeg` / `webp` |\n| `output_compression` | int | all | `0`–`100`, only for `jpeg` / `webp` |\n| `background` | string | all | `opaque` / `transparent` / `auto` |\n| `moderation` | string | all | Content moderation level, passed through |\n\n- **`response_format` does not apply to the gpt-image family.** The gateway strips the field before forwarding, without an error; images are always returned as `b64_json` — there is no `url` form.\n- A `size` / `quality` outside the table, or a missing `prompt` → HTTP `400`, nothing charged.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared `size` / `quality`; if no supplier can currently produce that tier the request returns `400` and nothing is charged.\n\n### Output token reference (measured)\n\n| Model | `size` | `quality` | `output_tokens_details.image_tokens` |\n| --- | --- | --- | --- |\n| `gpt-image-2` | `1024x1024` | `auto` (default) | 196 |\n| `gpt-image-2` | `1536x1024` | `high` | 5488 |\n| `gpt-image-1.5` | `1024x1024` | `auto` (default) | 4444 |\n\nOutput tokens are determined by model, size and quality together: on gpt-image-2, `high` is more than an order of magnitude above the default tier; at the same default tier, gpt-image-1.5 emits more than 20× the output tokens of gpt-image-2. Token counts and prices differ between the two models, so re-check cost before switching.\n\n## 3. Full example (Python, official OpenAI SDK)\n\n```python\nimport base64, os\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/v1\")\n\n# Text to image\nr = client.images.generate(model=\"gpt-image-2\", prompt=\"An orange cat on a windowsill, film grain\",\n                           size=\"1536x1024\", quality=\"high\", output_format=\"png\")\nopen(\"cat.png\", \"wb\").write(base64.b64decode(r.data[0].b64_json))\nprint(r.usage.output_tokens_details.image_tokens)\n\n# Image to image (mask editing)\nwith open(\"cat.png\", \"rb\") as img, open(\"mask.png\", \"rb\") as mask:\n    e = client.images.edit(model=\"gpt-image-2\", prompt=\"Replace the background with a neon night street\",\n                           image=[img], mask=mask, size=\"1024x1024\", quality=\"medium\")\nopen(\"cat-neon.png\", \"wb\").write(base64.b64decode(e.data[0].b64_json))\n```\n\n## 4. Billing\n\n- **Token-based**, with three prices: text input (`input`), image input (`image_input`) and image output (`image_output`), each per million tokens. The image portion of the output is billed at the `image_output` price.\n- gpt-image-2 and gpt-image-1.5 each have their own price card, and their output token counts for the same tier differ materially (196 vs 4444 at the default tier), so the cost of one request cannot be inferred from the other model.\n- A reservation is frozen at request time and settled from the returned `usage`: `input_tokens_details.text_tokens` → `input`, `input_tokens_details.image_tokens` → `image_input`, `output_tokens_details.image_tokens` → `image_output`.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- Prices are those shown in the console's model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `size` / `quality` outside the parameter table; missing `prompt`; edits missing `image[]` or `mask` dimensions differ from the image; no supplier can currently produce the requested tier | Fix per the parameter table or change tier |\n| `response_format: \"url\"` sent but `b64_json` returned | The gpt-image family does not support the field; the gateway strips it silently | Decode `data[].b64_json` |\n| `429` | Rate limit hit | Back off and retry; contact the platform for a higher quota |\n| `401` | Invalid API key or missing `Authorization` header | Check the key |\n","china/en/models/images/qwen-image.md":"---\ntitle: Qwen Image\ndescription: Call qwen-image-3.0 / qwen-image-3.0-pro on either of two synchronous inbound lanes — OpenAI-compatible and Bailian DashScope native — with text to image and image to image (1-3 reference images), the two spellings of size, the 1k / 2k resolution tiers and per-image billing. The official Bailian SDK works by changing base_url.\n---\n\n# Qwen Image\n\n## Models\n\n| Model | Output resolution | Notes |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | Total pixels 512×512 – 2048×2048 | Pro tier; the 2k tier costs more than 1k |\n| `qwen-image-3.0` | Same | Standard tier; both tiers priced the same |\n\nBoth models serve **text to image (T2I)** and **image to image / editing (I2I)**: no reference image means T2I, 1–3 reference images mean I2I. Images are returned **synchronously** — no polling.\n\n> **The async task lane is not supported.** This family is served only on the synchronous endpoints; a call to `/v1/content_generation/tasks` is refused.\n\n## Two inbound lanes\n\nOne model, two spellings, identical capability. Pick whichever matches the code you already have:\n\n| Lane | Path | Who it is for |\n| --- | --- | --- |\n| OpenAI-compatible | `POST /v1/images/generations` | Apps already written against the OpenAI Images protocol or SDK — change `base_url` and `model` only |\n| Bailian native | `POST /api/v1/services/aigc/multimodal-generation/generation` | Apps already using the Bailian DashScope SDK — change `base_url` only |\n\n> **The two lanes spell `size` differently and neither accepts the other's spelling**: the OpenAI-compatible lane uses the letter `x` (`1024x1024`), the Bailian native lane uses an asterisk (`1024*1024`). The wrong one returns `400` naming the separator it expects; it is **not** silently rewritten — mixing the two protocols should surface here rather than as a harder problem further down.\n\n## 1. OpenAI-compatible lane\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### Text to image\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"A fluffy ginger cat on a sunlit windowsill, afternoon light, film grain\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### Image to image / editing\n\nNo multipart: the reference images go in the top-level `image` field.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"Keep her facial features; change the outfit to a champagne silk shirt and a dark grey blazer\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### Response\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- Images are PNG, and the **link is valid for 24 hours** — download promptly and do not persist the URL.\n- `usage` carries **image counts and tiers, not token usage**: this family bills purely per image (see Billing).\n- `response_format: \"b64_json\"` does not error but is ignored; the response still carries an image URL.\n\n### Using the OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # Generation is slow; 40-60s for a single image in practice\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"A fluffy ginger cat on a sunlit windowsill, film grain\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # extensions go through extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` are not OpenAI parameters: pass them via `extra_body` with the OpenAI SDK, or at the top level of the request body over plain HTTP.\n\n## 2. Bailian native lane\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\nRequest and response are Bailian's own shapes in both directions — the gateway does not translate.\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### Constraints of this lane\n\n- `input.messages` carries **exactly one** object and `role` must be `user` (single-turn only).\n- `content` carries **exactly one** `{\"text\": ...}`; omitting it or passing several returns `400`.\n- `{\"image\": ...}` 0–3 entries: 0 is text to image, 1–3 is image to image.\n- Generation parameters live under `parameters` (not at the top level): `size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`.\n- With the official Bailian SDK (`dashscope`), point `dashscope.base_http_api_url` at `{{ api_endpoint }}/api/v1` and use your ModelGo API key.\n\n## 3. Parameters\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt` (compat lane) / `content[].text` (native lane) | string | Required, non-empty. Chinese and English; up to about 4500 tokens recommended |\n| `image` (compat lane) / `content[].image` (native lane) | string / string[] | Reference images, 1–3. **`null` and an empty array are refused** |\n| `size` | string | `WxH` on the compat lane, `W*H` on the native lane. Omitted means the model picks a resolution from the prompt |\n| `n` | int | 1–6 output images, default 1. **Must be an integer**; the string form (e.g. `\"1\"`) returns `400` |\n| `negative_prompt` | string | What to keep out of the picture |\n| `seed` | int | `0` – `2147483647`. A fixed seed makes results relatively stable |\n| `prompt_extend` | boolean | Prompt rewriting, default `true` (recommended) |\n| `prompt_extend_mode` | string | `direct` (default, T2I and I2I) / `agent` (finer, **text to image only**) |\n| `enable_thinking` | boolean | Thinking mode, default `true`. Better images, longer latency. Only effective when `prompt_extend=true` |\n| `watermark` | boolean | Watermark, default `false` |\n\n### Validation happens before the call\n\nThe following are refused at creation (HTTP `400`) — nothing reaches the upstream and nothing is charged:\n\n- `n` is not an integer in 1–6, or is written as a string or a decimal;\n- `size` total pixels fall outside 512×512 – 2048×2048, or the aspect ratio is outside 1:8 – 8:1;\n- `size` uses the other lane's separator (the error names whether `x` or `*` is expected);\n- `image` is `null`, an empty array, or more than 3 entries;\n- `prompt_extend_mode: \"agent\"` is combined with `image` (APE is text to image only);\n- `seed` is outside `0` – `2147483647`;\n- on the native lane, `messages` is not exactly one, or `content` does not carry exactly one `text`.\n\n### Reference image requirements\n\n- Formats: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF.\n- Width and height between 384 and 2048 pixels recommended; at most 10 MB each.\n- Public URLs (HTTP / HTTPS) or Base64 (`data:{MIME_type};base64,{base64_data}`).\n- A public URL must be directly `GET`-able by the upstream: no auth, no redirect, no Referer / Cookie dependency. Some sites return 403 to non-browser clients, which fails the request.\n\n## 4. Billing\n\n**Per image, not per token.** Input (reference) and output (generated) images are priced separately, each split into a 1k and a 2k tier:\n\n| Model | Output tier | Output price | Input price |\n| --- | --- | --- | --- |\n| `qwen-image-3.0-pro` | 1k | CNY 0.25 / image | CNY 0.02 / image |\n| `qwen-image-3.0-pro` | 2k | CNY 0.50 / image | CNY 0.02 / image |\n| `qwen-image-3.0` | 1k | CNY 0.18 / image | CNY 0.02 / image |\n| `qwen-image-3.0` | 2k | CNY 0.18 / image | CNY 0.02 / image |\n\n**The tier is decided by the OUTPUT pixel area**: an area of 2,250,000 (that is, 1500×1500) or less is `1k`, anything larger is `2k`. **The input tier is judged by the output area too**, not by the size of the reference image — that is the upstream's own rule. `output_image_type` / `input_image_type` in the response `usage` name the tier the call actually hit.\n\nCharge = output count × that tier's output price + input count × input price. Measured examples (China production, 2026-09-11):\n\n| Request | `usage` | Settled |\n| --- | --- | --- |\n| `qwen-image-3.0`, `1024x1024`, `n=1`, T2I | `output_image_count: 1`, `qima_output_1k` | CNY 0.18 |\n| `qwen-image-3.0`, `1024x1024`, `n=2`, T2I | `output_image_count: 2`, `qima_output_1k` | CNY 0.36 |\n| `qwen-image-3.0-pro`, `1024x1024`, `n=1`, T2I | `output_image_count: 1`, `qima_output_1k` | CNY 0.25 |\n| `qwen-image-3.0-pro`, `2048x2048`, `n=1`, T2I | `output_image_count: 1`, `qima_output_2k` | CNY 0.50 |\n\n**Text to image incurs no input charge**: with no reference image `input_image_count` is 0 and only the output count settles.\n\n## 5. Full example (Python, official Bailian SDK)\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt; modern minimalist cafe background\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","china/en/models/images/seedream.md":"---\ntitle: Seedream\ndescription: Call the Seedream family (doubao-seedream-5.0-pro / 5.0-lite / 5.0 / 4.5) on the official Volcengine Ark Images API — text to image / multi-reference, per-model size tiers and explicit pixel sizes, url / b64_json responses and per-image billing. The official Ark SDK works by changing base_url.\n---\n\n# Seedream\n\n## Models and tiers\n\n| Model | Default `size` | Offered `size` | Typical output (measured) |\n| --- | --- | --- | --- |\n| `doubao-seedream-5.0-pro` | `2K` | `1K` / `1.5K` / `2K`, or `WxH` | `1K` ≈ 1152×864; `1.5K` ≈ 1792×1344; `2K` + 16:9 prompt → 2816×1584 |\n| `doubao-seedream-5.0-lite` | `2K` | `2K` / `3K` / `4K`, or `WxH` with total pixels ≥ 3,686,400 | `2K` → 2048×2048; `3K` → 3072×3072; `4K` → 4096×4096 |\n| `doubao-seedream-5.0` | `2K` | Same as 5.0 lite | Same as 5.0 lite |\n| `doubao-seedream-4.5` | `2K` | `2K` / `4K`, or `WxH` with total pixels ≥ 3,686,400 (**no `3K`**) | `2K` → 2048×2048; `4K` → 4096×4096 |\n\n- All four models share the same inbound `POST /api/v3/images/generations`, support text to image and image to image (single / multiple references), and require `model` and `prompt`.\n- `doubao-seedream-5.0` is an alias of `doubao-seedream-5.0-lite`: Ark has no standalone 5.0 model, so the two share tiers and price.\n- 5.0 pro does **not** offer `3K` / `4K`; 5.0 lite / 5.0 / 4.5 do **not** offer `1K` / `1.5K` (Ark requires at least 3,686,400 pixels); 4.5 additionally does **not** offer `3K`. A tier outside the table is refused at creation (HTTP `400`) — nothing is rendered, nothing is charged.\n- On 5.0 pro, `1.5K` is priced the same as `1K` (Ark pricing) and is served by only part of the supplier pool, so fewer lanes are available than for the other tiers.\n\nThe ModelGo gateway accepts Seedream requests on the official Volcengine Ark **Images API** path with the official request/response shapes unchanged; the gateway routes to a supplier and bills the call. Which supplier renders the image is invisible to the caller. Images are returned **synchronously** — there is no polling.\n\n> With the official Ark SDK (`volcenginesdkarkruntime`), point `base_url` at `{{ api_endpoint }}/api/v3` and use your ModelGo API key as `api_key`.\n\n## 1. Create an image\n\n`POST {{ api_endpoint }}/api/v3/images/generations`\n\n### Text to image (5.0 pro)\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, 16:9 landscape, film grain\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### Text to image (5.0 lite)\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"A fluffy orange cat sitting on a sunny windowsill, film grain\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### Image to image / multiple references\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"Place the cat from the first image into the neon street of the second image\",\n    \"image\": [\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n    \"size\": \"1280x720\",\n    \"response_format\": \"b64_json\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"model\": \"doubao-seedream-5.0-pro\",\n  \"created\": 1757318400,\n  \"data\": [{\"url\": \"https://ark-content-generation.tos-cn-beijing.volces.com/...\", \"size\": \"2816x1584\", \"output_format\": \"jpeg\"}],\n  \"usage\": {\"generated_images\": 1, \"input_images\": 0, \"output_tokens\": 17424, \"total_tokens\": 17424}\n}\n```\n\n- `model` always echoes the logical model you requested (e.g. `doubao-seedream-5.0-lite`), not Ark's internal version id (which looks like `doubao-seedream-5-0-260128` / `doubao-seedream-4-5-251128` / `doubao-seedream-5-0-pro-260628`).\n- `response_format` defaults to `url`; **the link is valid for 24 hours** — download promptly and do not persist the URL.\n- With `response_format: \"b64_json\"`, `data[].b64_json` carries the base64 image directly.\n- `data[].size` is the actual output resolution and `output_format` the actual encoding.\n- `usage.output_tokens` / `total_tokens` are informational values echoed from upstream and **are not billed**; settlement uses `usage.generated_images` only.\n\nSave to a file:\n\n```bash\ncurl -s {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedream-5.0-lite\",\"prompt\":\"a red ball on a wooden table\",\"size\":\"2K\",\"response_format\":\"b64_json\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.jpg\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `model` | string | `doubao-seedream-5.0-pro` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0` / `doubao-seedream-4.5` |\n| `prompt` | string | Required. Describes the image; with tier sizes, describe the composition / aspect here |\n| `image` | string / string[] | Reference image URL (single) or array of URLs (multiple references); must be public direct links the upstream can `GET` |\n| `size` | string | Resolution tier (default `2K`; the tiers offered per model are listed under \"Models and tiers\"), or explicit pixels `WxH` (e.g. `1280x720`, `2560x1440`) |\n| `seed` | int | Random seed |\n| `guidance_scale` | number | Prompt adherence |\n| `watermark` | boolean | Add a watermark, default `true` |\n| `response_format` | string | `url` (default, valid 24 hours) / `b64_json` |\n| `output_format` | string | Output encoding, passed through |\n\n- `sequential_image_generation: \"auto\"` (image sets) is not supported on 5.0 pro → `400`.\n- `stream: true` → `400`: streaming is not supported.\n- Any field outside the table → `400`; unknown fields are rejected, not ignored.\n- **Routing follows deliverable tiers.** The gateway only hands a request to suppliers that can deliver the declared `size`; if no supplier can currently produce that tier the request returns `400` and nothing is charged.\n\n### Resolution tiers\n\n| Model | `size` form | Output | Measured example |\n| --- | --- | --- | --- |\n| 5.0 pro | `1K` / `1.5K` / `2K` (default) | The tier sets the total pixel budget; the aspect ratio follows the composition described in `prompt` | `\"2K\"` + 16:9 prompt → 2816×1584; `\"1.5K\"` → 1792×1344; `\"1K\"` → 1152×864 |\n| 5.0 lite / 5.0 | `2K` (default) / `3K` / `4K` | The tier sets the output edge length | `\"2K\"` → 2048×2048; `\"3K\"` → 3072×3072; `\"4K\"` → 4096×4096 |\n| 4.5 | `2K` (default) / `4K` | Same; 4.5 does not offer `3K` | `\"2K\"` → 2048×2048; `\"4K\"` → 4096×4096 |\n| all | `WxH` | Exactly the requested dimensions; aspect ratio between 1/16 and 16. 5.0 lite / 5.0 / 4.5 require total pixels ≥ 3,686,400 | 5.0 pro: `\"1280x720\"` → 1280×720; 5.0 lite: `\"2560x1440\"` → 2560×1440 |\n\n- A `size` outside the table (a tier the model does not offer, pixels below the minimum, or aspect out of range) is rejected at creation (HTTP `400`); it is never silently downgraded or upgraded, and nothing is charged.\n\n### Reference image requirements\n\n- Must be a direct link the upstream server can `GET`: no auth, no redirects, no Referer / Cookie dependency.\n- Some sites return 403 to non-browser fetches, which fails the request — not billed. Use your own object storage or CDN.\n\n## 3. Full example (Python, official Ark SDK)\n\n```python\nimport os, requests\nfrom volcenginesdkarkruntime import Ark\n\nclient = Ark(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/api/v3\")\n\n# 5.0 pro: tier + aspect described in the prompt\nr = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"An orange cat on a windowsill, 16:9 landscape, film grain\",\n                           size=\"2K\", watermark=False)\nimg = r.data[0]\nprint(r.model, img.size, r.usage.generated_images)\nopen(\"cat.jpg\", \"wb\").write(requests.get(img.url, timeout=60).content)\n\n# 5.0 lite: default 2K tier (2048x2048)\nl = client.images.generate(model=\"doubao-seedream-5.0-lite\",\n                           prompt=\"An orange cat on a windowsill, film grain\",\n                           size=\"2K\", watermark=False)\nopen(\"cat-lite.jpg\", \"wb\").write(requests.get(l.data[0].url, timeout=60).content)\n\n# Multiple references\ne = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"Place the cat from the first image into the neon street of the second image\",\n                           image=[\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n                           size=\"1280x720\")\nopen(\"cat-neon.jpg\", \"wb\").write(requests.get(e.data[0].url, timeout=60).content)\n```\n\n## 4. Billing\n\n- **Per image**: settlement uses `usage.generated_images` at a flat price per image, independent of the `size` tier.\n- **One price per model**: 5.0 pro / 5.0 lite / 5.0 / 4.5 each have their own price card in the console's model list and the prices differ (5.0 and 5.0 lite share one price).\n- A reservation is frozen at request time and settled on the actual number of generated images.\n- Rejected requests (`400`) and failed generations are never billed; the reservation is released automatically.\n- An HTTP `200` whose `data[]` contains no `url` / `b64_json` at all (e.g. every entry is an `error`) is not billed.\n- A content-moderation refusal (e.g. `OutputImageSensitiveContentDetected`) returns HTTP `400` with the upstream error code; it is neither billed nor retried.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `400` | `size` outside the tier table or `WxH` out of bounds; missing `prompt`; `sequential_image_generation` / `stream` or another unsupported field present; no supplier can currently produce the requested tier | Fix per the parameter table or change tier |\n| `400` (5.0 lite / 5.0 / 4.5) | `size` below the model's minimum: `1K` / `1.5K`, or `WxH` with total pixels < 3,686,400; `3K` on 4.5 | Use `2K` / `4K` (`3K` also on lite / 5.0), or `WxH` with total pixels ≥ 3,686,400 (e.g. `2560x1440`) |\n| `400` (5.0 pro) | `3K` / `4K` requested; 5.0 pro does not offer those tiers | Use `1K` / `1.5K` / `2K` or `WxH` |\n| `400` with `metadata.upstream_error_code` such as `OutputImageSensitiveContentDetected` | Upstream content moderation refused the request; not billed, not retried | Adjust the `prompt` / reference images and retry |\n| Generation failed | Upstream could not download a URL in `image` | Use a publicly downloadable direct link |\n| `data[].url` download returns `403` / `404` | The 24-hour link has expired | Regenerate, or use `response_format: \"b64_json\"` |\n| `401` | Invalid API key or missing `Authorization` header | Check the key |\n","china/en/models/realtime/api.md":"---\ntitle: Realtime API reference\ndescription: Handshake, events, and audio formats for GET /api-ws/v1/realtime (WebSocket).\n---\n\n# Realtime API reference: `GET /api-ws/v1/realtime`\n\nThis endpoint is a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol verbatim in both directions with **no protocol translation**; the full field definitions and the tool-calling (Function Calling / MCP) events follow Bailian's official [client events](https://help.aliyun.com/zh/model-studio/client-events) and [server events](https://help.aliyun.com/zh/model-studio/server-events). This page covers the handshake, auth, event list, and audio conventions needed to integrate.\n\n## Request\n\n| Item | Value |\n| --- | --- |\n| Method | `GET` (WebSocket upgrade) |\n| Path | `/api-ws/v1/realtime` |\n| Full URL | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<logical model>` |\n| Query | `model` (required) — the platform logical model, not the upstream model |\n| Header | `Authorization: Bearer <mgk_ API Key>` (required) |\n| Header | `X-Request-ID` (optional) — propagated to the call log; the `request_id` starts with `gw_rt_` |\n\nOnly a logical model whose `public_protocols` includes `dashscope_realtime` can use this surface.\n\n## Handshake errors {#handshake-errors}\n\nFailures before the WebSocket upgrade are returned as HTTP status codes with a body of:\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | Trigger | Observed message (cn production, 2026-10-08) |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | no API key | `missing api key` |\n| 401 | `unauthorized` | invalid / disabled key | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | model not in catalog | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | model does not advertise `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | no route for the model in the policy (including its fallback chain) | `no route for model <model>` |\n| 503 | `no_provider` | a route exists but no provider instance is available | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | preauthorization failed (balance / budget) | `billing: insufficient funds` |\n\nAfter a successful upgrade (HTTP 101), later problems are delivered as an in-band `error` event, then the connection closes:\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## Session configuration `session.update`\n\nAfter connecting, the server first sends `session.created`; the client overrides with `session.update`, and a valid update is acknowledged with `session.updated`. Common fields:\n\n| Field | Values | Default |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | see Bailian's voice list | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | server VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | any text | empty |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | enabled |\n\n`turn_detection: null` disables the server VAD so the client commits and triggers responses manually.\n\n## Client events\n\n| Event | Purpose |\n| --- | --- |\n| `session.update` | Update session config (modalities, voice, audio format, VAD, instructions, …) |\n| `input_audio_buffer.append` | Append Base64 audio to the input buffer |\n| `input_image_buffer.append` | Append a Base64 image (JPG/JPEG; audio must have been sent first) |\n| `input_audio_buffer.commit` | Commit the audio buffer in manual mode (does not trigger a response) |\n| `input_audio_buffer.clear` | Clear the audio buffer |\n| `conversation.item.create` | Create an item: plain text input, `function_call_output`, `mcp_approval_response` |\n| `response.create` | Trigger one model response |\n| `response.cancel` | Cancel the in-progress response (interruption) |\n\n## Server events\n\n| Event | Meaning |\n| --- | --- |\n| `session.created` / `session.updated` | Session created / config applied |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD detected the user starting / stopping (interruption trigger) |\n| `input_audio_buffer.committed` / `cleared` | Audio buffer committed / cleared |\n| `conversation.item.created` | An item was created |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | Input speech transcription (streaming preview / final) |\n| `response.created` | A response turn began |\n| `response.output_item.added` / `response.content_part.added` | Output item / content part began |\n| `response.text.delta` / `response.text.done` | Text-only streaming / full text |\n| `response.audio_transcript.delta` / `.done` | Transcript of the audio output |\n| `response.audio.delta` / `response.audio.done` | Base64 output audio (24 kHz PCM) / end of audio |\n| `response.output_item.done` / `response.content_part.done` | Output item / content part completed |\n| `response.done` | Response turn ended; `response.usage` carries per-modality token usage |\n\nTool-calling events (`response.function_call_arguments.delta` / `.done`) and the MCP events (`mcp_*`) are documented in Bailian's server-events reference.\n\nObserved event order for one voice turn (cn production, 2026-10-08):\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## Audio formats\n\n| Direction | Format | Field |\n| --- | --- | --- |\n| Uplink (input) | 16000 Hz, 16-bit little-endian, mono PCM, Base64 | `audio` of `input_audio_buffer.append` |\n| Downlink (output) | 24000 Hz, 16-bit little-endian, mono PCM, Base64 | `delta` of `response.audio.delta` |\n\nSending input audio in full 100 ms frames (3200 bytes per frame) proved most reliable. `input_audio_buffer.append` only buffers; whether it is committed is decided by VAD or by a client `input_audio_buffer.commit`.\n\n## VAD and interruption\n\n- With a non-`null` `turn_detection`, the server auto-detects speech boundaries and, after `silence_duration_ms` of silence (default 800 ms), auto-commits and triggers a response.\n- When the user speaks again: the server emits `input_audio_buffer.speech_started` → the client **stops playback** and sends `response.cancel` → `response.done` (cancelled) arrives → a new turn begins.\n- `turn_detection: null` is manual mode: after recording, the client sends `input_audio_buffer.commit` (wait for `input_audio_buffer.committed`) then `response.create`.\n\n## Usage and billing\n\nEach turn's `response.done.response.usage` carries per-modality tokens:\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\nThe gateway settles the accumulated session usage at close: a session-level estimate is held at connect (currently about ¥1.2; insufficient balance fails the handshake with `402`), then refund/top-up applies based on actual usage; a session with no usage releases the hold. See the [guide](./guide#billing).\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Upstream rate limit | 60 RPM |\n\n## Related\n\n- [Realtime (WebSocket) models guide](./guide)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","china/en/models/realtime/guide.md":"---\ntitle: Realtime (WebSocket) models\ndescription: Call Qwen-Omni-Realtime over WebSocket for live voice chat, interruption, and omni-modal input.\n---\n\n# Realtime (WebSocket) models\n\nRealtime models do **not** use `/v1/chat/completions`; they are called over a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol **verbatim in both directions** — there is no protocol translation: you send Bailian events and receive Bailian events. This page covers connection, a runnable minimal example, and billing; the exact event and error schema is in the [API reference](./api).\n\n## What it does\n\n- **Live voice chat**: speak and get streamed text and audio back as you go.\n- **Interruption**: when the user speaks again the server emits `input_audio_buffer.speech_started`; the client stops playback and sends `response.cancel` to interrupt the current reply.\n- **Omni-modal input**: streaming audio, images (frames sampled from video), and plain text.\n- **Text + audio output**: the model produces both text and speech.\n\n## Supported models\n\nA logical model can use this surface only if its catalog `public_protocols` includes `dashscope_realtime`. The realtime model currently available is `qwen3.8-omni-flash-realtime` (check the marketplace for what is actually listed). Check the model marketplace at [{{ console_endpoint }}]({{ console_endpoint }}) to confirm whether a model offers this protocol.\n\n## Connecting\n\n| Item | Value |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<logical model>` (required) |\n| Auth | `Authorization: Bearer <mgk_ API Key>` |\n| Request ID | optional `X-Request-ID`; the call-log `request_id` starts with `gw_rt_` |\n\nHandshake failures are returned as HTTP status codes (e.g. an invalid key is `401 unauthorized`, a model without the realtime protocol is `403 model_protocol_not_offered`, insufficient balance is `402`); see the full list in the [API reference](./api#handshake-errors).\n\n## Minimal example\n\nThe examples below run **server-side**: connect with an `mgk_` API key, configure the session, push 16 kHz PCM audio, commit, request a reply, and write the returned 24 kHz PCM to `reply.pcm`.\n\n:::note\n- A browser's native `WebSocket` constructor **cannot set an `Authorization` header**, so the API key must not be placed in a browser connection.\n- For browser microphone capture, relay through your own server (which holds the key and opens the connection), or use an authenticated server-side proxy.\n- The Python / Node.js examples below are server-side and run as-is.\n:::\n\nPrepare input: capture the microphone, or save 16 kHz, 16-bit little-endian, mono, **headerless** PCM as `input.pcm`. If you have a WAV, extract the raw PCM first:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython (`pip install websocket-client`):\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js (`npm install ws`):\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\nWrap the returned `reply.pcm` (24 kHz, 16-bit, mono) into a playable WAV:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\nTo smoke-test connectivity without audio, send one `conversation.item.create` with an `input_text` content item, then `response.create`, to get a text-only reply.\n\n## Session configuration\n\nRight after connecting, the server sends `session.created` (with defaults); the client overrides with `session.update`. Common fields:\n\n| Field | Meaning |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` (default) or `[\"text\"]` |\n| `voice` | output voice, default `Tina`; prefer `audio.output.voice` |\n| `turn_detection` | server VAD: `{\"type\":\"server_vad\"}` or `{\"type\":\"semantic_vad\"}`; `null` = client-side manual commit |\n| `audio.input.format` | input format, e.g. `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | output format, e.g. `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | system persona |\n| `audio.input.transcription` | input transcription; the server enables it automatically (model `qwen3-asr-flash-realtime`) |\n\nThe legacy `input_audio_format` / `output_audio_format` fields still work, but new integrations should use `audio.input.format` / `audio.output.format`.\n\n## Interruption\n\nWith a non-`null` `turn_detection`, the server VAD drives turns. When the user speaks again:\n\n1. the server emits `input_audio_buffer.speech_started`;\n2. the client **stops playing** buffered reply audio and sends `response.cancel`;\n3. the server then emits `response.done` (status cancelled) and starts a new turn.\n\nIn manual mode (`turn_detection: null`) the client sends `input_audio_buffer.commit` and `response.create` after recording.\n\n## Billing {#billing}\n\n- **Token-based, per modality**: input is split into text/image/video and audio; output into text and audio. When the model produces speech, the audio **and** its transcript text are billed separately.\n- **Preauthorization at connect**: a session-level estimate is held when the connection opens (currently about ¥1.2). If the balance cannot cover it, the handshake returns `402` and no connection is established.\n- **Settled after close on actual usage**: the total of every `response.done` `usage` over the connection is settled at close — refund or top-up applies. A session that meters nothing releases the hold and charges nothing.\n\nCheck the console model page for current prices; for example, domestic `qwen3.8-omni-flash-realtime` (CNY / million tokens) is priced at input text/image/video `1.5`, input audio `6`, output text `4.5`, output audio `12`.\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced; the socket is closed and settled at the cap) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Audio history | up to 100 turns / 600 s |\n| Video history | up to 50 turns / 240 s |\n| Upstream rate limit | 60 RPM |\n\n## Next steps\n\n- [API reference: `GET /api-ws/v1/realtime`](./api)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","china/en/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: Re-order candidate documents by relevance to a query.\n---\n\n# Rerank\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | Re-rank documents by relevance to a query |\n| `POST` | `/v1/reranks` | Alias, equivalent to `/v1/rerank` |\n\nThe Rerank endpoint takes a query and a set of candidate documents and returns them ordered by relevance. It is commonly used for the re-ranking stage in retrieval-augmented (RAG) pipelines. `/v1/rerank` and `/v1/reranks` are two equivalent paths to the same capability.\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"Which protocols does ModelGo support\",\n    \"documents\":[\n      \"OpenAI and Anthropic compatible protocols\",\n      \"The weather is nice today\",\n      \"Supports image, video, vector, and audio capabilities\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## Key conventions\n\n- `model` must be the platform logical model name; the body is forwarded per the upstream Rerank protocol, and whether specific fields (e.g. `top_n`, `return_documents`) take effect depends on the routed upstream model.\n- The response typically contains a relevance score and rank index for each document.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","china/en/models/text/generation.md":"---\ntitle: Text Generation\ndescription: Unified guidance for OpenAI Responses, Chat Completions compatibility, and Anthropic Messages.\n---\n\n# Text Generation\n\nThe gateway exposes the following public text entrypoints. Prefer `POST /v1/responses` for new integrations, and use the others for SDK compatibility or native Claude clients.\n\n| Protocol | Method and path | Use |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | Preferred unified text generation API for new projects |\n| OpenAI | `POST /v1/chat/completions` | Widely compatible chat completion endpoint |\n| OpenAI | `POST /v1/completions` | Legacy text completions, only for compatibility |\n| Anthropic | `POST /v1/messages` | Claude native message format |\n| OpenAI | `GET /v1/models` | List logical models available under the current routing |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"Introduce ModelGo in three sentences.\"\n  }'\n```\n\nUse this entrypoint when you want a single OpenAI-compatible response API with a forward-looking request shape.\n\n## OpenAI Chat Completions compatibility {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this for existing OpenAI SDK flows that still depend on chat completions. New projects should usually start from `POST /v1/responses`.\n\n## OpenAI Completions (legacy)\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"Introduce ModelGo in three sentences.\",\n    \"max_tokens\":256\n  }'\n```\n\nThe legacy text-completions endpoint, only for call chains that still use a `prompt`. New projects should use Responses or Chat Completions above. `stream` is likewise delivered over SSE. Most current chat models do not offer this protocol: `qwen3.6-flash` returned HTTP 400 `model_protocol_not_offered` on 2026-09-10.\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this when the client already speaks Claude's native `/v1/messages` schema. The gateway preserves the native event-stream framing for streamed Anthropic responses.\n\n## Listing models\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` returns the logical models allowed by the API key's bound policy (resolved against the platform model catalog). It does not probe upstream capabilities at request time and may differ from the console; billing and policy follow the console and bound policies.\n\n## Key conventions\n\n- `model` must be the platform logical model name.\n- `GET /v1/models` is available; the list is derived from the API key's bound policy and the platform model catalog.\n- Both OpenAI and Anthropic style endpoints may return upstream-native `usage`.\n- Stream failures may arrive as error chunks; do not rely only on `data: [DONE]`.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","china/en/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI-compatible embedding endpoint.\n---\n\n# Embeddings\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Multimodal (image/text) embeddings |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` may be a single string or an array of strings. The response follows the OpenAI-compatible embeddings shape.\n\n## Multimodal embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\nFor embedding inputs that mix text and image content. The `input` shape depends on the routed model's multimodal capabilities; whether it takes effect is determined by the upstream model.\n","china/en/models/video/ark.md":"---\ntitle: Seedance\ndescription: Drive platform-managed async Seedance video tasks over Ark's own paths, with Ark-shaped request and response bodies.\n---\n\n# Seedance\n\nBeyond the standard video protocols, the Doubao Seedance series (`doubao-seedance-*`) can also be\ncalled over **Volcengine Ark's own paths**, with request and response bodies following Ark's\ncontent-generation protocol:\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | Create a content generation (video) task |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Poll task status and result |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent**, see below) |\n\nThis is a **platform-managed** lane: the path is Ark's own, but the request runs on the gateway's\nstandard async task pipeline — the very same one behind\n[Generic Async Content Generation Tasks](./async-tasks), just spelled with Ark's path. It therefore\nkeeps per-dimension metering, task persistence, artifact delivery, and preauthorize/settle intact.\n\n## Create a task\n\nThe body follows Ark's content-generation protocol, and `model` is the **platform logical model\nname** (e.g. `doubao-seedance-2.0-mini`):\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a neon city cat\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\nBeyond text, the `content` array can carry images/videos, tagged by `role`; **the media combination\ndetermines the generation mode, and the mode determines which parameters are legal**:\n\n| content element | `role` | Generation mode |\n| --- | --- | --- |\n| `text` only | — | Text-to-video (t2v) |\n| `image_url` | `first_frame` | First-frame image-to-video (i2v) |\n| `image_url` | `first_frame` + `last_frame` | First/last-frame (flf2v) |\n| `image_url` / `video_url` | `reference_image` / `reference_video` | Multimodal reference-to-video |\n\n### Parameter and mode constraints\n\nValid values for `resolution` / `ratio` / `duration` **vary by model** — the Fast and Mini variants of\nSeedance 2.0, for instance, do not support `1080p`, and `duration` has a floor of 4 seconds. Ark\nextension parameters such as `camera_fixed`, `generate_audio`, `return_last_frame` and `watermark`\n**also vary by generation mode**. Sending a parameter the current model/mode does not support is\nrejected by the upstream at create time (`400` `provider_invalid`). One known case:\n\n- **`camera_fixed` is not supported in the first/last-frame (flf2v) scenario** — a request carrying\n  both `first_frame` and `last_frame` is refused when it also sets `camera_fixed`\n  (`camera_fixed ... must be empty`). First/last-frame already constrains the camera; if you need a\n  locked-off camera, use a mode that supports it (e.g. text-to-video or single first-frame).\n\nBecause this lane **does not pin an upstream family** (the same logical model is served by several\nsuppliers), whether a parameter is accepted also depends on the supplier and model version actually\nserving the call. Treat the model capability notes plus the mode constraints above as authoritative,\nand **do not assume a parameter that works in one mode works in another**.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll answer with exactly the Ark task object documented under\n[Generic Async Content Generation Tasks](./async-tasks) — it is the same pipeline, so the response\npayload and every field's meaning (`status` values, `content.video_url`, `error`, when `usage` is\nomitted) are identical to that page and are not repeated here.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nA successful cancel voids the preauthorization; nothing is settled.\n\n**Not every upstream supports cancelling, though.** Whether a task can be cancelled depends on\nwhether the supplier serving it implements cancellation, and because this lane does not pin an\nupstream family, two calls on the same logical model may differ — one cancellable, one not. Two\nfailure shapes:\n\n| Case | Response |\n| --- | --- |\n| The supplier serving the task cannot cancel | `400` / `4003` `provider_unsupported`, `endpoint not supported by provider` |\n| The task already reached a terminal state (`succeeded` / `failed`) | `409` `task_already_terminal`, `task already finished; nothing to cancel` |\n\nWhen a cancel fails the preauthorization is not released early — it follows the normal\nsettle/expiry path once the task reaches a terminal state. So **do not treat \"create then cancel\"\nas a reliable way to back out of a charge.**\n\n## Key conventions\n\n- **`id` is the gateway task id, not the upstream one.** Polling and cancelling only accept that id,\n  so hold on to the `id` returned by create.\n- **The response shape is fixed.** Whichever upstream actually serves the request, create and poll\n  both answer with the same Ark task object — it does not change when routing changes.\n- **The lane does not pin an upstream family.** The URL spelling plays no part in routing: whoever\n  the logical model behind `model` routes to serves it. Seedance is carried by several suppliers on\n  the platform, so two calls on the same logical model may land on different upstreams — that is\n  expected.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the Ark paths — use `content.video_url` from the response.\n- Whether a model is offered on this lane depends on its catalog `public_protocols` including\n  `content_generation`; without it the call is refused with `4005`. Check with\n  `GET {{ api_endpoint }}/v1/models`.\n\nIf you do not need Ark's path and field style, [OpenAI-Compatible Video Flow](./openai-compatible) is\nthe more standardized choice.\n","china/en/models/video/async-tasks.md":"---\ntitle: Async Tasks\ndescription: A platform-managed async task entrypoint for image, video, and other content generation capabilities.\n---\n\n# Async Tasks\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | Create a generic async content generation task (image / video / ...) |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | Poll a generic content generation task |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent** — see \"Cancel a task\" in [Seedance Video Inbound Protocol](./ark)) |\n\n`/v1/content_generation/tasks` is a more general async task entrypoint than the standard OpenAI-compatible video flow. It covers image, video, and other generation capabilities that must run as backend tasks.\n\n## Create a task\n\nThe body follows the upstream generic generation shape and must include at least `model`:\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\nVerified 2026-09-10 on domestic production: create returned `status=queued` with a `gw_…` id; polling the same id ended at `succeeded` with `resolution=720p`, `ratio=16:9`, `duration=5`. The same model on `POST /v1/video/generations` is `model_protocol_not_offered`. `DELETE` cancel returned `provider_unsupported` on that upstream.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll both answer with the **same** Ark-shaped task object, regardless of which upstream served the request:\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` is one of `queued` / `running` / `succeeded` / `failed`; `id` is the **gateway task id**, and it is the only id polling and cancelling accept.\n\n## Three spellings, one pipeline\n\nThe same managed async pipeline has three inbound spellings. Which one you pick depends only on whose payload style you want to write your client against:\n\n| Entry point | Request body | Response body |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | Generic generation shape | Ark task object (above) |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark content-generation native body | Ark task object |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax video-generation V2 native body | MiniMax shapes (`{\"task_id\"}` / `{\"task\":{…}}`) |\n\nBilling, task persistence, artifact delivery, and preauthorize/settle behave identically across all three.\n\n## When to use it\n\n- The platform capability is asynchronous but does not use the OpenAI Video-standard request / response shape\n- You want a unified platform-managed create-and-poll flow instead of handling each vendor's native protocol yourself\n- You are calling a video model such as Jimeng that is exposed only through the managed async lane\n\n## Key conventions\n\n- `model` is still the platform logical model name; the platform decides which upstream implementation handles the task.\n- Request fields depend on the routed capability; the response shape, by contrast, is fixed — see above.\n- If you do not want to manage multiple vendor-specific polling styles, prefer this entrypoint.\n\nFor the standard OpenAI-compatible video protocol, see [OpenAI-Compatible Video Flow](./openai-compatible).\n","china/en/models/video/kling-v3.md":"---\ntitle: Kling 3.0\ndescription: Call kling-v3 on Kling's official API — text2video / image2video, mode tiers, the sound switch, polling, download and billing. Kling's official SDK works by changing the host.\n---\n\n# Kling 3.0\n\n| Endpoint | Capability | Required fields |\n| --- | --- | --- |\n| `POST /kling/v1/videos/text2video` | Text to video | `model_name`, `prompt` |\n| `POST /kling/v1/videos/image2video` | Image to video (first frame, optional last frame) | `model_name`, `prompt`, `image` |\n\nModelGo accepts Kling's official API paths and request/response shapes (`model_name`, `mode`, `sound`, `duration`, `aspect_ratio`, …); the gateway routes to a supplier and bills. Which supplier renders the clip is invisible to the caller. Polling follows the official rule: **the same path + `/{task_id}`**.\n\n> With Kling's official SDK or samples, replace the API host with `{{ api_endpoint }}/kling` and authenticate with `Authorization: Bearer $MODELGO_API_KEY` (no Kling JWT signing).\n\n## 1. Create a task\n\n### Text to video\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\",\n    \"mode\": \"std\",\n    \"duration\": \"5\",\n    \"aspect_ratio\": \"16:9\",\n    \"sound\": \"on\",\n    \"cfg_scale\": 0.5\n  }'\n```\n\n### Image to video\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/image2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"The dog slowly turns its head\",\n    \"image\": \"https://example-cdn.com/dog.jpg\",\n    \"mode\": \"pro\",\n    \"duration\": \"5\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"task_status\": \"submitted\", \"created_at\": 1788773081000, \"updated_at\": 1788773081000}\n}\n```\n\n`data.task_id` is the gateway task id; use it to poll and to fetch content.\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model_name` | string | all | Always `kling-v3` |\n| `prompt` | string | all | Required on text2video; optional on image2video (as in the official API). ≤ 2500 chars |\n| `image` | string | image2video | Required. **Publicly downloadable** URL of the first frame. A text2video request must not carry `image` / `image_tail` (it is refused rather than silently treated as text-to-video). The current supplier channels do not take inline base64 images (bare base64 or a `data:` URI) and return `400` (`error_class=provider_unsupported`) |\n| `image_tail` | string | image2video | Last-frame image URL; send it together with `image`: an `image_tail`-only request gets `400` (`error_class=provider_unsupported`) from the current supplier channels |\n| `mode` | string | all | Tier: `std` (720P), `pro` (1080P) or `4k`, **default `std` (720P)**, the same as the official Kling protocol; a request with no tier is billed at 720P |\n| `duration` | string / int | all | Whole seconds, 3–15, default `5` |\n| `aspect_ratio` | string | text2video | `16:9` / `9:16` / `1:1`, default `16:9`; image to video follows the first frame |\n| `sound` | string | all | `on` / `off`, default `off`. **Switches to the with-audio price tier** |\n| `negative_prompt` | string | all | Negative prompt |\n| `cfg_scale` | number | all | Prompt adherence in [0, 1], default 0.5 |\n| `watermark_info` | object | all | Watermark settings, forwarded to the supplier as sent; does not affect billing. `enabled: true` works only on supplier channels that forward the field; others return `400` (`error_class=provider_unsupported`) |\n| `multi_shot` | bool | all | Storyboard switch, default `false` |\n| `shot_type` | string | all | Required when `multi_shot=true`: `customize` (you write each shot) or `intelligence` (the model splits the main prompt) |\n| `multi_prompt` | array | all | Required when `shot_type=customize`, 1–6 items: `index` (unique integer from 1), `prompt` (≤512 characters), `duration` (whole seconds); the shot durations must add up to `duration`, so `duration` must be stated explicitly. text2video still needs the main `prompt` |\n| `voice_list` | array | image2video | 1–2 items `{\"voice_id\": \"…\"}`; requires `sound=on`; cannot be combined with `element_list` |\n| `element_list` | array | image2video | 1–3 items, each with an integer `element_id` |\n| `callback_url` / `external_task_id` | string | all | Accepted but inert: the gateway does not call back; poll by `task_id` |\n\n- Fields outside this table (e.g. `camera_control`, `static_mask`, `dynamic_masks`) are refused at create time (HTTP `400`), never ignored.\n- The storyboard, voice and element fields (`multi_shot` / `shot_type` / `multi_prompt` / `voice_list` / `element_list`) are routed only to supplier channels that forward them unchanged; when no such channel is available the request returns `400` (`error_class=provider_unsupported`) instead of being silently dropped and billed as a plain clip. Billing follows `duration` (the sum of the shot durations) and `sound`; these fields do not change the unit price themselves.\n\n### Tiers\n\n| `mode` | Output |\n| --- | --- |\n| `std` | 1280×720 (per aspect ratio), default |\n| `pro` | 1920×1080 (per aspect ratio) |\n| `4k` | 4K (per aspect ratio), served only by suppliers that render it; priced separately |\n\n- **Only these three tiers are offered.** Any other value is refused at create time (HTTP `400`). The gateway routes by deliverable tier: a `4k` request only goes to a supplier that renders 4K and is never downgraded silently; if no 4K-capable supplier is available the create returns `400` and nothing is charged.\n\n### First-frame image requirements (image2video)\n\n- A direct link the upstream can `GET`; JPG / PNG, ≤ 10 MB, each side ≥ 300 px, aspect 1:2.5–2.5:1.\n- A frame the upstream cannot fetch fails the task (`task_status=failed`) without billing. Use your own object storage or CDN.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/kling/v1/videos/text2video/{task_id}` (tasks created via image2video poll at `.../image2video/{task_id}`)\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video/gw_6dce033e-9243-4a64-9c57-73d08a8e379a \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"succeed\",\n    \"task_result\": {\"videos\": [{\"id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"url\": \"{{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content\", \"duration\": \"6\"}]},\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773250000\n  }\n}\n```\n\n- `task_status`: `submitted` → `processing` → `succeed` / `failed`. On failure `task_status_msg` carries the reason and the task is **not billed**.\n- Generation usually takes 1–3 minutes; poll every 5–10 s with backoff.\n- `videos[].url` points at the gateway content endpoint (API key required); `duration` is the delivered length in seconds.\n\n## 4. Download the video\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o kling.mp4\n```\n\nStreams `video/mp4`, `Range` supported. Only the owning API key (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}/kling/v1/videos\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\"}\n\ndef generate(kind: str, body: dict, out: str, timeout: int = 600) -> None:\n    body.setdefault(\"model_name\", \"kling-v3\")\n    r = requests.post(f\"{BASE}/{kind}\", json=body, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"data\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        data = requests.get(f\"{BASE}/{kind}/{task_id}\", headers=H, timeout=30).json()[\"data\"]\n        if data[\"task_status\"] == \"succeed\":\n            break\n        if data[\"task_status\"] == \"failed\":\n            raise RuntimeError(data.get(\"task_status_msg\", \"generation failed\"))\n        time.sleep(8)\n    url = data[\"task_result\"][\"videos\"][0][\"url\"]\n    with requests.get(url, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"text2video\", {\"prompt\": \"A small red ball rolling across a wooden table\", \"mode\": \"std\", \"duration\": \"5\", \"sound\": \"on\"}, \"t2v.mp4\")\ngenerate(\"image2video\", {\"prompt\": \"The dog slowly turns its head\", \"image\": \"https://example-cdn.com/dog.jpg\", \"mode\": \"pro\", \"duration\": \"5\"}, \"i2v.mp4\")\n```\n\n## 6. Billing\n\n- **Video seconds × unit price**, keyed on three dimensions: input mode (text / image), tier (`std` 720P / `pro` 1080P / `4k`) and audio (`sound`).\n- The requested `duration` is pre-authorized at create time; the task settles on the **delivered** seconds. Some suppliers deliver about one extra second (5 s requested, 6 s delivered); `videos[].duration` is the settled figure.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`failed`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `mode` not `std`/`pro`/`4k`; `sound` not `on`/`off`; `model_name` missing; `prompt` missing on text2video; neither `image` nor `image_tail` on image2video; a frame that is neither an http(s) URL nor a base64 image; `image`/`image_tail` sent to text2video; a field outside the parameter table; no supplier renders the requested tier right now | Fix per the parameter table or switch endpoint / tier |\n| Create returns `400` with `error_class=provider_unsupported` | `image_tail` sent alone, or an inline base64 image: the current supplier channels do not support it | Send `image` as well; pass frames as public URLs |\n| `task_status=failed` | Upstream could not fetch the first frame, or generation failed | Use a publicly downloadable direct link |\n| Poll returns `task_not_found` | `task_id` not created by this key, or polled under a different endpoint family | Poll on the same path used to create |\n| `/content` returns `409` / `404` | Not completed / artifact expired | Poll to `succeed`; download promptly |\n","china/en/models/video/minimax.md":"---\ntitle: MiniMax Video\ndescription: Drive platform-managed async video tasks with MiniMax video-generation V2 request and response bodies, for the MiniMax-H3 family.\n---\n\n# MiniMax Video\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | Create a video generation task |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | Poll task status and result |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | Cancel an unfinished task and release its preauthorization |\n\nThis is **MiniMax video generation V2** as an inbound protocol, aimed mainly at the MiniMax-H3 family.\nLike the Ark lane it runs on the platform-managed async pipeline — the request body is MiniMax's own\nshape, and **the responses are rendered in MiniMax's shape too**, so a client written against\nMiniMax's own documentation can decode this surface directly.\n\nThe task lives on the platform, so per-dimension metering, artifact\ndelivery, and preauthorize/settle all apply as usual.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a boy playing basketball by the sea\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\nCreate answers the bare task handle from MiniMax's documentation:\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### Request fields\n\n`content[]` is a multimodal array; `type` and `role` together decide what each part is:\n\n| `type` | Valid `role` | Meaning |\n| --- | --- | --- |\n| `text` | — | Prompt |\n| `image_url` | `first_frame` / `last_frame` | First / last frame image |\n| `image_url` | `reference_image` | Reference image |\n| `video_url` | `reference_video` | Reference video |\n| `audio_url` | `reference_audio` | Reference audio |\n\n- **Frames and references cannot be mixed**: a request carrying `first_frame` / `last_frame` may not\n  also carry any `reference_*` part, and vice versa — they map to two different upstream jobs.\n- `resolution`, `duration`, and `ratio` are flat siblings of `content`. For MiniMax-H3 the accepted\n  values are `resolution` ∈ `768P` / `2K`, `duration` an integer in `4`–`15`, and `ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`. Omitting one applies the upstream default\n  (`2K`, 5 seconds) — **and bills at that default tier**.\n- Prompt length is capped at roughly 7000 characters.\n- Which values are actually supported still depends on the logical model behind `model`.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nPoll answers a `task` envelope — a **different shape** from create:\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` is one of `queued` / `running` / `succeeded` / `failed`.\n- On success the artifact URL is in `task.content.url`.\n- `usage` is denominated in **seconds** (H3 is quoted per second of output), not tokens; it is\n  omitted when the upstream reports only token counts and no seconds.\n- On failure a `task.error` (`code` / `message`) is added. That field is not part of MiniMax's\n  documented success schema — it is included so a failure reason is visible at all, and a client\n  decoding the documented struct simply ignores it.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCancelling voids the preauthorization. Note that this lane never reports MiniMax's documented\n`cancelled` status — a cancelled task is surfaced as `failed`, which is what makes its\npreauthorization be released rather than settled.\n\n## Key conventions\n\n- **`id` / `task_id` are the gateway task id**, not the upstream one; polling and cancelling only\n  accept that id.\n- The lane does not pin an upstream family; the logical model behind `model` decides who serves the\n  request, and the URL spelling plays no part in it.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the MiniMax paths.\n\nFor the most standardized experience, use [OpenAI-Compatible Video Flow](./openai-compatible).\n","china/en/models/video/openai-compatible.md":"---\ntitle: OpenAI-Compatible Video Flow\ndescription: Standard OpenAI Video-compatible endpoints for task creation, polling, and asset retrieval.\n---\n\n# OpenAI-Compatible Video Flow\n\n> **Video models accept their vendor's official native protocol only**: [Wan 2.7 (DashScope)](./wan27), [Kling 3.0 (Kling)](./kling-v3), [Veo 3.1 (Google)](./veo31). `wan2.7-t2v` / `wan2.7-i2v` / `kling-v3` / `veo-3.1` / `veo-3.1-fast` no longer accept `POST /v1/video/generations` on this page (the gateway answers `400` with `app_error_id=4005 model_protocol_not_offered`). Task polling `GET /v1/videos/{task_id}` and the artifact endpoint `GET /v1/videos/{task_id}/content` keep working for tasks created on the native protocols; the generic async lane is documented under [Async content generation tasks](./async-tasks).\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | Create an OpenAI-compatible video task |\n| `GET` | `/v1/videos/{task_id}` | Poll video task status and result |\n| `GET` | `/v1/videos/{task_id}/content` | Fetch the produced content of a finished video task |\n\nThis set of endpoints is the platform's **standard video protocol**: the request uses OpenAI Video-compatible fields, and the platform translates it into the upstream vendor's async video task format.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\nA successful create returns a `task_id`. Subsequent polling and content fetches are all keyed by that `task_id`.\n\n## Poll task status\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` is one of `queued` / `in_progress` / `completed` / `failed`; on `completed`, the produced asset URL appears in `metadata.url`.\n\n## Fetch the asset\n\nOnce the task is done, you can fetch the asset bytes through the content endpoint. The gateway **streams the `video/mp4` bytes directly** (no `302` redirect to object storage), supports `Range` requests, and only the API key that owns the task (or a console session in the same tenant) may read it:\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\nContent availability depends on the backend \"media delivery\" setting:\n\n- `404` (`content_delivery_disabled`) when delivery is disabled\n- `409` (`task_not_completed`) when the task is still running\n- `404` (`content_not_available`) when the asset has expired or is missing\n\n## Key conventions\n\n- This is the standard OpenAI-compatible video entrypoint; clients do not need to understand vendor-native protocols.\n- Whether fields such as `duration` or `size` are supported, and which upstream vendor is selected, depends on the logical model referenced by `model`.\n- Video generation is asynchronous. Poll with backoff to avoid unnecessary rate-limit pressure.\n\nFor the more generic async task entrypoint, see [Generic Async Content Generation Tasks](./async-tasks). To write against a vendor's own payload style while keeping platform-managed billing and task handling, see the [Seedance Video Inbound Protocol](./ark) and the [MiniMax Video Inbound Protocol](./minimax).\n","china/en/models/video/veo31.md":"---\ntitle: Veo 3.1\ndescription: Call veo-3.1 and veo-3.1-fast on the official Google Gemini API Veo protocol — predictLongRunning create, operations polling, download, USD billing. The Google GenAI SDK works by changing base_url.\n---\n\n# Veo 3.1\n\n| Official model id (in the path) | Platform model | Positioning |\n| --- | --- | --- |\n| `veo-3.1-generate-preview` | `veo-3.1` | Quality model, native audio |\n| `veo-3.1-fast-generate-preview` | `veo-3.1-fast` | Speed-optimized, lower cost |\n\nModelGo accepts Veo requests on the Google Gemini API **long-running-operation** protocol unchanged: `predictLongRunning` create → `operations` poll → download. The body matches Google's documentation (`instances` + `parameters`); the gateway routes to a supplier and bills.\n\n> With the Google GenAI SDK, set `http_options.base_url` to `{{ api_endpoint }}` and use your ModelGo API key. Both `x-goog-api-key: $KEY` and `Authorization: Bearer $KEY` are accepted.\n\n## 1. Create a task\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:predictLongRunning` (`/v1/models/...` is accepted too)\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"instances\": [{\"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\"}],\n    \"parameters\": {\"aspectRatio\": \"16:9\", \"resolution\": \"1080p\", \"durationSeconds\": 8, \"generateAudio\": true}\n  }'\n```\n\n### Response\n\n```json\n{\"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\", \"done\": false}\n```\n\n`name` is the official operation name; its last segment is the gateway task id. Poll by appending `name` to `/v1beta/`.\n\n## 2. Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `instances[0].prompt` | string | Required for text-to-video; may be omitted when `image` is given. Scene and motion description |\n| `instances[0].image` | object | First frame (image to video). **URL forms only**: `{\"imageUri\": \"https://...\"}` / `gcsUri`; inline `bytesBase64Encoded` is refused |\n| `instances[0].lastFrame` | object | Last frame, same forms |\n| `parameters.resolution` | string | `720p` or `1080p`, **default `720p`** |\n| `parameters.durationSeconds` | int | `4` / `6` / `8`, default `8`. **1080p requires 8 seconds** |\n| `parameters.aspectRatio` | string | `16:9` or `9:16`, default `16:9` |\n| `parameters.generateAudio` | boolean | Veo 3.1 always generates an audio track; billing does not distinguish audio |\n| `parameters.negativePrompt` | string | Negative prompt |\n| `parameters.seed` | int | Random seed |\n| `parameters.sampleCount` / `numberOfVideos` | int | Must be `1` — one video per task; larger values are refused |\n| `parameters.personGeneration` | string | Passed through |\n\n### Resolution tiers\n\n| Tier | Output |\n| --- | --- |\n| `720p` | 1280×720 (16:9) / 720×1280 (9:16), default |\n| `1080p` | 1920×1080 / 1080×1920 |\n\n- **Only these two tiers are offered.** `4k` is refused at create time (HTTP `400`); nothing is rendered at a lower tier silently and nothing is charged.\n- One video per task; exactly one `instance` is accepted.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/v1beta/{operation.name}`, i.e. `GET /v1beta/models/{model}/operations/{task_id}`\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\",\n  \"done\": true,\n  \"response\": {\n    \"@type\": \"type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse\",\n    \"generateVideoResponse\": {\"generatedSamples\": [{\"video\": {\"uri\": \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\"}}]}\n  }\n}\n```\n\n- `done=false` while running; on failure `done=true` with `error.{code,message}` and the task is **not billed**.\n- An 8-second clip usually takes 1–2 minutes; poll every 5–10 s with backoff.\n- Transient upstream errors surface as `502` at create; not billed, just retry.\n\n## 4. Download the video\n\n`generatedSamples[].video.uri` points at the gateway content endpoint; as with Google's own uri, the API key is required:\n\n```bash\ncurl \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -o veo.mp4\n```\n\nStreams `video/mp4` (with an AAC track), `Range` supported. Only the owning API key (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"x-goog-api-key\": os.environ[\"MODELGO_API_KEY\"]}\n\ndef generate(model: str, prompt: str, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/v1beta/models/{model}:predictLongRunning\",\n                      json={\"instances\": [{\"prompt\": prompt}], \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    name = r.json()[\"name\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(name)\n        op = requests.get(f\"{BASE}/v1beta/{name}\", headers=H, timeout=30).json()\n        if op.get(\"done\"):\n            break\n        time.sleep(8)\n    if \"error\" in op:\n        raise RuntimeError(op[\"error\"][\"message\"])\n    uri = op[\"response\"][\"generateVideoResponse\"][\"generatedSamples\"][0][\"video\"][\"uri\"]\n    with requests.get(uri, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"veo-3.1-fast-generate-preview\", \"A small red ball rolling across a wooden table\",\n         {\"resolution\": \"1080p\", \"durationSeconds\": 8, \"aspectRatio\": \"16:9\"}, \"veo-fast.mp4\")\ngenerate(\"veo-3.1-generate-preview\", \"A cinematic drone shot over a misty forest at dawn\",\n         {\"resolution\": \"720p\", \"durationSeconds\": 4}, \"veo.mp4\")\n```\n\n## 6. Billing\n\n- **Priced in USD**, billed as **video seconds × resolution-tier unit price**, converted to the account currency at the daily rate on settlement.\n- The requested `durationSeconds` are pre-authorized at create time; the task settles on the delivered seconds.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`done=true` + `error`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `resolution` outside 720p / 1080p; `sampleCount` > 1; several `instances`; inline base64 `image` | Fix per the parameter table; use an image URL |\n| Create returns `502` | Transient upstream error | Retry; not billed |\n| Poll returns `task_not_found` | The operation was not created by this key | Check `name` and the key |\n| Download `409` / `404` | Not completed / artifact expired | Poll to `done=true`; download promptly |\n","china/en/models/video/wan27.md":"---\ntitle: Wan 2.7\ndescription: Call wan2.7-t2v / wan2.7-i2v on Alibaba Bailian's official DashScope video-synthesis API — create, poll, download, billing. The official DashScope SDK works by changing base_url.\n---\n\n# Wan 2.7\n\n| Model | Capability | Required fields |\n| --- | --- | --- |\n| `wan2.7-t2v` | Text to video | `input.prompt` |\n| `wan2.7-i2v` | Image to video (first frame, optional last frame) | `input.prompt`, `input.img_url` (or a `first_frame` in `input.media[]`) |\n\nWan 2.7's official protocol is Alibaba Bailian's **DashScope asynchronous video synthesis** API. The ModelGo gateway accepts the official paths and request/response shapes unchanged: **create → poll → fetch content**. Which supplier renders the clip is a routing decision inside the gateway and invisible to the caller.\n\n> With the official DashScope SDK, point `base_url` (`DASHSCOPE_HTTP_BASE_URL`) at `{{ api_endpoint }}` and use your ModelGo API key as `api_key`.\n\n## 1. Create a task\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis`\n\nHeaders: `Authorization: Bearer $MODELGO_API_KEY`, `X-DashScope-Async: enable`, `Content-Type: application/json`.\n\n### Text to video\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-t2v\",\n    \"input\": {\"prompt\": \"A fluffy orange kitten playing with a ball of yarn on a sunny windowsill\"},\n    \"parameters\": {\"resolution\": \"1080P\", \"duration\": 5, \"prompt_extend\": true}\n  }'\n```\n\n### Image to video\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-i2v\",\n    \"input\": {\"prompt\": \"The cat slowly tilts its head and blinks\", \"img_url\": \"https://example-cdn.com/cat.jpg\"},\n    \"parameters\": {\"resolution\": \"720P\", \"duration\": 5}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\", \"task_status\": \"PENDING\", \"submit_time\": \"2026-09-07 17:05:59.000\"},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n`output.task_id` is the gateway task id; use it to poll and to fetch content.\n\n## 2. Parameters\n\n| Field | Type | Applies to | Description |\n| --- | --- | --- | --- |\n| `model` | string | all | `wan2.7-t2v` or `wan2.7-i2v` |\n| `input.prompt` | string | all | Required. Scene and motion description |\n| `input.img_url` | string | i2v | Required (or use a `first_frame` in `input.media[]` instead). **Publicly downloadable** URL of the first frame. A `wan2.7-t2v` request must not carry `img_url` / `last_frame_url` (or a `media` `first_frame` / `last_frame`) (it is refused rather than silently treated as text-to-video) |\n| `input.last_frame_url` | string | i2v | Last-frame image URL for first/last-frame interpolation |\n| `input.audio_url` | string | all | Driving audio URL (wav/mp3) |\n| `input.media[]` | object[] | all | Bailian's wan2.7 new-protocol spelling, items `{\"type\": ..., \"url\": ...}`: `first_frame` = `img_url`, `last_frame` = `last_frame_url` (both i2v only), `driving_audio` = `audio_url`. `first_clip` = `first_clip_url` (video continuation, i2v only, see below). One slot must not be given in both spellings; any other `type` is refused |\n| `input.negative_prompt` | string | all | Negative prompt |\n| `parameters.resolution` | string | all | Tier `720P` / `1080P`, default `1080P` |\n| `parameters.ratio` | string | all | Aspect ratio `16:9` (default) / `9:16` / `1:1` / `4:3` / `3:4`; with `resolution` it determines the output size (see the table below). `aspect_ratio` is accepted too; if both are sent they must match |\n| `parameters.size` | string | t2v | Pixel spelling of the same tier, e.g. `1280*720`, `1920*1080`; if sent together with `ratio`, the aspect ratios must match |\n| `parameters.duration` | int | all | Duration in seconds, default `5` |\n| `parameters.prompt_extend` | boolean | all | Let the upstream rewrite the prompt |\n| `parameters.watermark` | boolean | all | Add a watermark |\n| `parameters.seed` | int | all | Random seed |\n| `parameters.audio` | boolean | all | Generate audio. **Omitted = video with sound, billed at the audio tier** (Bailian's default); `true` = with sound, audio tier; `false` = silent video, silent tier. A top-level `generate_audio` (boolean or `\"true\"`/`\"false\"`) is accepted too. A `false` request is only routed to channels that can render silence; when none is available, creation returns `400` (`error_class=provider_unsupported`) and costs nothing |\n\n### Resolution tiers\n\n| Tier | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 |\n| --- | --- | --- | --- | --- | --- |\n| 720P | `1280*720` | `720*1280` | `960*960` | `1088*832` | `832*1088` |\n| 1080P | `1920*1080` | `1080*1920` | `1440*1440` | `1632*1248` | `1248*1632` |\n\n- For 4:3 / 3:4, `size` also accepts Bailian's spelling: 720P `1104*832` / `832*1104`, 1080P `1648*1248` / `1248*1648` — the same tier and price as the spelling in the table.\n- **Only 720P / 1080P are offered.** `4K` or a `size` outside the table is refused at create time (HTTP `400`); nothing is rendered at a lower tier silently and nothing is charged.\n- **Routed by deliverable tier.** The gateway only hands a request to a supplier that renders the stated tier (for example `wan2.7-t2v` at 720P is currently rendered by the official Bailian lane only); no supplier renders 1080P in its place while 720P is billed. If no supplier can render the tier right now the create returns `400` and nothing is charged.\n- `input` keys not in the table above (e.g. `ref_images_url`) are not supported on this endpoint and are refused rather than ignored.\n\n### Video continuation (`first_clip`, i2v only)\n\n- Send `{\"type\": \"first_clip\", \"url\": \"<video URL>\"}` in `input.media[]` (or the flat `input.first_clip_url`) to continue from an existing video. The clip must be a 2–10 s mp4 / mov at a **publicly downloadable** URL (not an authenticated address such as this gateway's own `/v1/videos/{id}/content`).\n- `wan2.7-i2v` only. It cannot be combined with `first_frame` (`img_url`) or `driving_audio` (`audio_url`); it may be paired with `last_frame`. Any violation is refused at creation with `400` and costs nothing.\n- Billed as i2v, at the same tier price as a non-continuation i2v call.\n- Not every supplier channel can carry a continuation: the gateway only routes it to channels confirmed to support it, and returns `400` (no charge) when none is available.\n\n### First-frame image requirements (i2v)\n\n- A direct link the upstream can `GET`: no auth, no redirects, no Referer / Cookie dependency.\n- Some hosts return 403 to non-browser fetches; the task then fails (`task_status=FAILED`) and is not billed. Use your own object storage or CDN.\n\n## 3. Poll the task\n\n`GET {{ api_endpoint }}/api/v1/tasks/{task_id}`\n\n```bash\ncurl {{ api_endpoint }}/api/v1/tasks/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nWhen finished:\n\n```json\n{\n  \"output\": {\n    \"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\",\n    \"task_status\": \"SUCCEEDED\",\n    \"submit_time\": \"2026-09-07 17:05:59.000\",\n    \"end_time\": \"2026-09-07 17:09:06.000\",\n    \"video_url\": \"{{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content\"\n  },\n  \"usage\": {\"video_duration\": 6, \"video_count\": 1},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n- `task_status`: `PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`. On failure `output.code` / `output.message` carry the reason and the task is **not billed**.\n- Generation usually takes 1–3 minutes; poll every 5–10 s with backoff.\n- `output.video_url` points at the gateway content endpoint and requires the API key. Do not persist it; artifacts have a retention period.\n\n## 4. Download the video\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o cat.mp4\n```\n\nStreams `video/mp4`, `Range` supported. Only the API key that owns the task (or a console session of the same tenant) may fetch it; `409` while not completed, `404` once expired or unknown.\n\n## 5. Full example (Python, SDK style)\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\", \"X-DashScope-Async\": \"enable\"}\n\ndef synthesize(model: str, inp: dict, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/api/v1/services/aigc/video-generation/video-synthesis\",\n                      json={\"model\": model, \"input\": inp, \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"output\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        o = requests.get(f\"{BASE}/api/v1/tasks/{task_id}\", headers=H, timeout=30).json()[\"output\"]\n        if o[\"task_status\"] == \"SUCCEEDED\":\n            break\n        if o[\"task_status\"] == \"FAILED\":\n            raise RuntimeError(o.get(\"message\") or o.get(\"code\"))\n        time.sleep(8)\n    with requests.get(o[\"video_url\"], headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\nsynthesize(\"wan2.7-t2v\", {\"prompt\": \"A fluffy orange kitten playing with yarn\"}, {\"resolution\": \"1080P\", \"duration\": 5}, \"t2v.mp4\")\nsynthesize(\"wan2.7-i2v\", {\"prompt\": \"The cat slowly tilts its head and blinks\", \"img_url\": \"https://example-cdn.com/cat.jpg\"}, {\"resolution\": \"720P\", \"duration\": 5}, \"i2v.mp4\")\n```\n\n## 6. Billing\n\n- **Video seconds × resolution-tier unit price.** The requested `duration` is pre-authorized at create time; the task settles on the **delivered** seconds (`usage.video_duration`). The upstream may deliver one extra second (5 s requested, 6 s delivered) — 6 s are billed.\n- **A request without a duration is pre-authorized at the default** (Wan / Kling 5 s, Veo 8 s) and that default is sent to the supplier; settlement uses the supplier-reported delivered length **rounded half-up to whole seconds** (5.041 → 5, 5.5 → 6), which may differ from the requested duration by ±1 s.\n- A refused create (`400`) or a failed generation (`FAILED`) is not billed and the hold is released.\n- Unit prices are those shown in the console model list.\n\n## Common errors\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Create returns `400` | `resolution` / `size` outside 720P / 1080P; `input.prompt` missing; `input.img_url` (or a `media` `first_frame`) missing on i2v; `input.img_url` / `input.last_frame_url` sent with a t2v model (use `wan2.7-i2v`); unsupported `input` key, or an `input.media[]` `type` that is unsupported or duplicates a legacy field; `ratio` outside the allowed values, or disagreeing with `aspect_ratio` / `size`; no supplier renders the requested tier right now | Fix per the parameter table or switch model / tier |\n| `task_status=FAILED` | Upstream could not fetch `img_url`, or generation failed | Use a publicly downloadable direct link |\n| Poll returns `task_not_found` | `task_id` was not created by this key | Check `task_id` and the key |\n| `/content` returns `409` / `404` | Not completed / artifact expired | Poll to `SUCCEEDED`; download promptly |\n","china/en/quickstart/agent-clients.md":"---\ntitle: AI Tool Setup\ndescription: Choose an AI client or Agent and use it with ModelGo models.\n---\n\n# AI Tool Setup\n\nModelGo supports common AI coding clients and Agents. After you create an API key, use the official configuration tool for one-click setup; clients not covered by that tool can be configured manually through a custom provider.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\nSelect one or more tools when prompted. To configure every supported tool in an automated workflow, use:\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n## Supported AI tools\n\n:::agent-tools\n| Tool | Official config tool | Manual setup docs |\n| --- | --- | --- |\n| Hermes Agent | Supported | [Setup guide](../agents/hermes-agent) |\n| Claude Code | Supported | [Setup guide](../agents/claude-code) |\n| Kilo Code | Not supported | [Setup guide](../agents/kilo-code) |\n| Cline | Not supported | [Setup guide](../agents/cline) |\n| Codex | Supported | [Setup guide](../agents/codex) |\n| OpenClaw | Supported | [Setup guide](../agents/openclaw) |\n| DeepSeek Harness | Not supported | [Setup guide](../agents/deepseek-harness) |\n| ZCode | Not supported | [Setup guide](../agents/zcode) |\n| Cursor | Not supported | [Setup guide](../agents/cursor) |\n| OpenCode | Supported | [Setup guide](../agents/opencode) |\n| CC Switch | Supported | [Setup guide](../agents/cc-switch) |\n| Cherry Studio | Not supported | [Setup guide](../agents/cherry-studio) |\n| Crush | Supported | [Setup guide](../agents/crush) |\n| Factory Droid | Supported | [Setup guide](../agents/factory-droid) |\n| Copilot CLI | Supported | [Setup guide](../agents/copilot-cli) |\n| nanobot | Supported | [Setup guide](../agents/nanobot) |\n| Oh My Pi | Supported | [Setup guide](../agents/oh-my-pi) |\n| CodeBuddy | Supported | [Setup guide](../agents/codebuddy) |\n| Kilo CLI | Not supported | [Setup guide](../agents/kilo-cli) |\n:::\n\n## Before you connect\n\n1. Create an API key in the [console]({{ console_endpoint }}/api-keys).\n2. Run the command above and select the clients or Agents you want to configure.\n3. Confirm the site, Base URL, and masked API key when prompted. The configuration tool verifies the connection automatically.\n\nTo manage your ModelGo account, models, calls, and Skills from the terminal, continue to [CLI Tools](cli).\n\n## Integration guide\n\nMost tools only need the following information to connect to ModelGo:\n\n1. **API address**: Use `{{ api_endpoint }}/v1` for OpenAI-compatible APIs, or `{{ api_endpoint }}` for Anthropic-compatible APIs.\n2. **API key**: The token created in [ModelGo Console]({{ console_endpoint }}/api-keys).\n3. **Model name**: The logical model ID selected from the [Model Catalog]({{ site_endpoint }}/models).\n\nSee the setup guide for each tool above for the exact configuration steps.\n","china/en/quickstart/authentication.md":"---\ntitle: Authentication\ndescription: API key handling, supported headers, precedence, and common auth failures.\n---\n\n# Authentication\n\nAll model endpoints authenticate with an API key.\n\n## Recommended header\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic-style clients may also use:\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini-style clients may also use:\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nWhen several are present, precedence is `Authorization` > `x-api-key` > `x-goog-api-key`.\n\n## Get & manage\n\n- Console: `{{ console_endpoint }}`\n- An API key is shown in full only once, at creation time\n- Revoking or disabling a key takes effect after the auth cache expires\n\n## Common failures\n\n| HTTP | error_class | Meaning |\n| --- | --- | --- |\n| `401` | `auth` | Missing, invalid, disabled, or expired API key |\n| `403` | `policy` | Key is valid but not allowed to call the model |\n\nSee [Errors & Rate Limits](errors) for the unified error shape.\n","china/en/quickstart/cli.md":"---\ntitle: CLI Tools\ndescription: Choose the official command-line tool for your task and complete your ModelGo setup.\n---\n\n# CLI Tools\n\nModelGo provides two official command-line tools. Choose the task you want to complete and run the corresponding command.\n\n:::tools\n@model-go/config | Connect AI coding clients | Configure Claude Code, Codex, and other common clients with one command. | npx @model-go/config -r {{ region_flag }} | View npm package | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | Use the official CLI | Pair it with official ModelGo Skills so an AI agent can operate ModelGo directly. | npx @model-go/cli@latest install | View npm package | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## Connect AI coding clients `@model-go/config` {#connect-ai-clients}\n\nTo use ModelGo in Claude Code, Codex, OpenCode, or another supported AI coding client, choose guided setup or configure all clients with a single command.\n\n**Guided setup**\n\nFollow the terminal prompts to enter your API key, select clients, review the configuration, and verify connectivity after the changes are written.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**One-command setup (non-interactive, suitable for automation)**\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n### Supported clients\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\nGuided setup lets you select one or more clients; use `--only all` to configure every supported client at once.\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Enter your [ModelGo API key]({{ console_endpoint }}/api-keys). |\n| `02` | Select one or more clients, or choose “Configure all.” |\n| `03` | Review the site, Base URL, masked API key, and selected clients. |\n| `04` | Confirm the changes, write the client configuration, and verify connectivity. |\n\n> **Setup succeeded:** the terminal reports that configuration is complete and the connectivity check passes, then shows how to start the selected client.\n\n[View @model-go/config on npm](https://www.npmjs.com/package/@model-go/config)\n\n## Let an AI agent operate ModelGo `@model-go/cli` {#install-agent-tools}\n\nInstall the official CLI and ModelGo Skills when you want an agent such as Claude Code or Codex to use ModelGo directly. The installer sets up the CLI, distributes Skills, selects the site, and optionally signs you in.\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Confirm installation of `@model-go/cli` when npm asks. |\n| `02` | Choose Simplified Chinese or English. The rest of the installation prompts will use your selected language. |\n| `03` | Install or upgrade the ModelGo CLI and install ModelGo Skills. |\n| `04` | Select the environment for this site (`{{ api_endpoint }}`). |\n| `05` | Choose whether to sign in through the browser now, or skip and run `modelgo auth login` later. |\n\n### Using the CLI after installation\n\nAfter installation, restart your AI agent or open a new session. ModelGo Skills lets the agent call the ModelGo CLI directly to perform queries and operations, so you can ask in natural language, for example:\n\n- “Which models does ModelGo currently support?”\n- “What is my current ModelGo account balance?”\n\nTo use the CLI yourself, run `modelgo` in your terminal to see every available command and option:\n\n```bash\nmodelgo\n```\n\nThe most common commands are grouped by task:\n\n| Task | Common commands | What they do |\n| --- | --- | --- |\n| Authentication | `modelgo auth login`, `modelgo auth status`, `modelgo auth logout` | Sign in to ModelGo, inspect the current authentication state, or clear local credentials. |\n| Environments | `modelgo env list`, `modelgo env current`, `modelgo env use <name>` | List environments, show the active environment, or switch sites. Use `env add` and `env remove` to manage custom environments. |\n| Workspaces | `modelgo tenant list`, `modelgo tenant use <slug>` | List the workspaces available to your account and use a workspace slug or ID to select the workspace for subsequent CLI commands. |\n| Account and usage | `modelgo balance`, `modelgo permissions`, `modelgo logs` | View balances and transactions, account permissions, call logs, and usage statistics. |\n| Model calls | `modelgo models`, `modelgo chat`, `modelgo embeddings`, `modelgo call` | List available models, make chat or embedding requests, or call any `/v1/*` model endpoint directly. |\n| Keys and payments | `modelgo key`, `modelgo pay` | Manage the model API key stored for the active environment or configure x402 pay-per-call payments. |\n| CLI maintenance | `modelgo update`, `modelgo --version`, `modelgo --help` | Update the CLI, print its version, or reopen the complete help output. |\n\nRun `modelgo <command> --help` to inspect the options for a specific command. For `balance`, `permissions`, and `logs`, you can also use the global `--tenant <slug\\|id>` option to target a workspace for that command only.\n\n[View @model-go/cli on npm](https://www.npmjs.com/package/@model-go/cli)\n\n:::note Security\n- Prefer the interactive API-key prompt instead of putting a key directly in a command.\n- Never commit an API key to source control or paste it into a shared script.\n- If you skipped login during CLI installation, run `modelgo auth login` later.\n:::\n\n## Continue exploring\n\n- [First API Call](quickstart): make your first model call.\n- [Authentication](authentication): learn how to use and protect your API key.\n","china/en/quickstart/errors.md":"---\ntitle: Errors & Rate Limits\ndescription: Unified error shape, common categories, and rate-limit handling.\n---\n\n# Errors & Rate Limits\n\n## Error shape\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\nBesides the `error` object, the body carries a top-level `trace_id` field (matching the `X-Trace-ID` response header; omitted when tracing is disabled) so you can grep logs by it. `metadata.reason` is an optional subtype (for example `model_not_in_catalog`). Full catalog and verified examples: [API catalog](openapi).\n\n## Common categories\n\n| error_class | HTTP | Meaning |\n| --- | --- | --- |\n| `client_invalid` | 400 | Bad request shape or parameters |\n| `model_protocol_not_offered` | 400 | The logical model does not declare this inbound protocol (`app_error_id=4005`). Switch endpoint or model |\n| `provider_invalid` | 400 | Upstream rejected the request (upstream returned a 4xx other than 401/403/408/429) |\n| `provider_unsupported` | 400 | The upstream does not support this endpoint (for example some video models reject `DELETE` cancel) |\n| `provider_timeout` | 408 | Upstream request timed out |\n| `auth` | 401 | API key authentication failed |\n| `billing_insufficient` | 402 | Insufficient balance |\n| `policy` | 403 | Model not allowed or no policy bound |\n| `quota` | 429 | Platform quota or limit hit |\n| `provider_rate_limit` | 429 | Upstream rate limit (upstream returned 429) |\n| `gateway_internal` | 500 | Gateway internal error (catch-all) |\n| `billing_system` | 502 | Billing system unavailable |\n| `provider_server` | 502 | Upstream server error |\n| `provider_unauthorized` | 502 | Upstream credential rejected (bucketed as 5xx; upstream-key issues are not exposed to callers) |\n| `provider_unavailable` | 503 | No available provider |\n| `route_unconfigured` | 503 | Model route has no upstream configured |\n\n## Billing of failed requests\n\n- Pre-authorization: every accepted request freezes balance based on an estimate; after the request ends it is settled by actual usage and any excess is released immediately.\n- Successful requests, and streaming requests that already delivered content, are settled by the usage actually returned.\n- **Requests that were dispatched to the upstream provider but ultimately failed** (upstream 4xx/5xx, upstream timeout, mid-stream disconnect, or the client closing the connection while waiting for the response) are settled at the pre-authorized amount and are not refunded. The upstream provider has already incurred cost for such requests; the platform bears it at the pre-authorized figure and bills the caller accordingly.\n- Requests rejected before reaching an upstream provider (validation, authentication, policy, quota, insufficient balance, gateway internal errors) release the full pre-authorization and incur no charge.\n- The settlement basis is visible in the console's usage transactions; records settled at the pre-authorized amount carry the failure reason.\n\n## Troubleshooting\n\n- Keep `X-Request-ID` and `X-Trace-ID` from the response headers; the error body also carries a top-level `trace_id` with the same value.\n- On `429`, honor the `Retry-After` response header and back off exponentially (the platform sets it when a platform rate limit is hit).\n- If a streaming response delivers a chunk with an `error` field, treat it as a failure (such a mid-stream break maps to `provider_stream_broken` and is not returned as a separate HTTP status).\n\nFor endpoint details see:\n\n- [Text Generation](../models/text/generation)\n- [Image Generation](../models/images/generations)\n- [OpenAI-Compatible Video Flow](../models/video/openai-compatible)\n- [Generic Async Content Generation Tasks](../models/video/async-tasks)\n- [Seedance Video Inbound Protocol](../models/video/ark)\n- [MiniMax Video Inbound Protocol](../models/video/minimax)\n","china/en/quickstart/openapi.md":"---\ntitle: API catalog\ndescription: Full customer-facing OpenAPI list, auth, protocol matching, and verified examples.\n---\n\n# API catalog\n\nThis page lists the public model-calling HTTP APIs (`mgk_` API Key, gateway `{{ api_endpoint }}`).\n\n## Before you call\n\n1. Create an API key (`mgk_`) at `{{ console_endpoint }}`. The full secret is shown once.\n2. `export MODELGO_API_KEY=\"your-key\"`.\n3. Call `GET /v1/models` for logical model names.\n4. A model only accepts endpoints listed in its `public_protocols`. Hitting any other path returns HTTP 400, `error_class=model_protocol_not_offered` (`app_error_id=4005`).\n\n## Auth\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic clients may send `x-api-key`; Gemini clients may send `x-goog-api-key`. Priority: `Authorization` > `x-api-key` > `x-goog-api-key`. See [Authentication](authentication).\n\nMissing or invalid key (HTTP 401):\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\nKeep `X-Request-ID`, `X-Trace-ID`, and body `trace_id`.\n\n## Protocol matching\n\n| Model | Endpoint | Result |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`, `POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`, `POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations` with `size` ≥ ~1920×1920 | 200 |\n\n## Catalog\n\n**Public** means the gateway mounts the route. Whether a given model accepts it still depends on `public_protocols` and the key's policy.\n\n### Text and model list\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | Public | Logical models allowed for this key |\n| `POST` | `/v1/responses` | Public | OpenAI Responses (preferred) |\n| `POST` | `/v1/chat/completions` | Public | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | Public | Legacy; most chat models do not offer it |\n| `POST` | `/v1/messages` | Public | Anthropic Messages |\n\n### Vectors / images / audio / rerank\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | Public | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Public | Needs a multimodal-embedding protocol |\n| `POST` | `/v1/images/generations` | Public | Image generation |\n| `POST` | `/v1/images/edits` | Public | Multipart image edits |\n| `POST` | `/v1/audio/speech` | Public | OpenAI TTS; not every speech model offers it |\n| `POST` | `/minimax/v1/t2a_v2` | Public | MiniMax native TTS; see [MiniMax audio inbound](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | Public | Multipart STT |\n| `POST` | `/v1/audio/translations` | Public | Multipart translation |\n| `POST` | `/v1/rerank` | Public | Rerank |\n| `POST` | `/v1/reranks` | Public / alias | Same as `/v1/rerank` |\n\n### Managed async video\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST`/`GET`/`DELETE` | `/v1/content_generation/tasks` and `.../{task_id}` | Public | Generic async tasks |\n| `POST`/`GET`/`DELETE` | `/ark/api/v3/contents/generations/tasks` and `.../{task_id}` | Public | Same pipeline, Ark spelling |\n| `POST`/`GET`/`DELETE` | `/minimax/v2/video_generation` and `.../{task_id}` | Public | MiniMax video V2; pricing dimensions required |\n| `POST`/`GET`/`DELETE` | `/v1/video/generations`, `/v1/videos/{task_id}`, `/v1/videos/{task_id}/content` | Public | OpenAI-compatible video; model must offer it |\n\nCancel (`DELETE`) may return `provider_unsupported` if the upstream has no cancel API.\n\n## Verified calls\n\nList models:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nChat Completions:\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":64}'\n```\n\nEmpty `{}` → HTTP 400 `client_invalid`. Unknown model → HTTP 403 `policy` / `model_not_in_catalog`.\n\nResponses: `POST /v1/responses` with `input` + `max_output_tokens`. Messages: `POST /v1/messages` with `x-api-key` and `max_tokens`. The Messages response `model` field may be an upstream id, not the logical name.\n\nEmbeddings: `text-embedding-3-small` returned 1536-d vectors.\n\nImages: `doubao-seedream-5.0-lite` rejects `1024x1024` (`provider_invalid`, min 3686400 pixels). `2048x2048` succeeded.\n\nSpeech: use [MiniMax audio inbound](../models/audio/minimax) for `speech-2.8-*`.\n\nVideo: Seedance uses `/v1/content_generation/tasks` (create returns `{\"id\",\"model\",\"status\":\"queued\"}`; poll later returns `status=succeeded`, plus `resolution` / `ratio` / `duration`). `/v1/video/generations` is `model_protocol_not_offered` for `doubao-seedance-2.0-mini`.\n\n## Streaming\n\nSet `stream: true`. OpenAI-shaped endpoints use `text/event-stream` frames `data: {json}` ending with `data: [DONE]`. `/v1/messages` keeps native Anthropic `event:` frames. A chunk with `error` is a failure even if HTTP status was 200.\n\n## Limits\n\n- Rate limits: HTTP 429 (`quota` or `provider_rate_limit`); honor `Retry-After`.\n- No client idempotency key on sync calls. Each async POST creates a new task; poll by returned `id`.\n- No pagination on this surface; `GET /v1/models` returns the full list for the key.\n\nSee [Errors](errors), [Text generation](../models/text/generation), [MiniMax audio inbound](../models/audio/minimax), [Async tasks](../models/video/async-tasks).\n","china/en/quickstart/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [First API Call](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","china/en/quickstart/quickstart.md":"---\ntitle: First API Call\ndescription: Create an API key, choose a model, and make your first request with the Responses API.\n---\n\n# First API Call\n\nYou can reuse an existing OpenAI or Anthropic SDK with ModelGo, or follow the three steps below to make your first request with the Responses API.\n\n## Connect with standard protocols\n\nModelGo supports both OpenAI and Anthropic standard protocols. If your project already uses either SDK, you can usually keep the existing integration and replace only the Base URL and API key.\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## Make your first API call in three steps\n\nIf this is your first ModelGo integration, complete these three steps to send a request and receive a generated result.\n\n### 1. Create an API key\n\n- Sign in to the [console]({{ console_endpoint }}).\n- Open the API Keys page and create a new API key.\n- Store it in an environment variable instead of placing it directly in your code:\n\n```bash\nexport MODELGO_API_KEY=\"your-api-key\"\n```\n\n### 2. Choose a model\n\nThe `model` request field must use a ModelGo logical model name. Browse models in the [Model Catalog]({{ site_endpoint }}/models) or use the following request to list the logical models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative. Choose a model name and replace `<model>` in the next step.\n\n### 3. Send your first request\n\nWe recommend starting with `POST /v1/responses`. Run the example in your preferred language:\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"Introduce ModelGo in three sentences.\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"Introduce ModelGo in three sentences.\",\n)\n\nprint(response.output_text)\n```\n\nA successful request returns the model-generated result. With the Python SDK, read the generated text from `response.output_text`.\n\n## Use other compatible protocols\n\nIf your project already uses another compatible interface, you can keep its existing request shape:\n\n- [Use Chat Completions](../models/text/generation#chat-completions): For existing OpenAI Chat Completions integrations.\n- [Use Anthropic Messages](../models/text/generation#anthropic-messages): For existing Claude SDK or Anthropic Messages integrations.\n\n## Continue exploring\n\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See the complete Responses, Chat Completions, and Anthropic Messages documentation.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n","china/zh/about/overview.md":"---\ntitle: 平台概览\ndescription: 了解 ModelGo 的统一模型 API、兼容协议、模型能力与生产调用管理方式。\n---\n\n# 平台概览\n\n## ModelGo 概述\n\nModelGo 是面向生产环境的 AI 模型聚合网关。通过一个 API Key 和统一的 API，你可以调用文本、图像、视频、音频、向量与重排模型，无需为不同模型重复维护接入代码。\n\n无论你是在验证模型效果、开发 AI 功能，还是将模型调用投入生产，都可以通过相同的开发流程完成接入，并在一个平台内管理权限、用量、日志和安全策略。\n\n## 一个 API，调用多种模型\n\nModelGo 将不同类型的模型能力接入到同一套开发流程中。你可以根据业务场景选择对应能力，并进入详细文档查看接口、参数与调用示例。\n\n| 模型类别 | 模型能力 | 查看文档 |\n| --- | --- | --- |\n| 文本 | 对话、内容生成、推理与工具调用 | [文本生成](../models/text/generation) |\n| 图像 | 根据文本生成图像，或编辑已有图像 | [图像生成](../models/images/generations) · [图像编辑](../models/images/edits) |\n| 视频 | 生成视频，并通过异步任务查询进度与结果 | [标准视频接口](../models/video/openai-compatible) · [异步任务](../models/video/async-tasks) |\n| 向量 | 生成文本或多模态 Embeddings，用于语义检索与 RAG | [Embeddings](../models/vectors/embeddings) |\n| 音频 | 语音合成、语音识别与语音翻译 | [语音合成](../models/audio/speech) · [MiniMax 音频](../models/audio/minimax) · [语音转文本](../models/audio/transcriptions) · [语音翻译](../models/audio/translations) |\n| 重排 | 对候选结果重新排序，提升搜索和 RAG 的检索效果 | [Rerank](../models/rerank/rerank) |\n\n你也可以在模型广场查看可用模型，在模型体验中测试模型效果，或通过 `GET /v1/models` 获取当前 API Key 可调用的模型列表。\n\n## 使用熟悉的协议与工具\n\nModelGo 兼容 OpenAI 与 Anthropic 文本协议。已经使用相关 SDK 或客户端的项目，通常只需要替换 Base URL 和 API Key，即可沿用现有调用方式。\n\n根据客户端使用的协议选择对应地址：\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n所有请求使用同一套 ModelGo API Key 进行鉴权。你可以在[控制台]({{ console_endpoint }})创建 API Key，具体请求头与安全建议请查看[认证鉴权](authentication)。\n\n## 为生产调用而设计\n\nModelGo 不只提供统一接口，也提供模型调用进入真实业务后需要的管理能力：\n\n- **稳定调用**：在接入层统一处理模型路由与故障回退，减少单一路径异常对业务的影响。\n- **权限与安全**：通过工作空间、成员和 API Key 划分调用权限，并限制预算、可用模型与调用来源。\n- **用量与成本**：按时间、工作空间、模型、成员和 API Key 查看请求数、Token 用量与消费金额。\n- **调用追踪**：通过 Request ID、调用状态、延迟和错误信息定位同步调用与异步任务问题。\n\n## 开始使用\n\n如果是第一次接入 ModelGo，建议按以下顺序开始：\n\n- [快速开始](quickstart)：获取 API Key，并完成第一次模型调用。\n- [接口清单](openapi)：全量对外路径、协议匹配规则与已验证示例。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的调用示例。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n\n:::note 开发前请注意\n- 请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名，而不是上游厂商的原始模型 ID。\n- 通过 `GET /v1/models` 可以查询当前 API Key 有权调用的逻辑模型。返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。\n- 文本流式响应使用 SSE 传输，并以 `data: [DONE]` 表示响应结束。\n- 视频等异步生成接口会先返回 `task_id`，需要使用该 ID 查询任务进度和结果。\n- 排查调用问题时，请保留响应中的 `X-Request-ID`，方便定位具体请求。\n:::\n","china/zh/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: 使用 ModelGo 配置 CC Switch 和 Claude Code。\n---\n\n# CC Switch\n\nCC Switch 是桌面端配置管理工具，可以统一管理 Claude Code、Codex、Gemini、OpenCode、OpenClaw 等工具的 Provider。下面以 Claude Code 为例，将 ModelGo 添加到 CC Switch 并启用。\n\n## 接入前准备\n\n- 已安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)，并能正常打开。\n- 已安装 Claude Code，并至少启动过一次。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 打开 Claude Code 配置\n\n打开 CC Switch，在顶部选择 **Claude**，点击右侧的 **+** 新增配置。\n\n![CC Switch 主界面](/images/agents/cc-switch/overview.webp)\n\n![在 CC Switch 中添加 Claude 配置](/images/agents/cc-switch/claude-add.webp)\n\n## 2. 添加 ModelGo Provider\n\n在配置编辑器中粘贴下面的 JSON。将 `你的模型名` 替换为模型广场中的逻辑模型名，将 `sk-你的token` 替换为 ModelGo API Key：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-你的token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"你的模型名\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"你的模型名\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![在 CC Switch 中编辑 ModelGo 配置](/images/agents/cc-switch/config-cn.webp)\n\n如果你的 CC Switch 版本支持环境变量占位符，可以将 Token 改为 `{env:MODELGO_API_KEY}`，并在启动 Claude Code 的终端中设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | ModelGo 控制台创建的 API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | 模型广场中的逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的逻辑模型名 |\n\n:::note\n- Anthropic Base URL 填写 ModelGo 根地址，不要追加 `/v1/messages`；Claude Code 会自动请求 `/v1/messages`。\n- API Key 只保存在本机 CC Switch 配置或环境变量中，不要提交到代码仓库。\n- CC Switch 的 Provider 名称可以填写 `ModelGo`，方便后续识别和切换。\n:::\n\n## 3. 保存并启用\n\n填写 Provider 名称 **ModelGo** 后点击 **Add** 或 **Save**。回到 Claude 配置列表，选中 ModelGo 配置并启用。\n\n![在 CC Switch 中添加 ModelGo Provider](/images/agents/cc-switch/provider-cn.webp)\n\n![在 CC Switch 中启用 ModelGo 配置](/images/agents/cc-switch/use-cn.webp)\n\n启动 Claude Code：\n\n```bash\nclaude\n```\n\n输入一条简单任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n## 4. 验证配置\n\n如果需要单独验证 API Key 和模型，可执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果中的 `id` 即可作为 `ANTHROPIC_MODEL` 和 `ANTHROPIC_SMALL_FAST_MODEL` 的逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 Token 是有效的 ModelGo API Key，且当前 CC Switch 配置没有残留的旧 Token。复制 Token 时不要带空格或换行。\n\n### 返回 404 或找不到接口\n\n确认 `ANTHROPIC_BASE_URL` 为 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages` 或完整请求路径。\n\n### 模型不可用\n\n确认模型名与[模型广场]({{ site_endpoint }}/models)中的逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n### 修改后 Claude Code 仍使用旧配置\n\n在 CC Switch 中确认 ModelGo 配置已启用，然后完全退出并重新打开终端，再运行 `claude`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [CC Switch 官方快速开始](https://cc-switch.cc/docs/getting-started/quick-start/)：了解界面和配置切换流程。\n- [CC Switch Provider 配置教程](https://cc-switch.cc/en/tutorials/provider-setup)：了解自定义 Provider 字段和凭据管理。\n","china/zh/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: 通过自定义服务商将 Cherry Studio 接入 ModelGo。\n---\n\n# Cherry Studio\n\nCherry Studio 已内置多个官方服务商，但 ModelGo 不在预置列表中。请使用“自定义服务商”创建一个 ModelGo Provider，再获取并添加模型。ModelGo 同时提供 OpenAI 兼容接口和 Anthropic 兼容接口，可按使用场景选择。\n\n## 接入前准备\n\n- 已安装 Cherry Studio，并能打开设置页面。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的逻辑模型名。\n\n## 1. 打开模型服务设置\n\n打开 Cherry Studio 的“设置”，进入“模型服务”，点击左侧底部的“+ 添加服务商”。\n\n![在 Cherry Studio 中打开添加服务商](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. 添加自定义服务商\n\n在“添加自定义提供商”窗口中填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| 提供商名称 | `ModelGo` |\n| API 密钥 | ModelGo 控制台创建的 API Key |\n| OpenAI 地址 | `{{ api_endpoint }}/v1` |\n| Anthropic 地址 | `{{ api_endpoint }}`（仅在使用 Anthropic 兼容模型或 Agent 模式时填写） |\n\n点击“添加”保存。OpenAI 地址用于普通聊天和模型列表；Anthropic 地址不要追加 `/v1`，Cherry Studio 会按协议补全请求路径。\n\n![添加 ModelGo 自定义提供商](/images/agents/cherry-studio/custom-provider.webp)\n\n:::note\n- 不要把完整的 `/chat/completions` 或 `/messages` 写进地址。\n- OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`，Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n:::\n\n## 3. 获取并添加模型\n\n回到 ModelGo 服务商页面，点击“获取模型列表”。Cherry Studio 会从 ModelGo 的模型接口读取当前 API Key 可用的逻辑模型。\n\n![在 Cherry Studio 中获取 ModelGo 模型列表](/images/agents/cherry-studio/fetch-models.webp)\n\n模型列表弹窗打开后，可以按需点击单个模型右侧的“+”，也可以点击“添加全部模型”。\n\n![在 Cherry Studio 中添加全部 ModelGo 模型](/images/agents/cherry-studio/model-picker.webp)\n\n添加完成后，模型会出现在 ModelGo 服务商的模型区域。只添加自己需要的模型可以让选择器更简洁。\n\n![ModelGo 服务商中的模型列表](/images/agents/cherry-studio/model-list.webp)\n\n## 4. 启用并开始对话\n\n在 ModelGo 服务商右上角打开开关，确认 API 密钥检测通过。新建对话时选择 **ModelGo** 及刚添加的模型，然后发送一条简单消息验证调用。\n\n如果只使用 OpenAI 兼容模型，保留 OpenAI 地址即可；使用 Claude 等 Anthropic 兼容模型或 Cherry Studio Agent 模式时，再配置 Anthropic 地址并添加对应模型。\n\n## 验证配置\n\n可以在终端检查 API Key 是否能读取模型列表：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是 Cherry Studio 中应添加的 ModelGo 逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认服务商右上角开关已打开。\n\n### 返回 404 或接口路径错误\n\nOpenAI 地址应为 `{{ api_endpoint }}/v1`，Anthropic 地址应为 `{{ api_endpoint }}`。不要填写完整的 `/v1/chat/completions` 或 `/v1/messages`。\n\n### 获取模型列表为空\n\n先用上面的 `curl` 验证 `/v1/models`，再确认模型已在模型广场开通。获取列表后还要点击模型右侧的“+”或“添加全部模型”，仅获取列表不会自动加入选择器。\n\n### Agent 模式无法调用\n\n确认已填写 Anthropic 地址 `{{ api_endpoint }}`，并添加支持 Anthropic 兼容协议的模型。普通 OpenAI 兼容聊天不需要填写该地址。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cherry Studio 自定义服务商文档](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang)：查看官方的自定义服务商流程。\n- [Cherry Studio Provider 设置说明](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers)：了解 Base URL、模型管理和连通性检测规则。\n","china/zh/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: 使用 ModelGo 的 Anthropic 兼容接口配置 Claude Code。\n---\n\n# Claude Code\n\nClaude Code 是运行在终端中的 AI 编程助手。通过配置 Anthropic 兼容接口，你可以让 Claude Code 使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 Node.js。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Claude Code\n\n在终端执行：\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n安装完成后检查版本：\n\n```bash\nclaude --version\n```\n\n## 2. 配置 ModelGo\n\n### macOS / Linux\n\n创建并编辑 Claude Code 配置文件：\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\n在 PowerShell 中执行：\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\n将下面内容写入 `settings.json`。把 `YOUR_MODELGO_API_KEY` 和 `YOUR_MODELGO_MODEL` 替换为真实的 ModelGo API Key 与逻辑模型名：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n`ANTHROPIC_BASE_URL` 填写 ModelGo 的根地址，不要追加 `/v1/messages`。Claude Code 会自动请求 ModelGo 的 `POST /v1/messages` 接口。\n\n:::note\n- 如果你只使用一个模型，建议将五个模型变量都设置为同一个 ModelGo 逻辑模型名，避免辅助模型未授权导致启动失败。\n- API Key 仅写入本机配置，不要将 `settings.json` 提交到代码仓库或分享给他人。\n:::\n\n## 3. 可选：跳过官方账号初始化\n\n如果首次输入 `claude` 时卡在官方账号登录引导，可以在用户目录创建 `.claude.json`，写入已完成初始化标识。\n\nmacOS / Linux：\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell：\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. 启动 Claude Code\n\n进入你的项目目录并启动：\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\n首次进入项目时，选择 **Trust This Folder**，允许 Claude Code 访问项目文件。然后输入一条简单的编码需求，能够正常返回结果即表示接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | ModelGo 平台逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n\n模型名可以通过[模型广场]({{ site_endpoint }}/models)确认，也可以查询当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的 ModelGo API Key，复制时不要带多余空格。\n\n### 返回 403 或模型不可用\n\n确认五个模型变量使用的都是当前 API Key 策略允许调用的 ModelGo 逻辑模型名。\n\n### 返回 404 或找不到接口\n\n`ANTHROPIC_BASE_URL` 应填写 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages`；Claude Code 会自动补充 `/v1/messages`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)：查看最新安装与配置说明。\n","china/zh/agents/cline.md":"---\ntitle: Cline\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cline。\n---\n\n# Cline\n\nCline 是 VS Code 中的 AI 编程助手。选择 `OpenAI Compatible` Provider 后，可以通过 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 VS Code。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cline\n\n打开 VS Code 扩展市场，搜索 **Cline** 并安装扩展。\n\n![在 VS Code 扩展市场安装 Cline](/images/agents/cline/cline-market.webp)\n\n## 2. 配置 ModelGo\n\n安装完成后，点击 VS Code 左侧工具栏中的 Cline 图标，打开 **API Configuration**。\n\n![打开 Cline API Configuration](/images/agents/cline/cline-config-cn.webp)\n\n按下表填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | ModelGo API Key |\n| Model ID | ModelGo 平台逻辑模型名 |\n\n点击 **Done** 保存。\n\n:::note\n- Base URL 使用 `{{ api_endpoint }}/v1`，不要填写 `/chat/completions`；Cline 会自动拼接接口路径。\n- Model ID 使用模型广场中当前 API Key 可调用的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 只保存在本机 Cline 设置中，不要提交到代码仓库或截图分享。\n:::\n\n如需先确认当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. 开始使用\n\n在 Cline 面板输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n![Cline 完成一次对话](/images/agents/cline/cline-chat.webp)\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写在 API Key 字段。\n\n### 返回 403 或模型不可用\n\n确认 Model ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应为 `{{ api_endpoint }}/v1`，不要粘贴完整的 `/chat/completions` URL。\n\n### 模型列表为空\n\n先请求 `GET {{ api_endpoint }}/v1/models` 验证接口；若 Cline 下拉列表不显示模型，可直接手动输入 Model ID。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Cline OpenAI Compatible 文档](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx)：查看 Cline 官方 Provider 配置说明。\n","china/zh/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: 通过 ModelGo 接入 CodeBuddy。\n---\n\n# CodeBuddy\n\nCodeBuddy Code 是腾讯云的终端 AI 编程工具。它支持用环境变量覆盖 API 地址、Key 和模型，因此无需修改项目代码即可接入 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已安装 CodeBuddy CLI，并能执行 `codebuddy --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. 配置 ModelGo 环境变量\n\n在启动 CodeBuddy 的同一终端设置：\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-你的token\"\nexport CODEBUDDY_MODEL=\"你的模型名\"\n```\n\n`CODEBUDDY_BASE_URL` 覆盖请求地址，`CODEBUDDY_API_KEY` 用于模型调用，`CODEBUDDY_MODEL` 指定 ModelGo 逻辑模型。不要将 `CODEBUDDY_AUTH_TOKEN` 与 ModelGo API Key 混用；前者是 CodeBuddy 平台登录凭据。\n\n:::note\n- Base URL 填 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- 若使用非交互模式 `codebuddy -p`，必须设置 `CODEBUDDY_API_KEY`。\n- API Key 和模型名建议写进本地 shell profile 或密钥管理器，不要提交到仓库。\n:::\n\n## 3. 启动并验证\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\n```\n\n在会话中让 CodeBuddy 执行一个只读任务；非交互调用示例：\n\n```bash\ncodebuddy -p \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 仍然使用默认模型或地址\n\n确认环境变量在当前终端可见，并完全退出后重新启动 `codebuddy`。检查变量名拼写是否为大写形式。\n\n### 401 或 404\n\n检查 `CODEBUDDY_API_KEY`、`CODEBUDDY_MODEL` 和 `CODEBUDDY_BASE_URL`，不要把完整接口路径写进 Base URL。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [CodeBuddy CLI 快速开始](https://www.codebuddy.ai/docs/cli/quickstart)：查看安装、登录和首次运行流程。\n- [CodeBuddy CLI 环境变量](https://www.codebuddy.ai/docs/cli/env-vars)：查看 `CODEBUDDY_BASE_URL`、`CODEBUDDY_API_KEY` 和模型变量。\n","china/zh/agents/codex.md":"---\ntitle: Codex\ndescription: 使用 ModelGo 的 Responses API 配置 Codex CLI。\n---\n\n# Codex\n\nCodex 是 OpenAI 的命令行 AI 编程助手。通过自定义 `model_provider`，可以将 Codex CLI 的 Responses API 请求发送到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Codex\n\n在 macOS、Linux 或 Windows 终端中执行：\n\n```bash\nnpm install -g @openai/codex\n```\n\n安装完成后检查版本：\n\n```bash\ncodex --version\n```\n\n首次启动时，如果 Codex 提示有新版本可用，可以选择 **Skip**，先完成 ModelGo 配置。\n\n![跳过 Codex 升级提示](/images/agents/codex/codex-start.webp)\n\n## 2. 配置 ModelGo\n\nCodex 从用户目录下的 `~/.codex/config.toml` 读取模型和 Provider 配置。先创建目录和配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\n将下面内容粘贴到 `config.toml`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中当前 API Key 可调用的逻辑模型名：\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\n其中，`base_url` 使用 ModelGo 的 OpenAI 兼容根地址，Codex 会自动请求 `/v1/responses`。\n\n## 3. 设置 API Key\n\n将 ModelGo API Key 保存到系统环境变量 `MODELGO_API_KEY`。不要把真实 API Key 直接写入 `config.toml`。\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n检查变量是否已生效（只输出是否存在，不要打印 Key 内容）：\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- `MODELGO_API_KEY` 只应保存在本机环境变量中，不要提交到代码仓库或分享终端截图。\n- `model` 必须填写 ModelGo 逻辑模型名；截图中的 `gpt-5.6-sol` 仅为示例，请替换为你实际可调用的模型。\n- `wire_api = \"responses\"` 是当前 Codex 配置要求；不要使用已经弃用的 `wire_api = \"chat\"`。\n:::\n\n:::note 切换 API Key 或服务地址后请新建会话\n- Codex 在多轮对话中会继续携带之前的 Responses 上下文，其中可能包含只能由原上游账号继续处理的加密推理内容。\n- 如果你更换了 `MODELGO_API_KEY`、`base_url`，或者代理、号池将同一会话切换到其他上游账号，请新建 Codex 会话，不要继续或恢复原会话，否则请求可能返回 `400 invalid_encrypted_content`。\n:::\n\n## 4. 启动并验证\n\n进入一个本地项目目录，执行：\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\n首次进入项目时，按提示选择信任当前目录。看到 Codex 欢迎界面后，输入一条简单的编码需求，例如“用三句话介绍这个项目”。\n\n![Codex 首次进入项目的欢迎界面](/images/agents/codex/codex-skip.webp)\n\n能够正常返回模型结果，即表示 ModelGo 接入成功。\n\n![Codex 开始对话](/images/agents/codex/codex-chat.webp)\n\n如需先确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 启动后提示找不到 Provider\n\n确认配置文件路径是用户目录下的 `~/.codex/config.toml`，并检查 `model_provider = \"modelgo\"` 与 `[model_providers.modelgo]` 的名称一致。\n\n### 返回 401 或认证失败\n\n检查当前终端是否已设置 `MODELGO_API_KEY`，并确认 API Key 没有多余空格或换行。\n\n### 返回 403 或模型不可用\n\n确认 `model` 使用模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`base_url` 应填写 `{{ api_endpoint }}/v1`。不要填写完整的 `/responses` 或 `/v1/responses`，Codex 会自动拼接路径。\n\n### 出现 Chat wire API 弃用提示\n\n在 `[model_providers.modelgo]` 中加入 `wire_api = \"responses\"`，并升级到最新 Codex CLI：\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### 返回 `400 invalid_encrypted_content`\n\n这通常说明当前会话携带了原上游账号生成的加密上下文，但本轮请求被另一个上游账号处理。\n\n先检查是否更换过 API Key、Base URL，或者代理、号池是否切换了上游账号。发生过切换时，请新建会话，不要继续或恢复原会话。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Codex 配置参考](https://developers.openai.com/codex/config-reference/)：查看当前 Codex 的 `config.toml` 字段说明。\n","china/zh/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: 通过 ModelGo 接入 Copilot CLI。\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI 支持 BYOK（Bring Your Own Key）。设置 Provider 环境变量后，Copilot CLI 会把模型请求发送到 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 GitHub Copilot CLI，并能执行 `copilot --help`。\n- 已完成 GitHub 登录或组织要求的 Copilot 认证。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认支持工具调用和流式输出的逻辑模型。\n\n## 1. 配置 ModelGo BYOK\n\n在启动 Copilot CLI 的同一终端设置：\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"你的模型名\"\ncopilot\n```\n\n如果还没有通用环境变量，可直接设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\n```\n\n`openai` Provider 类型用于 OpenAI Chat Completions 兼容服务；`COPILOT_MODEL` 填 ModelGo 逻辑模型 ID。\n\n:::note\n- Copilot CLI 仍可能需要 GitHub 登录；登录身份与模型请求所用的 ModelGo Key 是两套凭据。\n- Base URL 填 `{{ api_endpoint }}/v1`，不要写 `/chat/completions`。\n- 建议选择支持 tool calling、streaming 且上下文窗口较大的模型。\n:::\n\n## 2. 验证模型\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\n在会话中让 Copilot CLI 执行一个只读任务，例如“列出项目入口文件”，确认能正常返回结果。\n\n## 常见问题\n\n### Copilot CLI 仍调用默认模型\n\n确认 `COPILOT_MODEL` 与 `COPILOT_PROVIDER_BASE_URL` 在当前终端可见，并重新启动 `copilot`。\n\n### 返回 401、404 或不支持工具调用\n\n检查 API Key、Base URL 和逻辑模型名；如果模型不支持工具调用或流式响应，请在模型广场更换模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)：查看 Provider 环境变量和模型要求。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","china/zh/agents/crush.md":"---\ntitle: Crush\ndescription: 通过 ModelGo 接入 Crush。\n---\n\n# Crush\n\nCrush 是 Charmbracelet 提供的终端 AI 编程 Agent。它支持 OpenAI 兼容 Provider，可通过 `crushrc` 将请求转发到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+、Go 或 Homebrew。\n- 已安装 Crush，并能执行 `crush --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\n也可以使用 `npm install -g @charmland/crush`、`go install github.com/charmbracelet/crush@latest`，Windows 用户可执行 `winget install charmbracelet.crush`。\n\n## 2. 添加 ModelGo Provider\n\nCrush 的项目配置放在项目根目录的 `.crushrc` 或 `crushrc`，全局配置放在 `~/.config/crush/crushrc`（Windows：`%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`）。推荐使用 CLI 写入配置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/你的模型名 --name \"你的模型名\"\n```\n\n将 `你的模型名` 替换为模型广场中的逻辑模型 ID。`openai-compat` 表示使用 OpenAI Chat Completions 兼容协议。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- API Key 建议通过 `MODELGO_API_KEY` 环境变量提供，不要写入仓库。\n- `modelgo/你的模型名` 是 Crush 的 Provider/模型标识，Provider ID 可按需修改。\n:::\n\n## 3. 启动并验证\n\n```bash\ncrush\n```\n\n在模型选择器中选择 ModelGo 模型，发送一条简单请求。也可先验证目录接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 找不到 Provider\n\n确认 `crushrc` 路径和文件名正确，并重新启动 Crush。项目配置会覆盖全局配置。\n\n### 返回 401 或 404\n\n检查 `MODELGO_API_KEY` 是否生效，Base URL 是否为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Crush 官方仓库](https://github.com/charmbracelet/crush)：查看安装、Provider 和命令参考。\n- [Crush 配置 Schema](https://github.com/charmbracelet/crush/blob/main/schema.json)：查看 `crushrc` 字段定义。\n","china/zh/agents/cursor.md":"---\ntitle: Cursor\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cursor。\n---\n\n# Cursor\n\nCursor 是一款 AI 编程编辑器。通过自定义 OpenAI Base URL，Cursor 可以调用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 [Cursor](https://www.cursor.com/)。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cursor\n\n访问 [Cursor 官网](https://www.cursor.com/)，下载并安装适合你操作系统的版本。\n\n![Cursor 官网下载页面](/images/agents/cursor/install.webp)\n\n## 2. 打开 Cursor 模型设置\n\n打开 Cursor 设置，进入 **Models** 页面。\n\n![打开 Cursor Settings 的 Models](/images/agents/cursor/settings.webp)\n\n## 3. 添加并启用模型\n\n点击 **Add model**，输入[模型广场]({{ site_endpoint }}/models)中的逻辑模型名，然后保存。\n\n![在 Cursor 中添加模型](/images/agents/cursor/add-model.webp)\n\n在 **Model Names** 列表中保留需要使用的模型，并关闭不需要的模型。\n\n![在 Cursor 中启用目标模型](/images/agents/cursor/model-list.webp)\n\n## 4. 配置 ModelGo 接口\n\n在 **Settings → Models → API Keys** 中配置 OpenAI 兼容接口：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| OpenAI API Key | ModelGo API Key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | ModelGo 模型广场中的逻辑模型名 |\n\n![在 Cursor 中配置 ModelGo 接口](/images/agents/cursor/config-cn.webp)\n\n如果你的 Cursor 使用另一版设置界面，可参考下面的布局，填写相同的 ModelGo 参数。\n\n![Cursor 另一版设置界面](/images/agents/cursor/config-global.webp)\n\n点击 **Verify** 或 **Save** 保存配置。Cursor 的不同版本可能会调整设置项名称，但 Base URL、API Key 和模型名的含义不变。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- 模型名必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图里的示例。\n- 如果 Verify 无法完成，可先在聊天窗口直接发送请求，或用下方命令检查接口和 Key。\n:::\n\n## 5. 测试连接\n\n回到 Cursor 聊天窗口，选择刚添加的模型，发送一条简单消息。能够正常返回结果，即表示接入成功。\n\n![在 Cursor 中测试 ModelGo 模型](/images/agents/cursor/chat.webp)\n\n也可以在终端查看当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 API Key 复制完整且没有多余空格，并检查是否填入 **OpenAI API Key** 字段。\n\n### 返回 404 或接口路径错误\n\n确认 Base URL 为 `{{ api_endpoint }}/v1`，不要把 `/chat/completions` 拼到 Base URL 后面。\n\n### Verify 失败或模型不可用\n\n确认模型名是 ModelGo 模型广场中的逻辑模型名，并检查该模型是否已对当前 API Key 开通。\n\n### 聊天窗口没有返回内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 验证网络和 Key，再确认 Cursor 的 Model Names 列表中已启用目标模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cursor 官方文档](https://docs.cursor.com/)：查看 Cursor 设置、模型和自定义 API 配置说明。\n","china/zh/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 DeepSeek Harness。\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness（DSH）是 DeepSeek AI 开源的智能体框架，可以将模型、工具、文件系统、终端、会话和 Web UI 组合成可运行的 Agent。通过自定义提供方，DSH 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已安装 pnpm 11 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装并启动 DeepSeek Harness\n\nDeepSeek Harness 当前推荐从源码安装：\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![从源码启动 DeepSeek Harness](/images/agents/deepseek-harness/install.webp)\n\n终端会打印 Web UI 地址，默认是 `http://127.0.0.1:3080`。如果端口已被占用，请以终端实际打印的地址为准。\n\n如果只想快速体验，也可以直接运行：\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. 配置 ModelGo\n\n在浏览器打开终端打印的地址，点击左上角侧边栏按钮，然后点击 **设置**。\n\n![打开 DeepSeek Harness 设置](/images/agents/deepseek-harness/settings.webp)\n\n在设置中选择 **模型**，点击 **添加自定义提供方**。\n\n![添加自定义提供方](/images/agents/deepseek-harness/model-picker.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider ID | `modelgo` |\n| 显示名称 | `ModelGo` |\n| API 地址 | `{{ api_endpoint }}/v1` |\n| API 协议 | `openai-completions` |\n| API 密钥 | ModelGo API Key |\n| 模型 ID | 模型广场中的逻辑模型名 |\n| 显示名称 | 可填写与模型 ID 相同的名称 |\n\n![填写 ModelGo 自定义提供方](/images/agents/deepseek-harness/provider-config.webp)\n\n点击 **创建提供方** 保存配置。配置时请注意：\n\n:::note\n- API 地址填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`；DSH 会根据 `openai-completions` 协议拼接请求路径。\n- 模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例模型。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 开始会话\n\n回到主界面，选择一个工作区，再选择刚刚添加的 ModelGo 模型。\n\n![选择 ModelGo 模型开始会话](/images/agents/deepseek-harness/session.webp)\n\n输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 已接入成功。\n\n## 常见问题\n\n### Web UI 无法打开\n\n确认 `pnpm dsh web` 进程仍在运行，并访问终端打印的实际端口。默认端口是 `3080`，端口冲突时 DSH 可能会自动使用其他端口。\n\n### 返回 401 或认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写的是 ModelGo 控制台创建的 API Key。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\nAPI 地址应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。API 协议请选择 `openai-completions`。\n\n### 模型列表为空\n\n检查模型 ID 是否填写，并确认 DSH 的自定义提供方已保存。必要时可以先用下面的命令验证 ModelGo 接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [DeepSeek Harness 官方网站](https://www.deepseek.com/harness/)：查看最新安装方式和产品说明。\n- [DeepSeek Harness GitHub 仓库](https://github.com/deepseek-ai/deepseek-harness)：查看源码和版本信息。\n","china/zh/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: 通过 ModelGo 接入 Factory Droid。\n---\n\n# Factory Droid\n\nFactory Droid 是 Factory 的终端 Agent。通过 BYOK 自定义模型，可以让 Droid 使用 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 Node.js 18+ 和 Droid CLI。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装并启动 Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\n也可以使用 Factory 官方安装器。进入 Droid 后输入 `/settings` 可打开设置。\n\n## 2. 配置 ModelGo 自定义模型\n\n编辑 `~/.factory/settings.json`（Windows：`%USERPROFILE%\\\\.factory\\\\settings.json`），合并以下 `customModels` 配置：\n\n```json\n{\n  \"customModels\": [\n    {\n      \"model\": \"你的模型名\",\n      \"displayName\": \"ModelGo / 你的模型名\",\n      \"baseUrl\": \"{{ api_endpoint }}/v1\",\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"provider\": \"openai\"\n    }\n  ]\n}\n```\n\n先设置 Key：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n重新启动 Droid，在 `/models` 或模型选择器中选择 `ModelGo / 你的模型名`。\n\n:::note\n- `baseUrl` 填 `{{ api_endpoint }}/v1`，不要附加 `/chat/completions`。\n- `model` 必须使用 ModelGo 模型广场中的逻辑模型 ID。\n- 保留原有 `settings.json` 字段，只合并 `customModels`，不要覆盖其他个人设置。\n:::\n\n## 3. 验证请求\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"你的模型名\" \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 模型没有出现在列表中\n\n检查 JSON 是否有效、`customModels` 是否位于文件顶层，并完全退出后重新启动 Droid。\n\n### 认证失败或接口路径错误\n\n确认环境变量已在启动 Droid 的同一终端中设置，且 `baseUrl` 没有重复的 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Factory Droid 设置](https://docs.factory.ai/droid-cli/settings)：查看 `settings.json` 的位置和设置入口。\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok)：了解自定义模型字段和模型独立性。\n","china/zh/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Hermes Agent。\n---\n\n# Hermes Agent\n\nHermes Agent 是一款运行在终端中的 AI Agent。通过自定义 Provider，Hermes 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的 ModelGo 逻辑模型名。\n\n## 1. 安装 Hermes Agent\n\nmacOS 或 Linux：\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell：\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\n重新打开终端后，检查安装是否成功：\n\n```bash\nhermes --version\n```\n\n## 2. 配置 ModelGo\n\n先把 API Key 放入当前终端的环境变量。不要把真实 Key 提交到代码仓库或公开脚本中：\n\n```bash\nexport MODELGO_API_KEY=\"你的-ModelGo-API-Key\"\nexport MODELGO_MODEL=\"你的-ModelGo-逻辑模型名\"\n```\n\n如果还不确定模型名，可以先查询当前 API Key 可用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n然后使用 `hermes config set` 写入自定义 Provider。将 `<model>` 替换为模型广场或 `GET /v1/models` 返回的逻辑模型名：\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\n如果你的 Hermes 版本通过 `hermes model` 提供配置向导，也可以运行：\n\n```bash\nhermes model\n```\n\n选择 **Custom endpoint**，依次填写下方配置表中的 ModelGo Base URL、API Key 和模型名，并选择 **Chat Completions** 协议。\n\n:::note\n- 部分旧版本将 Chat Completions 协议显示为 `openai_messages`。如果 `chat_completions` 被提示为无效，请升级 Hermes，或在 `hermes model` 向导中选择 Chat Completions。\n:::\n\n## 3. 检查配置并开始对话\n\n检查 Hermes 配置：\n\n```bash\nhermes config check\n```\n\n检查通过后启动 Hermes：\n\n```bash\nhermes\n```\n\n输入一条消息，例如“用三句话介绍 ModelGo”。如果能返回模型结果，说明接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API 模式 | `chat_completions` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model ID | ModelGo 的平台逻辑模型名，不是上游厂商原始模型 ID |\n\nHermes 会将非敏感配置保存到 `~/.hermes/config.yaml`，API Key 等敏感信息保存到 `~/.hermes/.env`。不要分享或提交 `~/.hermes/` 下包含密钥的文件。\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n确认 API Key 没有被撤销或过期，并重新执行：\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 返回 403 或模型不可用\n\n确认 `model.default` 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要再拼接 `/chat/completions`；Hermes 会在请求时补充具体路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs)：查看安装器、配置项和 CLI 的最新说明。\n","china/zh/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: 通过 ModelGo 接入 Kilo CLI。\n---\n\n# Kilo CLI\n\nKilo CLI 是终端 AI 编程 Agent。它支持自定义 OpenAI 兼容 Provider；由于 ModelGo CLI 尚未提供官方自动配置，本文采用 Kilo 的 `/connect` 与配置文件方式。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\n进入项目目录后运行 `kilo`，首次启动可使用 `/connect` 添加 Provider。\n\n## 2. 添加 ModelGo Provider\n\n在项目根目录创建 `kilo.jsonc`（或编辑全局配置），加入 OpenAI 兼容 Provider：\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/你的模型名\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"ModelGo / 你的模型名\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n也可以在 TUI 中选择 `/connect` → `OpenAI Compatible`，填写同样的 Base URL、API Key 和模型 ID。\n\n:::note\n- Provider ID 使用小写 `modelgo`；模型选择格式为 `modelgo/你的模型名`。\n- `baseURL` 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- Kilo CLI 的模型 ID 必须与 ModelGo 模型广场逻辑模型名一致。\n:::\n\n## 3. 验证配置\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\n在模型选择器中选中 ModelGo 模型，发送一条只读任务确认连接。\n\n## 常见问题\n\n### Provider 没有出现在选择器\n\n检查 `kilo.jsonc` 的 JSONC 格式、Provider ID 和 `model` 路径，并重新启动 Kilo。\n\n### 401 或 404\n\n确认 `MODELGO_API_KEY` 已导出，`baseURL` 为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Kilo CLI 官方文档](https://kilo.ai/docs/code-with-ai/platforms/cli)：查看安装、`/connect` 和 CLI 命令。\n- [Kilo 自定义模型](https://kilo.ai/docs/code-with-ai/agents/custom-models)：查看 OpenAI Compatible Provider 字段和模型格式。\n","china/zh/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Kilo Code。\n---\n\n# Kilo Code\n\nKilo Code 是一款支持 VS Code 和 JetBrains 的 AI 编程助手。通过 OpenAI 兼容 Provider，你可以在 Kilo Code 中使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 VS Code 或 JetBrains IDE。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Kilo Code\n\n### VS Code\n\n打开 VS Code 扩展市场，搜索 **Kilo Code**，确认发布者后安装扩展。安装完成后，打开左侧 Kilo Code 面板。\n\n![在 VS Code 扩展市场安装 Kilo Code](/images/agents/kilo-code/vscode-market.webp)\n\n首次安装时，VS Code 会要求确认是否信任发布者。确认发布者为 Kilo Code 后，点击 **Trust Publisher & Install**。\n\n![确认信任 Kilo Code 发布者](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\n打开 Settings / Preferences → Plugins，在 Marketplace 搜索 **Kilo Code** 并安装。安装完成后重启 IDE，使扩展生效。\n\n![在 JetBrains Marketplace 安装 Kilo Code](/images/agents/kilo-code/jetbrains-market.webp)\n\n安装第三方插件时，JetBrains 会显示插件声明。确认后点击 **接受**，完成安装。\n\n![确认 JetBrains 第三方插件声明](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. 在 VS Code 中配置 ModelGo\n\n打开 Kilo Code 的设置，进入 **Providers**，选择 **OpenAI Compatible**，填写以下信息：\n\n先在 Kilo Code 的欢迎页选择 **Bring my own Key**：\n\n![选择 Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model | ModelGo 平台逻辑模型名 |\n\n![Kilo Code VS Code 配置界面](/images/agents/kilo-code/vscode-config-cn.webp)\n\n保存后，Kilo Code 会尝试从兼容的 `/v1/models` 接口获取模型。如果下拉列表中没有目标模型，可以选择 **Use custom**，手动输入模型广场中的逻辑模型名。\n\n:::note\n- Base URL 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。Kilo Code 会自动拼接标准路径。\n- 截图中的模型名仅为界面示例，请替换为当前 API Key 可调用的 ModelGo 逻辑模型名。\n- API Key 只填写在本机的 Kilo Code 设置中，不要提交到代码仓库或截图分享。\n:::\n\n## 3. 在 JetBrains 中配置 ModelGo\n\n打开 Kilo Code 设置，点击 **Bring my own Key**，选择 **OpenAI Compatible**，然后填写与 VS Code 相同的配置：\n\n![在 JetBrains 中选择 Bring my own Key](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**：`{{ api_endpoint }}/v1`\n2. **API Key**：ModelGo API Key\n3. **Model**：ModelGo 逻辑模型名\n4. 点击 **Save** 保存。\n\n![JetBrains 中的 ModelGo Provider 配置](/images/agents/kilo-code/jetbrains-config-cn.webp)\n\n如果模型下拉列表为空，先确认 Base URL 可访问，再选择自定义模型并手动输入逻辑模型名。\n\n![在 JetBrains 中完成一次编码任务](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. 检查配置并开始对话\n\n进入一个本地项目，在 Kilo Code 面板中输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回模型结果，即表示接入成功。\n\n![Kilo Code 完成一次编码任务](/images/agents/kilo-code/vscode-start.webp)\n\n如需检查当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整，确认没有多余空格，并确认填写在 **API Key** 而不是 Base URL 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 **Model** 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。不要直接填写上游厂商原始模型 ID，除非模型广场明确提供该名称。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。Kilo Code 会在请求时补充具体接口路径。\n\n### 模型下拉列表没有内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 检查 API Key 和接口是否可用；如果接口正常，使用 **Use custom** 手动输入逻辑模型名。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Kilo Code 官方文档](https://kilo.ai/docs)：查看最新的扩展安装和 Provider 配置说明。\n","china/zh/agents/nanobot.md":"---\ntitle: nanobot\ndescription: 通过 ModelGo 接入 nanobot。\n---\n\n# nanobot\n\nnanobot 是轻量级终端 Agent。它通过 JSON 配置 Provider 和模型预设，可直接使用 ModelGo 的 OpenAI 兼容 API。\n\n## 接入前准备\n\n- 已安装 Python 3.11+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\n配置文件默认位于 `~/.nanobot/config.json`。\n\n## 2. 配置 ModelGo Provider\n\n编辑 `~/.nanobot/config.json`，合并以下字段：\n\n```json\n{\n  \"providers\": {\n    \"modelgo\": {\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"apiBase\": \"{{ api_endpoint }}/v1\"\n    }\n  },\n  \"modelPresets\": {\n    \"ModelGo\": {\n      \"provider\": \"modelgo\",\n      \"model\": \"你的模型名\",\n      \"maxTokens\": 4096,\n      \"contextWindowTokens\": 65536,\n      \"temperature\": 0.1\n    }\n  },\n  \"agents\": { \"defaults\": { \"modelPreset\": \"ModelGo\" } }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nnanobot 对 OpenAI 兼容自定义端点无需额外填写 `apiType`；`apiBase` 使用带 `/v1` 的根地址。\n\n:::note\n- 保留原配置中的 channels、tools 等字段，只合并 providers、modelPresets 和 agents.defaults。\n- API Key 使用环境变量，不要把真实 Key 写进 JSON 或提交到仓库。\n- 模型名必须是 ModelGo 模型广场中的逻辑模型 ID。\n:::\n\n## 3. 验证连接\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### `nanobot` 找不到模型\n\n确认 `modelPresets.ModelGo.provider` 与 `providers.modelgo` 的 ID 一致，并检查 JSON 格式。\n\n### 401 或请求地址错误\n\n确认 API Key 环境变量已导出，`apiBase` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [nanobot OpenAI 兼容 Provider 指南](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md)：查看完整 JSON 配置说明。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","china/zh/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: 通过 ModelGo 接入 Oh My Pi。\n---\n\n# Oh My Pi\n\nOh My Pi（命令 `omp`）是终端 AI 编程 Agent。它支持在 `models.yml` 中声明 OpenAI 兼容 Provider，并按 `provider-id/model-id` 选择模型。\n\n## 接入前准备\n\n- 已安装 Bun 或使用官方安装脚本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux 也可以执行官方安装脚本：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. 添加 ModelGo Provider\n\n编辑 `~/.omp/agent/models.yml`，加入：\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: 你的模型名\n        name: ModelGo / 你的模型名\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` 填环境变量名，而不是 Key 本身：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n:::note\n- `api` 使用 `openai-completions`，`baseUrl` 使用 `{{ api_endpoint }}/v1`。\n- 模型选择格式为 `modelgo/你的模型名`。\n- 不要把真实 API Key 写入 `models.yml`，并确认文件权限仅当前用户可读。\n:::\n\n## 3. 选择模型并验证\n\n```bash\nomp --list-models\nomp --model modelgo/你的模型名\n```\n\n进入会话后发送一条简单任务；也可先检查 ModelGo 模型目录：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 模型列表没有 ModelGo\n\n确认文件路径为 `~/.omp/agent/models.yml`，YAML 缩进正确，并重新启动 `omp`。\n\n### 401 或接口路径错误\n\n确认 `MODELGO_API_KEY` 已导出，`baseUrl` 没有重复 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Oh My Pi Provider 文档](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md)：查看 Provider、API 类型和密钥配置。\n- [Oh My Pi 模型文档](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md)：查看模型选择和 `models.yml` 结构。\n","china/zh/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenClaw。\n---\n\n# OpenClaw\n\nOpenClaw 是一款开源、自托管的个人 AI 助手。通过自定义 Provider，可以让 OpenClaw 使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22.22.3 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\n检查安装是否成功：\n\n```bash\nopenclaw --version\n```\n\n## 2. 设置 API Key\n\nOpenClaw 配置支持从环境变量读取 Provider API Key。将 ModelGo API Key 设置为 `MODELGO_API_KEY`：\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. 配置 ModelGo Provider\n\n创建并打开 OpenClaw 配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\n将下面内容粘贴到 `openclaw.json`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | ModelGo 逻辑模型名 |\n| `agents.defaults.model.primary` | `modelgo/<逻辑模型名>` |\n\n:::note\n- `baseUrl` 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- `contextWindow` 和 `maxTokens` 应与所选模型的限制匹配；上方数值是通用示例，请以模型广场信息为准。\n- 如果模型支持推理，可将对应模型的 `reasoning` 改为 `true`。\n- API Key 通过环境变量注入，不要把真实 Key 写入配置文件或提交到仓库。\n:::\n\n## 4. 启动并验证\n\n保存配置后，在终端执行：\n\n```bash\nopenclaw onboard --install-daemon\n```\n\n查看当前模型和 Provider 状态：\n\n```bash\nopenclaw models status\n```\n\n如果状态正常，启动 Gateway：\n\n```bash\nopenclaw gateway start\n```\n\n在 OpenClaw 对话界面发送一条简单消息，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 接入成功。\n\n## 常见问题\n\n### 找不到模型\n\n确认 `models.providers.modelgo.models[].id` 与 `agents.defaults.model.primary` 中的模型名一致，并使用 `modelgo/<模型名>` 格式。\n\n### 返回 401 或认证失败\n\n检查当前终端是否存在 `MODELGO_API_KEY`，并确认 `apiKey` 使用 `${MODELGO_API_KEY}`，没有多余空格。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`baseUrl` 应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；OpenClaw 会按 `openai-completions` 协议拼接路径。\n\n### Gateway 没有加载新配置\n\n修改配置后重启 Gateway：\n\n```bash\nopenclaw gateway restart\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [OpenClaw 自定义 Provider 文档](https://docs.openclaw.ai/gateway/config-tools)：查看 Provider、Base URL 和模型列表配置说明。\n","china/zh/agents/opencode.md":"---\ntitle: OpenCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenCode。\n---\n\n# OpenCode\n\nOpenCode 是一个开源终端 AI 编程 Agent，支持通过自定义 Provider 接入 OpenAI 兼容接口。配置 ModelGo 后，可以在终端、IDE 或桌面端使用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已安装 OpenCode，并能在终端执行 `opencode -v`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenCode\n\n在终端执行：\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nWindows 用户也可以使用 OpenCode 官方提供的安装方式。安装完成后，执行 `opencode -v`，看到版本号即表示安装成功。\n\n## 2. 配置 ModelGo Provider\n\nOpenCode 默认从以下位置读取用户配置：\n\n- macOS/Linux：`~/.config/opencode/opencode.json`\n- Windows：`%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\n创建或编辑 `opencode.json`，填入以下内容。将 `你的模型名` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"你的模型名\"\n        }\n      }\n    }\n  }\n}\n```\n\n设置环境变量：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `name` | `ModelGo`，用于界面显示 |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | 模型广场中的逻辑模型 ID 和显示名称 |\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- `modelgo` 是本地 Provider ID，可以按需修改；修改后选择模型时使用新的 Provider ID。\n- API Key 通过环境变量读取，不要把真实 Key 直接写入配置文件或提交到仓库。\n- 模型 ID 必须是 ModelGo 模型广场中的逻辑模型名，不要直接照抄示例。\n:::\n\n## 3. 选择模型并开始对话\n\n启动 OpenCode：\n\n```bash\nopencode\n```\n\n输入 `/models` 打开模型选择器，搜索并选择 **ModelGo** Provider 下的模型。\n\n![在 OpenCode 中打开模型选择器](/images/agents/opencode/model-search.webp)\n\n模型列表中显示 **ModelGo** 的条目，即表示 Provider 已被识别。\n\n![在 OpenCode 模型列表中识别 ModelGo](/images/agents/opencode/provider-name.webp)\n\n也可以在模型选择器中输入 `ModelGo` 进行筛选：\n\n![在 OpenCode 中筛选 ModelGo 模型](/images/agents/opencode/provider-filter.webp)\n\n选择模型后输入一条简单任务，例如“用三句话介绍这个项目”。\n\n![在 OpenCode 中使用 ModelGo 开始对话](/images/agents/opencode/chat.webp)\n\n## 4. 验证配置\n\n如果模型列表为空，可以先确认 API Key 能访问 ModelGo：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是可填入 `models` 配置的逻辑模型名。\n\n## 常见问题\n\n### OpenCode 找不到配置文件\n\n确认文件名为 `opencode.json`，并放在 `~/.config/opencode/`（Windows 为 `%USERPROFILE%\\\\.config\\\\opencode\\\\`）目录下。也可以在项目目录放置同名配置覆盖用户配置。\n\n### 返回 401 或认证失败\n\n确认当前终端已设置 `MODELGO_API_KEY`，且 API Key 没有多余空格。重新打开终端后再启动 OpenCode。\n\n### 返回 404 或接口路径错误\n\n确认 `baseURL` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n### 模型列表为空或模型不可用\n\n确认 `models` 中的 ID 与模型广场逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [OpenCode 官方 Providers 文档](https://opencode.ai/docs/providers)：查看 Provider、凭据和自定义 Base URL 的配置方式。\n- [OpenCode 官方配置文档](https://opencode.ai/docs/config/)：了解配置文件结构及模型选项。\n","china/zh/agents/zcode.md":"---\ntitle: ZCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 ZCode。\n---\n\n# ZCode\n\nZCode 是智谱 AI 推出的桌面 AI 编程工具，支持 Windows、macOS 和 Linux。ZCode 支持自定义 OpenAI 兼容供应商，配置后可以直接使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 ZCode 桌面客户端。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 ZCode\n\n访问 [ZCode 官方下载页](https://zcode.z.ai/cn/docs/install)，根据操作系统下载对应安装包。ZCode 提供 macOS、Windows 和 Linux 版本，Linux 用户可以选择 `.deb`、`.rpm` 或 AppImage。\n\n![ZCode 官方下载页](/images/agents/zcode/install.webp)\n\n下载完成后，按系统提示完成安装并启动 ZCode。首次启动时可以选择工作区；完成引导后进入主界面。\n\n![ZCode 全平台安装包](/images/agents/zcode/setup.webp)\n\n## 2. 添加 ModelGo 供应商\n\n在 ZCode 左下角点击设置图标，进入 **Model settings**，然后在供应商列表底部点击 **Add provider**。\n\n![打开 ZCode Model settings 并添加供应商](/images/agents/zcode/provider-fields.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在 [控制台]({{ console_endpoint }}/api-keys) 创建的 ModelGo API Key |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | 点击 **Add model**，填写模型广场中的逻辑模型名 |\n| Context window | 按模型实际上下文长度填写；不确定时可先填 `200000` |\n\n![ModelGo 供应商配置示例](/images/agents/zcode/provider-saved.webp)\n\n点击 **Add provider** 保存。配置时请注意：\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；ZCode 会根据 API format 自动拼接路径。\n- Name 是本机显示名称，填写 `ModelGo` 即可，不需要填写上游厂商名称。\n- Model list 中的模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 添加模型并开始对话\n\n点击 **Add model**，输入一个 ModelGo 逻辑模型名并保存。可以按需添加多个模型。\n\n![ZCode 中选择 ModelGo 模型](/images/agents/zcode/chat.webp)\n\n回到对话界面，在模型下拉菜单中选择 **ModelGo** 和刚添加的模型，输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n如需确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认填写在 **API Key** 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 Model list 中填写的是模型广场中的逻辑模型名，且当前 API Key 策略允许调用该模型。\n\n### 返回 404 或接口路径错误\n\nBase URL 应为 `{{ api_endpoint }}/v1`，API format 请选择 **Chat completions (/chat/completions)**，不要把完整接口路径填入 Base URL。\n\n### 模型列表为空或无法保存\n\n确认至少添加了一个模型，并检查 Base URL 是否可以访问。必要时先用 `GET {{ api_endpoint }}/v1/models` 验证 API Key 和接口。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [ZCode 安装文档](https://zcode.z.ai/cn/docs/install)：查看最新安装说明。\n- [ZCode 连接模型文档](https://zcode.z.ai/cn/docs/configuration)：查看自定义供应商和模型配置说明。\n","china/zh/models/audio/minimax.md":"---\ntitle: MiniMax 音频\ndescription: 用 MiniMax T2A 原厂请求体与响应体做平台托管的同步语音合成。\n---\n\n# MiniMax 音频\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | 目录公示的 MiniMax T2A 入站 |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK 别名，语义相同 |\n\n这是 **MiniMax 同步语音合成（T2A V2）** 的原厂入站协议。请求体按 MiniMax `T2aV2Req` 原样接收（`model`、`text`、`voice_setting`、`audio_setting`、`stream` 等），**响应体也按 MiniMax `T2aV2Resp` 渲染**，照 MiniMax 官方文档写的客户端可以直接解析。\n\n`model` 填写平台逻辑模型名，策略、路由与计费照常生效。逻辑模型必须在 `public_protocols` 中声明 `minimax_t2a`，否则网关返回协议不匹配。\n\n只需要 OpenAI 形态的二进制音频时，见[语音合成](./speech)。\n\n## 合成\n\n两条路径等价，任选其一：\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"你好，欢迎使用 ModelGo。\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\n非流式成功响应是 MiniMax JSON，音频在 `data.audio`，为**十六进制字符串**（不是 `audio/mpeg` 直出）：\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\n2026-09-10 国内生产用 `speech-2.8-turbo` 打 `POST /minimax/v1/t2a_v2` 得到上述形态（hex 已截断）。同一模型打 `POST /v1/audio/speech` 返回 `model_protocol_not_offered`。\n\n`base_resp.status_code` **只有数字 `0` 表示成功**。HTTP 200 但 `status_code != 0` 仍按调用失败处理。\n\n### 流式\n\n请求里加 `\"stream\": true`，响应为 SSE，每帧仍是 MiniMax JSON（含增量 hex 音频），不是 OpenAI chat 的 `choices[].delta`。\n\n### 失败与 HTTP\n\n带内错误会把 MiniMax JSON 回传给调用方，并按 `status_code` 映射 HTTP 状态：\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| 其余非 `0` | `502` |\n\n### 计费\n\n按上游报告的 **字符数** 计量（`usage.characters`，否则 `extra_info.usage_characters`），不会用 `text` 的字符串长度估算。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；是否可走本通道以该模型的 `public_protocols` 为准。\n- 路径不参与选路：由逻辑模型的路由决定 MiniMax 直连或百炼等 adaptor。\n- 路由上的 Provider 必须声明支持 MiniMax T2A；仅 OpenAI 兼容中继时会返回 `provider_unsupported`。\n","china/zh/models/audio/speech.md":"---\ntitle: 语音合成\ndescription: OpenAI 兼容 text-to-speech 接口说明。\n---\n\n# 语音合成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\n请求体为 JSON（OpenAI `{input, voice}`），响应体为二进制音频，`Content-Type` 由上游决定并原样返回。\n\n**先确认模型声明了 OpenAI TTS 协议。** 国内生产上的 `speech-2.8-hd` / `speech-2.8-turbo` 当前走 MiniMax T2A，打本接口会返回 `model_protocol_not_offered`。这两款模型请用 [MiniMax 音频入站协议](./minimax)。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"你好，欢迎使用 ModelGo。\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\n需要 MiniMax 原厂字段（音色、字幕、hex JSON、SSE）时，见[MiniMax 音频入站协议](./minimax)。\n","china/zh/models/audio/transcriptions.md":"---\ntitle: 语音转文本\ndescription: OpenAI 兼容 speech-to-text 接口说明。\n---\n\n# 语音转文本\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\n该接口通常以 `multipart/form-data` 上传音频文件和 `model` 字段，响应为 JSON，包含识别出的 `text`。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/zh/models/audio/translations.md":"---\ntitle: 语音翻译\ndescription: OpenAI 兼容语音翻译接口说明。\n---\n\n# 语音翻译\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\n上传方式与语音转文本一致，响应为 JSON。适合把音频内容翻译为目标文本输出。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","china/zh/models/images/edits.md":"---\ntitle: 图像编辑\ndescription: OpenAI 兼容图像编辑接口说明。\n---\n\n# 图像编辑\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\n该接口使用 `multipart/form-data` 上传原图和 `model` 字段。网关会保留原始 body 与 `Content-Type` 向上游透传，因此调用时应直接使用 `POST /v1/images/edits` 的 multipart 方式。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\n如果上游模型不支持图像编辑，平台会返回 `provider_unsupported`。\n","china/zh/models/images/gemini-image.md":"---\ntitle: Gemini 图像\ndescription: 按 Google Gemini API 官方 generateContent 协议调用 gemini-3-pro-image、gemini-3.1-flash-image、gemini-3.1-flash-lite-image：responseModalities、aspectRatio / imageSize 档位、inlineData 响应与按 token 计费口径。Google GenAI SDK 改 base_url 即可直连。\n---\n\n# Gemini 图像\n\n| 模型（路径中使用） | 定位 | 可选 `imageSize` |\n| --- | --- | --- |\n| `gemini-3-pro-image` | 质量版 | `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-image` | 速度与成本均衡 | `512px` / `1K` / `2K` / `4K` |\n| `gemini-3.1-flash-lite-image` | 最低成本 | 仅 `1K` |\n\nModelGo 按 Google Gemini API 的 **`generateContent`** 协议原样接收图像生成请求：`contents` + `generationConfig`，同步返回 `candidates[].content.parts[].inlineData`。网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。**URL 路径中的模型名是唯一权威**，请求体中无需再写模型。\n\n> 使用 Google GenAI SDK 时，把 `http_options.base_url` 指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key 即可。鉴权头同时接受 `x-goog-api-key: $KEY` 与 `Authorization: Bearer $KEY`。\n>\n> Google 新推出的 Interactions API 暂不支持，请使用 `generateContent`。\n\n## 1. 创建图像\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:generateContent`（也接受 `/v1/models/...`）\n\n### 文生图\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [{\"text\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\"}]}],\n    \"generationConfig\": {\n      \"responseModalities\": [\"IMAGE\"],\n      \"imageConfig\": {\"aspectRatio\": \"16:9\", \"imageSize\": \"2K\"}\n    }\n  }'\n```\n\n### 图生图\n\n参考图以 `inlineData`（base64）或 `fileData`（公网 URL）放进 `parts`：\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/gemini-3-pro-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"contents\": [{\"role\": \"user\", \"parts\": [\n      {\"text\": \"把背景换成霓虹夜景，保留猫的姿态\"},\n      {\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"<base64>\"}}\n    ]}],\n    \"generationConfig\": {\"responseModalities\": [\"IMAGE\"], \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}}\n  }'\n```\n\n`fileData` 写法：`{\"fileData\": {\"fileUri\": \"https://example-cdn.com/cat.png\"}}`，必须是上游可直接 `GET` 的直链。\n\n### 响应\n\n```json\n{\n  \"candidates\": [{\n    \"content\": {\n      \"role\": \"model\",\n      \"parts\": [{\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"iVBORw0KGgo...\"}}]\n    },\n    \"finishReason\": \"STOP\",\n    \"index\": 0\n  }],\n  \"usageMetadata\": {\n    \"promptTokenCount\": 18,\n    \"candidatesTokenCount\": 1680,\n    \"totalTokenCount\": 1698,\n    \"promptTokensDetails\": [{\"modality\": \"TEXT\", \"tokenCount\": 18}],\n    \"candidatesTokensDetails\": [{\"modality\": \"IMAGE\", \"tokenCount\": 1680}]\n  },\n  \"modelVersion\": \"gemini-3.1-flash-image\"\n}\n```\n\n- 图像在 `parts[].inlineData.data`（base64）。`responseModalities` 含 `TEXT` 时，`parts` 中可能另有 `{\"text\": ...}` 段。\n- `modelVersion` 回显请求路径中的模型名。\n\n保存到文件：\n\n```bash\ncurl -s \"{{ api_endpoint }}/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"contents\":[{\"parts\":[{\"text\":\"a red ball on a wooden table\"}]}],\"generationConfig\":{\"responseModalities\":[\"IMAGE\"]}}' \\\n  | python3 -c '\nimport sys, json, base64\nfor p in json.load(sys.stdin)[\"candidates\"][0][\"content\"][\"parts\"]:\n    if \"inlineData\" in p:\n        open(\"out.png\", \"wb\").write(base64.b64decode(p[\"inlineData\"][\"data\"])); break'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `contents[].role` | string | `user` |\n| `contents[].parts[].text` | string | 提示词。画面内容描述；图生图时描述如何修改 |\n| `contents[].parts[].inlineData` | object | 参考图，`{\"mimeType\": \"image/png\", \"data\": \"<base64>\"}` |\n| `contents[].parts[].fileData` | object | 参考图 URL，`{\"fileUri\": \"https://...\"}` |\n| `systemInstruction` | object | 可选，系统指令，与 Gemini 文本调用一致 |\n| `generationConfig.responseModalities` | string[] | `[\"IMAGE\"]` 只出图；`[\"TEXT\",\"IMAGE\"]` 图文混排 |\n| `generationConfig.imageConfig.aspectRatio` | string | `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` |\n| `generationConfig.imageConfig.imageSize` | string | 分辨率档位，各模型可选值见首表，缺省 `1K` |\n\n- `candidateCount` > 1 → `400`：一次只出一张。\n- `tools`、`responseSchema` / `responseMimeType` → `400`：图像模型不支持工具调用与结构化输出。\n- `:streamGenerateContent` → `400`：图像生成不支持流式。\n- 模型不提供的 `imageSize`（如 `gemini-3.1-flash-lite-image` 传 `2K`）→ `400`，**不会静默降档生成**，不产生费用。\n- **按可交付档位选路。** 网关只把请求交给能按所声明档位交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 分辨率档位\n\n| 档位 | 像素量级 | 实测输出（示例） |\n| --- | --- | --- |\n| `512px` | 约 0.25 MP | — |\n| `1K`（缺省） | 约 1 MP | 缺省 → 1408×768 |\n| `2K` | 约 4 MP | `16:9` → 2752×1536 |\n| `4K` | 约 16 MP | `9:16` → 3072×5504 |\n\n档位决定总像素量级，**精确宽高由 `aspectRatio` 决定**；不指定 `aspectRatio` 时缺省为供应商的近似 16:9 输出。\n\n## 3. 完整示例（Python，Google GenAI SDK）\n\n```python\nimport os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(api_key=os.environ[\"MODELGO_API_KEY\"],\n                      http_options={\"base_url\": \"{{ api_endpoint }}\"})\n\nresp = client.models.generate_content(\n    model=\"gemini-3.1-flash-image\",\n    contents=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    config=types.GenerateContentConfig(\n        response_modalities=[\"IMAGE\"],\n        image_config=types.ImageConfig(aspect_ratio=\"16:9\", image_size=\"2K\"),\n    ),\n)\nfor part in resp.candidates[0].content.parts:\n    if part.inline_data:\n        open(\"cat.png\", \"wb\").write(part.inline_data.data)\nprint(resp.usage_metadata.candidates_token_count)\n```\n\n图生图时把 `contents` 换成列表：`[\"把背景换成霓虹夜景\", types.Part.from_bytes(data=open(\"cat.png\",\"rb\").read(), mime_type=\"image/png\")]`。\n\n## 4. 计费口径\n\n- **按 token 计费**：`promptTokensDetails` 中的文本按 `input`、图像按 `image_input`；`candidatesTokensDetails` 中 `IMAGE` 按 `image_output`、`TEXT` 按 `output`。\n- 输出图像 token 随档位增长（实测）：`1K` ≈ 1120，`2K` ≈ 1680，`4K` ≈ 2000。\n- 请求时预授权冻结，响应返回后按 `usageMetadata` 实际值结算。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- 各模型单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `imageSize` 不在该模型可选档位内；`aspectRatio` 不在参数表内；`candidateCount` > 1；带了 `tools` / `responseSchema` / `responseMimeType`；调用了 `:streamGenerateContent`；当前无供应商能出所请求档位 | 按参数表修正，改用 `generateContent` |\n| `parts` 中没有 `inlineData` | `responseModalities` 未含 `IMAGE`，或提示词被安全策略拦截（`finishReason` 非 `STOP`） | 显式传 `[\"IMAGE\"]`；检查 `finishReason` |\n| 参考图未生效 | `fileData.fileUri` 不是公网直链（需鉴权 / 跳转 / 403） | 改用 `inlineData` 或自有 CDN 直链 |\n| 返回 `401` | API Key 无效或未带 `x-goog-api-key` / `Authorization` 头 | 核对 Key |\n","china/zh/models/images/generations.md":"---\ntitle: 图像生成\ndescription: OpenAI 兼容图像生成接口说明。\n---\n\n# 图像生成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\n请求体遵循 OpenAI Images 兼容格式，平台将其透传到支持图像生成的上游 Provider。核心入口是 `POST /v1/images/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\n常见可选字段包括 `size`、`quality`、`n` 等，是否生效取决于实际路由到的上游模型能力。\n\n## 已验证限制（Seedream）\n\n`doubao-seedream-5.0-lite` 在 `size=1024x1024` 时上游拒绝：HTTP 400、`error_class=provider_invalid`，要求像素总数至少 3686400（约 1920×1920）。改用 `2048x2048` 后于 2026-09-10 国内生产返回 200。完整 curl 见[接口清单](../../../quickstart/openapi)。\n","china/zh/models/images/gpt-image-2.md":"---\ntitle: GPT Image\ndescription: 按 OpenAI Images API 官方协议调用 gpt-image-2 / gpt-image-1.5：generations 文生图、edits 图生图与蒙版编辑、size / quality 参数、b64_json 响应与按 token 计费口径。OpenAI 官方 SDK 改 base_url 即可直连。\n---\n\n# GPT Image\n\n| 模型 | 接口 | 缺省档输出 token（`1024x1024` + `quality: auto`，实测） |\n| --- | --- | --- |\n| `gpt-image-2` | generations / edits | 196 |\n| `gpt-image-1.5` | generations / edits | 4444 |\n\n| 接口 | 能力 | 请求体 | 必填字段 |\n| --- | --- | --- | --- |\n| `POST /v1/images/generations` | 文生图 | JSON | `model`、`prompt` |\n| `POST /v1/images/edits` | 图生图 / 蒙版编辑（多参考图） | `multipart/form-data` | `model`、`prompt`、`image[]` |\n\n两个模型参数集相同、走同一组接口，仅 `model` 字段不同；输出 token 数与单价各不相同（见「计费口径」）。\n\nModelGo 按 OpenAI Images API 的官方路径与请求/响应格式原样接收 `gpt-image-2` / `gpt-image-1.5` 请求，网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。图像**同步返回**，无需轮询。\n\n> 使用 OpenAI 官方 SDK 时，把 `base_url` 指向 `{{ api_endpoint }}/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 1. 创建图像\n\n### 文生图\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-image-2\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    \"size\": \"1536x1024\",\n    \"quality\": \"high\",\n    \"output_format\": \"png\"\n  }'\n```\n\n### 图生图 / 蒙版编辑\n\n`POST {{ api_endpoint }}/v1/images/edits`（`multipart/form-data`）\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=gpt-image-2\" \\\n  -F \"prompt=把背景换成霓虹夜景，保留猫的姿态\" \\\n  -F \"image[]=@./cat.png\" \\\n  -F \"mask=@./mask.png\" \\\n  -F \"size=1024x1024\" \\\n  -F \"quality=medium\" \\\n  -F \"input_fidelity=high\"\n```\n\n- `image[]` 可重复出现，一次传入多张参考图。\n- `model`、`prompt`、`size`、`quality`、`n` 等文本字段只能出现一次，且必须是普通表单字段（不能作为文件上传），否则返回 400。\n- `mask` 可选，PNG，尺寸必须与第一张 `image[]` 一致；透明区域为需要重绘的区域。\n\n### 响应\n\n```json\n{\n  \"created\": 1757318400,\n  \"data\": [{\"b64_json\": \"iVBORw0KGgoAAAANSUhEUgAA...\"}],\n  \"usage\": {\n    \"input_tokens\": 17,\n    \"input_tokens_details\": {\"text_tokens\": 17, \"image_tokens\": 0},\n    \"output_tokens\": 5488,\n    \"output_tokens_details\": {\"image_tokens\": 5488, \"text_tokens\": 0},\n    \"total_tokens\": 5505\n  }\n}\n```\n\n图像始终以 `data[].b64_json`（base64）返回。保存到文件：\n\n```bash\ncurl -s {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gpt-image-2\",\"prompt\":\"a red ball on a wooden table\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.png\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 全部 | `gpt-image-2` / `gpt-image-1.5` |\n| `prompt` | string | 全部 | 必填。画面内容描述；edits 中描述要如何修改 |\n| `image[]` | file | edits | 必填。一张或多张参考图（png / jpeg / webp） |\n| `mask` | file | edits | 可选。PNG 蒙版，尺寸与图像一致，透明区域为重绘区 |\n| `input_fidelity` | string | edits | 对参考图的保真度，`low` / `high` |\n| `n` | int | 全部 | 生成张数，缺省 `1` |\n| `size` | string | 全部 | 缺省 `auto`。**gpt-image-2**：任意 `宽x高`，宽、高都是 16 的倍数，且宽 × 高在 655,360 到 8,294,400 之间（例如 `1248x832`、`1248x1248`、`3840x2160`）；长宽比等更细的限制由上游判定，不通过时 400 的报错信息会写明原因。**gpt-image-1.5**：仅 `1024x1024` / `1536x1024` / `1024x1536` / `auto` |\n| `quality` | string | 全部 | `low` / `medium` / `high` / `auto`，缺省 `auto`。直接决定输出 token 数 |\n| `output_format` | string | 全部 | `png` / `jpeg` / `webp` |\n| `output_compression` | int | 全部 | `0`–`100`，仅对 `jpeg` / `webp` 生效 |\n| `background` | string | 全部 | `opaque` / `transparent` / `auto` |\n| `moderation` | string | 全部 | 内容审核强度，透传 |\n\n- **`response_format` 不适用于 gpt-image 系列。** 网关会在转发前剥离该字段，不报错；图像始终以 `b64_json` 返回，不提供 `url` 形态。\n- `size` / `quality` 不在上表内、缺 `prompt` → HTTP `400`，不计费。\n- **按可交付档位选路。** 网关只把请求交给能按所声明 `size` / `quality` 交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 输出 token 参考（实测）\n\n| 模型 | `size` | `quality` | `output_tokens_details.image_tokens` |\n| --- | --- | --- | --- |\n| `gpt-image-2` | `1024x1024` | `auto`（缺省） | 196 |\n| `gpt-image-2` | `1536x1024` | `high` | 5488 |\n| `gpt-image-1.5` | `1024x1024` | `auto`（缺省） | 4444 |\n\n输出 token 由模型、尺寸与质量档共同决定：gpt-image-2 的 `high` 档比缺省档高一个数量级以上；同为缺省档，gpt-image-1.5 的输出 token 是 gpt-image-2 的 20 倍以上。两个模型的 token 数与单价都不同，换模型前请核算成本。\n\n## 3. 完整示例（Python，OpenAI 官方 SDK）\n\n```python\nimport base64, os\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/v1\")\n\n# 文生图\nr = client.images.generate(model=\"gpt-image-2\", prompt=\"一只橘猫坐在窗台上，胶片质感\",\n                           size=\"1536x1024\", quality=\"high\", output_format=\"png\")\nopen(\"cat.png\", \"wb\").write(base64.b64decode(r.data[0].b64_json))\nprint(r.usage.output_tokens_details.image_tokens)\n\n# 图生图（蒙版编辑）\nwith open(\"cat.png\", \"rb\") as img, open(\"mask.png\", \"rb\") as mask:\n    e = client.images.edit(model=\"gpt-image-2\", prompt=\"把背景换成霓虹夜景\",\n                           image=[img], mask=mask, size=\"1024x1024\", quality=\"medium\")\nopen(\"cat-neon.png\", \"wb\").write(base64.b64decode(e.data[0].b64_json))\n```\n\n## 4. 计费口径\n\n- **按 token 计费**，三个价目：文本输入（`input`）、图像输入（`image_input`）、图像输出（`image_output`），单位为每百万 token。输出中的图像部分按 `image_output` 单价计。\n- gpt-image-2 与 gpt-image-1.5 各有独立价卡，且同一档位的输出 token 数差异显著（缺省档 196 对 4444），同一请求在两个模型上的费用不可互推。\n- 请求时预授权冻结，响应返回后按 `usage` 中的实际 token 结算：`input_tokens_details.text_tokens` → `input`，`input_tokens_details.image_tokens` → `image_input`，`output_tokens_details.image_tokens` → `image_output`。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- 各价目以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `size` / `quality` 不在参数表内；缺 `prompt`；edits 缺 `image[]` 或 `mask` 尺寸与图像不一致；当前无供应商能出所请求档位 | 按参数表修正或换档位 |\n| 传了 `response_format: \"url\"` 仍返回 `b64_json` | gpt-image 系列不支持该字段，网关静默剥离 | 从 `data[].b64_json` 解码保存 |\n| 返回 `429` | 触发速率限制 | 退避重试；如需更高配额联系平台 |\n| 返回 `401` | API Key 无效或未带 `Authorization` 头 | 核对 Key |\n","china/zh/models/images/qwen-image.md":"---\ntitle: 千问图像\ndescription: 调用 qwen-image-3.0 / qwen-image-3.0-pro：OpenAI 兼容与百炼 DashScope 原生两条同步入站通道、文生图与图生图（1-3 张参考图）、size 的两种分隔符写法、1k / 2k 分辨率档位与按张计费口径。百炼官方 SDK 改 base_url 即可直连。\n---\n\n# 千问图像\n\n## 模型\n\n| 模型 | 输出分辨率 | 说明 |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | 总像素 512×512 – 2048×2048 | Pro 系列，2k 档单价高于 1k 档 |\n| `qwen-image-3.0` | 同上 | 标准版，两个档位同价 |\n\n两个模型都同时支持**文生图（T2I）**和**图生图 / 图像编辑（I2I）**：不传参考图是文生图，传 1–3 张参考图是图生图。图像**同步返回**，无需轮询。\n\n> **不支持异步任务通道。** 这一族只在同步接口上服务；打 `/v1/content_generation/tasks` 会被拒。\n\n## 两条入站通道\n\n同一个模型有两种调用写法，能力完全一致，按你现有代码的形状选：\n\n| 通道 | 路径 | 适合谁 |\n| --- | --- | --- |\n| OpenAI 兼容 | `POST /v1/images/generations` | 已按 OpenAI Images 协议或 OpenAI SDK 开发的应用，只改 `base_url` 与 `model` |\n| 百炼原生 | `POST /api/v1/services/aigc/multimodal-generation/generation` | 已在用百炼 DashScope SDK 的应用，只改 `base_url` |\n\n> **两条通道的 `size` 分隔符不同，且互不接受**：OpenAI 兼容通道用字母 `x`（`1024x1024`），百炼原生通道用星号 `*`（`1024*1024`）。写错的那一侧会返回 `400` 并点名正确的分隔符，**不会**被静默改写 —— 这是为了让协议混用尽早显形，而不是在别处出更难查的问题。\n\n## 1. OpenAI 兼容通道\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### 文生图\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，午后光线，胶片质感\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### 图生图 / 图像编辑\n\n不用 multipart，参考图放在请求体顶层的 `image` 字段：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"保留这位女性的面部特征，把服装换成香槟色真丝衬衫与深灰西装外套\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- 图像格式为 PNG，**链接有效期 24 小时**，请及时下载，不要持久化该 URL。\n- `usage` 是**图片张数与档位**，不是 token 用量 —— 这一族的计费完全按张，见「计费口径」。\n- 传 `response_format: \"b64_json\"` 不会报错，但会被忽略，响应中仍是图像 URL。\n\n### 使用 OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # 出图耗时较长，实测单张 40-60 秒\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # 扩展字段走 extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` 不是 OpenAI 官方参数，用 OpenAI SDK 时通过 `extra_body` 传入；直接发 HTTP 请求时放在请求体顶层即可。\n\n## 2. 百炼原生通道\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\n请求与响应两头都是百炼原样的形状，网关不做翻译。\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### 这条通道的约束\n\n- `input.messages` **有且只有一个**对象，`role` 必须是 `user`（仅支持单轮对话）。\n- `content` 里**有且只有一个** `{\"text\": ...}`，不传或传多个都会 `400`。\n- `{\"image\": ...}` 0–3 个：0 个是文生图，1–3 个是图生图。\n- 生成参数放在 `parameters` 下（不是顶层）：`size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`。\n- 使用百炼官方 SDK（`dashscope`）时，把 `dashscope.base_http_api_url` 指向 `{{ api_endpoint }}/api/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 3. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt`（兼容通道）/ `content[].text`（原生通道） | string | 必填，非空。支持中英文，建议不超过 4500 token |\n| `image`（兼容通道）/ `content[].image`（原生通道） | string / string[] | 参考图，1–3 张。**不能传 `null` 或空数组** |\n| `size` | string | 兼容通道 `宽x高`，原生通道 `宽*高`；不传则由模型按提示词自动推荐分辨率 |\n| `n` | int | 输出张数 1–6，缺省 1。**必须是整数**，传字符串形式（如 `\"1\"`）返回 `400` |\n| `negative_prompt` | string | 反向提示词 |\n| `seed` | int | 随机数种子，`0` – `2147483647`。固定种子可让结果相对稳定 |\n| `prompt_extend` | boolean | 是否开启提示词智能改写，缺省 `true`（建议开启） |\n| `prompt_extend_mode` | string | `direct`（缺省，T2I / I2I 均支持）/ `agent`（更精细，**仅文生图**） |\n| `enable_thinking` | boolean | 思考模式，缺省 `true`。提升出图质量但增加耗时。仅在 `prompt_extend=true` 时生效 |\n| `watermark` | boolean | 是否加水印，缺省 `false` |\n\n### 参数校验在调用前完成\n\n下列请求在**创建时**就被拒（HTTP `400`），不会打到上游、不产生费用：\n\n- `n` 不是 1–6 的整数，或写成了字符串 / 小数；\n- `size` 的总像素不在 512×512 – 2048×2048 之间，或宽高比超出 1:8 – 8:1；\n- `size` 用了另一条通道的分隔符（错误信息会点名该用 `x` 还是 `*`）；\n- `image` 为 `null`、空数组，或超过 3 张；\n- `prompt_extend_mode: \"agent\"` 与 `image` 同时出现（APE 仅支持文生图）；\n- `seed` 超出 `0` – `2147483647`；\n- 原生通道上 `messages` 不是恰好一个、或 `content` 里的 `text` 不是恰好一个。\n\n### 参考图的要求\n\n- 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF。\n- 建议宽高均在 384 – 2048 像素之间，单张不超过 10 MB。\n- 支持公网 URL（HTTP / HTTPS）或 Base64（`data:{MIME_type};base64,{base64_data}`）。\n- 公网 URL 必须是上游能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。部分站点对非浏览器抓取返回 403，会导致请求失败。\n\n## 4. 计费口径\n\n**按张计费，不按 token。** 输入（参考图）与输出（生成图）分别计价，各自再分 1k / 2k 两档：\n\n| 模型 | 输出档位 | 输出单价 | 输入单价 |\n| --- | --- | --- | --- |\n| `qwen-image-3.0-pro` | 1k | 0.25 元/张 | 0.02 元/张 |\n| `qwen-image-3.0-pro` | 2k | 0.50 元/张 | 0.02 元/张 |\n| `qwen-image-3.0` | 1k | 0.18 元/张 | 0.02 元/张 |\n| `qwen-image-3.0` | 2k | 0.18 元/张 | 0.02 元/张 |\n\n**档位按「输出」像素面积判定**：面积 ≤ 2,250,000（即 1500×1500）为 `1k`，更大为 `2k`。**输入图的档位同样按输出面积判定**，不是按参考图自己的尺寸 —— 这是上游的口径。响应 `usage` 里的 `output_image_type` / `input_image_type` 就是本次实际命中的档位。\n\n计费金额 = 输出张数 × 该档输出单价 + 输入张数 × 输入单价。几个实测例子（国内生产，2026-09-11）：\n\n| 请求 | `usage` | 结算金额 |\n| --- | --- | --- |\n| `qwen-image-3.0`，`1024x1024`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_1k` | 0.18 元 |\n| `qwen-image-3.0`，`1024x1024`，`n=2`，文生图 | `output_image_count: 2`，`qima_output_1k` | 0.36 元 |\n| `qwen-image-3.0-pro`，`1024x1024`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_1k` | 0.25 元 |\n| `qwen-image-3.0-pro`，`2048x2048`，`n=1`，文生图 | `output_image_count: 1`，`qima_output_2k` | 0.50 元 |\n\n**文生图不产生输入费用**：没有参考图时 `input_image_count` 为 0，只结算输出张数。\n\n## 5. 完整示例（Python，百炼官方 SDK）\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫，背景换成现代简约咖啡店\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","china/zh/models/images/seedream.md":"---\ntitle: Seedream\ndescription: 按火山引擎方舟 Images API 官方协议调用 Seedream 系列（doubao-seedream-5.0-pro / 5.0-lite / 5.0 / 4.5）：文生图 / 多图参考、各模型 size 档位与像素写法、url / b64_json 响应与按张计费口径。方舟官方 SDK 改 base_url 即可直连。\n---\n\n# Seedream\n\n## 模型与档位\n\n| 模型 | 缺省 `size` | 可用 `size` | 典型输出（实测） |\n| --- | --- | --- | --- |\n| `doubao-seedream-5.0-pro` | `2K` | `1K` / `1.5K` / `2K`，或 `WxH` | `1K` ≈ 1152×864；`1.5K` ≈ 1792×1344；`2K` + 16:9 提示 → 2816×1584 |\n| `doubao-seedream-5.0-lite` | `2K` | `2K` / `3K` / `4K`，或总像素 ≥ 3,686,400 的 `WxH` | `2K` → 2048×2048；`3K` → 3072×3072；`4K` → 4096×4096 |\n| `doubao-seedream-5.0` | `2K` | 同 5.0 lite | 同 5.0 lite |\n| `doubao-seedream-4.5` | `2K` | `2K` / `4K`，或总像素 ≥ 3,686,400 的 `WxH`（**不提供 `3K`**） | `2K` → 2048×2048；`4K` → 4096×4096 |\n\n- 四个模型走同一入口 `POST /api/v3/images/generations`，能力均为文生图、图生图（单图 / 多图参考），必填 `model`、`prompt`。\n- `doubao-seedream-5.0` 是 `doubao-seedream-5.0-lite` 的别名：方舟没有独立的 5.0 模型，二者档位与单价完全一致。\n- 5.0 pro **不提供** `3K` / `4K`；5.0 lite / 5.0 / 4.5 **不提供** `1K` / `1.5K`（方舟要求总像素 ≥ 3,686,400）；4.5 另外**不提供** `3K`。表外档位在创建时被拒（HTTP `400`），不渲染、不计费。\n- 5.0 pro 的 `1.5K` 与 `1K` 同价（方舟定价），且只有部分供应商能出该档位，可用线路少于其他档位。\n\nModelGo 按火山引擎方舟 **Images API** 的官方路径与请求/响应格式原样接收 Seedream 请求，网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。图像**同步返回**，无需轮询。\n\n> 使用方舟官方 SDK（`volcenginesdkarkruntime`）时，把 `base_url` 指向 `{{ api_endpoint }}/api/v3`、`api_key` 换成 ModelGo API Key 即可。\n\n## 1. 创建图像\n\n`POST {{ api_endpoint }}/api/v3/images/generations`\n\n### 文生图（5.0 pro）\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，16:9 横构图，胶片质感\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### 文生图（5.0 lite）\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    \"size\": \"2K\",\n    \"watermark\": false\n  }'\n```\n\n### 图生图 / 多图参考\n\n```bash\ncurl {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-pro\",\n    \"prompt\": \"把第一张图的猫放到第二张图的霓虹街景里\",\n    \"image\": [\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n    \"size\": \"1280x720\",\n    \"response_format\": \"b64_json\"\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"model\": \"doubao-seedream-5.0-pro\",\n  \"created\": 1757318400,\n  \"data\": [{\"url\": \"https://ark-content-generation.tos-cn-beijing.volces.com/...\", \"size\": \"2816x1584\", \"output_format\": \"jpeg\"}],\n  \"usage\": {\"generated_images\": 1, \"input_images\": 0, \"output_tokens\": 17424, \"total_tokens\": 17424}\n}\n```\n\n- `model` 始终回显你请求的逻辑模型名（如 `doubao-seedream-5.0-lite`），不是方舟内部的版本 id（形如 `doubao-seedream-5-0-260128` / `doubao-seedream-4-5-251128` / `doubao-seedream-5-0-pro-260628`）。\n- `response_format` 缺省 `url`，**链接 24 小时内有效**，请及时下载，不要持久化该 URL。\n- `response_format: \"b64_json\"` 时 `data[].b64_json` 直接给出 base64 图像。\n- `data[].size` 是实际输出像素，`output_format` 是实际编码格式。\n- `usage.output_tokens` / `total_tokens` 为上游回显的参考值，**不参与计费**；结算只看 `usage.generated_images`。\n\n保存到文件：\n\n```bash\ncurl -s {{ api_endpoint }}/api/v3/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedream-5.0-lite\",\"prompt\":\"a red ball on a wooden table\",\"size\":\"2K\",\"response_format\":\"b64_json\"}' \\\n  | python3 -c 'import sys,json,base64; open(\"out.jpg\",\"wb\").write(base64.b64decode(json.load(sys.stdin)[\"data\"][0][\"b64_json\"]))'\n```\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `doubao-seedream-5.0-pro` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0` / `doubao-seedream-4.5` |\n| `prompt` | string | 必填。画面内容描述；使用档位写法时在此描述构图比例 |\n| `image` | string / string[] | 参考图 URL（单图）或 URL 数组（多图参考），必须是上游可直接 `GET` 的公网直链 |\n| `size` | string | 分辨率档位（缺省 `2K`；各模型可用档位见「模型与档位」），或显式像素 `WxH`（如 `1280x720`、`2560x1440`） |\n| `seed` | int | 随机种子 |\n| `guidance_scale` | number | 提示词贴合度 |\n| `watermark` | boolean | 是否加水印，缺省 `true` |\n| `response_format` | string | `url`（缺省，24 小时有效）/ `b64_json` |\n| `output_format` | string | 输出编码格式，透传 |\n\n- `sequential_image_generation: \"auto\"`（组图）在 5.0 pro 上不支持 → `400`。\n- `stream: true` → `400`：不支持流式。\n- 请求体中出现上表之外的字段 → `400`，不会被忽略。\n- **按可交付档位选路。** 网关只把请求交给能按所声明 `size` 交付的供应商；若当前无供应商能出该档位，返回 `400`，不产生费用。\n\n### 分辨率档位\n\n| 模型 | `size` 写法 | 输出 | 实测示例 |\n| --- | --- | --- | --- |\n| 5.0 pro | `1K` / `1.5K` / `2K`（缺省） | 档位决定总像素量级，宽高比由 `prompt` 中的构图描述决定 | `\"2K\"` + 16:9 提示 → 2816×1584；`\"1.5K\"` → 1792×1344；`\"1K\"` → 1152×864 |\n| 5.0 lite / 5.0 | `2K`（缺省）/ `3K` / `4K` | 档位决定输出边长 | `\"2K\"` → 2048×2048；`\"3K\"` → 3072×3072；`\"4K\"` → 4096×4096 |\n| 4.5 | `2K`（缺省）/ `4K` | 同上；4.5 不提供 `3K` | `\"2K\"` → 2048×2048；`\"4K\"` → 4096×4096 |\n| 全部 | `WxH` | 精确按指定宽高输出；宽高比在 1/16 – 16 之间。5.0 lite / 5.0 / 4.5 要求总像素 ≥ 3,686,400 | 5.0 pro：`\"1280x720\"` → 1280×720；5.0 lite：`\"2560x1440\"` → 2560×1440 |\n\n- 表外的 `size`（该模型不提供的档位、像素低于下限或宽高比越界）在创建时被拒（HTTP `400`），不会静默降档或升档生成，也不产生费用。\n\n### 参考图的要求\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。\n- 部分站点直链对非浏览器抓取返回 403，会导致请求失败，不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 完整示例（Python，方舟官方 SDK）\n\n```python\nimport os, requests\nfrom volcenginesdkarkruntime import Ark\n\nclient = Ark(api_key=os.environ[\"MODELGO_API_KEY\"], base_url=\"{{ api_endpoint }}/api/v3\")\n\n# 5.0 pro：档位 + 提示词里的构图比例\nr = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"一只橘猫坐在窗台上，16:9 横构图，胶片质感\",\n                           size=\"2K\", watermark=False)\nimg = r.data[0]\nprint(r.model, img.size, r.usage.generated_images)\nopen(\"cat.jpg\", \"wb\").write(requests.get(img.url, timeout=60).content)\n\n# 5.0 lite：2K 缺省档（2048x2048）\nl = client.images.generate(model=\"doubao-seedream-5.0-lite\",\n                           prompt=\"一只橘猫坐在窗台上，胶片质感\",\n                           size=\"2K\", watermark=False)\nopen(\"cat-lite.jpg\", \"wb\").write(requests.get(l.data[0].url, timeout=60).content)\n\n# 多图参考\ne = client.images.generate(model=\"doubao-seedream-5.0-pro\",\n                           prompt=\"把第一张图的猫放到第二张图的霓虹街景里\",\n                           image=[\"https://example-cdn.com/cat.jpg\", \"https://example-cdn.com/street.jpg\"],\n                           size=\"1280x720\")\nopen(\"cat-neon.jpg\", \"wb\").write(requests.get(e.data[0].url, timeout=60).content)\n```\n\n## 4. 计费口径\n\n- **按张计费**：以 `usage.generated_images` 为结算数量，每张固定单价，与 `size` 档位无关。\n- **每个模型一个单价**：5.0 pro / 5.0 lite / 5.0 / 4.5 在控制台「模型列表」中各有一张价卡，单价不同（5.0 与 5.0 lite 同价）。\n- 请求时预授权冻结，响应返回后按实际生成张数结算。\n- 请求被拒（`400`）或生成失败不计费，预授权自动释放。\n- HTTP `200` 但 `data[]` 中没有任何 `url` / `b64_json`（例如各条目均为 `error`）不计费。\n- 内容审核拒绝（如 `OutputImageSensitiveContentDetected`）返回 HTTP `400` 并携带上游错误码，不计费、不重试。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 返回 `400` | `size` 不在档位表内或 `WxH` 越界；缺 `prompt`；带了 `sequential_image_generation` / `stream` 或其他不支持的字段；当前无供应商能出所请求档位 | 按参数表修正或换档位 |\n| 返回 `400`（5.0 lite / 5.0 / 4.5） | `size` 低于该模型下限：传了 `1K` / `1.5K`，或 `WxH` 总像素 < 3,686,400；4.5 传了 `3K` | 改用 `2K` / `4K`（lite / 5.0 还可用 `3K`），或 `WxH` 总像素 ≥ 3,686,400（如 `2560x1440`） |\n| 返回 `400`（5.0 pro） | 传了 `3K` / `4K`，5.0 pro 不提供该档位 | 改用 `1K` / `1.5K` / `2K` 或 `WxH` |\n| 返回 `400`，`metadata.upstream_error_code` 为 `OutputImageSensitiveContentDetected` 等 | 上游内容审核拒绝，不计费、不重试 | 修改 `prompt` / 参考图后重试 |\n| 生成失败 | 上游无法下载 `image` 中的 URL | 换成公网可直接下载的直链 |\n| `data[].url` 下载 `403` / `404` | 链接已过 24 小时有效期 | 重新生成；或改用 `response_format: \"b64_json\"` |\n| 返回 `401` | API Key 无效或未带 `Authorization` 头 | 核对 Key |\n","china/zh/models/realtime/api.md":"---\ntitle: Realtime API 参考\ndescription: GET /api-ws/v1/realtime（WebSocket）的握手、事件与音频格式说明。\n---\n\n# Realtime API 参考：`GET /api-ws/v1/realtime`\n\n本接口是一个 WebSocket 长连接。网关把百炼 **Qwen-Omni-Realtime** 协议原样双向转发，**不做协议转换**；事件字段的完整定义与工具调用（Function Calling / MCP）事件以百炼官方[客户端事件](https://help.aliyun.com/zh/model-studio/client-events)与[服务端事件](https://help.aliyun.com/zh/model-studio/server-events)为准。本页覆盖接入所需的握手、鉴权、事件清单与音频约定。\n\n## 请求\n\n| 项 | 值 |\n| --- | --- |\n| 方法 | `GET`（WebSocket 升级） |\n| 路径 | `/api-ws/v1/realtime` |\n| 完整地址 | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<逻辑模型名>` |\n| Query | `model`（必填）——平台逻辑模型名，不是上游模型名 |\n| Header | `Authorization: Bearer <mgk_ API Key>`（必填） |\n| Header | `X-Request-ID`（可选）——透传到调用日志，`request_id` 以 `gw_rt_` 开头 |\n\n只有 `public_protocols` 声明了 `dashscope_realtime` 的逻辑模型才能走本入口。\n\n## 握手错误码 {#handshake-errors}\n\n握手（升级为 WebSocket 之前）失败时，以 HTTP 状态码返回，body 为：\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | 触发条件 | 实测 message（cn 生产，2026-10-08） |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | 未携带 API Key | `missing api key` |\n| 401 | `unauthorized` | Key 无效 / 已禁用 | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | 模型不在目录 | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | 模型未声明 `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | 策略（含回落链）中没有该模型的路由 | `no route for model <model>` |\n| 503 | `no_provider` | 有路由但无可用上游实例 | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | 预授权失败（余额/预算不足） | `billing: insufficient funds` |\n\n握手通过（HTTP 101）后再出现的问题，会以带内 `error` 事件下发，然后关闭连接：\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## 会话配置 `session.update`\n\n建连后服务端先发 `session.created`，客户端用 `session.update` 覆盖配置，配置合法则回 `session.updated`。常用字段：\n\n| 字段 | 可选值 | 默认 |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | 见百炼音色列表 | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | 服务端 VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | 任意文本 | 空 |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | 开启 |\n\n`turn_detection: null` 表示关闭服务端 VAD，改由客户端手动提交与触发响应。\n\n## 客户端事件\n\n| 事件 | 作用 |\n| --- | --- |\n| `session.update` | 更新会话配置（模态、音色、音频格式、VAD、instructions 等） |\n| `input_audio_buffer.append` | 追加 Base64 音频到输入缓冲区 |\n| `input_image_buffer.append` | 追加 Base64 图片（JPG/JPEG，需先发过音频） |\n| `input_audio_buffer.commit` | 手动模式下提交音频缓冲区（提交不触发响应） |\n| `input_audio_buffer.clear` | 清空音频缓冲区 |\n| `conversation.item.create` | 创建对话项：纯文本输入、`function_call_output`、`mcp_approval_response` |\n| `response.create` | 触发一次模型响应 |\n| `response.cancel` | 取消正在进行的响应（打断） |\n\n## 服务端事件\n\n| 事件 | 说明 |\n| --- | --- |\n| `session.created` / `session.updated` | 会话建立 / 配置生效 |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD 检测到用户开始 / 停止说话（打断依据） |\n| `input_audio_buffer.committed` / `cleared` | 音频缓冲区提交 / 清空 |\n| `conversation.item.created` | 对话项已创建 |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | 输入语音转写（流式预览 / 最终结果） |\n| `response.created` | 一轮响应开始 |\n| `response.output_item.added` / `response.content_part.added` | 输出项 / 内容片段开始 |\n| `response.text.delta` / `response.text.done` | 仅文本模式的流式 / 完整文本 |\n| `response.audio_transcript.delta` / `.done` | 含音频模式下，音频对应的文本 |\n| `response.audio.delta` / `response.audio.done` | Base64 输出音频（24 kHz PCM）/ 音频结束 |\n| `response.output_item.done` / `response.content_part.done` | 输出项 / 内容片段完成 |\n| `response.done` | 一轮响应结束，`response.usage` 携带分模态 token 用量 |\n\n工具调用（`response.function_call_arguments.delta` / `.done`）与 MCP 相关事件（`mcp_*`）字段见百炼服务端事件文档。\n\n一次完整语音问答的实测事件序（cn 生产，2026-10-08）：\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## 音频格式\n\n| 方向 | 格式 | 事件 / 字段 |\n| --- | --- | --- |\n| 上行（输入） | 16000 Hz、16-bit 小端、单声道 PCM，Base64 | `input_audio_buffer.append` 的 `audio` |\n| 下行（输出） | 24000 Hz、16-bit 小端、单声道 PCM，Base64 | `response.audio.delta` 的 `delta` |\n\n实测满 100 ms 一包推送输入音频（3200 字节 / 帧）最稳。`input_audio_buffer.append` 只入缓冲，不触发响应；是否提交由 VAD 或客户端 `input_audio_buffer.commit` 决定。\n\n## VAD 与打断\n\n- `turn_detection` 非 `null` 时，服务端自动检测语音起止并在静音 `silence_duration_ms`（默认 800ms）后自动提交、触发响应。\n- 用户再次说话：服务端下发 `input_audio_buffer.speech_started` → 客户端**停止播放**并发 `response.cancel` → 收到 `response.done`（cancelled）→ 新一轮。\n- `turn_detection: null` 为手动模式：客户端在录音结束后依次发送 `input_audio_buffer.commit`（等 `input_audio_buffer.committed`）与 `response.create`。\n\n## 用量与计费\n\n每轮响应的 `response.done.response.usage` 携带分模态 token：\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\n网关按整段连接的累计用量在关闭时结算：连接时按会话级预估预授权（当前约 ¥1.2，余额不足则握手 `402`），关闭连接后按实际用量多退少补，无用量则释放预授权。详见[使用指南](./guide#billing)。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 上游限流 | 60 RPM |\n\n## 相关\n\n- [实时语音（Realtime）模型使用指南](./guide)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","china/zh/models/realtime/guide.md":"---\ntitle: 实时语音（Realtime）模型\ndescription: 通过 WebSocket 接入 Qwen-Omni-Realtime，实现实时语音对话、打断与全模态输入。\n---\n\n# 实时语音（Realtime）模型\n\nRealtime 类模型**不走** `/v1/chat/completions`，只能通过 WebSocket 长连接调用。网关把百炼 Qwen-Omni-Realtime 协议**原样双向转发**，不做任何协议转换：你按百炼协议发事件，也按百炼协议收事件。本文给出接入方式、可运行的最小示例与计费口径；逐字段的事件与错误定义见[API 参考](./api)。\n\n## 能做什么\n\n- **实时语音对话**：边说边回，端到端流式返回文本与音频。\n- **语音打断**：用户再次开口时，服务端下发 `input_audio_buffer.speech_started`；客户端停播并发 `response.cancel` 打断当前回复。\n- **全模态输入**：流式音频、图片（可由视频抽帧实时采集）、纯文本。\n- **文本 + 音频输出**：模型同时产出文本与语音。\n\n## 适用模型\n\n一个逻辑模型要能走本入口，必须在模型目录的 `public_protocols` 中声明 `dashscope_realtime`。目前上架的 realtime 模型是 `qwen3.8-omni-flash-realtime`（以模型广场实际上架为准）。可在 [{{ console_endpoint }}]({{ console_endpoint }}) 的模型广场确认某个模型是否提供了该协议。\n\n## 接入\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<逻辑模型名>`（必填） |\n| 鉴权 | `Authorization: Bearer <mgk_ API Key>` |\n| 请求 ID | 可选 `X-Request-ID`；调用日志里 `request_id` 以 `gw_rt_` 开头 |\n\n握手阶段的失败会直接返回 HTTP 状态码（如 Key 无效 `401 unauthorized`、模型未声明 realtime 协议 `403 model_protocol_not_offered`、余额不足 `402`），完整清单见[API 参考](./api#handshake-errors)。\n\n## 最小示例\n\n下面示例在**服务端**运行：用 `mgk_` API Key 建连，配置会话，推送一段 16 kHz PCM 语音，提交后请求回复，并把返回的 24 kHz PCM 写入 `reply.pcm`。\n\n:::note\n- 浏览器原生 `WebSocket` 构造器**不能携带 `Authorization` 头**，所以不能把 API Key 直接放进浏览器连接。\n- 浏览器采集麦克风后，需经你自己的服务端中转（服务端持有 Key 并建连转发），或使用具备鉴权的服务端代理。\n- 下面 Python / Node.js 示例均为服务端代码，可直接复制运行。\n:::\n\n准备输入：把麦克风录音或一段 **16 kHz、16-bit 小端、单声道、无文件头**的 PCM 存为 `input.pcm`。若手上是 WAV，先提取裸 PCM：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython（`pip install websocket-client`）：\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js（`npm install ws`）：\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\n把返回的 `reply.pcm`（24 kHz、16-bit、单声道）封装成可播放的 WAV：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\n只想验证链路时，也可以不传音频：发送一条 `conversation.item.create`（`content` 为 `input_text`），再发 `response.create`，即可只拿文本回复。\n\n## 会话配置\n\n建连后服务端先发 `session.created`（含默认配置），客户端用 `session.update` 覆盖。常用字段：\n\n| 字段 | 说明 |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]`（默认，文本+音频）或 `[\"text\"]`（仅文本） |\n| `voice` | 输出音色，默认 `Tina`；建议使用 `audio.output.voice` |\n| `turn_detection` | 服务端 VAD：`{\"type\":\"server_vad\"}` 或 `{\"type\":\"semantic_vad\"}`；设为 `null` 由客户端手动 commit |\n| `audio.input.format` | 输入音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | 输出音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | 系统人设 |\n| `audio.input.transcription` | 输入转写，服务端会自动开启（模型 `qwen3-asr-flash-realtime`） |\n\n历史兼容字段 `input_audio_format` / `output_audio_format` 仍可用，但新接入建议使用 `audio.input.format` / `audio.output.format`。\n\n## 打断\n\n`turn_detection` 非 `null` 时由服务端 VAD 驱动轮次。用户再次开口会触发：\n\n1. 服务端下发 `input_audio_buffer.speech_started`；\n2. 客户端**停止播放**已缓冲的回复音频，并发送 `response.cancel`；\n3. 服务端随后下发 `response.done`（状态为 cancelled），开始新一轮。\n\n手动模式（`turn_detection: null`）下，客户端负责在录音结束后发送 `input_audio_buffer.commit` 与 `response.create`。\n\n## 计费 {#billing}\n\n- **按 token 分模态计价**：输入分文本/图片/视频与音频两档，输出分文本与音频两档。输出语音时，音频与其对应的文本**分别**计费。\n- **连接时预授权**：建连时按一个会话级预估冻结一笔余额（当前配置约 ¥1.2）。余额不足以覆盖预授权时，握手直接返回 `402`，不建立连接。\n- **关闭连接后按实际用量结算**：按本次连接内所有 `response.done` 的 `usage` 累计结算，多退少补；整段会话没有产生任何用量时释放预授权、不扣费。\n\n价格以控制台模型页为准；例如国内生产 `qwen3.8-omni-flash-realtime` 的单价（元/百万 token）：输入 文本/图片/视频 `1.5`、输入音频 `6`、输出文本 `4.5`、输出音频 `12`。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制；到达上限即关闭连接并结算） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 音频历史 | 最多 100 轮 / 累计 600 秒 |\n| 视频历史 | 最多 50 轮 / 累计 240 秒 |\n| 上游限流 | 60 RPM |\n\n## 下一步\n\n- [API 参考：`GET /api-ws/v1/realtime`](./api)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","china/zh/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: 对候选文档按相关性重排序的 Rerank 接口。\n---\n\n# Rerank\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | 对文档按与查询的相关性重排序 |\n| `POST` | `/v1/reranks` | 同上（别名，等价于 `/v1/rerank`） |\n\nRerank 接口接收一段查询与若干候选文档，按相关性返回排序后的结果，常用于检索增强（RAG）场景的精排。`/v1/rerank` 与 `/v1/reranks` 是同一能力的两条等价路径。\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"ModelGo 支持哪些协议\",\n    \"documents\":[\n      \"兼容 OpenAI 与 Anthropic 协议\",\n      \"今天的天气不错\",\n      \"支持图像、视频、向量、音频能力\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；请求体按上游 Rerank 协议透传，具体字段（如 `top_n`、`return_documents`）是否生效取决于路由到的上游模型。\n- 返回结果通常包含每条文档的相关性得分与排序序号。\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","china/zh/models/text/generation.md":"---\ntitle: 文本生成\ndescription: OpenAI Responses、Chat Completions 兼容入口与 Anthropic Messages 的统一说明。\n---\n\n# 文本生成\n\n文本能力当前覆盖以下公开入口，推荐优先使用 `POST /v1/responses`，其余入口用于兼容已有 SDK 和原生 Claude 客户端。\n\n| 协议 | 方法与路径 | 用途 |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | 新项目优先使用的统一文本生成接口 |\n| OpenAI | `POST /v1/chat/completions` | 兼容大量现有 OpenAI SDK 的对话补全接口 |\n| OpenAI | `POST /v1/completions` | 旧版文本补全接口，仅用于兼容历史调用链 |\n| Anthropic | `POST /v1/messages` | Claude 原生消息格式接口 |\n| OpenAI | `GET /v1/models` | 查询当前路由可用的逻辑模型清单 |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"用三句话介绍 ModelGo。\"\n  }'\n```\n\n适合新接入和统一封装场景。请求体、流式返回和 `usage` 字段遵循 OpenAI Responses 兼容格式。\n\n## OpenAI Chat Completions 兼容入口 {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合已经绑定 OpenAI SDK 或历史对话补全调用链的客户端。推荐新项目优先迁移到 `POST /v1/responses`。\n\n## OpenAI Completions（旧版补全）\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"用三句话介绍 ModelGo。\",\n    \"max_tokens\":256\n  }'\n```\n\n旧版文本补全接口，仅用于兼容仍在使用 `prompt` 的历史调用链，新项目请使用上面的 Responses / Chat Completions。`stream` 同样以 SSE 返回。多数当前对话模型未声明此协议：`qwen3.6-flash` 实测 HTTP 400、`model_protocol_not_offered`。\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合直接复用 Claude 原生消息格式的客户端。该入口保持 `/v1/messages` 的事件流语义，不会在网关侧改造成 OpenAI SSE 帧。\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` 返回该 API Key 绑定策略所允许的逻辑模型（结合平台模型目录），不会在请求时实时探测上游能力，可能与控制台展示略有差异；计费、策略以控制台和绑定策略为准。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名\n- `GET /v1/models` 可用，清单由 API Key 绑定的策略与平台模型目录决定\n- OpenAI 与 Anthropic 协议都可能返回上游原样 `usage`\n- 流式失败时可能不会发送 `data: [DONE]`，请以数据块中的 `error` 判断\n- 如果上游或路由不支持当前协议，平台会返回 `provider_unsupported` 或协议不兼容错误\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","china/zh/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI 兼容向量嵌入接口说明。\n---\n\n# Embeddings\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | 文本向量嵌入 |\n| `POST` | `/v1/embeddings/multimodal` | 多模态（图文等）向量嵌入 |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` 可以是单条字符串，也可以是字符串数组。返回结果遵循 OpenAI Embeddings 兼容格式。\n\n## 多模态 Embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\n面向同时包含文本与图像等内容的向量嵌入场景。`input` 结构与具体模型的多模态能力相关，是否生效取决于路由到的上游模型。\n","china/zh/models/video/ark.md":"---\ntitle: Seedance\ndescription: 用 Ark 原厂路径调用平台托管的 Seedance 异步视频任务，请求体与响应体都按 Ark 内容生成协议书写。\n---\n\n# Seedance\n\n豆包 Seedance 系列（`doubao-seedance-*`）除标准视频协议外，还可以用**火山方舟（Ark）原厂路径**调用，\n请求体与响应体按 Ark 内容生成协议书写：\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 创建内容生成任务（视频） |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见下） |\n\n这是**平台托管**通道：路径是 Ark 自己的，但请求走的是网关标准的异步任务流水线，与\n[通用异步内容生成任务](./async-tasks)完全同一条链路，只是换了 Ark 的路径拼写。因此它同样享受\n维度计费、任务落库、产物持久化与预扣/结算的全部保障。\n\n## 创建任务\n\n请求体按 Ark 内容生成协议书写，`model` 填**平台逻辑模型名**（如 `doubao-seedance-2.0-mini`）：\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一只霓虹都市里的猫\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\n`content` 里除文本外还可以带图片/视频，元素用 `role` 标明用途；**素材组合决定生成模式，生成模式又决定哪些参数合法**：\n\n| content 元素 | `role` | 生成模式 |\n| --- | --- | --- |\n| 只有 `text` | — | 文生视频（t2v） |\n| `image_url` | `first_frame` | 首帧图生视频（i2v） |\n| `image_url` | `first_frame` + `last_frame` | 首尾帧（flf2v） |\n| `image_url` / `video_url` | `reference_image` / `reference_video` | 多模态参考生视频 |\n\n### 参数与生成模式约束\n\n`resolution` / `ratio` / `duration` 的合法取值**随模型而异**（例如 Seedance 2.0 的 Fast 与 Mini 不支持\n`1080p`，`duration` 下限是 4 秒）；`camera_fixed`、`generate_audio`、`return_last_frame`、`watermark`\n等 Ark 扩展参数**还随生成模式而异**。携带当前模型/模式不支持的参数，会在创建时被上游拒绝\n（`400` `provider_invalid`）。已知一例：\n\n- **`camera_fixed` 在首尾帧（同时带 `first_frame` + `last_frame`）场景不被支持**，携带它会被上游拒\n  （`camera_fixed ... must be empty`）。首尾帧本身已约束镜头；确需固定镜头请改用文生 / 单首帧等\n  支持该参数的模式。\n\n因为本通道**不锁定上游 family**（同一逻辑模型由多家供应商承接），某参数是否被接受还取决于实际\n承接的供应商与其模型版本。请以「模型能力说明 + 上述模式约束」为准，**不要假定某模式可用的参数在\n另一种模式同样可用**。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与查询返回的就是[通用异步内容生成任务](./async-tasks)那一种 Ark 任务对象——同一条流水线，\n响应报文与字段语义（`status` 取值、`content.video_url`、`error`、`usage` 缺省规则）与那一页完全一致，\n此处不再重复。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消成功后预扣会被退回（void），不产生结算。\n\n**但取消不是所有上游都支持。** 能否取消取决于承接该任务的供应商是否实现了取消能力，而这条通道\n不锁定上游 family，所以同一个逻辑模型的两次调用可能一次能取消、一次不能。两种失败：\n\n| 情况 | 响应 |\n| --- | --- |\n| 承接该任务的供应商不支持取消 | `400` / `4003` `provider_unsupported`，`endpoint not supported by provider` |\n| 任务已到终态（`succeeded` / `failed`） | `409` `task_already_terminal`，`task already finished; nothing to cancel` |\n\n取消失败时预扣不会提前退回，会等任务到终态或预扣过期后按正常结算/释放流程处理。所以**不要把\n「先创建、再取消」当成一种可靠的止损手段**。\n\n## 关键约定\n\n- **`id` 是网关任务 ID，不是上游任务 ID。** 查询、取消都只认这个 ID，请以创建响应里的 `id` 为准。\n- **响应形态是固定的。** 无论实际由哪家上游承接，创建与查询都返回同一种 Ark 任务对象，\n  不会因为路由到不同供应商而变形。\n- **该通道不锁定上游 family。** 路径拼写不参与选路：`model` 对应的逻辑模型路由到谁，就由谁承接。\n  Seedance 在平台上由多家供应商共同承接，同一个逻辑模型的两次调用可能落到不同上游，这是正常的。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），Ark 路径下没有对应端点；\n  直接使用响应里的 `content.video_url` 即可。\n- 该模型是否开放本通道，取决于它在模型目录里声明的 `public_protocols` 是否含\n  `content_generation`；未声明则返回 `4005`。可用 `GET {{ api_endpoint }}/v1/models` 核对。\n\n如果你不需要 Ark 的路径与字段风格，[OpenAI 兼容视频流](./openai-compatible)是更标准化的选择。\n","china/zh/models/video/async-tasks.md":"---\ntitle: 异步任务\ndescription: 平台统一的异步任务入口，覆盖图像、视频等需要任务式处理的内容生成能力。\n---\n\n# 异步任务\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 创建通用异步内容生成任务（图像 / 视频等） |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 轮询通用内容生成任务状态与结果 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见[Seedance 视频入站协议](./ark)的「取消任务」） |\n\n`/v1/content_generation/tasks` 是比标准 OpenAI 视频流更通用的异步任务入口，覆盖图像、视频等需要后台任务执行的生成能力。\n\n## 创建任务\n\n请求体遵循对应上游的通用生成格式，至少需要 `model`：\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\n2026-09-10 国内生产：创建返回 `status=queued`、`id` 形如 `gw_…`；轮询同一 `id` 最终为 `succeeded`，并带 `resolution=720p`、`ratio=16:9`、`duration=5`。同一模型打 `POST /v1/video/generations` 为 `model_protocol_not_offered`。`DELETE` 取消在该上游上返回 `provider_unsupported`。\n\n## 轮询任务\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与轮询都返回**同一种** Ark 形态的任务对象，不随实际承接的上游变化：\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` 取值为 `queued` / `running` / `succeeded` / `failed`；`id` 是**网关任务 ID**，轮询与取消都只认它。\n\n## 三种拼法，同一条流水线\n\n同一条托管异步流水线有三个入站拼写，选哪个只取决于你想按谁的报文风格写客户端：\n\n| 入口 | 请求体 | 响应体 |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | 通用生成格式 | Ark 任务对象（上表） |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark 内容生成原生体 | Ark 任务对象 |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax 视频生成 V2 原生体 | MiniMax 形态（`{\"task_id\"}` / `{\"task\":{…}}`） |\n\n三者的计费、任务落库、产物持久化与预扣/结算行为完全一致。\n\n## 适用场景\n\n- 你要调用的平台能力本身是异步任务，但不走 OpenAI Video 标准形态\n- 你希望统一使用平台托管的「创建任务 → 轮询结果」模型，而不是自行管理厂商原生协议\n- 你调用的是即梦等仅提供托管异步入口的视频模型\n\n## 关键约定\n\n- `model` 仍填写平台逻辑模型名，由平台决定最终路由到哪个上游实现。\n- 请求体字段取决于路由到的具体能力；响应形态则是固定的，见上文。\n- 如果你不想自己处理厂商侧的多种原生轮询协议，优先使用这一入口。\n\n如需标准 OpenAI 视频协议，见[OpenAI 兼容视频流](./openai-compatible)。\n","china/zh/models/video/kling-v3.md":"---\ntitle: 可灵 3.0\ndescription: 按可灵官方 API 协议调用 kling-v3：text2video / image2video 创建、mode 档位、sound 音频开关、轮询、下载与计费口径。可灵官方 SDK 改域名即可直连。\n---\n\n# 可灵 3.0\n\n| 接口 | 能力 | 必填字段 |\n| --- | --- | --- |\n| `POST /kling/v1/videos/text2video` | 文生视频 | `model_name`、`prompt` |\n| `POST /kling/v1/videos/image2video` | 图生视频（首帧驱动，可选尾帧） | `model_name`、`prompt`、`image` |\n\nModelGo 按可灵官方 API 的路径与请求/响应格式接收请求（`model_name`、`mode`、`sound`、`duration`、`aspect_ratio`……），网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。轮询路径与官方一致：**同一路径 + `/{task_id}`**。\n\n> 使用可灵官方 SDK / 示例代码时，把 API 域名换成 `{{ api_endpoint }}/kling`，鉴权改为 `Authorization: Bearer $MODELGO_API_KEY`（无需可灵的 JWT 签名）。\n\n## 1. 创建任务\n\n### 文生视频\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"一颗红色小球在木桌上缓缓滚动，柔和日光\",\n    \"mode\": \"std\",\n    \"duration\": \"5\",\n    \"aspect_ratio\": \"16:9\",\n    \"sound\": \"on\",\n    \"cfg_scale\": 0.5\n  }'\n```\n\n### 图生视频\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/image2video \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model_name\": \"kling-v3\",\n    \"prompt\": \"小狗缓缓转头\",\n    \"image\": \"https://example-cdn.com/dog.jpg\",\n    \"mode\": \"pro\",\n    \"duration\": \"5\"\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"submitted\",\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773081000\n  }\n}\n```\n\n`data.task_id` 是网关任务 ID，轮询与取内容都用它。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model_name` | string | 全部 | 固定 `kling-v3` |\n| `prompt` | string | 全部 | text2video 必填；image2video 可选（与官方一致）。≤ 2500 字符 |\n| `image` | string | image2video | 必填。首帧图片的**公网可直接下载**的 URL。text2video 请求不得携带 `image` / `image_tail`（会被拒绝，不会静默按文生视频处理）。当前供应商通道不接受 base64 内联图片（裸 base64 或 `data:` URI），会返回 `400`（`error_class=provider_unsupported`） |\n| `image_tail` | string | image2video | 尾帧图片 URL，需与 `image` 一起传：只传 `image_tail` 时当前供应商通道返回 `400`（`error_class=provider_unsupported`） |\n| `mode` | string | 全部 | 档位：`std`（720P）、`pro`（1080P）或 `4k`，**缺省 `std`（720P）**，与可灵官方协议默认值一致；不传档位按 720P 计费 |\n| `duration` | string / int | 全部 | 时长（整数秒）3–15，缺省 `5` |\n| `aspect_ratio` | string | text2video | `16:9` / `9:16` / `1:1`，缺省 `16:9`。图生视频跟随首帧比例 |\n| `sound` | string | 全部 | `on` / `off`，缺省 `off`。**开启会切换到含音频的计费档** |\n| `negative_prompt` | string | 全部 | 反向提示词 |\n| `cfg_scale` | number | 全部 | 提示词遵循度 [0, 1]，缺省 0.5 |\n| `watermark_info` | object | 全部 | 水印设置，按原样转交供应商，不影响计费。`enabled: true` 只在转发该字段的供应商通道上可用，其余通道返回 `400`（`error_class=provider_unsupported`） |\n| `multi_shot` | bool | 全部 | 分镜开关，缺省 `false` |\n| `shot_type` | string | 全部 | `multi_shot=true` 时必填：`customize`（自己写每个分镜）或 `intelligence`（模型按主提示词自动分镜） |\n| `multi_prompt` | array | 全部 | `shot_type=customize` 时必填，1–6 项：`index`（从 1 起的唯一整数）、`prompt`（≤512 字符）、`duration`（整数秒）；各分镜时长之和必须等于 `duration`，所以此时必须显式传 `duration`。text2video 仍需传主提示词 `prompt` |\n| `voice_list` | array | image2video | 1–2 项 `{\"voice_id\": \"…\"}`，必须同时 `sound=on`，不能和 `element_list` 一起用 |\n| `element_list` | array | image2video | 1–3 项，每项含整数 `element_id` |\n| `callback_url` / `external_task_id` | string | 全部 | 接受但不生效：网关不回调，任务以 `task_id` 轮询 |\n\n- 上表之外的字段（如 `camera_control`、`static_mask`、`dynamic_masks`）会在创建时被拒绝（HTTP `400`），不会被忽略。\n- 分镜、音色、主体字段（`multi_shot` / `shot_type` / `multi_prompt` / `voice_list` / `element_list`）只会路由到能原样转发它们的供应商通道；当前没有这样的通道可用时返回 `400`（`error_class=provider_unsupported`），不会静默丢弃后按普通视频计费。计费按 `duration`（分镜时长之和）和 `sound` 对应的档位，这些字段本身不改变单价。\n\n### 档位\n\n| `mode` | 输出 |\n| --- | --- |\n| `std` | 1280×720（按比例），缺省 |\n| `pro` | 1920×1080（按比例） |\n| `4k` | 4K（按比例），仅由支持 4K 的供应商承接，单价另计 |\n\n- **只提供以上三档。** 其他值会在创建时被拒（HTTP `400`）。网关按各供应商可交付档位选路：请求 `4k` 时只会交给能出 4K 的供应商，不会静默降档；若当前没有可用的 4K 供应商，创建返回 `400`，不产生费用。\n\n### 首帧图片的要求（image2video）\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie；JPG / PNG，≤ 10MB，宽高 ≥ 300px，比例 1:2.5–2.5:1。\n- 图片拉取失败会导致任务失败（`task_status=failed`），不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/kling/v1/videos/text2video/{task_id}`（image2video 创建的任务到 `.../image2video/{task_id}` 轮询）\n\n```bash\ncurl {{ api_endpoint }}/kling/v1/videos/text2video/gw_6dce033e-9243-4a64-9c57-73d08a8e379a \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"SUCCEED\",\n  \"request_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n  \"data\": {\n    \"task_id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\",\n    \"task_status\": \"succeed\",\n    \"task_result\": {\n      \"videos\": [{\"id\": \"gw_6dce033e-9243-4a64-9c57-73d08a8e379a\", \"url\": \"{{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content\", \"duration\": \"6\"}]\n    },\n    \"created_at\": 1788773081000,\n    \"updated_at\": 1788773250000\n  }\n}\n```\n\n- `task_status`：`submitted` → `processing` → `succeed` / `failed`。失败时 `task_status_msg` 给出原因，任务**不计费**。\n- 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。\n- `videos[].url` 指向网关内容接口，需带 API Key 下载；`duration` 为实际交付秒数。\n\n## 4. 下载视频\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o kling.mp4\n```\n\n返回 `video/mp4` 字节流，支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}/kling/v1/videos\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\"}\n\ndef generate(kind: str, body: dict, out: str, timeout: int = 600) -> None:\n    body.setdefault(\"model_name\", \"kling-v3\")\n    r = requests.post(f\"{BASE}/{kind}\", json=body, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"data\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        data = requests.get(f\"{BASE}/{kind}/{task_id}\", headers=H, timeout=30).json()[\"data\"]\n        if data[\"task_status\"] == \"succeed\":\n            break\n        if data[\"task_status\"] == \"failed\":\n            raise RuntimeError(data.get(\"task_status_msg\", \"generation failed\"))\n        time.sleep(8)\n    url = data[\"task_result\"][\"videos\"][0][\"url\"]\n    with requests.get(url, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"text2video\", {\"prompt\": \"一颗红色小球在木桌上缓缓滚动\", \"mode\": \"std\", \"duration\": \"5\", \"sound\": \"on\"}, \"t2v.mp4\")\ngenerate(\"image2video\", {\"prompt\": \"小狗缓缓转头\", \"image\": \"https://example-cdn.com/dog.jpg\", \"mode\": \"pro\", \"duration\": \"5\"}, \"i2v.mp4\")\n```\n\n## 6. 计费口径\n\n- 按**视频秒数 × 单价**计费，单价由三个维度决定：输入方式（文生 / 图生）、档位（`std` 720P / `pro` 1080P / `4k`）、是否生成音频（`sound`）。\n- 创建时按请求的 `duration` 预授权冻结，任务完成后按**实际交付秒数**结算；部分通道多交付约 1 秒（请求 5 秒交付 6 秒），以 `videos[].duration` 为准。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`failed`）不计费，预授权自动释放。\n- 各档单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `mode` 不是 `std`/`pro`/`4k`；`sound` 不是 `on`/`off`；缺 `model_name`；text2video 缺 `prompt`；image2video 的 `image` 与 `image_tail` 都未传；图片既不是 http(s) URL 也不是 base64 图片；text2video 带了 `image`/`image_tail`；带了参数表之外的字段；当前无供应商能出所请求档位 | 按参数表修正或换接口/档位 |\n| 创建返回 `400`，`error_class=provider_unsupported` | 只传了 `image_tail`，或图片使用 base64 内联：当前供应商通道不支持 | 同时传 `image`；图片改用公网 URL |\n| `task_status=failed` | 上游无法下载首帧图或生成失败 | 换成公网可直接下载的直链 |\n| 轮询 `task_not_found` | `task_id` 不是本 Key 创建的任务，或轮询路径的接口族与创建时不一致 | 用创建时的同一路径轮询 |\n| `/content` 返回 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `succeed`；及时下载 |\n","china/zh/models/video/minimax.md":"---\ntitle: MiniMax 视频\ndescription: 用 MiniMax 视频生成 V2 的原厂请求体与响应体调用平台托管的异步视频任务，适用于 MiniMax-H3 系列。\n---\n\n# MiniMax 视频\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | 创建视频生成任务 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 取消未完成的任务并退回预扣 |\n\n这是 **MiniMax 视频生成 V2** 的原厂入站协议，主要面向 MiniMax-H3 系列视频模型。和 Ark 通道一样，\n它跑在平台托管的异步任务流水线上——请求体是 MiniMax 自己的形状，**响应体也按 MiniMax 的形状渲染**，\n所以照着 MiniMax 官方文档写的客户端可以直接解析。\n\n任务落在平台侧，维度计费、产物持久化、预扣/结算都照常生效。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一个男孩在海边打篮球\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\n创建响应就是 MiniMax 文档里的裸任务句柄：\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### 请求体字段\n\n`content[]` 是多模态数组，每项由 `type` 与 `role` 共同决定它的用途：\n\n| `type` | 可用 `role` | 含义 |\n| --- | --- | --- |\n| `text` | —— | 提示词 |\n| `image_url` | `first_frame` / `last_frame` | 首帧 / 尾帧图 |\n| `image_url` | `reference_image` | 参考图 |\n| `video_url` | `reference_video` | 参考视频 |\n| `audio_url` | `reference_audio` | 参考音频 |\n\n- **首尾帧与参考素材不能混用**：带了 `first_frame` / `last_frame` 就不能再带任何 `reference_*`，\n  反之亦然——它们对应上游两种不同的生成任务。\n- `resolution`、`duration`、`ratio` 与 `content` 平级。对 MiniMax-H3，取值范围为\n  `resolution` ∈ `768P` / `2K`，`duration` 为 `4`–`15` 的整数，`ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`；不传时按上游缺省（`2K`、`5` 秒）执行**并按该缺省档计费**。\n- 提示词长度上限约 7000 字符。\n- 具体支持哪些取值仍以 `model` 对应的逻辑模型配置为准。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n查询响应是 `task` 信封，与创建响应**形状不同**：\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` 取值为 `queued` / `running` / `succeeded` / `failed`。\n- 成功后产物地址在 `task.content.url`。\n- `usage` 以**秒**计量（H3 按输出秒数定价），不是 token 数；上游只报告 token 而没有秒数时该字段缺省。\n- 失败时追加 `task.error`（`code` / `message`）。这一项不在 MiniMax 官方成功响应结构里，\n  是为了让失败原因可见而额外补上的，按官方结构解析的客户端会自然忽略它。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消后预扣退回。注意本通道**不会**返回 MiniMax 文档中的 `cancelled` 状态——已取消的任务统一以\n`failed` 呈现，以保证预扣被退回而不是结算。\n\n## 关键约定\n\n- **`id` / `task_id` 都是网关任务 ID**，不是上游任务 ID；查询与取消只认它。\n- 该通道不锁定上游 family，由 `model` 对应逻辑模型的路由决定实际承接方，路径拼写不参与选路。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），MiniMax 路径下没有对应端点。\n\n标准化入口见[OpenAI 兼容视频流](./openai-compatible)。\n","china/zh/models/video/openai-compatible.md":"---\ntitle: OpenAI 兼容视频流\ndescription: 标准 OpenAI Video 兼容接口，包括创建任务、轮询状态与拉取产物内容。\n---\n\n# OpenAI 兼容视频流\n\n> **视频模型只接受厂商官方原生协议**：[万相 2.7（DashScope）](./wan27)、[可灵 3.0（Kling）](./kling-v3)、[Veo 3.1（Google）](./veo31)。`wan2.7-t2v` / `wan2.7-i2v` / `kling-v3` / `veo-3.1` / `veo-3.1-fast` 已不再开放本页的 `POST /v1/video/generations`（对这些模型返回 `400`、`app_error_id=4005 model_protocol_not_offered`）。任务轮询 `GET /v1/videos/{task_id}` 与产物接口 `GET /v1/videos/{task_id}/content` 对原生协议创建的任务仍可用；通用异步任务接口见[异步内容生成任务](./async-tasks)。\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | 创建 OpenAI 兼容视频任务 |\n| `GET` | `/v1/videos/{task_id}` | 轮询视频任务状态与结果 |\n| `GET` | `/v1/videos/{task_id}/content` | 拉取已完成视频任务的产物内容 |\n\n这组接口是平台定义的**标准视频协议**：请求体使用 OpenAI Video 兼容字段，平台负责识别并转换成对应上游的视频异步任务格式。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\n创建成功后返回 `task_id`。后续轮询与产物拉取都围绕该 `task_id` 进行。\n\n## 轮询任务状态\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` 取值为 `queued` / `in_progress` / `completed` / `failed`；为 `completed` 时，`metadata.url` 中会给出产物地址。\n\n## 拉取产物内容\n\n任务完成后，也可以通过内容接口直接拿视频文件。该接口由网关**直接回传 `video/mp4` 字节流**（不再 `302` 跳转到对象存储），支持 `Range` 断点续传，且只有任务所属 API Key（或同租户控制台登录态）可访问：\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\n内容接口的可用性取决于后台「媒体交付」配置：\n\n- 未启用时返回 `404`（`content_delivery_disabled`）\n- 任务尚未完成时返回 `409`（`task_not_completed`）\n- 产物已过期或不存在时返回 `404`（`content_not_available`）\n\n## 关键约定\n\n- 这是标准 OpenAI 兼容视频入口，客户端不需要理解厂商原生协议。\n- 是否支持 `duration`、`size` 等字段，以及最终落到哪个上游，取决于 `model` 对应的逻辑模型配置。\n- 视频任务属于异步模型，轮询时请带退避，避免高频请求触发限流。\n\n如需更通用的异步任务入口，见[通用异步内容生成任务](./async-tasks)；想按厂商原厂报文书写、但仍要平台托管的计费与任务管理，见[Seedance 视频入站协议](./ark)与[MiniMax 视频入站协议](./minimax)。\n","china/zh/models/video/veo31.md":"---\ntitle: Veo 3.1\ndescription: 按 Google Gemini API 官方 Veo 协议调用 veo-3.1 与 veo-3.1-fast：predictLongRunning 创建、operations 轮询、下载与 USD 计费口径。Google GenAI SDK 改 base_url 即可直连。\n---\n\n# Veo 3.1\n\n| 官方模型 ID（路径中使用） | 平台逻辑模型 | 定位 |\n| --- | --- | --- |\n| `veo-3.1-generate-preview` | `veo-3.1` | 质量版，原生音画同出 |\n| `veo-3.1-fast-generate-preview` | `veo-3.1-fast` | 速度优化版，成本更低 |\n\nModelGo 按 Google Gemini API 的 **长时任务（Long-running operation）** 协议原样接收 Veo 请求：`predictLongRunning` 创建 → `operations` 轮询 → 下载。请求体与 Google 文档一致（`instances` + `parameters`）；网关负责路由到供应商并计费。\n\n> 使用 Google GenAI SDK 时，把 `http_options.base_url` 指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key 即可。鉴权头同时接受 `x-goog-api-key: $KEY` 与 `Authorization: Bearer $KEY`。\n\n## 1. 创建任务\n\n`POST {{ api_endpoint }}/v1beta/models/{model}:predictLongRunning`（也接受 `/v1/models/...`）\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"instances\": [{\"prompt\": \"A small red ball rolling slowly across a wooden table, soft daylight\"}],\n    \"parameters\": {\"aspectRatio\": \"16:9\", \"resolution\": \"1080p\", \"durationSeconds\": 8, \"generateAudio\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\", \"done\": false}\n```\n\n`name` 是官方形态的 operation 名称，最后一段是网关任务 ID；轮询时把 `name` 原样拼到 `/v1beta/` 之后。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `instances[0].prompt` | string | 文生视频必填；图生视频提供了 `image` 时可省略。画面内容与动作描述 |\n| `instances[0].image` | object | 首帧图片（图生视频）。**仅支持 URL 形态** `{\"imageUri\": \"https://...\"}` / `gcsUri`；内联 `bytesBase64Encoded` 会被拒绝 |\n| `instances[0].lastFrame` | object | 尾帧图片，同上 |\n| `parameters.resolution` | string | `720p` 或 `1080p`，**缺省 `720p`** |\n| `parameters.durationSeconds` | int | `4` / `6` / `8`，缺省 `8`。**1080p 需使用 8 秒** |\n| `parameters.aspectRatio` | string | `16:9` 或 `9:16`，缺省 `16:9` |\n| `parameters.generateAudio` | boolean | Veo 3.1 总是生成音轨；计费不区分音频 |\n| `parameters.negativePrompt` | string | 反向提示词 |\n| `parameters.seed` | int | 随机种子 |\n| `parameters.sampleCount` / `numberOfVideos` | int | 只能为 `1`：一个任务一段视频，`>1` 会被拒绝 |\n| `parameters.personGeneration` | string | 透传 |\n\n### 分辨率档位\n\n| 档位 | 输出 |\n| --- | --- |\n| `720p` | 1280×720（16:9）/ 720×1280（9:16），缺省 |\n| `1080p` | 1920×1080 / 1080×1920 |\n\n- **只提供以上两档。** 传 `4k` 会在创建时被拒（HTTP `400`），不会静默降档生成，也不产生费用。\n- 一次只能创建一个视频；只接受一个 `instance`。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/v1beta/{operation.name}`，即 `GET /v1beta/models/{model}/operations/{task_id}`\n\n```bash\ncurl \"{{ api_endpoint }}/v1beta/models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"name\": \"models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77\",\n  \"done\": true,\n  \"response\": {\n    \"@type\": \"type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse\",\n    \"generateVideoResponse\": {\n      \"generatedSamples\": [{\"video\": {\"uri\": \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\"}}]\n    }\n  }\n}\n```\n\n- 未完成时 `done=false`；失败时 `done=true` 且带 `error.{code,message}`，任务**不计费**。\n- 8 秒片段通常 1–2 分钟完成，请按 5–10 秒间隔轮询并带退避。\n- 上游偶发临时错误会使创建返回 `502`，不计费，重试即可。\n\n## 4. 下载视频\n\n`generatedSamples[].video.uri` 指向网关内容接口，与 Google 官方一致需带 API Key：\n\n```bash\ncurl \"{{ api_endpoint }}/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content\" \\\n  -H \"x-goog-api-key: $MODELGO_API_KEY\" -o veo.mp4\n```\n\n返回 `video/mp4`（含 AAC 音轨），支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"x-goog-api-key\": os.environ[\"MODELGO_API_KEY\"]}\n\ndef generate(model: str, prompt: str, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/v1beta/models/{model}:predictLongRunning\",\n                      json={\"instances\": [{\"prompt\": prompt}], \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    name = r.json()[\"name\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(name)\n        op = requests.get(f\"{BASE}/v1beta/{name}\", headers=H, timeout=30).json()\n        if op.get(\"done\"):\n            break\n        time.sleep(8)\n    if \"error\" in op:\n        raise RuntimeError(op[\"error\"][\"message\"])\n    uri = op[\"response\"][\"generateVideoResponse\"][\"generatedSamples\"][0][\"video\"][\"uri\"]\n    with requests.get(uri, headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\ngenerate(\"veo-3.1-fast-generate-preview\", \"A small red ball rolling across a wooden table\",\n         {\"resolution\": \"1080p\", \"durationSeconds\": 8, \"aspectRatio\": \"16:9\"}, \"veo-fast.mp4\")\ngenerate(\"veo-3.1-generate-preview\", \"A cinematic drone shot over a misty forest at dawn\",\n         {\"resolution\": \"720p\", \"durationSeconds\": 4}, \"veo.mp4\")\n```\n\n## 6. 计费口径\n\n- **USD 计价**，按**视频秒数 × 分辨率档位单价**计费，结算时按当日汇率折算到账户币种。\n- 创建时按请求的 `durationSeconds` 预授权冻结，任务完成后按实际交付秒数结算。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`done=true` + `error`）不计费，预授权自动释放。\n- 各档单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `resolution` 不在 720p / 1080p；`sampleCount` > 1；多个 `instances`；`image` 用了内联 base64 | 按参数表修正，图片改用 URL |\n| 创建返回 `502` | 上游临时错误 | 重试；不计费 |\n| 轮询 `task_not_found` | operation 名称不是本 Key 创建的任务 | 核对 `name` 与 Key |\n| 下载 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `done=true`；及时下载 |\n","china/zh/models/video/wan27.md":"---\ntitle: 万相 2.7\ndescription: 按阿里百炼 DashScope 官方 video-synthesis 协议调用 wan2.7-t2v / wan2.7-i2v：创建任务、轮询、下载与计费口径。官方 SDK 改 base_url 即可直连。\n---\n\n# 万相 2.7\n\n| 模型 | 能力 | 必填字段 |\n| --- | --- | --- |\n| `wan2.7-t2v` | 文生视频 | `input.prompt` |\n| `wan2.7-i2v` | 图生视频（首帧驱动，可选尾帧） | `input.prompt`、`input.img_url`（或 `input.media[]` 中的 `first_frame`） |\n\n万相 2.7 的官方协议是阿里百炼 DashScope 的 **视频合成异步接口**，ModelGo 网关按官方路径与请求/响应格式原样接收：**创建 → 轮询 → 取内容**。请求体与阿里百炼文档一致，具体由哪家供应商渲染由网关路由决定，对调用方不可见。\n\n> 使用阿里官方 DashScope SDK 时，只需把 `base_url`（`DASHSCOPE_HTTP_BASE_URL`）指向 `{{ api_endpoint }}`、`api_key` 换成 ModelGo API Key。\n\n## 1. 创建任务\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis`\n\n请求头：`Authorization: Bearer $MODELGO_API_KEY`、`X-DashScope-Async: enable`、`Content-Type: application/json`。\n\n### 文生视频\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-t2v\",\n    \"input\": {\"prompt\": \"一只毛茸茸的橘猫在阳光下的窗台上玩毛线球\"},\n    \"parameters\": {\"resolution\": \"1080P\", \"duration\": 5, \"prompt_extend\": true}\n  }'\n```\n\n### 图生视频\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/video-generation/video-synthesis \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"X-DashScope-Async: enable\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"wan2.7-i2v\",\n    \"input\": {\"prompt\": \"猫缓缓转头并眨眼\", \"img_url\": \"https://example-cdn.com/cat.jpg\"},\n    \"parameters\": {\"resolution\": \"720P\", \"duration\": 5}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\", \"task_status\": \"PENDING\", \"submit_time\": \"2026-09-07 17:05:59.000\"},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n`output.task_id` 是网关任务 ID，轮询与取内容都用它。\n\n## 2. 参数说明\n\n| 字段 | 类型 | 适用 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 全部 | `wan2.7-t2v` 或 `wan2.7-i2v` |\n| `input.prompt` | string | 全部 | 必填。画面内容与动作描述 |\n| `input.img_url` | string | i2v | 必填（也可改用 `input.media[]` 的 `first_frame`）。首帧图片的**公网可直接下载**的 URL。`wan2.7-t2v` 请求不得携带 `img_url` / `last_frame_url`（或 `media` 的 `first_frame` / `last_frame`）（会被拒绝，不会静默按文生视频处理） |\n| `input.last_frame_url` | string | i2v | 尾帧图片 URL，与首帧配合生成首尾帧视频 |\n| `input.audio_url` | string | 全部 | 驱动音频 URL（wav/mp3） |\n| `input.media[]` | object[] | 全部 | 百炼 wan2.7 新版协议写法，元素为 `{\"type\": ..., \"url\": ...}`：`first_frame` 等同 `img_url`、`last_frame` 等同 `last_frame_url`（二者仅 i2v）、`driving_audio` 等同 `audio_url`。`first_clip` 等同 `first_clip_url`（视频续写，仅 i2v，见下）。同一项不能用两种写法重复给出；其他 `type` 会被拒绝 |\n| `input.negative_prompt` | string | 全部 | 反向提示词 |\n| `parameters.resolution` | string | 全部 | 分辨率档位 `720P` / `1080P`，缺省 `1080P` |\n| `parameters.ratio` | string | 全部 | 宽高比 `16:9`（缺省）/ `9:16` / `1:1` / `4:3` / `3:4`，与 `resolution` 共同决定输出尺寸（见下表）。也接受 `aspect_ratio` 写法，两者同时给出时必须一致 |\n| `parameters.size` | string | t2v | 与 `resolution` 等价的像素写法，如 `1280*720`、`1920*1080`；与 `ratio` 同时给出时比例必须一致 |\n| `parameters.duration` | int | 全部 | 时长（秒），缺省 `5` |\n| `parameters.prompt_extend` | boolean | 全部 | 是否让上游智能改写提示词 |\n| `parameters.watermark` | boolean | 全部 | 是否加水印 |\n| `parameters.seed` | int | 全部 | 随机种子 |\n| `parameters.audio` | boolean | 全部 | 是否生成音频。**不传 = 有声视频，按有声档计费**（与百炼默认一致）；传 `true` = 有声，按有声档计费；传 `false` = 无声视频，按无声档计费。也接受顶层 `generate_audio`（布尔或 `\"true\"`/`\"false\"`）。`false` 的请求只会交给能出无声视频的渠道；若当前没有这样的渠道，创建返回 `400`（`error_class=provider_unsupported`），不产生费用 |\n\n### 分辨率档位\n\n| 档位 | 16:9 | 9:16 | 1:1 | 4:3 | 3:4 |\n| --- | --- | --- | --- | --- | --- |\n| 720P | `1280*720` | `720*1280` | `960*960` | `1088*832` | `832*1088` |\n| 1080P | `1920*1080` | `1080*1920` | `1440*1440` | `1632*1248` | `1248*1632` |\n\n- 4:3 / 3:4 的 `size` 同时接受百炼写法：720P `1104*832` / `832*1104`，1080P `1648*1248` / `1248*1648`，与表中写法为同一档位、同价。\n- **只提供 720P / 1080P。** 传 `4K` 或表外 `size` 会在创建时被拒（HTTP `400`），不会静默降档生成，也不产生费用。\n- **按可交付档位选路。** 网关只把请求交给能按所声明档位交付的供应商（如 `wan2.7-t2v` 的 720P 目前仅由官方百炼通道渲染），不会由其他供应商按 1080P 代出再按 720P 计费；若当前没有能出该档位的供应商，创建返回 `400`，不产生费用。\n- `input` 中除上表字段外的键（如 `ref_images_url`）不被本接口支持，会被拒绝而不是忽略。\n\n### 视频续写（`first_clip`，仅 i2v）\n\n- 用 `input.media[]` 的 `{\"type\": \"first_clip\", \"url\": \"<视频直链>\"}`（或平铺的 `input.first_clip_url`）从一段已有视频接着往下生成；片段须为 2–10 秒的 mp4 / mov，URL 须**公网可直接下载**（不能是需要鉴权的地址，例如本网关的 `/v1/videos/{id}/content`）。\n- 只能用于 `wan2.7-i2v`，不能与 `first_frame`（`img_url`）或 `driving_audio`（`audio_url`）同时给出，可与 `last_frame` 搭配；违反上述任一条件创建时返回 `400`，不产生费用。\n- 按 i2v 计费，档位与不带续写的 i2v 相同。\n- 并非所有供应商通道都能承载续写：网关只把续写请求交给确认支持的通道，当前没有可用通道时创建返回 `400`，不产生费用。\n\n### 首帧图片的要求（i2v）\n\n- 必须是上游服务器能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。\n- 部分站点直链对非浏览器抓取返回 403，会导致任务在生成阶段失败（`task_status=FAILED`），不计费。建议使用自有对象存储或 CDN 地址。\n\n## 3. 轮询任务\n\n`GET {{ api_endpoint }}/api/v1/tasks/{task_id}`\n\n```bash\ncurl {{ api_endpoint }}/api/v1/tasks/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n完成时：\n\n```json\n{\n  \"output\": {\n    \"task_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\",\n    \"task_status\": \"SUCCEEDED\",\n    \"submit_time\": \"2026-09-07 17:05:59.000\",\n    \"end_time\": \"2026-09-07 17:09:06.000\",\n    \"video_url\": \"{{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content\"\n  },\n  \"usage\": {\"video_duration\": 6, \"video_count\": 1},\n  \"request_id\": \"gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5\"\n}\n```\n\n- `task_status`：`PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`。失败时 `output.code` / `output.message` 给出原因，任务**不计费**。\n- 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。\n- `output.video_url` 指向网关内容接口，需带 API Key 下载；不要持久化，产物有保留期。\n\n## 4. 下载视频\n\n`GET {{ api_endpoint }}/v1/videos/{task_id}/content`\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/gw_e99647a0-692d-4fdd-ae46-e1d777e72bf5/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" -o cat.mp4\n```\n\n返回 `video/mp4` 字节流，支持 `Range`。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 `409`，过期或不存在返回 `404`。\n\n## 5. 完整示例（Python，官方 SDK 风格）\n\n```python\nimport os, time, requests\n\nBASE = \"{{ api_endpoint }}\"\nH = {\"Authorization\": f\"Bearer {os.environ['MODELGO_API_KEY']}\", \"X-DashScope-Async\": \"enable\"}\n\ndef synthesize(model: str, inp: dict, params: dict, out: str, timeout: int = 600) -> None:\n    r = requests.post(f\"{BASE}/api/v1/services/aigc/video-generation/video-synthesis\",\n                      json={\"model\": model, \"input\": inp, \"parameters\": params}, headers=H, timeout=30)\n    r.raise_for_status()\n    task_id = r.json()[\"output\"][\"task_id\"]\n    deadline = time.time() + timeout\n    while True:\n        if time.time() > deadline:\n            raise TimeoutError(task_id)\n        o = requests.get(f\"{BASE}/api/v1/tasks/{task_id}\", headers=H, timeout=30).json()[\"output\"]\n        if o[\"task_status\"] == \"SUCCEEDED\":\n            break\n        if o[\"task_status\"] == \"FAILED\":\n            raise RuntimeError(o.get(\"message\") or o.get(\"code\"))\n        time.sleep(8)\n    with requests.get(o[\"video_url\"], headers=H, stream=True, timeout=120) as c:\n        c.raise_for_status()\n        with open(out, \"wb\") as f:\n            for chunk in c.iter_content(1 << 20):\n                f.write(chunk)\n\nsynthesize(\"wan2.7-t2v\", {\"prompt\": \"一只毛茸茸的橘猫在阳光下玩毛线球\"}, {\"resolution\": \"1080P\", \"duration\": 5}, \"t2v.mp4\")\nsynthesize(\"wan2.7-i2v\", {\"prompt\": \"猫缓缓转头并眨眼\", \"img_url\": \"https://example-cdn.com/cat.jpg\"}, {\"resolution\": \"720P\", \"duration\": 5}, \"i2v.mp4\")\n```\n\n## 6. 计费口径\n\n- 按**视频秒数 × 分辨率档位单价**计费；创建时按请求的 `duration` 预授权冻结，任务完成后按**实际交付秒数**结算（`usage.video_duration`）。上游可能多交付 1 秒（请求 5 秒、交付 6 秒），按 6 秒结算。\n- **未传时长按缺省值预授权**（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，**四舍五入到整秒**（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。\n- 创建被拒（`400`）或生成失败（`FAILED`）不计费，预授权自动释放。\n- 各模型单价以控制台「模型列表」中的价格为准。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n| --- | --- | --- |\n| 创建返回 `400` | `resolution` / `size` 不在 720P / 1080P 内；缺 `input.prompt`；i2v 缺 `input.img_url`（或 `media` 的 `first_frame`）；t2v 带了 `input.img_url` / `input.last_frame_url`（图生视频请用 `wan2.7-i2v`）；`input` 含不支持的键，或 `input.media[]` 的 `type` 不支持、与旧字段重复；`ratio` 不在可选值内，或与 `aspect_ratio` / `size` 的比例不一致；当前无供应商能出所请求档位 | 按参数表修正或换模型/档位 |\n| `task_status=FAILED` | 上游无法下载 `img_url` 或生成失败 | 换成公网可直接下载的直链 |\n| 轮询返回 `task_not_found` | `task_id` 不是本 Key 创建的任务 | 核对 `task_id` 与 Key |\n| `/content` 返回 `409` / `404` | 任务未完成 / 产物过期 | 先轮询到 `SUCCEEDED`；及时下载 |\n","china/zh/quickstart/agent-clients.md":"---\ntitle: AI 工具接入\ndescription: 选择 AI 客户端或 Agent，通过 ModelGo 调用模型。\n---\n\n# AI 工具接入\n\nModelGo 支持常用的 AI 编程客户端和 Agent。创建 API Key 后，推荐使用 ModelGo CLI 自动完成接入；未接入 CLI 的客户端可通过自定义 Provider 手动配置。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n运行后选择一个或多个工具；如需自动化配置全部支持的工具，可使用：\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n## 支持的 AI 工具\n\n:::agent-tools\n| 工具 | ModelGo CLI自动接入 | 手动接入文档 |\n| --- | --- | --- |\n| Hermes Agent | 支持 | [接入文档](../agents/hermes-agent) |\n| Claude Code | 支持 | [接入文档](../agents/claude-code) |\n| Kilo Code | 暂不支持 | [接入文档](../agents/kilo-code) |\n| Cline | 暂不支持 | [接入文档](../agents/cline) |\n| Codex | 支持 | [接入文档](../agents/codex) |\n| OpenClaw | 支持 | [接入文档](../agents/openclaw) |\n| DeepSeek Harness | 暂不支持 | [接入文档](../agents/deepseek-harness) |\n| ZCode | 暂不支持 | [接入文档](../agents/zcode) |\n| Cursor | 暂不支持 | [接入文档](../agents/cursor) |\n| OpenCode | 支持 | [接入文档](../agents/opencode) |\n| CC Switch | 支持 | [接入文档](../agents/cc-switch) |\n| Cherry Studio | 暂不支持 | [接入文档](../agents/cherry-studio) |\n| Crush | 支持 | [接入文档](../agents/crush) |\n| Factory Droid | 支持 | [接入文档](../agents/factory-droid) |\n| Copilot CLI | 支持 | [接入文档](../agents/copilot-cli) |\n| nanobot | 支持 | [接入文档](../agents/nanobot) |\n| Oh My Pi | 支持 | [接入文档](../agents/oh-my-pi) |\n| CodeBuddy | 支持 | [接入文档](../agents/codebuddy) |\n| Kilo CLI | 暂不支持 | [接入文档](../agents/kilo-cli) |\n:::\n\n## 接入前准备\n\n1. 在[控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n2. 运行上方命令并选择需要接入的客户端或 Agent。\n3. 按终端提示确认站点、Base URL 和脱敏后的 API Key；配置工具会完成连通性验证。\n\n如果你希望用命令行管理 ModelGo 账户、模型、调用和 Skills，继续阅读[命令行工具](cli)。\n\n## 集成指南\n\n大多数工具只需要配置以下信息，即可连接 ModelGo：\n\n1. **API 地址**：OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`；Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n2. **API Key**：在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建的令牌。\n3. **模型名称**：在[模型广场]({{ site_endpoint }}/models)选择的逻辑模型名。\n\n具体配置步骤请参考上方各工具对应的接入文档。\n","china/zh/quickstart/authentication.md":"---\ntitle: 认证鉴权\ndescription: API Key 的获取、传递方式、优先级与常见认证失败处理。\n---\n\n# 认证鉴权\n\n所有模型调用接口都通过 API Key 认证。\n\n## 推荐请求头\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic 风格客户端也可使用：\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini 风格客户端也可使用：\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\n当多个头同时出现时，优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。\n\n## 获取与管理\n\n- 控制台：`{{ console_endpoint }}`\n- API Key 仅在创建时完整展示一次\n- 吊销或停用后会在鉴权缓存失效后生效\n\n## 认证失败\n\n常见错误：\n\n| HTTP | error_class | 说明 |\n| --- | --- | --- |\n| `401` | `auth` | 缺少、无效、停用或过期的 API Key |\n| `403` | `policy` | Key 有效，但不允许调用该模型或未绑定策略 |\n\n更多错误结构见[错误码与限流](errors)。\n","china/zh/quickstart/cli.md":"---\ntitle: 命令行工具\ndescription: 选择适合你的官方命令行工具，完成 ModelGo 配置。\n---\n\n# 命令行工具\n\nModelGo 提供两个官方命令行工具。选择你要完成的任务，运行对应命令即可开始。\n\n:::tools\n@model-go/config | 接入 AI 编程客户端 | 一条命令配置 Claude Code、Codex 等常用客户端。 | npx @model-go/config -r {{ region_flag }} | 查看 npm 包 | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | 使用官方 CLI | 配合官方 ModelGo Skills，让 AI Agent 直接操作 ModelGo。 | npx @model-go/cli@latest install | 查看 npm 包 | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## 接入 AI 编程客户端 `@model-go/config` {#connect-ai-clients}\n\n如果你想在 Claude Code、Codex、OpenCode 等 AI 编程客户端中使用 ModelGo，可以选择引导式配置，也可以通过一条命令完成全部客户端配置。\n\n**引导式配置**\n\n根据终端提示输入 API Key、选择客户端并预览配置，确认后自动写入并验证连接。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**一键式配置（非交互，适合自动化）**\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n### 支持的客户端\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\n引导式配置支持勾选一个或多个客户端；使用 `--only all` 可一次配置全部客户端。\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | 输入你的 [ModelGo API Key]({{ console_endpoint }}/api-keys)。 |\n| `02` | 勾选需要配置的客户端，也可以选择“全部配置”。 |\n| `03` | 预览站点、Base URL、脱敏后的 API Key 和目标客户端。 |\n| `04` | 确认后写入客户端配置，并自动验证连接。 |\n\n> **配置成功：** 终端会显示“配置完成”和“链路验证通过”，并给出启动所选客户端的命令。\n\n[查看 @model-go/config npm 包](https://www.npmjs.com/package/@model-go/config)\n\n## 让 AI Agent 操作 ModelGo `@model-go/cli` {#install-agent-tools}\n\n如果你希望 Claude Code、Codex 等 Agent 直接使用 ModelGo，安装官方 CLI 和 ModelGo Skills。安装向导会完成 CLI 设置、Skills 分发、站点选择和可选登录。\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | npm 首次运行时，确认安装 `@model-go/cli`。 |\n| `02` | 选择安装向导语言，支持中文和英文，后续安装提示将使用所选语言。 |\n| `03` | 安装或升级 ModelGo CLI，并安装 ModelGo Skills。 |\n| `04` | 在向导中选择当前站点环境（`{{ api_endpoint }}`）。 |\n| `05` | 选择是否立即通过浏览器登录；也可以跳过并稍后运行 `modelgo auth login`。 |\n\n### 安装后如何使用\n\n安装完成后，重新启动 AI Agent 或新建会话。ModelGo Skills 会让 AI Agent 直接调用 ModelGo CLI 完成查询和操作，你可以用自然语言向它提问，例如：\n\n- “当前 ModelGo 支持的模型有哪些？”\n- “当前 ModelGo 的账户余额还剩多少？”\n\n如果你希望自己在终端操作，输入 `modelgo` 即可查看全部可用命令和参数说明：\n\n```bash\nmodelgo\n```\n\n常用能力按使用场景分为以下几类：\n\n| 使用场景 | 常用命令 | 说明 |\n| --- | --- | --- |\n| 登录与身份 | `modelgo auth login`、`modelgo auth status`、`modelgo auth logout` | 登录 ModelGo、查看当前登录状态或清除本地登录信息。 |\n| 站点环境 | `modelgo env list`、`modelgo env current`、`modelgo env use <name>` | 查看可用环境、确认当前环境或切换站点；也可以通过 `env add` 和 `env remove` 管理自定义环境。 |\n| 工作空间 | `modelgo tenant list`、`modelgo tenant use <slug>` | 查看当前账号可用的工作空间，并通过工作空间 slug 或 ID 切换 CLI 后续操作使用的工作空间。 |\n| 账户与用量 | `modelgo balance`、`modelgo permissions`、`modelgo logs` | 查看余额和交易记录、账号权限、调用日志及用量统计。 |\n| 模型调用 | `modelgo models`、`modelgo chat`、`modelgo embeddings`、`modelgo call` | 查询可用模型，发起对话或向量请求，或直接调用任意 `/v1/*` 模型接口。 |\n| Key 与支付 | `modelgo key`、`modelgo pay` | 管理当前环境保存的模型 API Key，或管理 x402 按次支付配置。 |\n| CLI 维护 | `modelgo update`、`modelgo --version`、`modelgo --help` | 更新 CLI、查看版本或重新打开完整帮助。 |\n\n需要查看某个命令的参数时，运行 `modelgo <command> --help`。对于 `balance`、`permissions` 和 `logs`，还可以使用全局参数 `--tenant <slug\\|id>` 临时指定本次查询的工作空间。\n\n[查看 @model-go/cli npm 包](https://www.npmjs.com/package/@model-go/cli)\n\n:::note 安全提示\n- 推荐通过交互提示输入 API Key，不要把 Key 直接写进命令。\n- 不要把 API Key 提交到代码仓库或粘贴到共享脚本。\n- 如果安装 CLI 时跳过登录，稍后运行 `modelgo auth login`。\n:::\n\n## 继续探索\n\n- [首次调用](quickstart)：发起第一次模型调用。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n","china/zh/quickstart/errors.md":"---\ntitle: 错误码与限流\ndescription: 统一错误结构、常见错误分类与限流处理建议。\n---\n\n# 错误码与限流\n\n## 错误响应结构\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\n错误响应体除了 `error` 对象外，还带一个与 `X-Trace-ID` 响应头一致的顶层 `trace_id` 字段（链路追踪关闭时省略），便于按日志检索。`metadata.reason` 是可选细分原因（例如 `model_not_in_catalog`）。完整清单与已验证示例见[接口清单](openapi)。\n\n## 常见错误分类\n\n| error_class | HTTP | 含义 |\n| --- | --- | --- |\n| `client_invalid` | 400 | 请求格式或参数无效 |\n| `model_protocol_not_offered` | 400 | 该逻辑模型未声明当前入口对应的 `public_protocols`（`app_error_id=4005`）。换入口或换模型，不要改写请求体撞协议 |\n| `provider_invalid` | 400 | 上游拒绝请求（上游返回非 401/403/408/429 的 4xx） |\n| `provider_unsupported` | 400 | 上游不支持该接口（例如部分视频模型不支持 `DELETE` 取消） |\n| `provider_timeout` | 408 | 上游请求超时 |\n| `auth` | 401 | API Key 认证失败 |\n| `billing_insufficient` | 402 | 余额不足 |\n| `policy` | 403 | 无权调用该模型或未绑定策略 |\n| `quota` | 429 | 触发平台配额或限流 |\n| `provider_rate_limit` | 429 | 上游触发限流（上游返回 429） |\n| `gateway_internal` | 500 | 网关内部错误（兜底分类） |\n| `billing_system` | 502 | 计费系统不可用 |\n| `provider_server` | 502 | 上游服务错误 |\n| `provider_unauthorized` | 502 | 上游凭证被拒（统一归为 5xx，不向调用方暴露上游 Key 问题） |\n| `provider_unavailable` | 503 | 无可用模型供应方 |\n| `route_unconfigured` | 503 | 模型路由未配置上游 |\n\n## 失败请求的计费规则\n\n- 预扣：每次请求受理后按预估用量冻结余额，请求结束后按实际用量结算，多冻结的部分立即释放。\n- 成功请求与已交付部分内容的流式请求：按实际返回的用量结算。\n- **请求已发往上游供应方但最终失败**（上游 4xx/5xx、上游超时、流中途断开，以及客户端在等待响应期间主动断开）：按本次请求的预扣金额结算，不再退回。上游供应方对这类请求已产生实际成本，平台按预扣口径承担并向调用方收取。\n- 请求尚未发往上游即被平台拒绝（参数校验、鉴权、策略、配额、余额不足、网关内部错误）：预扣全额释放，不产生费用。\n- 结算依据可在控制台用量明细的交易记录中查看，按预扣结算的记录会标注失败原因。\n\n## 排障建议\n\n- 保留响应头中的 `X-Request-ID` 与 `X-Trace-ID`；错误响应体也会带同值的顶层 `trace_id` 字段\n- 遇到 `429` 时结合 `Retry-After` 响应头做退避重试（平台限流命中时会下发该头）\n- 流式请求若收到带 `error` 字段的数据块，应按失败处理（此类流中断对应 `provider_stream_broken`，不会再以独立的 HTTP 状态码返回）\n\n能力接口的细节见：\n\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n","china/zh/quickstart/openapi.md":"---\ntitle: 接口清单\ndescription: 客户模型调用面的全量 OpenAPI 清单、鉴权、协议匹配规则与已验证示例。\n---\n\n# 接口清单\n\n本页列出当前对外开放的模型调用 HTTP 接口（`mgk_` API Key，网关 `{{ api_endpoint }}`）。\n\n## 接入前置\n\n1. 在 `{{ console_endpoint }}` 创建 API Key（`mgk_` 前缀），完整明文只展示一次。\n2. `export MODELGO_API_KEY=\"你的-API-Key\"`。\n3. 调用 `GET /v1/models` 确认该 Key 能用的**逻辑模型名**。\n4. 选接口前先确认该模型是否声明了对应协议：打到模型未提供的入口，网关返回 HTTP 400、`error_class=model_protocol_not_offered`（`app_error_id=4005`），而不是帮你改写成别的协议。\n\n## 鉴权\n\n所有下列接口都用同一套 API Key：\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic 客户端可用 `x-api-key`，Gemini 客户端可用 `x-goog-api-key`。多头同时出现时优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。详见[认证鉴权](authentication)。\n\n缺 Key 或 Key 无效时的真实响应（HTTP 401）：\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\n排障请同时保留响应头 `X-Request-ID`、`X-Trace-ID` 与 body 里的 `trace_id`。\n\n## 协议匹配（必读）\n\n平台按模型目录里的 `public_protocols` 决定一个逻辑模型能打哪些入口。文档里的 curl **不能**对任意模型复制粘贴。\n\n| 模型 | 入口 | 结果 |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`、`POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings/multimodal` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`、`POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations`（`size` 至少约 1920×1920） | 200 |\n\n## 全量清单\n\n状态含义：\n\n- **正式对外**：网关已挂载，客户可调；能否对某个模型调通，仍取决于该模型的 `public_protocols` 与 Key 策略。\n- **正式对外 / 别名**：与上一行行为相同。\n\n### 文本与模型目录\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | 正式对外 | 列出当前 Key 策略允许的逻辑模型 |\n| `POST` | `/v1/responses` | 正式对外 | OpenAI Responses，新项目优先 |\n| `POST` | `/v1/chat/completions` | 正式对外 | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | 正式对外 | 旧版 Completions；多数对话模型未声明此协议 |\n| `POST` | `/v1/messages` | 正式对外 | Anthropic Messages |\n\n### 向量 / 图像 / 音频 / 重排\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | 正式对外 | 文本向量 |\n| `POST` | `/v1/embeddings/multimodal` | 正式对外 | 多模态向量；需模型声明对应协议 |\n| `POST` | `/v1/images/generations` | 正式对外 | 图像生成 |\n| `POST` | `/v1/images/edits` | 正式对外 | 图像编辑，`multipart/form-data` |\n| `POST` | `/v1/audio/speech` | 正式对外 | OpenAI TTS；**不是**所有语音模型都提供此协议 |\n| `POST` | `/minimax/v1/t2a_v2` | 正式对外 | MiniMax 原生同步语音合成，见[MiniMax 音频入站协议](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | 正式对外 | 语音转文本，multipart |\n| `POST` | `/v1/audio/translations` | 正式对外 | 语音翻译，multipart |\n| `POST` | `/v1/rerank` | 正式对外 | 重排序 |\n| `POST` | `/v1/reranks` | 正式对外 / 别名 | 与 `/v1/rerank` 等价 |\n\n### 视频与异步任务（托管）\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 正式对外 | 通用异步任务创建 |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 取消；上游不支持时返回 `provider_unsupported` |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 正式对外 | 与上一组同一托管流水线，Ark 路径拼写 |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上轮询 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上取消 |\n| `POST` | `/minimax/v2/video_generation` | 正式对外 | MiniMax 视频 V2 托管入口，请求需带齐计费维度 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 取消 |\n| `POST` | `/v1/video/generations` | 正式对外 | OpenAI 兼容视频创建；需模型声明该协议 |\n| `GET` | `/v1/videos/{task_id}` | 正式对外 | 轮询 |\n| `GET` | `/v1/videos/{task_id}/content` | 正式对外 | 302 拉产物 |\n| `DELETE` | `/v1/videos/{task_id}` | 正式对外 | 取消 |\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n真实响应形态（条目已截断）：\n\n```json\n{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"claude-fable-5\",\n      \"object\": \"model\",\n      \"created\": 1735689600,\n      \"context_length\": 1000000,\n      \"input_modalities\": [\"file\", \"image\", \"text\"],\n      \"output_modalities\": [\"text\"]\n    }\n  ]\n}\n```\n\n`id` 就是请求里的 `model`。清单**不包含** `public_protocols`；某个模型能不能打某个入口，以实际调用结果和控制台模型页为准。\n\n## 文本调用（已验证）\n\n### `POST /v1/chat/completions`\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}],\n    \"max_tokens\": 64\n  }'\n```\n\n成功时 HTTP 200，`object` 为 `chat.completion`，含 `choices[0].message` 与 `usage`。部分推理模型会额外返回 `reasoning_content`，且 `usage.completion_tokens` 可能远大于 `max_tokens`（实测 `max_tokens: 64` 时 completion 仍可达上千）。\n\n流式：同一路径加 `\"stream\": true`，响应 `Content-Type: text/event-stream`，每行 `data: {chunk}`，以 `data: [DONE]` 结束。\n\n空 body `{}` 的真实错误（HTTP 400）：\n\n```json\n{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"invalid request\",\n    \"metadata\": {\n      \"app_error_id\": 4001,\n      \"error_class\": \"client_invalid\",\n      \"request_id\": \"gw_a542461f-fe16-4f72-88d7-4c67b4bc9d7c\"\n    }\n  },\n  \"trace_id\": \"d6630b36c387a9e1e2d7bc9b6aa89020\"\n}\n```\n\n模型不在目录（HTTP 403）：\n\n```json\n{\n  \"error\": {\n    \"code\": 403,\n    \"message\": \"model is not registered or enabled in catalog\",\n    \"metadata\": {\n      \"app_error_id\": 4031,\n      \"error_class\": \"policy\",\n      \"reason\": \"model_not_in_catalog\",\n      \"request_id\": \"gw_ecc21066-c4a9-4eb1-97e7-799c4b1290\"\n    }\n  }\n}\n```\n\n### `POST /v1/responses`\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"input\": \"用一句话介绍 ModelGo。\",\n    \"max_output_tokens\": 64\n  }'\n```\n\n成功时 `object` 为 `response`，`output` 为数组（可能含 `reasoning` 与 `message`），并带 `output_text`。\n\n### `POST /v1/messages`\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"claude-fable-5\",\n    \"max_tokens\": 64,\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}]\n  }'\n```\n\n成功时 Anthropic 消息形态：`type: \"message\"`，`content[].type: \"text\"`。响应里的 `model` 可能是上游内部名（实测为 `pa/venus-cathedral-5`），与请求里的逻辑名不同，请以请求 `model` 和控制台为准。\n\n## 向量 / 图像 / 语音（已验证）\n\n### `POST /v1/embeddings`\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"text-embedding-3-small\",\"input\":\"hello ModelGo\"}'\n```\n\n成功：`data[0].embedding` 为浮点数组（`text-embedding-3-small` 实测维度 1536），`usage.prompt_tokens` 为计费 token。\n\n### `POST /v1/images/generations`\n\n`doubao-seedream-5.0-lite` 拒绝过小的 `size`。`1024x1024` 实测 HTTP 400、`error_class=provider_invalid`，上游要求像素总数至少 3686400（约 1920×1920）。用 `2048x2048` 可通过：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"a tiny red apple on white background, simple\",\n    \"size\": \"2048x2048\"\n  }'\n```\n\n成功响应含 `data[0].url`（对象存储地址，有时效）和 `usage.generated_images`。响应 `model` 可能是上游名（实测 `doubao-seedream-5-0-260128`）。\n\n### `POST /minimax/v1/t2a_v2`\n\n见[MiniMax 音频入站协议](../models/audio/minimax)。`speech-2.8-turbo` / `speech-2.8-hd` 当前声明的是这条 MiniMax 原生协议，不是 OpenAI `/v1/audio/speech`。\n\n## 异步视频（已验证）\n\nSeedance 类模型走托管异步任务，而不是 OpenAI `/v1/video/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedance-2.0-mini\",\n    \"content\": [{\"type\": \"text\", \"text\": \"a red apple on a table\"}]\n  }'\n```\n\n创建成功（HTTP 200）：\n\n```json\n{\n  \"id\": \"gw_c731f504-5a53-4e37-a972-30653a8ee390\",\n  \"model\": \"doubao-seedance-2.0-mini\",\n  \"status\": \"queued\",\n  \"created_at\": 1789012940,\n  \"error\": null\n}\n```\n\n同一 `id` 也可在 `GET /ark/api/v3/contents/generations/tasks/{id}` 轮询，状态会变为 `running`，完成后为 **`succeeded`**（实测 `resolution=720p`、`ratio=16:9`、`duration=5`）。`DELETE` 取消在该上游上实测返回 HTTP 400、`error_class=provider_unsupported`、`endpoint not supported by provider`——不要假设所有视频模型都支持取消。\n\n`POST /minimax/v2/video_generation` 若缺少计费维度，返回 HTTP 400、`client_invalid`（`billing_error_code=4223`）。按 MiniMax 视频文档补齐 `duration` / `resolution` 等字段后再试。\n\n## 流式约定\n\n- 文本流式接口（`/v1/chat/completions`、`/v1/responses`、`/v1/messages`）在请求体设 `stream: true`（Anthropic 为 `stream: true`）。\n- OpenAI 形态：`Content-Type: text/event-stream`，帧为 `data: <json>`，正常结束带 `data: [DONE]`。\n- Anthropic `/v1/messages` 保持原生 `event:` 帧，网关不会改写成 OpenAI SSE。\n- 流中若出现带 `error` 的数据块，按失败处理；此时可能没有独立的 HTTP 错误状态码。\n\n## 限流、超时、幂等、分页\n\n- 限流：HTTP 429，`error_class` 为 `quota` 或 `provider_rate_limit`；平台限流时会带 `Retry-After`。\n- 超时：客户端自行设置；上游超时为 `provider_timeout`（408）。\n- 幂等：同步文本/图像/语音请求没有客户侧幂等键。异步视频任务以返回的 `id` / `task_id` 为后续轮询主键；重复 POST 会再创建新任务。\n- 分页：模型调用面没有 cursor/page 列表接口。`GET /v1/models` 一次返回当前 Key 可见的全部逻辑模型。\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [错误码与限流](errors)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [MiniMax 音频入站协议](../models/audio/minimax)\n- [通用异步内容生成任务](../models/video/async-tasks)\n","china/zh/quickstart/overview.md":"---\ntitle: 平台概览\ndescription: 了解 ModelGo 的统一模型 API、兼容协议、模型能力与生产调用管理方式。\n---\n\n# 平台概览\n\n## ModelGo 概述\n\nModelGo 是面向生产环境的 AI 模型聚合网关。通过一个 API Key 和统一的 API，你可以调用文本、图像、视频、音频、向量与重排模型，无需为不同模型重复维护接入代码。\n\n无论你是在验证模型效果、开发 AI 功能，还是将模型调用投入生产，都可以通过相同的开发流程完成接入，并在一个平台内管理权限、用量、日志和安全策略。\n\n## 一个 API，调用多种模型\n\nModelGo 将不同类型的模型能力接入到同一套开发流程中。你可以根据业务场景选择对应能力，并进入详细文档查看接口、参数与调用示例。\n\n| 模型类别 | 模型能力 | 查看文档 |\n| --- | --- | --- |\n| 文本 | 对话、内容生成、推理与工具调用 | [文本生成](../models/text/generation) |\n| 图像 | 根据文本生成图像，或编辑已有图像 | [图像生成](../models/images/generations) · [图像编辑](../models/images/edits) |\n| 视频 | 生成视频，并通过异步任务查询进度与结果 | [标准视频接口](../models/video/openai-compatible) · [异步任务](../models/video/async-tasks) |\n| 向量 | 生成文本或多模态 Embeddings，用于语义检索与 RAG | [Embeddings](../models/vectors/embeddings) |\n| 音频 | 语音合成、语音识别与语音翻译 | [语音合成](../models/audio/speech) · [MiniMax 音频](../models/audio/minimax) · [语音转文本](../models/audio/transcriptions) · [语音翻译](../models/audio/translations) |\n| 重排 | 对候选结果重新排序，提升搜索和 RAG 的检索效果 | [Rerank](../models/rerank/rerank) |\n\n你也可以在模型广场查看可用模型，在模型体验中测试模型效果，或通过 `GET /v1/models` 获取当前 API Key 可调用的模型列表。\n\n## 使用熟悉的协议与工具\n\nModelGo 兼容 OpenAI 与 Anthropic 文本协议。已经使用相关 SDK 或客户端的项目，通常只需要替换 Base URL 和 API Key，即可沿用现有调用方式。\n\n根据客户端使用的协议选择对应地址：\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n所有请求使用同一套 ModelGo API Key 进行鉴权。你可以在[控制台]({{ console_endpoint }})创建 API Key，具体请求头与安全建议请查看[认证鉴权](authentication)。\n\n## 为生产调用而设计\n\nModelGo 不只提供统一接口，也提供模型调用进入真实业务后需要的管理能力：\n\n- **稳定调用**：在接入层统一处理模型路由与故障回退，减少单一路径异常对业务的影响。\n- **权限与安全**：通过工作空间、成员和 API Key 划分调用权限，并限制预算、可用模型与调用来源。\n- **用量与成本**：按时间、工作空间、模型、成员和 API Key 查看请求数、Token 用量与消费金额。\n- **调用追踪**：通过 Request ID、调用状态、延迟和错误信息定位同步调用与异步任务问题。\n\n## 开始使用\n\n如果是第一次接入 ModelGo，建议按以下顺序开始：\n\n- [首次调用](quickstart)：获取 API Key，并完成第一次模型调用。\n- [接口清单](openapi)：全量对外路径、协议匹配规则与已验证示例。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的调用示例。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n\n:::note 开发前请注意\n- 请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名，而不是上游厂商的原始模型 ID。\n- 通过 `GET /v1/models` 可以查询当前 API Key 有权调用的逻辑模型。返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。\n- 文本流式响应使用 SSE 传输，并以 `data: [DONE]` 表示响应结束。\n- 视频等异步生成接口会先返回 `task_id`，需要使用该 ID 查询任务进度和结果。\n- 排查调用问题时，请保留响应中的 `X-Request-ID`，方便定位具体请求。\n:::\n","china/zh/quickstart/quickstart.md":"---\ntitle: 首次调用\ndescription: 获取 API Key、选择模型，并通过 Responses API 完成第一次调用。\n---\n\n# 首次调用\n\n你可以复用现有 OpenAI 或 Anthropic SDK 接入 ModelGo，也可以按下面三步完成第一次 Responses API 调用。\n\n## 使用标准协议接入\n\nModelGo 同时兼容 OpenAI 与 Anthropic 标准协议。如果项目已经使用对应 SDK，通常只需替换 Base URL 和 API Key，无需重写调用逻辑。\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## 三步完成第一次 API 调用\n\n如果是第一次接入 ModelGo，完成下面三步即可发起请求并获得生成结果。\n\n### 第 1 步：获取 API Key\n\n- 登录[控制台]({{ console_endpoint }})。\n- 进入「API Key」页面，创建一个新的 API Key。\n- 将 API Key 写入环境变量，避免直接放进代码：\n\n```bash\nexport MODELGO_API_KEY=\"你的-API-Key\"\n```\n\n### 第 2 步：选择模型\n\n请求参数 `model` 需要填写 ModelGo 的平台逻辑模型名。你可以在[模型广场]({{ site_endpoint }}/models)查看模型，也可以通过以下请求查询当前 API Key 有权调用的逻辑模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果基于平台模型目录和 API Key 策略，并非实时探测上游能力；可用范围以控制台模型页与策略配置为准。选择一个模型名，在下一步中替换 `<model>`。\n\n### 第 3 步：发起第一次调用\n\n推荐使用 `POST /v1/responses`。选择你熟悉的方式运行下面的请求：\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"用三句话介绍 ModelGo。\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"用三句话介绍 ModelGo。\",\n)\n\nprint(response.output_text)\n```\n\n请求成功后会返回模型生成结果。Python SDK 可以通过 `response.output_text` 直接读取文本内容。\n\n## 使用其他兼容协议\n\n如果你的项目已经使用其他兼容接口，可以继续沿用原有请求结构：\n\n- [使用 Chat Completions](../models/text/generation#chat-completions)：适合已有 OpenAI Chat Completions 项目。\n- [使用 Anthropic Messages](../models/text/generation#anthropic-messages)：适合已有 Claude SDK 或 Anthropic Messages 项目。\n\n## 继续探索\n\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n- [文本生成](../models/text/generation)：查看 Responses、Chat Completions 与 Anthropic Messages 的完整说明。\n- [错误码与限流](errors)：了解错误结构、限流规则和排障方式。\n","international/en/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: Configure CC Switch and Claude Code with ModelGo.\n---\n\n# CC Switch\n\nCC Switch is a desktop provider manager for Claude Code, Codex, Gemini, OpenCode, OpenClaw, and more. This guide uses Claude Code as an example and shows how to add and enable ModelGo.\n\n## Before you start\n\n- Install [CC Switch](https://github.com/farion1231/cc-switch/releases) and make sure it opens normally.\n- Install Claude Code and launch it at least once.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open the Claude Code configuration\n\nOpen CC Switch, select **Claude** at the top, and click **+** to add a configuration.\n\n![CC Switch overview](/images/agents/cc-switch/overview.webp)\n\n![Add a Claude configuration in CC Switch](/images/agents/cc-switch/claude-add.webp)\n\n## 2. Add a ModelGo provider\n\nPaste the following JSON into the configuration editor. Replace `your-model-id` with a logical model name from the model catalog and `sk-your-token` with your ModelGo API key:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-your-token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"your-model-id\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"your-model-id\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![Edit the ModelGo configuration in CC Switch](/images/agents/cc-switch/config-global.webp)\n\nIf your CC Switch version supports environment placeholders, you can use `{env:MODELGO_API_KEY}` for the token and set it in the terminal where you start Claude Code:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | API key created in the ModelGo console |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A logical model name from the model catalog |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable logical model name |\n\n:::note\n- Use the ModelGo root URL for the Anthropic base URL. Do not append `/v1/messages`; Claude Code adds that path.\n- Keep the API key in the local CC Switch configuration or an environment variable. Do not commit it to a repository.\n- Name the provider **ModelGo** so it is easy to identify and switch later.\n:::\n\n## 3. Save and enable the provider\n\nSet the provider name to **ModelGo**, then click **Add** or **Save**. Return to the Claude configuration list and enable the ModelGo entry.\n\n![Add the ModelGo provider in CC Switch](/images/agents/cc-switch/provider-global.webp)\n\n![Enable the ModelGo profile in CC Switch](/images/agents/cc-switch/use-global.webp)\n\nStart Claude Code:\n\n```bash\nclaude\n```\n\nEnter a simple task such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n## 4. Verify the configuration\n\nTo verify the API key and model access separately:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse an `id` from the response as the logical model name for `ANTHROPIC_MODEL` and `ANTHROPIC_SMALL_FAST_MODEL`.\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nConfirm that the token is a valid ModelGo API key and that the CC Switch profile does not contain an old token. Remove extra spaces or line breaks.\n\n### 404 or endpoint errors\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`. Do not use `{{ api_endpoint }}/v1/messages` or a full request path.\n\n### Model unavailable\n\nMake sure the model name exactly matches a logical model in the [model catalog]({{ site_endpoint }}/models) and is enabled for the API key.\n\n### Claude Code still uses the old profile\n\nConfirm that the ModelGo profile is enabled in CC Switch. Fully restart the terminal, then run `claude` again.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [CC Switch Quick Start](https://cc-switch.cc/docs/getting-started/quick-start/): learn the interface and profile switching flow.\n- [CC Switch Provider Setup](https://cc-switch.cc/en/tutorials/provider-setup): learn custom provider fields and credential management.\n","international/en/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: Connect Cherry Studio to the international ModelGo endpoint through a custom provider.\n---\n\n# Cherry Studio\n\nCherry Studio includes several built-in providers, but ModelGo is not one of them. Use Cherry Studio's **Custom Provider** flow to create a ModelGo provider, then fetch and add the models you need. ModelGo exposes both OpenAI-compatible and Anthropic-compatible endpoints.\n\n## Prerequisites\n\n- Cherry Studio is installed and you can open its Settings page.\n- You have created or copied an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- You have confirmed the logical model ID to use in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Open model service settings\n\nOpen Cherry Studio **Settings**, go to **Model Services**, and click **+ Add Provider** at the bottom of the provider list.\n\n![Open the provider picker in Cherry Studio](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. Add a custom provider\n\nIn the **Add Custom Provider** dialog, enter:\n\n| Setting | Value for international ModelGo |\n| --- | --- |\n| Provider name | `ModelGo` |\n| API key | The API key created in the ModelGo console |\n| OpenAI endpoint | `{{ api_endpoint }}/v1` |\n| Anthropic endpoint | `{{ api_endpoint }}` (only for Anthropic-compatible models or Agent mode) |\n\nClick **Add** to save the provider. Use the OpenAI endpoint for regular chats and model discovery. Do not append `/v1` to the Anthropic endpoint; Cherry Studio builds the protocol path for you.\n\n![Add the ModelGo custom provider](/images/agents/cherry-studio/custom-provider-global.webp)\n\n:::note\n- Do not enter a full `/chat/completions` or `/messages` URL.\n- Use `{{ api_endpoint }}/v1` for OpenAI-compatible requests and `{{ api_endpoint }}` for Anthropic-compatible requests.\n:::\n\n## 3. Fetch and add models\n\nReturn to the ModelGo provider page and click **Get Models**. Cherry Studio reads the logical models available to the current API key.\n\n![Fetch ModelGo models in Cherry Studio](/images/agents/cherry-studio/fetch-models-global.webp)\n\nIn the model picker, click **+** next to individual models or choose **Add All Models**.\n\n![Add all ModelGo models in Cherry Studio](/images/agents/cherry-studio/model-picker.webp)\n\nAdded models appear in the ModelGo provider's model section. Adding only the models you use keeps the model picker easier to navigate.\n\n![ModelGo models in the provider list](/images/agents/cherry-studio/model-list-global.webp)\n\n## 4. Enable the provider and start chatting\n\nTurn on the switch in the upper-right corner of the ModelGo provider page and run the API key check. Start a new chat, select **ModelGo** and one of the models you added, then send a short message.\n\nFor OpenAI-compatible models, the OpenAI endpoint is enough. For Claude or Cherry Studio Agent mode, configure the Anthropic endpoint and add an Anthropic-compatible model as well.\n\n## Verify the configuration\n\nYou can verify model discovery from a terminal:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical ModelGo model IDs to add in Cherry Studio.\n\n## Troubleshooting\n\n### 401 or authentication failure\n\nCheck that the API key was copied in full with no extra spaces, and that the provider switch is enabled.\n\n### 404 or an invalid endpoint path\n\nSet the OpenAI endpoint to `{{ api_endpoint }}/v1` and the Anthropic endpoint to `{{ api_endpoint }}`. Do not enter the complete `/v1/chat/completions` or `/v1/messages` path.\n\n### The model list is empty\n\nFirst verify `/v1/models` with the `curl` command above, then confirm the model is enabled for your API key in the model catalog. After fetching, click **+** or **Add All Models**; fetching alone does not add models to the picker.\n\n### Agent mode cannot send a request\n\nSet the Anthropic endpoint to `{{ api_endpoint }}` and add a model that supports the Anthropic-compatible protocol. The Anthropic endpoint is not required for ordinary OpenAI-compatible chats.\n\n## Related documentation\n\n- [First call](../quickstart/quickstart): Create an API key, inspect models, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): Learn how to keep API keys safe.\n- [Cherry Studio custom providers](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang): Follow Cherry Studio's official custom-provider flow.\n- [Cherry Studio provider settings](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers): Learn how Base URLs, model management, and connection checks work.\n","international/en/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: Configure Claude Code with ModelGo's Anthropic-compatible API.\n---\n\n# Claude Code\n\nClaude Code is a terminal-based AI coding assistant. Configure its Anthropic-compatible endpoint to use ModelGo models and API keys.\n\n## Before you start\n\n- Install Node.js.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Claude Code\n\nRun:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nVerify the installation:\n\n```bash\nclaude --version\n```\n\n## 2. Configure ModelGo\n\n### macOS / Linux\n\nCreate and edit the Claude Code settings file:\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\nRun these commands in PowerShell:\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\nPaste the following into `settings.json`. Replace `YOUR_MODELGO_API_KEY` and `YOUR_MODELGO_MODEL` with a real ModelGo API key and logical model name:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\nUse the ModelGo root URL for `ANTHROPIC_BASE_URL`; do not append `/v1/messages`. Claude Code adds the path and calls ModelGo's `POST /v1/messages` endpoint.\n\n:::note\n- If you use one model only, set all five model variables to the same ModelGo logical model so an unavailable auxiliary model does not prevent startup.\n- Keep the API key in your local settings. Do not commit `settings.json` or share it with others.\n:::\n\n## 3. Optional: skip official account onboarding\n\nIf the first `claude` launch stops at the official account login flow, create `.claude.json` in your user directory with the completed-onboarding flag.\n\nmacOS / Linux:\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell:\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. Start Claude Code\n\nChange to your project directory and start Claude Code:\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\nOn the first visit, choose **Trust This Folder** to allow Claude Code to access project files. Send a simple coding request; a normal response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | A ModelGo logical model name |\n| `ANTHROPIC_SMALL_FAST_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The same callable ModelGo logical model name |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The same callable ModelGo logical model name |\n\nFind a model in the [Model Gallery]({{ site_endpoint }}/models), or query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that `ANTHROPIC_AUTH_TOKEN` is a valid ModelGo API key and contains no extra spaces.\n\n### 403 or model unavailable\n\nMake sure all five model variables use ModelGo logical model names allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet `ANTHROPIC_BASE_URL` to `{{ api_endpoint }}`, not `{{ api_endpoint }}/v1/messages`; Claude Code adds `/v1/messages` itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code): see the latest installation and configuration guidance.\n","international/en/agents/cline.md":"---\ntitle: Cline\ndescription: Configure Cline with ModelGo's OpenAI-compatible API.\n---\n\n# Cline\n\nCline is an AI coding assistant for VS Code. Select the `OpenAI Compatible` provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install VS Code.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cline\n\nOpen the VS Code Extensions marketplace, search for **Cline**, and install the extension.\n\n![Install Cline from the VS Code Extensions marketplace](/images/agents/cline/cline-market.webp)\n\n## 2. Configure ModelGo\n\nAfter installation, click the Cline icon in the VS Code activity bar and open **API Configuration**.\n\n![Open Cline API Configuration](/images/agents/cline/cline-config-global.webp)\n\nFill in the following values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | Your ModelGo API key |\n| Model ID | A ModelGo logical model name |\n\nClick **Done** to save.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL. Do not include `/chat/completions`; Cline appends the endpoint path.\n- Use a logical model name available to the current API key in the Model Catalog rather than copying the example from the screenshot.\n- Keep the API key in your local Cline settings. Do not commit it or share screenshots containing it.\n:::\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. Start using Cline\n\nOpen the Cline panel and send a simple coding request, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Complete a conversation in Cline](/images/agents/cline/cline-chat.webp)\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in the API Key field.\n\n### 403 or model unavailable\n\nMake sure Model ID is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`; do not paste a full `/chat/completions` URL.\n\n### The model list is empty\n\nRequest `GET {{ api_endpoint }}/v1/models` to verify the endpoint. If Cline does not show the model in its list, enter Model ID manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Cline OpenAI Compatible docs](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx): see Cline's official provider configuration guidance.\n","international/en/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: Connect CodeBuddy to ModelGo.\n---\n\n# CodeBuddy\n\nCodeBuddy Code is Tencent Cloud's terminal coding assistant. Environment variables override its API endpoint, key, and model so requests can use ModelGo.\n\n## Prerequisites\n\n- Node.js 18+ and CodeBuddy CLI are installed; `codebuddy --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. Configure ModelGo variables\n\nSet these variables in the shell that starts CodeBuddy:\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-your-token\"\nexport CODEBUDDY_MODEL=\"your-model-id\"\n```\n\n`CODEBUDDY_AUTH_TOKEN` is CodeBuddy platform login, not the ModelGo model key.\n\n:::note\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Non-interactive `codebuddy -p` requires `CODEBUDDY_API_KEY`.\n- Keep keys and model IDs in a local profile or secret manager.\n:::\n\n## 3. Start and verify\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\ncodebuddy -p \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### CodeBuddy still uses its default model\n\nConfirm variables are visible in the current shell, then fully restart `codebuddy`.\n\n### 401 or 404 responses\n\nCheck `CODEBUDDY_API_KEY`, `CODEBUDDY_MODEL`, and `CODEBUDDY_BASE_URL`; do not put a full endpoint path in the Base URL.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [CodeBuddy CLI quickstart](https://www.codebuddy.ai/docs/cli/quickstart): Review installation, login, and first run.\n- [CodeBuddy CLI environment variables](https://www.codebuddy.ai/docs/cli/env-vars): Review endpoint, key, and model variables.\n","international/en/agents/codex.md":"---\ntitle: Codex\ndescription: Configure Codex CLI with ModelGo's Responses API.\n---\n\n# Codex\n\nCodex is OpenAI's command-line AI coding assistant. With a custom `model_provider`, Codex CLI can send Responses API requests to ModelGo.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Codex\n\nRun this command in macOS, Linux, or Windows:\n\n```bash\nnpm install -g @openai/codex\n```\n\nVerify the installation:\n\n```bash\ncodex --version\n```\n\nIf Codex shows an upgrade prompt on first launch, choose **Skip** and finish the ModelGo setup first.\n\n![Skip the Codex upgrade prompt](/images/agents/codex/codex-start.webp)\n\n## 2. Configure ModelGo\n\nCodex reads its user-level model and provider settings from `~/.codex/config.toml`. Create the file first:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\nPaste the following into `config.toml`, replacing `YOUR_MODELGO_MODEL` with a logical model name allowed for the current API key:\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\nThe `base_url` is ModelGo's OpenAI-compatible API root. Codex appends `/v1/responses` when it sends a request.\n\n## 3. Set the API key\n\nStore your ModelGo API key in the `MODELGO_API_KEY` environment variable. Do not put the real key directly in `config.toml`.\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\nCheck that the variable is set without printing the key:\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- Keep `MODELGO_API_KEY` in your local environment. Do not commit it or share terminal screenshots containing it.\n- `model` must be a ModelGo logical model name. The `gpt-5.6-sol` shown in the screenshot is only an example; replace it with a model you can call.\n- `wire_api = \"responses\"` is required by current Codex configurations. Do not use the deprecated `wire_api = \"chat\"`.\n:::\n\n:::note Start a new conversation after changing the API key or endpoint\n- In a multi-turn conversation, Codex continues to send prior Responses context. That context may include encrypted reasoning data that can only be handled by the original upstream account.\n- If you change `MODELGO_API_KEY` or `base_url`, or a proxy or account pool routes the same conversation to another upstream account, start a new Codex conversation. Do not continue or resume the existing conversation, or the request may fail with `400 invalid_encrypted_content`.\n:::\n\n## 4. Start and verify\n\nChange to a local project directory and run:\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\nWhen Codex asks for permission to work in the project, trust the directory as appropriate. After the welcome screen appears, send a simple coding request such as “Describe this project in three sentences.”\n\n![Codex project welcome screen](/images/agents/codex/codex-skip.webp)\n\nA normal model response confirms that ModelGo is connected.\n\n![Start a conversation in Codex](/images/agents/codex/codex-chat.webp)\n\nTo verify which models the API key can call:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### Provider not found at startup\n\nMake sure the file is the user-level `~/.codex/config.toml`, and that `model_provider = \"modelgo\"` matches `[model_providers.modelgo]`.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces or newlines.\n\n### 403 or model unavailable\n\nMake sure `model` is a logical ModelGo model name allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `base_url` to `{{ api_endpoint }}/v1`. Do not include `/responses` or `/v1/responses`; Codex appends the path.\n\n### Chat wire API deprecation warning\n\nAdd `wire_api = \"responses\"` under `[model_providers.modelgo]`, then upgrade Codex CLI:\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### `400 invalid_encrypted_content`\n\nThis usually means the conversation contains encrypted context created by the original upstream account, but the current request was handled by a different upstream account.\n\nCheck whether the API key or Base URL changed, or whether a proxy or account pool switched upstream accounts. If a switch occurred, start a new conversation instead of continuing or resuming the existing one.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [Codex configuration reference](https://developers.openai.com/codex/config-reference/): see current `config.toml` fields.\n","international/en/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: Connect Copilot CLI to ModelGo.\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI supports BYOK. Provider environment variables can route model requests to ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Copilot CLI is installed and `copilot --help` works.\n- GitHub/Copilot authentication is complete.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know a logical model ID that supports tool calling and streaming.\n\n## 1. Configure ModelGo BYOK\n\nSet these variables in the shell that starts Copilot CLI:\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"your-model-id\"\ncopilot\n```\n\nIf needed, define the key first:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nThe `openai` provider type targets OpenAI Chat Completions-compatible services.\n\n:::note\n- GitHub login and the ModelGo API key are separate credentials.\n- Use `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- Prefer a model with tool calling, streaming, and a large context window.\n:::\n\n## 2. Verify the model\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\nAsk Copilot CLI to perform a small read-only task, such as listing project entry points.\n\n## Troubleshooting\n\n### Copilot still uses its default model\n\nConfirm `COPILOT_MODEL` and `COPILOT_PROVIDER_BASE_URL` are visible in the current shell, then restart `copilot`.\n\n### 401, 404, or tool-call errors\n\nCheck the key, Base URL, and logical model ID. Choose a model with the required streaming and tool-calling capabilities.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models): Review provider variables and model requirements.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","international/en/agents/crush.md":"---\ntitle: Crush\ndescription: Connect Crush to ModelGo.\n---\n\n# Crush\n\nCrush is Charmbracelet's terminal coding agent. Its OpenAI-compatible provider support lets you route requests through ModelGo.\n\n## Prerequisites\n\n- Node.js 18+, Go, or Homebrew is available; `crush --version` works.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\nYou can also use `npm install -g @charmland/crush`, `go install github.com/charmbracelet/crush@latest`, or `winget install charmbracelet.crush` on Windows.\n\n## 2. Add a ModelGo provider\n\nCrush reads project `.crushrc`/`crushrc` files and the global `~/.config/crush/crushrc` (Windows: `%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`).\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/your-model-id --name \"your-model-id\"\n```\n\nReplace `your-model-id` with a ModelGo logical model ID.\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the Base URL; do not append `/chat/completions`.\n- Keep the API key in `MODELGO_API_KEY` instead of committing it to a config file.\n- `modelgo/your-model-id` is Crush's provider/model identifier.\n:::\n\n## 3. Start and verify\n\n```bash\ncrush\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck the `crushrc` filename and path, then restart Crush. Project configuration takes precedence over global configuration.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is available in the same shell and that the Base URL is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n- [Crush repository](https://github.com/charmbracelet/crush): Read installation, provider, and command references.\n- [Crush config schema](https://github.com/charmbracelet/crush/blob/main/schema.json): Check `crushrc` fields.\n","international/en/agents/cursor.md":"---\ntitle: Cursor\ndescription: Configure Cursor with ModelGo's OpenAI-compatible API.\n---\n\n# Cursor\n\nCursor is an AI coding editor. With a custom OpenAI Base URL, Cursor can call ModelGo logical models.\n\n## Before you start\n\n- Install [Cursor](https://www.cursor.com/).\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install Cursor\n\nVisit the [Cursor website](https://www.cursor.com/) and download the build for your operating system.\n\n![Cursor download page](/images/agents/cursor/install.webp)\n\n## 2. Open Cursor model settings\n\nOpen Cursor settings and go to **Models**.\n\n![Open Models in Cursor Settings](/images/agents/cursor/settings.webp)\n\n## 3. Add and enable a model\n\nClick **Add model**, enter a logical model name from the [model catalog]({{ site_endpoint }}/models), and save it.\n\n![Add a model in Cursor](/images/agents/cursor/add-model.webp)\n\nIn **Model Names**, keep the models you want to use and disable the rest.\n\n![Enable the target model in Cursor](/images/agents/cursor/model-list.webp)\n\n## 4. Configure the ModelGo endpoint\n\nIn **Settings → Models → API Keys**, configure the OpenAI-compatible endpoint:\n\n| Setting | ModelGo value |\n| --- | --- |\n| OpenAI API Key | Your ModelGo API key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | A logical model name from the ModelGo catalog |\n\n![Configure the ModelGo endpoint in Cursor](/images/agents/cursor/config-global.webp)\n\nIf your Cursor release uses the alternate settings layout, enter the same ModelGo values there.\n\n![Alternate Cursor settings layout](/images/agents/cursor/config-cn.webp)\n\nClick **Verify** or **Save**. Cursor may use slightly different labels in different releases, but the API key, Base URL, and model name have the same meaning.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- Use a logical model name from the ModelGo catalog instead of copying the example in the screenshot.\n- If Verify fails, send a test message in chat or use the command below to check the endpoint and key.\n:::\n\n## 5. Test the connection\n\nReturn to the Cursor chat, select the model you added, and send a simple message. A normal response confirms the integration.\n\n![Test a ModelGo model in Cursor](/images/agents/cursor/chat.webp)\n\nYou can also list the models available to the API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nMake sure the API key is complete, has no extra spaces, and is entered in **OpenAI API Key**.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions` to it.\n\n### Verify fails or the model is unavailable\n\nCheck that the model name is a logical ModelGo model and that the model is enabled for the API key.\n\n### The chat returns no content\n\nRun `GET {{ api_endpoint }}/v1/models` to verify connectivity and the key, then confirm the target model is enabled in Model Names.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [Cursor documentation](https://docs.cursor.com/): see Cursor settings, models, and custom API configuration.\n","international/en/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: Configure DeepSeek Harness with ModelGo's OpenAI-compatible API.\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness (DSH) is an open-source agent framework from DeepSeek AI. It combines models, tools, filesystems, terminals, sessions, and a Web UI into a runnable agent. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22 or later.\n- Install pnpm 11 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start DeepSeek Harness\n\nThe current source-install path is:\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![Start DeepSeek Harness from source](/images/agents/deepseek-harness/install.webp)\n\nThe terminal prints the Web UI address. The default is `http://127.0.0.1:3080`; use the address printed by your terminal if the port is already in use.\n\nFor a quick preview, you can also run:\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. Configure ModelGo\n\nOpen the address printed by the terminal, click the sidebar button in the upper-left corner, and then click **Settings**.\n\n![Open DeepSeek Harness settings](/images/agents/deepseek-harness/settings.webp)\n\nSelect **Models** and click **Add custom provider**.\n\n![Add a custom provider](/images/agents/deepseek-harness/model-picker.webp)\n\nUse these values:\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider ID | `modelgo` |\n| Display name | `ModelGo` |\n| API URL | `{{ api_endpoint }}/v1` |\n| API protocol | `openai-completions` |\n| API key | ModelGo API key |\n| Model ID | A logical model name from the Model Catalog |\n| Display name | You can use the same value as the model ID |\n\n![Fill in the ModelGo custom provider](/images/agents/deepseek-harness/provider-config.webp)\n\nClick **Create provider** to save the configuration. Keep these points in mind:\n\n:::note\n- Use `{{ api_endpoint }}/v1` as the API URL. Do not append `/chat/completions`; DSH builds the request path for the `openai-completions` protocol.\n- The model ID must be a logical ModelGo model name allowed by the API key. Do not copy the example model from the screenshot.\n- Keep the API key in your local configuration. Do not commit it or share it in screenshots.\n:::\n\n## 3. Start a session\n\nReturn to the main view, choose a workspace, and then select the ModelGo model you just added.\n\n![Select the ModelGo model](/images/agents/deepseek-harness/session.webp)\n\nSend a simple task such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### The Web UI does not open\n\nMake sure `pnpm dsh web` is still running and open the port printed by the terminal. The default is `3080`; DSH may choose another port when it is occupied.\n\n### 401 or authentication failed\n\nCheck that the API key is complete, has no extra spaces, and was created in the ModelGo Console.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet the API URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Select `openai-completions` as the API protocol.\n\n### The model list is empty\n\nCheck that a model ID is present and that the custom provider was saved. You can verify the ModelGo endpoint first:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [DeepSeek Harness official website](https://www.deepseek.com/harness/): see the latest installation and product information.\n- [DeepSeek Harness GitHub repository](https://github.com/deepseek-ai/deepseek-harness): view source and releases.\n","international/en/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: Connect Factory Droid to ModelGo.\n---\n\n# Factory Droid\n\nFactory Droid is Factory's terminal agent. Its BYOK custom model settings can point Droid at ModelGo's OpenAI-compatible endpoint.\n\n## Prerequisites\n\n- Node.js 18+ and the Droid CLI are installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install and start Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\nInside Droid, `/settings` opens the settings screen.\n\n## 2. Configure a ModelGo custom model\n\nMerge this `customModels` entry into `~/.factory/settings.json` (Windows: `%USERPROFILE%\\\\.factory\\\\settings.json`):\n\n```json\n{\n  \"customModels\": [{\n    \"model\": \"your-model-id\",\n    \"displayName\": \"ModelGo / your-model-id\",\n    \"baseUrl\": \"{{ api_endpoint }}/v1\",\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"provider\": \"openai\"\n  }]\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nRestart Droid and choose the custom model from `/models` or the model picker.\n\n:::note\n- Set `baseUrl` to `{{ api_endpoint }}/v1`; do not add `/chat/completions`.\n- `model` must be a ModelGo logical model ID.\n- Merge `customModels` into the existing file so other settings remain intact.\n:::\n\n## 3. Verify a request\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"your-model-id\" \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### The model is not listed\n\nValidate the JSON, keep `customModels` at the top level, and fully restart Droid.\n\n### Authentication or endpoint errors\n\nCheck the environment variable in the shell that launches Droid and remove duplicate `/v1` or full paths from `baseUrl`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Factory Droid settings](https://docs.factory.ai/droid-cli/settings): Find `settings.json` and settings entry points.\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok): Review custom model fields.\n","international/en/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: Configure Hermes Agent with ModelGo's OpenAI-compatible API.\n---\n\n# Hermes Agent\n\nHermes Agent is a terminal-based AI agent. With a custom provider, Hermes can use ModelGo's OpenAI-compatible API to call models.\n\n## Before you start\n\n- Install Node.js 22 or newer.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm the ModelGo logical model name you want to use in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Hermes Agent\n\nmacOS or Linux:\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\nReopen your terminal and verify the installation:\n\n```bash\nhermes --version\n```\n\n## 2. Configure ModelGo\n\nPut your API key in an environment variable for the current shell. Never commit a real key to a repository or public script:\n\n```bash\nexport MODELGO_API_KEY=\"your-ModelGo-API-key\"\nexport MODELGO_MODEL=\"your-ModelGo-logical-model-name\"\n```\n\nIf you are not sure which model name to use, query the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nUse `hermes config set` to create a custom provider. Replace `<model>` with a logical model name from the Model Gallery or the `GET /v1/models` response:\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\nIf your Hermes version includes the interactive setup wizard, you can run:\n\n```bash\nhermes model\n```\n\nChoose **Custom endpoint**, enter the ModelGo Base URL, API key, and model name, and select **Chat Completions** as the protocol.\n\n:::note\n- Some older Hermes releases label the Chat Completions protocol as `openai_messages`. If `chat_completions` is rejected, upgrade Hermes or select Chat Completions in the `hermes model` wizard.\n:::\n\n## 3. Check the configuration and start a session\n\nCheck the Hermes configuration:\n\n```bash\nhermes config check\n```\n\nStart Hermes after the check passes:\n\n```bash\nhermes\n```\n\nSend a message such as “Introduce ModelGo in three sentences.” A model response confirms the connection.\n\n## ModelGo values\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API mode | `chat_completions` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model ID | A ModelGo logical model name, not the upstream provider's raw model ID |\n\nHermes stores non-sensitive settings in `~/.hermes/config.yaml` and API keys and other secrets in `~/.hermes/.env`. Do not share or commit files under `~/.hermes/` that contain credentials.\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nMake sure the API key is valid and has not been revoked or expired, then run:\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 403 or model unavailable\n\nCheck that `model.default` is a ModelGo logical model allowed by the policy attached to your API key.\n\n### 404 or endpoint not found\n\nUse `{{ api_endpoint }}/v1` as the Base URL. Do not append `/chat/completions`; Hermes adds the request path itself.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs): see the latest installer, configuration, and CLI reference.\n","international/en/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: Connect Kilo CLI to ModelGo.\n---\n\n# Kilo CLI\n\nKilo CLI is a terminal coding agent with custom OpenAI-compatible providers. Because ModelGo CLI automation is not available for Kilo CLI, use `/connect` or a `kilo.jsonc` file.\n\n## Prerequisites\n\n- Node.js 18+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\nRun `kilo` in a project; `/connect` opens the interactive provider setup.\n\n## 2. Add a ModelGo provider\n\nCreate `kilo.jsonc` in the project root (or edit the global config):\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/your-model-id\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"ModelGo / your-model-id\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nAlternatively choose `/connect` → `OpenAI Compatible` and enter the same Base URL, key, and model ID.\n\n:::note\n- Use lowercase provider ID `modelgo`; select `modelgo/your-model-id`.\n- `baseURL` is `{{ api_endpoint }}/v1`; do not append `/chat/completions`.\n- The model ID must match a ModelGo logical model.\n:::\n\n## 3. Verify the configuration\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\nSelect the ModelGo model and send a small read-only task.\n\n## Troubleshooting\n\n### The provider is missing\n\nCheck JSONC syntax, the provider ID, and the `model` path, then restart Kilo.\n\n### 401 or 404 responses\n\nConfirm `MODELGO_API_KEY` is exported and `baseURL` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Kilo CLI documentation](https://kilo.ai/docs/code-with-ai/platforms/cli): Review installation, `/connect`, and CLI commands.\n- [Kilo custom models](https://kilo.ai/docs/code-with-ai/agents/custom-models): Review OpenAI Compatible provider fields.\n","international/en/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: Configure Kilo Code with ModelGo's OpenAI-compatible API.\n---\n\n# Kilo Code\n\nKilo Code is an AI coding assistant for VS Code and JetBrains. Use its OpenAI-compatible provider to connect Kilo Code to ModelGo models and API keys.\n\n## Before you start\n\n- Install VS Code or a JetBrains IDE.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Gallery]({{ site_endpoint }}/models).\n\n## 1. Install Kilo Code\n\n### VS Code\n\nOpen the VS Code Marketplace, search for **Kilo Code**, verify the publisher, and install the extension. Then open the Kilo Code panel from the activity bar.\n\n![Install Kilo Code from the VS Code Marketplace](/images/agents/kilo-code/vscode-market.webp)\n\nOn the first install, VS Code asks you to confirm the publisher. Verify that it is Kilo Code, then click **Trust Publisher & Install**.\n\n![Trust the Kilo Code publisher](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\nOpen Settings / Preferences → Plugins, search the Marketplace for **Kilo Code**, and install the plugin. Restart the IDE after installation so the plugin takes effect.\n\n![Install Kilo Code from the JetBrains Marketplace](/images/agents/kilo-code/jetbrains-market.webp)\n\nWhen installing a third-party plugin, JetBrains displays its plugin notice. Confirm it and click **Accept** to finish the installation.\n\n![Confirm the JetBrains third-party plugin notice](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. Configure ModelGo in VS Code\n\nOpen Kilo Code settings, go to **Providers**, select **OpenAI Compatible**, and enter:\n\nFrom the Kilo Code welcome screen, first choose **Bring my own Key**:\n\n![Choose Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API key | A ModelGo API key created in the [Console]({{ console_endpoint }}/api-keys) |\n| Model | A ModelGo logical model name |\n\n![Kilo Code VS Code configuration](/images/agents/kilo-code/vscode-config-global.webp)\n\nAfter saving, Kilo Code attempts to load models from the compatible `/v1/models` endpoint. If the target model is not in the picker, choose **Use custom** and enter the logical model name from the Model Gallery.\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append `/chat/completions`. Kilo Code adds the standard path when it sends a request.\n- The model shown in the screenshot is only an interface example. Replace it with a ModelGo logical model allowed for the API key.\n- Keep the API key in Kilo Code's local settings. Do not commit it to a repository or include it in screenshots.\n:::\n\n## 3. Configure ModelGo in JetBrains\n\nOpen Kilo Code settings, click **Bring my own Key**, select **OpenAI Compatible**, and use the same values as in VS Code:\n\n![Choose Bring my own Key in JetBrains](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**: `{{ api_endpoint }}/v1`\n2. **API key**: your ModelGo API key\n3. **Model**: a ModelGo logical model name\n4. Click **Save**.\n\n![ModelGo provider settings in JetBrains](/images/agents/kilo-code/jetbrains-config-global.webp)\n\nIf the model picker is empty, verify that the Base URL is reachable, then choose the custom-model option and enter the logical model name manually.\n\n![Kilo Code completing a task in JetBrains](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. Verify the connection\n\nOpen a local project and send a simple coding request in the Kilo Code panel, such as “Describe this project in three sentences.” A normal response confirms the connection.\n\n![Kilo Code completing a coding task](/images/agents/kilo-code/vscode-start.webp)\n\nTo inspect the models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication failed\n\nCheck that the API key is complete, contains no extra spaces, and is entered in **API key**, not the Base URL field.\n\n### 403 or model unavailable\n\nMake sure **Model** is a logical model listed in the ModelGo Model Gallery and allowed by the policy attached to the API key. Do not use an upstream provider's raw model ID unless the gallery explicitly lists it.\n\n### 404 or endpoint not found\n\nSet Base URL to `{{ api_endpoint }}/v1`, not a full `/chat/completions` URL. Kilo Code appends the endpoint path when it sends the request.\n\n### The model picker is empty\n\nUse `GET {{ api_endpoint }}/v1/models` to check the API key and endpoint. If the endpoint works, choose **Use custom** and enter the logical model name manually.\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use and protect ModelGo API keys.\n- [Kilo Code documentation](https://kilo.ai/docs): see the latest extension installation and provider setup guidance.\n","international/en/agents/nanobot.md":"---\ntitle: nanobot\ndescription: Connect nanobot to ModelGo.\n---\n\n# nanobot\n\nnanobot is a lightweight terminal agent that configures providers and model presets in JSON. It can call ModelGo through its OpenAI-compatible API.\n\n## Prerequisites\n\n- Python 3.11+ is installed.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\nThe default config is `~/.nanobot/config.json`.\n\n## 2. Configure a ModelGo provider\n\nMerge these fields into `~/.nanobot/config.json`:\n\n```json\n{\n  \"providers\": {\"modelgo\": {\n    \"apiKey\": \"${MODELGO_API_KEY}\",\n    \"apiBase\": \"{{ api_endpoint }}/v1\"\n  }},\n  \"modelPresets\": {\"ModelGo\": {\n    \"provider\": \"modelgo\",\n    \"model\": \"your-model-id\",\n    \"maxTokens\": 4096,\n    \"contextWindowTokens\": 65536,\n    \"temperature\": 0.1\n  }},\n  \"agents\": {\"defaults\": {\"modelPreset\": \"ModelGo\"}}\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nLeave `apiType` unset for a custom OpenAI-compatible endpoint.\n\n:::note\n- Preserve existing channels and tools fields when merging the JSON.\n- Keep the key in `MODELGO_API_KEY`, not in a committed config file.\n- The model must be a ModelGo logical model ID.\n:::\n\n## 3. Verify the connection\n\n```bash\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"Describe this project in one sentence\"\n```\n\n## Troubleshooting\n\n### nanobot cannot find the model\n\nMake sure `modelPresets.ModelGo.provider` matches `providers.modelgo` and that the JSON is valid.\n\n### 401 or endpoint errors\n\nConfirm the key is exported and `apiBase` is exactly `{{ api_endpoint }}/v1`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [nanobot OpenAI-compatible provider guide](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md): Review the JSON configuration.\n- [Authentication](../quickstart/authentication): Learn safe API key handling.\n","international/en/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: Connect Oh My Pi to ModelGo.\n---\n\n# Oh My Pi\n\nOh My Pi (`omp`) is a terminal coding agent. Declare an OpenAI-compatible provider in `models.yml`, then select models as `provider-id/model-id`.\n\n## Prerequisites\n\n- Bun or the official installer is available.\n- A ModelGo API key is available from [ModelGo Console]({{ console_endpoint }}/api-keys).\n- You know the logical model ID from the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux can also use the official installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. Add a ModelGo provider\n\nEdit `~/.omp/agent/models.yml`:\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: your-model-id\n        name: ModelGo / your-model-id\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` is the environment variable name:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\n:::note\n- Use `openai-completions` and `{{ api_endpoint }}/v1` for the endpoint.\n- Select models as `modelgo/your-model-id`.\n- Keep the real API key out of `models.yml` and source control.\n:::\n\n## 3. Select and verify\n\n```bash\nomp --list-models\nomp --model modelgo/your-model-id\ncurl {{ api_endpoint }}/v1/models -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nSend a small read-only task in the session.\n\n## Troubleshooting\n\n### ModelGo is missing from the model list\n\nCheck `~/.omp/agent/models.yml`, YAML indentation, and restart `omp`.\n\n### 401 or endpoint errors\n\nConfirm `MODELGO_API_KEY` is exported and `baseUrl` has no duplicate `/v1` or full endpoint path.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): Create a key, list models, and verify ModelGo.\n- [Oh My Pi providers](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md): Review provider, API, and key settings.\n- [Oh My Pi models](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md): Review model selection and `models.yml`.\n","international/en/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: Configure OpenClaw with ModelGo's OpenAI-compatible API.\n---\n\n# OpenClaw\n\nOpenClaw is an open-source, self-hosted personal AI assistant. Add a custom provider to call models through ModelGo's OpenAI-compatible API.\n\n## Before you start\n\n- Install Node.js 22.22.3 or later.\n- Create an API key in the [ModelGo Console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name allowed for the API key in the [Model Catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\nVerify the installation:\n\n```bash\nopenclaw --version\n```\n\n## 2. Set the API key\n\nOpenClaw can read a provider API key from an environment variable. Set your ModelGo API key as `MODELGO_API_KEY`:\n\n### macOS / Linux (zsh)\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor Bash, replace `~/.zshrc` with `~/.bashrc` or `~/.bash_profile`.\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. Configure the ModelGo provider\n\nCreate and open the OpenClaw configuration file:\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\nPaste the following into `openclaw.json`, replacing `YOUR_MODELGO_MODEL` with a logical model name from the Model Catalog:\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n| Setting | Value in ModelGo |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | A ModelGo logical model name |\n| `agents.defaults.model.primary` | `modelgo/<logical-model-name>` |\n\n:::note\n- Use `{{ api_endpoint }}/v1` as `baseUrl`; do not append `/chat/completions`.\n- Set `contextWindow` and `maxTokens` to values supported by the selected model. The values above are generic examples; use the Model Catalog as the source of truth.\n- Set `reasoning` to `true` when the selected model supports reasoning.\n- Inject the API key through the environment. Do not write a real key into the config file or commit it.\n:::\n\n## 4. Start and verify\n\nSave the configuration and run:\n\n```bash\nopenclaw onboard --install-daemon\n```\n\nCheck the active provider and model:\n\n```bash\nopenclaw models status\n```\n\nIf the status is healthy, start the Gateway:\n\n```bash\nopenclaw gateway start\n```\n\nSend a simple message in OpenClaw, such as “Describe this project in three sentences.” A normal response confirms the ModelGo connection.\n\n## Troubleshooting\n\n### Model not found\n\nMake sure `models.providers.modelgo.models[].id` matches the model name in `agents.defaults.model.primary`, which must use the `modelgo/<model-name>` format.\n\n### 401 or authentication failed\n\nCheck that `MODELGO_API_KEY` exists in the current terminal and that `apiKey` is `${MODELGO_API_KEY}` with no extra spaces.\n\n### 403 or model unavailable\n\nConfirm that the model ID is a logical ModelGo model allowed by the policy attached to the API key.\n\n### 404 or incorrect endpoint path\n\nSet `baseUrl` to `{{ api_endpoint }}/v1`; do not use a full `/chat/completions` URL. OpenClaw appends the path for `openai-completions`.\n\n### Gateway did not load the new configuration\n\nRestart the Gateway after editing the file:\n\n```bash\nopenclaw gateway restart\n```\n\n## Related docs\n\n- [First call](../quickstart/quickstart): create an API key, find a model, and verify a ModelGo request.\n- [Authentication](../quickstart/authentication): learn how to use ModelGo API keys.\n- [OpenClaw custom provider docs](https://docs.openclaw.ai/gateway/config-tools): see provider, Base URL, and model list configuration.\n","international/en/agents/opencode.md":"---\ntitle: OpenCode\ndescription: Configure OpenCode with ModelGo's OpenAI-compatible API.\n---\n\n# OpenCode\n\nOpenCode is an open-source terminal AI coding agent. Its custom provider support lets you connect any OpenAI-compatible endpoint, including ModelGo, from a terminal, IDE, or desktop client.\n\n## Before you start\n\n- Install Node.js 18 or later.\n- Install OpenCode and confirm that `opencode -v` works in your terminal.\n- Create or copy an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name available to your API key in the [model catalog]({{ site_endpoint }}/models).\n\n## 1. Install OpenCode\n\nRun:\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nYou can also use the installation method provided by the OpenCode project. A version printed by `opencode -v` confirms a successful installation.\n\n## 2. Configure the ModelGo provider\n\nOpenCode reads user configuration from:\n\n- macOS/Linux: `~/.config/opencode/opencode.json`\n- Windows: `%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\nCreate or edit `opencode.json`. Replace `your-model-id` with a logical model name from the model catalog:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"your-model-id\": {\n          \"name\": \"your-model-id\"\n        }\n      }\n    }\n  }\n}\n```\n\nSet the environment variable:\n\n```bash\nexport MODELGO_API_KEY=\"sk-your-token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-your-token\"\n```\n\n| Setting | ModelGo value |\n| --- | --- |\n| `name` | `ModelGo`, the display name in OpenCode |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | A logical model ID and display name from the model catalog |\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not append the full `/chat/completions` path.\n- `modelgo` is a local provider ID and can be changed. Use the new ID when selecting a model.\n- Keep the API key in an environment variable instead of committing it to a config file.\n- Model IDs must exactly match logical model names from the ModelGo catalog.\n:::\n\n## 3. Select a model and start a chat\n\nStart OpenCode:\n\n```bash\nopencode\n```\n\nEnter `/models` to open the model picker, then select a model under the **ModelGo** provider.\n\n![Open the model picker in OpenCode](/images/agents/opencode/model-search.webp)\n\nThe **ModelGo** provider label confirms that OpenCode recognized the provider.\n\n![Identify ModelGo in the OpenCode model list](/images/agents/opencode/provider-name.webp)\n\nYou can also type `ModelGo` in the picker to filter the list:\n\n![Filter ModelGo models in OpenCode](/images/agents/opencode/provider-filter.webp)\n\nSelect the model and enter a simple task such as “Describe this project in three sentences.”\n\n![Start a chat with ModelGo in OpenCode](/images/agents/opencode/chat.webp)\n\n## 4. Verify the configuration\n\nIf the model list is empty, confirm that the API key can reach ModelGo:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe `id` values in the response are the logical model names to use in `models`.\n\n## Troubleshooting\n\n### OpenCode cannot find the config file\n\nCheck that the file is named `opencode.json` and is in `~/.config/opencode/` (or `%USERPROFILE%\\\\.config\\\\opencode\\\\` on Windows). A project-level file with the same name can override user settings.\n\n### 401 or authentication errors\n\nConfirm that `MODELGO_API_KEY` is set in the current terminal and contains no extra spaces. Restart OpenCode after changing the variable.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as `baseURL`; do not append `/chat/completions`.\n\n### Empty model list or unavailable model\n\nMake sure the ID in `models` exactly matches a logical ModelGo model and that the model is enabled for the API key.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): use API keys safely.\n- [OpenCode Providers documentation](https://opencode.ai/docs/providers): configure providers, credentials, and custom Base URLs.\n- [OpenCode configuration documentation](https://opencode.ai/docs/config/): learn the config file structure and model options.\n","international/en/agents/zcode.md":"---\ntitle: ZCode\ndescription: Configure ZCode with ModelGo's OpenAI-compatible API.\n---\n\n# ZCode\n\nZCode is a desktop AI coding environment from Zhipu AI for Windows, macOS, and Linux. It supports custom OpenAI-compatible providers, so you can use ModelGo models and API keys directly in ZCode.\n\n## Before you start\n\n- Install the ZCode desktop app.\n- Create an API key in the [ModelGo console]({{ console_endpoint }}/api-keys).\n- Confirm a logical model name that the API key can call in the [Model catalog]({{ site_endpoint }}/models).\n\n## 1. Install ZCode\n\nOpen the [ZCode download page](https://zcode.z.ai/en/docs/install) and download the package for your operating system. ZCode provides macOS, Windows, and Linux builds; Linux users can choose `.deb`, `.rpm`, or AppImage.\n\n![ZCode download page](/images/agents/zcode/install.webp)\n\nComplete the installation and launch ZCode. On first launch, choose a workspace and finish the onboarding flow to reach the main interface.\n\n![ZCode platform installers](/images/agents/zcode/setup.webp)\n\n## 2. Add the ModelGo provider\n\nClick the settings icon in the lower-left corner, open **Model settings**, then click **Add provider** at the bottom of the provider list.\n\n![Open ZCode Model settings and add a provider](/images/agents/zcode/provider-fields.webp)\n\nEnter the following values:\n\n| Setting | ModelGo value |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | A ModelGo API key created in the [console]({{ console_endpoint }}/api-keys) |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | Click **Add model** and enter a logical model name from the model catalog |\n| Context window | Use the model's actual context length; if unsure, start with `200000` |\n\n![ModelGo provider settings](/images/agents/zcode/provider-saved-global.webp)\n\nClick **Add provider** to save. Keep these details in mind:\n\n:::note\n- Set Base URL to `{{ api_endpoint }}/v1`; do not enter the full `/chat/completions` URL. ZCode appends the request path based on the API format.\n- Name is only the local display name. Use `ModelGo`; do not enter an upstream vendor name.\n- Model IDs must be logical model names from the ModelGo catalog. Do not copy the example model in the screenshot.\n- Keep the API key in the local ZCode settings and out of repositories or public screenshots.\n:::\n\n## 3. Add a model and start a chat\n\nClick **Add model**, enter a ModelGo logical model name, and save it. You can add multiple models as needed.\n\n![Select a ModelGo model in ZCode](/images/agents/zcode/chat.webp)\n\nReturn to the chat view, select **ModelGo** and the model you added, then enter a simple task such as “Describe this project in three sentences.” A successful response confirms the integration.\n\nTo verify which models the API key can call, run:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## Troubleshooting\n\n### 401 or authentication errors\n\nCheck that the API key is complete, has no extra spaces, and is entered in the **API Key** field.\n\n### 403 or model unavailable\n\nConfirm that the Model list uses a logical model name from the ModelGo catalog and that the API key is allowed to call it.\n\n### 404 or endpoint errors\n\nUse `{{ api_endpoint }}/v1` as the Base URL and choose **Chat completions (/chat/completions)**. Do not paste a complete endpoint path into Base URL.\n\n### Empty model list or provider cannot be saved\n\nMake sure at least one model has been added and the Base URL is reachable. If needed, verify the API key and endpoint with `GET {{ api_endpoint }}/v1/models`.\n\n## Related docs\n\n- [First API Call](../quickstart/quickstart): create an API key, find a model, and verify ModelGo.\n- [Authentication](../quickstart/authentication): learn how to use API keys safely.\n- [ZCode installation docs](https://zcode.z.ai/en/docs/install): see the latest installation instructions.\n- [ZCode model connection docs](https://zcode.z.ai/en/docs/configuration): see custom provider and model settings.\n","international/en/models/audio/minimax.md":"---\ntitle: MiniMax Audio\ndescription: Drive platform-managed synchronous speech synthesis with MiniMax T2A request and response bodies.\n---\n\n# MiniMax Audio\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | Catalog-advertised MiniMax T2A inbound |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK alias with the same semantics |\n\nThis is **MiniMax synchronous speech synthesis (T2A V2)** as an inbound protocol. The gateway accepts a MiniMax `T2aV2Req` body as-is (`model`, `text`, `voice_setting`, `audio_setting`, `stream`, and other MiniMax fields) and **renders a MiniMax `T2aV2Resp`**, so a client written against MiniMax's own documentation can decode this surface directly.\n\n`model` is the platform logical model name; policy, routing, and billing apply as usual. The logical model must advertise `minimax_t2a` in `public_protocols`, or the gateway rejects the call as a protocol mismatch.\n\nFor OpenAI-shaped binary audio, see [Speech](./speech).\n\n## Synthesize\n\nThe two paths are equivalent:\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"Hello from ModelGo.\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\nA successful non-stream response is MiniMax JSON. Audio lives in `data.audio` as a **hexadecimal string** (not a raw `audio/mpeg` body):\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\nVerified 2026-09-10 on domestic production with `speech-2.8-turbo` against `POST /minimax/v1/t2a_v2` (hex truncated). The same model on `POST /v1/audio/speech` returns `model_protocol_not_offered`.\n\nOnly numeric `base_resp.status_code` **`0`** is success. HTTP 200 with a non-zero `status_code` is still a failed invoke.\n\n### Streaming\n\nSet `\"stream\": true`. The response is SSE whose events are MiniMax JSON (incremental hex audio), not OpenAI chat `choices[].delta` chunks.\n\n### Failures and HTTP status\n\nIn-band MiniMax errors are echoed to the caller. The gateway maps `status_code` to HTTP:\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| any other non-`0` | `502` |\n\n### Billing\n\nUsage is the upstream **character** count (`usage.characters`, else `extra_info.usage_characters`). The gateway does not bill `len(text)`.\n\n## Conventions\n\n- `model` is the platform logical model name; whether this lane is allowed is the model's `public_protocols`.\n- The path does not pick the upstream family. Routing on the logical model decides MiniMax-direct vs a Bailian adaptor.\n- Providers on the route must declare MiniMax T2A. An OpenAI-compatible relay alone returns `provider_unsupported`.\n","international/en/models/audio/speech.md":"---\ntitle: Speech\ndescription: OpenAI-compatible text-to-speech endpoint.\n---\n\n# Speech\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\nThe request is JSON (OpenAI `{input, voice}`) and the response body is binary audio returned with the upstream `Content-Type`.\n\n**Check `public_protocols` first.** Domestic `speech-2.8-hd` / `speech-2.8-turbo` currently offer MiniMax T2A, not this endpoint (`model_protocol_not_offered`). Use [MiniMax Audio Inbound Protocol](./minimax).\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"Hello from ModelGo.\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\nFor MiniMax-native fields (voice mix, subtitles, hex JSON, SSE), see [MiniMax Audio Inbound Protocol](./minimax).\n","international/en/models/audio/transcriptions.md":"---\ntitle: Transcriptions\ndescription: OpenAI-compatible speech-to-text endpoint.\n---\n\n# Transcriptions\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\nThis endpoint typically uploads audio as `multipart/form-data` and returns JSON with recognized `text`.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/en/models/audio/translations.md":"---\ntitle: Translations\ndescription: OpenAI-compatible audio translation endpoint.\n---\n\n# Translations\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\nUploads follow the same shape as transcriptions and return translated text in JSON.\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/en/models/images/edits.md":"---\ntitle: Image Edits\ndescription: OpenAI-compatible image edit endpoint.\n---\n\n# Image Edits\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\nThis endpoint uses `multipart/form-data` and forwards the original body and `Content-Type` upstream, so clients should call `POST /v1/images/edits` with multipart upload semantics.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\nIf the routed upstream model does not support image editing, the gateway returns `provider_unsupported`.\n","international/en/models/images/generations.md":"---\ntitle: Image Generation\ndescription: OpenAI-compatible image generation endpoint.\n---\n\n# Image Generation\n\n| Method | Path |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\nThe request body follows the OpenAI Images-compatible shape and is forwarded to an upstream provider that supports image generation. The main entrypoint is `POST /v1/images/generations`.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\nCommon optional fields include `size`, `quality`, and `n`, subject to upstream model support.\n\n## Verified Seedream limit\n\n`doubao-seedream-5.0-lite` rejects `size=1024x1024` (HTTP 400 `provider_invalid`, at least 3686400 pixels). `2048x2048` succeeded on 2026-09-10. Full curl: [API catalog](../../../quickstart/openapi).\n","international/en/models/images/qwen-image.md":"---\ntitle: Qwen Image\ndescription: Call qwen-image-3.0 / qwen-image-3.0-pro on either of two synchronous inbound lanes — OpenAI-compatible and Bailian DashScope native — with text to image and image to image (1-3 reference images), the two spellings of size, and the 1k / 2k resolution tiers. The official Bailian SDK works by changing base_url.\n---\n\n# Qwen Image\n\n## Models\n\n| Model | Output resolution | Notes |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | Total pixels 512×512 – 2048×2048 | Pro tier; the 2k tier costs more than 1k |\n| `qwen-image-3.0` | Same | Standard tier; both tiers priced the same |\n\n> **Availability and pricing differ by region.** Check the model list for this endpoint before integrating — see the [API catalog](../../../quickstart/openapi).\n\nBoth models serve **text to image (T2I)** and **image to image / editing (I2I)**: no reference image means T2I, 1–3 reference images mean I2I. Images are returned **synchronously** — no polling.\n\n> **The async task lane is not supported.** This family is served only on the synchronous endpoints; a call to `/v1/content_generation/tasks` is refused.\n\n## Two inbound lanes\n\nOne model, two spellings, identical capability. Pick whichever matches the code you already have:\n\n| Lane | Path | Who it is for |\n| --- | --- | --- |\n| OpenAI-compatible | `POST /v1/images/generations` | Apps already written against the OpenAI Images protocol or SDK — change `base_url` and `model` only |\n| Bailian native | `POST /api/v1/services/aigc/multimodal-generation/generation` | Apps already using the Bailian DashScope SDK — change `base_url` only |\n\n> **The two lanes spell `size` differently and neither accepts the other's spelling**: the OpenAI-compatible lane uses the letter `x` (`1024x1024`), the Bailian native lane uses an asterisk (`1024*1024`). The wrong one returns `400` naming the separator it expects; it is **not** silently rewritten — mixing the two protocols should surface here rather than as a harder problem further down.\n\n## 1. OpenAI-compatible lane\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### Text to image\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"A fluffy ginger cat on a sunlit windowsill, afternoon light, film grain\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### Image to image / editing\n\nNo multipart: the reference images go in the top-level `image` field.\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"Keep her facial features; change the outfit to a champagne silk shirt and a dark grey blazer\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### Response\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- Images are PNG, and the **link is valid for 24 hours** — download promptly and do not persist the URL.\n- `usage` carries **image counts and tiers, not token usage**: this family bills purely per image (see Billing).\n- `response_format: \"b64_json\"` does not error but is ignored; the response still carries an image URL.\n\n### Using the OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # Generation is slow; 40-60s for a single image in practice\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"A fluffy ginger cat on a sunlit windowsill, film grain\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # extensions go through extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` are not OpenAI parameters: pass them via `extra_body` with the OpenAI SDK, or at the top level of the request body over plain HTTP.\n\n## 2. Bailian native lane\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\nRequest and response are Bailian's own shapes in both directions — the gateway does not translate.\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### Response\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### Constraints of this lane\n\n- `input.messages` carries **exactly one** object and `role` must be `user` (single-turn only).\n- `content` carries **exactly one** `{\"text\": ...}`; omitting it or passing several returns `400`.\n- `{\"image\": ...}` 0–3 entries: 0 is text to image, 1–3 is image to image.\n- Generation parameters live under `parameters` (not at the top level): `size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`.\n- With the official Bailian SDK (`dashscope`), point `dashscope.base_http_api_url` at `{{ api_endpoint }}/api/v1` and use your ModelGo API key.\n\n## 3. Parameters\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt` (compat lane) / `content[].text` (native lane) | string | Required, non-empty. Chinese and English; up to about 4500 tokens recommended |\n| `image` (compat lane) / `content[].image` (native lane) | string / string[] | Reference images, 1–3. **`null` and an empty array are refused** |\n| `size` | string | `WxH` on the compat lane, `W*H` on the native lane. Omitted means the model picks a resolution from the prompt |\n| `n` | int | 1–6 output images, default 1. **Must be an integer**; the string form (e.g. `\"1\"`) returns `400` |\n| `negative_prompt` | string | What to keep out of the picture |\n| `seed` | int | `0` – `2147483647`. A fixed seed makes results relatively stable |\n| `prompt_extend` | boolean | Prompt rewriting, default `true` (recommended) |\n| `prompt_extend_mode` | string | `direct` (default, T2I and I2I) / `agent` (finer, **text to image only**) |\n| `enable_thinking` | boolean | Thinking mode, default `true`. Better images, longer latency. Only effective when `prompt_extend=true` |\n| `watermark` | boolean | Watermark, default `false` |\n\n### Validation happens before the call\n\nThe following are refused at creation (HTTP `400`) — nothing reaches the upstream and nothing is charged:\n\n- `n` is not an integer in 1–6, or is written as a string or a decimal;\n- `size` total pixels fall outside 512×512 – 2048×2048, or the aspect ratio is outside 1:8 – 8:1;\n- `size` uses the other lane's separator (the error names whether `x` or `*` is expected);\n- `image` is `null`, an empty array, or more than 3 entries;\n- `prompt_extend_mode: \"agent\"` is combined with `image` (APE is text to image only);\n- `seed` is outside `0` – `2147483647`;\n- on the native lane, `messages` is not exactly one, or `content` does not carry exactly one `text`.\n\n### Reference image requirements\n\n- Formats: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF.\n- Width and height between 384 and 2048 pixels recommended; at most 10 MB each.\n- Public URLs (HTTP / HTTPS) or Base64 (`data:{MIME_type};base64,{base64_data}`).\n- A public URL must be directly `GET`-able by the upstream: no auth, no redirect, no Referer / Cookie dependency. Some sites return 403 to non-browser clients, which fails the request.\n\n## 4. Metering\n\n**This family is metered per image, not per token.** The `usage` block carries image counts and tiers rather than token counts:\n\n| Field | Meaning |\n| --- | --- |\n| `output_image_count` | How many images were delivered |\n| `output_image_type` | The output tier this call hit: `qima_output_1k` or `qima_output_2k` |\n| `input_image_count` | How many reference images the request supplied (0 for text to image) |\n| `input_image_type` | The input tier, `qima_input_1k` or `qima_input_2k` |\n\n**The tier is decided by the OUTPUT pixel area**: an area of 2,250,000 (that is, 1500×1500) or less is `1k`, anything larger is `2k`. **The input tier is judged by the output area too**, not by the size of the reference image — that is the upstream's own rule.\n\nText to image supplies no reference image, so `input_image_count` is 0 and only the delivered images are metered. Requesting `n` images meters `n`, not one.\n\n## 5. Full example (Python, official Bailian SDK)\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"Change the outfit to a champagne silk shirt; modern minimalist cafe background\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","international/en/models/realtime/api.md":"---\ntitle: Realtime API reference\ndescription: Handshake, events, and audio formats for GET /api-ws/v1/realtime (WebSocket).\n---\n\n# Realtime API reference: `GET /api-ws/v1/realtime`\n\nThis endpoint is a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol verbatim in both directions with **no protocol translation**; the full field definitions and the tool-calling (Function Calling / MCP) events follow Bailian's official [client events](https://help.aliyun.com/zh/model-studio/client-events) and [server events](https://help.aliyun.com/zh/model-studio/server-events). This page covers the handshake, auth, event list, and audio conventions needed to integrate.\n\n## Request\n\n| Item | Value |\n| --- | --- |\n| Method | `GET` (WebSocket upgrade) |\n| Path | `/api-ws/v1/realtime` |\n| Full URL | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<logical model>` |\n| Query | `model` (required) — the platform logical model, not the upstream model |\n| Header | `Authorization: Bearer <mgk_ API Key>` (required) |\n| Header | `X-Request-ID` (optional) — propagated to the call log; the `request_id` starts with `gw_rt_` |\n\nOnly a logical model whose `public_protocols` includes `dashscope_realtime` can use this surface.\n\n## Handshake errors {#handshake-errors}\n\nFailures before the WebSocket upgrade are returned as HTTP status codes with a body of:\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | Trigger | Observed message (cn production, 2026-10-08) |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | no API key | `missing api key` |\n| 401 | `unauthorized` | invalid / disabled key | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | model not in catalog | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | model does not advertise `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | no route for the model in the policy (including its fallback chain) | `no route for model <model>` |\n| 503 | `no_provider` | a route exists but no provider instance is available | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | preauthorization failed (balance / budget) | `billing: insufficient funds` |\n\nAfter a successful upgrade (HTTP 101), later problems are delivered as an in-band `error` event, then the connection closes:\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## Session configuration `session.update`\n\nAfter connecting, the server first sends `session.created`; the client overrides with `session.update`, and a valid update is acknowledged with `session.updated`. Common fields:\n\n| Field | Values | Default |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | see Bailian's voice list | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | server VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | any text | empty |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | enabled |\n\n`turn_detection: null` disables the server VAD so the client commits and triggers responses manually.\n\n## Client events\n\n| Event | Purpose |\n| --- | --- |\n| `session.update` | Update session config (modalities, voice, audio format, VAD, instructions, …) |\n| `input_audio_buffer.append` | Append Base64 audio to the input buffer |\n| `input_image_buffer.append` | Append a Base64 image (JPG/JPEG; audio must have been sent first) |\n| `input_audio_buffer.commit` | Commit the audio buffer in manual mode (does not trigger a response) |\n| `input_audio_buffer.clear` | Clear the audio buffer |\n| `conversation.item.create` | Create an item: plain text input, `function_call_output`, `mcp_approval_response` |\n| `response.create` | Trigger one model response |\n| `response.cancel` | Cancel the in-progress response (interruption) |\n\n## Server events\n\n| Event | Meaning |\n| --- | --- |\n| `session.created` / `session.updated` | Session created / config applied |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD detected the user starting / stopping (interruption trigger) |\n| `input_audio_buffer.committed` / `cleared` | Audio buffer committed / cleared |\n| `conversation.item.created` | An item was created |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | Input speech transcription (streaming preview / final) |\n| `response.created` | A response turn began |\n| `response.output_item.added` / `response.content_part.added` | Output item / content part began |\n| `response.text.delta` / `response.text.done` | Text-only streaming / full text |\n| `response.audio_transcript.delta` / `.done` | Transcript of the audio output |\n| `response.audio.delta` / `response.audio.done` | Base64 output audio (24 kHz PCM) / end of audio |\n| `response.output_item.done` / `response.content_part.done` | Output item / content part completed |\n| `response.done` | Response turn ended; `response.usage` carries per-modality token usage |\n\nTool-calling events (`response.function_call_arguments.delta` / `.done`) and the MCP events (`mcp_*`) are documented in Bailian's server-events reference.\n\nObserved event order for one voice turn (cn production, 2026-10-08):\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## Audio formats\n\n| Direction | Format | Field |\n| --- | --- | --- |\n| Uplink (input) | 16000 Hz, 16-bit little-endian, mono PCM, Base64 | `audio` of `input_audio_buffer.append` |\n| Downlink (output) | 24000 Hz, 16-bit little-endian, mono PCM, Base64 | `delta` of `response.audio.delta` |\n\nSending input audio in full 100 ms frames (3200 bytes per frame) proved most reliable. `input_audio_buffer.append` only buffers; whether it is committed is decided by VAD or by a client `input_audio_buffer.commit`.\n\n## VAD and interruption\n\n- With a non-`null` `turn_detection`, the server auto-detects speech boundaries and, after `silence_duration_ms` of silence (default 800 ms), auto-commits and triggers a response.\n- When the user speaks again: the server emits `input_audio_buffer.speech_started` → the client **stops playback** and sends `response.cancel` → `response.done` (cancelled) arrives → a new turn begins.\n- `turn_detection: null` is manual mode: after recording, the client sends `input_audio_buffer.commit` (wait for `input_audio_buffer.committed`) then `response.create`.\n\n## Usage and billing\n\nEach turn's `response.done.response.usage` carries per-modality tokens:\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\nThe gateway settles the accumulated session usage at close: a session-level estimate is held at connect (currently about ¥1.2; insufficient balance fails the handshake with `402`), then refund/top-up applies based on actual usage; a session with no usage releases the hold. See the [guide](./guide#billing).\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Upstream rate limit | 60 RPM |\n\n## Related\n\n- [Realtime (WebSocket) models guide](./guide)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","international/en/models/realtime/guide.md":"---\ntitle: Realtime (WebSocket) models\ndescription: Call Qwen-Omni-Realtime over WebSocket for live voice chat, interruption, and omni-modal input.\n---\n\n# Realtime (WebSocket) models\n\nRealtime models do **not** use `/v1/chat/completions`; they are called over a long-lived WebSocket connection. The gateway relays the Bailian **Qwen-Omni-Realtime** protocol **verbatim in both directions** — there is no protocol translation: you send Bailian events and receive Bailian events. This page covers connection, a runnable minimal example, and billing; the exact event and error schema is in the [API reference](./api).\n\n## What it does\n\n- **Live voice chat**: speak and get streamed text and audio back as you go.\n- **Interruption**: when the user speaks again the server emits `input_audio_buffer.speech_started`; the client stops playback and sends `response.cancel` to interrupt the current reply.\n- **Omni-modal input**: streaming audio, images (frames sampled from video), and plain text.\n- **Text + audio output**: the model produces both text and speech.\n\n## Supported models\n\nA logical model can use this surface only if its catalog `public_protocols` includes `dashscope_realtime`. The realtime model currently available is `qwen3.8-omni-flash-realtime` (check the marketplace for what is actually listed). Check the model marketplace at [{{ console_endpoint }}]({{ console_endpoint }}) to confirm whether a model offers this protocol.\n\n## Connecting\n\n| Item | Value |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<logical model>` (required) |\n| Auth | `Authorization: Bearer <mgk_ API Key>` |\n| Request ID | optional `X-Request-ID`; the call-log `request_id` starts with `gw_rt_` |\n\nHandshake failures are returned as HTTP status codes (e.g. an invalid key is `401 unauthorized`, a model without the realtime protocol is `403 model_protocol_not_offered`, insufficient balance is `402`); see the full list in the [API reference](./api#handshake-errors).\n\n## Minimal example\n\nThe examples below run **server-side**: connect with an `mgk_` API key, configure the session, push 16 kHz PCM audio, commit, request a reply, and write the returned 24 kHz PCM to `reply.pcm`.\n\n:::note\n- A browser's native `WebSocket` constructor **cannot set an `Authorization` header**, so the API key must not be placed in a browser connection.\n- For browser microphone capture, relay through your own server (which holds the key and opens the connection), or use an authenticated server-side proxy.\n- The Python / Node.js examples below are server-side and run as-is.\n:::\n\nPrepare input: capture the microphone, or save 16 kHz, 16-bit little-endian, mono, **headerless** PCM as `input.pcm`. If you have a WAV, extract the raw PCM first:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython (`pip install websocket-client`):\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js (`npm install ws`):\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\nWrap the returned `reply.pcm` (24 kHz, 16-bit, mono) into a playable WAV:\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\nTo smoke-test connectivity without audio, send one `conversation.item.create` with an `input_text` content item, then `response.create`, to get a text-only reply.\n\n## Session configuration\n\nRight after connecting, the server sends `session.created` (with defaults); the client overrides with `session.update`. Common fields:\n\n| Field | Meaning |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` (default) or `[\"text\"]` |\n| `voice` | output voice, default `Tina`; prefer `audio.output.voice` |\n| `turn_detection` | server VAD: `{\"type\":\"server_vad\"}` or `{\"type\":\"semantic_vad\"}`; `null` = client-side manual commit |\n| `audio.input.format` | input format, e.g. `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | output format, e.g. `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | system persona |\n| `audio.input.transcription` | input transcription; the server enables it automatically (model `qwen3-asr-flash-realtime`) |\n\nThe legacy `input_audio_format` / `output_audio_format` fields still work, but new integrations should use `audio.input.format` / `audio.output.format`.\n\n## Interruption\n\nWith a non-`null` `turn_detection`, the server VAD drives turns. When the user speaks again:\n\n1. the server emits `input_audio_buffer.speech_started`;\n2. the client **stops playing** buffered reply audio and sends `response.cancel`;\n3. the server then emits `response.done` (status cancelled) and starts a new turn.\n\nIn manual mode (`turn_detection: null`) the client sends `input_audio_buffer.commit` and `response.create` after recording.\n\n## Billing {#billing}\n\n- **Token-based, per modality**: input is split into text/image/video and audio; output into text and audio. When the model produces speech, the audio **and** its transcript text are billed separately.\n- **Preauthorization at connect**: a session-level estimate is held when the connection opens (currently about ¥1.2). If the balance cannot cover it, the handshake returns `402` and no connection is established.\n- **Settled after close on actual usage**: the total of every `response.done` `usage` over the connection is settled at close — refund or top-up applies. A session that meters nothing releases the hold and charges nothing.\n\nCheck the console model page for current prices; for example, domestic `qwen3.8-omni-flash-realtime` (CNY / million tokens) is priced at input text/image/video `1.5`, input audio `6`, output text `4.5`, output audio `12`.\n\n## Limits\n\n| Item | Value |\n| --- | --- |\n| Max single connection | **30 minutes** (gateway-enforced; the socket is closed and settled at the cap) |\n| Total input tokens | 196,608 |\n| Max output tokens | 65,536 |\n| Audio history | up to 100 turns / 600 s |\n| Video history | up to 50 turns / 240 s |\n| Upstream rate limit | 60 RPM |\n\n## Next steps\n\n- [API reference: `GET /api-ws/v1/realtime`](./api)\n- [Authentication](../../quickstart/authentication)\n- [Errors and rate limits](../../quickstart/errors)\n","international/en/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: Re-order candidate documents by relevance to a query.\n---\n\n# Rerank\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | Re-rank documents by relevance to a query |\n| `POST` | `/v1/reranks` | Alias, equivalent to `/v1/rerank` |\n\nThe Rerank endpoint takes a query and a set of candidate documents and returns them ordered by relevance. It is commonly used for the re-ranking stage in retrieval-augmented (RAG) pipelines. `/v1/rerank` and `/v1/reranks` are two equivalent paths to the same capability.\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"Which protocols does ModelGo support\",\n    \"documents\":[\n      \"OpenAI and Anthropic compatible protocols\",\n      \"The weather is nice today\",\n      \"Supports image, video, vector, and audio capabilities\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## Key conventions\n\n- `model` must be the platform logical model name; the body is forwarded per the upstream Rerank protocol, and whether specific fields (e.g. `top_n`, `return_documents`) take effect depends on the routed upstream model.\n- The response typically contains a relevance score and rank index for each document.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","international/en/models/text/generation.md":"---\ntitle: Text Generation\ndescription: Unified guidance for OpenAI Responses, Chat Completions compatibility, and Anthropic Messages.\n---\n\n# Text Generation\n\nThe gateway exposes the following public text entrypoints. Prefer `POST /v1/responses` for new integrations, and use the others for SDK compatibility or native Claude clients.\n\n| Protocol | Method and path | Use |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | Preferred unified text generation API for new projects |\n| OpenAI | `POST /v1/chat/completions` | Widely compatible chat completion endpoint |\n| OpenAI | `POST /v1/completions` | Legacy text completions, only for compatibility |\n| Anthropic | `POST /v1/messages` | Claude native message format |\n| OpenAI | `GET /v1/models` | List logical models available under the current routing |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"Introduce ModelGo in three sentences.\"\n  }'\n```\n\nUse this entrypoint when you want a single OpenAI-compatible response API with a forward-looking request shape.\n\n## OpenAI Chat Completions compatibility {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this for existing OpenAI SDK flows that still depend on chat completions. New projects should usually start from `POST /v1/responses`.\n\n## OpenAI Completions (legacy)\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"Introduce ModelGo in three sentences.\",\n    \"max_tokens\":256\n  }'\n```\n\nThe legacy text-completions endpoint, only for call chains that still use a `prompt`. New projects should use Responses or Chat Completions above. `stream` is likewise delivered over SSE. Most current chat models do not offer this protocol: `qwen3.6-flash` returned HTTP 400 `model_protocol_not_offered` on 2026-09-10.\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\nUse this when the client already speaks Claude's native `/v1/messages` schema. The gateway preserves the native event-stream framing for streamed Anthropic responses.\n\n## Listing models\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` returns the logical models allowed by the API key's bound policy (resolved against the platform model catalog). It does not probe upstream capabilities at request time and may differ from the console; billing and policy follow the console and bound policies.\n\n## Key conventions\n\n- `model` must be the platform logical model name.\n- `GET /v1/models` is available; the list is derived from the API key's bound policy and the platform model catalog.\n- Both OpenAI and Anthropic style endpoints may return upstream-native `usage`.\n- Stream failures may arrive as error chunks; do not rely only on `data: [DONE]`.\n\nSee [Authentication](../../../quickstart/authentication) and [Errors & Rate Limits](../../../quickstart/errors).\n","international/en/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI-compatible embedding endpoint.\n---\n\n# Embeddings\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Multimodal (image/text) embeddings |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` may be a single string or an array of strings. The response follows the OpenAI-compatible embeddings shape.\n\n## Multimodal embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\nFor embedding inputs that mix text and image content. The `input` shape depends on the routed model's multimodal capabilities; whether it takes effect is determined by the upstream model.\n","international/en/models/video/ark.md":"---\ntitle: Seedance\ndescription: Drive platform-managed async Seedance video tasks over Ark's own paths, with Ark-shaped request and response bodies.\n---\n\n# Seedance\n\nBeyond the standard video protocols, the Doubao Seedance series (`doubao-seedance-*`) can also be\ncalled over **Volcengine Ark's own paths**, with request and response bodies following Ark's\ncontent-generation protocol:\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | Create a content generation (video) task |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Poll task status and result |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent**, see below) |\n\nThis is a **platform-managed** lane: the path is Ark's own, but the request runs on the gateway's\nstandard async task pipeline — the very same one behind\n[Generic Async Content Generation Tasks](./async-tasks), just spelled with Ark's path. It therefore\nkeeps per-dimension metering, task persistence, artifact delivery, and preauthorize/settle intact.\n\n## Create a task\n\nThe body follows Ark's content-generation protocol, and `model` is the **platform logical model\nname** (e.g. `doubao-seedance-2.0-mini`):\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a neon city cat\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\nBeyond text, the `content` array can carry images/videos, tagged by `role`; **the media combination\ndetermines the generation mode, and the mode determines which parameters are legal**:\n\n| content element | `role` | Generation mode |\n| --- | --- | --- |\n| `text` only | — | Text-to-video (t2v) |\n| `image_url` | `first_frame` | First-frame image-to-video (i2v) |\n| `image_url` | `first_frame` + `last_frame` | First/last-frame (flf2v) |\n| `image_url` / `video_url` | `reference_image` / `reference_video` | Multimodal reference-to-video |\n\n### Parameter and mode constraints\n\nValid values for `resolution` / `ratio` / `duration` **vary by model** — the Fast and Mini variants of\nSeedance 2.0, for instance, do not support `1080p`, and `duration` has a floor of 4 seconds. Ark\nextension parameters such as `camera_fixed`, `generate_audio`, `return_last_frame` and `watermark`\n**also vary by generation mode**. Sending a parameter the current model/mode does not support is\nrejected by the upstream at create time (`400` `provider_invalid`). One known case:\n\n- **`camera_fixed` is not supported in the first/last-frame (flf2v) scenario** — a request carrying\n  both `first_frame` and `last_frame` is refused when it also sets `camera_fixed`\n  (`camera_fixed ... must be empty`). First/last-frame already constrains the camera; if you need a\n  locked-off camera, use a mode that supports it (e.g. text-to-video or single first-frame).\n\nBecause this lane **does not pin an upstream family** (the same logical model is served by several\nsuppliers), whether a parameter is accepted also depends on the supplier and model version actually\nserving the call. Treat the model capability notes plus the mode constraints above as authoritative,\nand **do not assume a parameter that works in one mode works in another**.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll answer with exactly the Ark task object documented under\n[Generic Async Content Generation Tasks](./async-tasks) — it is the same pipeline, so the response\npayload and every field's meaning (`status` values, `content.video_url`, `error`, when `usage` is\nomitted) are identical to that page and are not repeated here.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nA successful cancel voids the preauthorization; nothing is settled.\n\n**Not every upstream supports cancelling, though.** Whether a task can be cancelled depends on\nwhether the supplier serving it implements cancellation, and because this lane does not pin an\nupstream family, two calls on the same logical model may differ — one cancellable, one not. Two\nfailure shapes:\n\n| Case | Response |\n| --- | --- |\n| The supplier serving the task cannot cancel | `400` / `4003` `provider_unsupported`, `endpoint not supported by provider` |\n| The task already reached a terminal state (`succeeded` / `failed`) | `409` `task_already_terminal`, `task already finished; nothing to cancel` |\n\nWhen a cancel fails the preauthorization is not released early — it follows the normal\nsettle/expiry path once the task reaches a terminal state. So **do not treat \"create then cancel\"\nas a reliable way to back out of a charge.**\n\n## Key conventions\n\n- **`id` is the gateway task id, not the upstream one.** Polling and cancelling only accept that id,\n  so hold on to the `id` returned by create.\n- **The response shape is fixed.** Whichever upstream actually serves the request, create and poll\n  both answer with the same Ark task object — it does not change when routing changes.\n- **The lane does not pin an upstream family.** The URL spelling plays no part in routing: whoever\n  the logical model behind `model` routes to serves it. Seedance is carried by several suppliers on\n  the platform, so two calls on the same logical model may land on different upstreams — that is\n  expected.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the Ark paths — use `content.video_url` from the response.\n- Whether a model is offered on this lane depends on its catalog `public_protocols` including\n  `content_generation`; without it the call is refused with `4005`. Check with\n  `GET {{ api_endpoint }}/v1/models`.\n\nIf you do not need Ark's path and field style, [OpenAI-Compatible Video Flow](./openai-compatible) is\nthe more standardized choice.\n","international/en/models/video/async-tasks.md":"---\ntitle: Async Tasks\ndescription: A platform-managed async task entrypoint for image, video, and other content generation capabilities.\n---\n\n# Async Tasks\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | Create a generic async content generation task (image / video / ...) |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | Poll a generic content generation task |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | Cancel an unfinished task and release its preauthorization (**upstream-dependent** — see \"Cancel a task\" in [Seedance Video Inbound Protocol](./ark)) |\n\n`/v1/content_generation/tasks` is a more general async task entrypoint than the standard OpenAI-compatible video flow. It covers image, video, and other generation capabilities that must run as backend tasks.\n\n## Create a task\n\nThe body follows the upstream generic generation shape and must include at least `model`:\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\nVerified 2026-09-10 on domestic production: create returned `status=queued` with a `gw_…` id; polling the same id ended at `succeeded` with `resolution=720p`, `ratio=16:9`, `duration=5`. The same model on `POST /v1/video/generations` is `model_protocol_not_offered`. `DELETE` cancel returned `provider_unsupported` on that upstream.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCreate and poll both answer with the **same** Ark-shaped task object, regardless of which upstream served the request:\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` is one of `queued` / `running` / `succeeded` / `failed`; `id` is the **gateway task id**, and it is the only id polling and cancelling accept.\n\n## Three spellings, one pipeline\n\nThe same managed async pipeline has three inbound spellings. Which one you pick depends only on whose payload style you want to write your client against:\n\n| Entry point | Request body | Response body |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | Generic generation shape | Ark task object (above) |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark content-generation native body | Ark task object |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax video-generation V2 native body | MiniMax shapes (`{\"task_id\"}` / `{\"task\":{…}}`) |\n\nBilling, task persistence, artifact delivery, and preauthorize/settle behave identically across all three.\n\n## When to use it\n\n- The platform capability is asynchronous but does not use the OpenAI Video-standard request / response shape\n- You want a unified platform-managed create-and-poll flow instead of handling each vendor's native protocol yourself\n- You are calling a video model such as Jimeng that is exposed only through the managed async lane\n\n## Key conventions\n\n- `model` is still the platform logical model name; the platform decides which upstream implementation handles the task.\n- Request fields depend on the routed capability; the response shape, by contrast, is fixed — see above.\n- If you do not want to manage multiple vendor-specific polling styles, prefer this entrypoint.\n\nFor the standard OpenAI-compatible video protocol, see [OpenAI-Compatible Video Flow](./openai-compatible).\n","international/en/models/video/minimax.md":"---\ntitle: MiniMax Video\ndescription: Drive platform-managed async video tasks with MiniMax video-generation V2 request and response bodies, for the MiniMax-H3 family.\n---\n\n# MiniMax Video\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | Create a video generation task |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | Poll task status and result |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | Cancel an unfinished task and release its preauthorization |\n\nThis is **MiniMax video generation V2** as an inbound protocol, aimed mainly at the MiniMax-H3 family.\nLike the Ark lane it runs on the platform-managed async pipeline — the request body is MiniMax's own\nshape, and **the responses are rendered in MiniMax's shape too**, so a client written against\nMiniMax's own documentation can decode this surface directly.\n\nThe task lives on the platform, so per-dimension metering, artifact\ndelivery, and preauthorize/settle all apply as usual.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"a boy playing basketball by the sea\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\nCreate answers the bare task handle from MiniMax's documentation:\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### Request fields\n\n`content[]` is a multimodal array; `type` and `role` together decide what each part is:\n\n| `type` | Valid `role` | Meaning |\n| --- | --- | --- |\n| `text` | — | Prompt |\n| `image_url` | `first_frame` / `last_frame` | First / last frame image |\n| `image_url` | `reference_image` | Reference image |\n| `video_url` | `reference_video` | Reference video |\n| `audio_url` | `reference_audio` | Reference audio |\n\n- **Frames and references cannot be mixed**: a request carrying `first_frame` / `last_frame` may not\n  also carry any `reference_*` part, and vice versa — they map to two different upstream jobs.\n- `resolution`, `duration`, and `ratio` are flat siblings of `content`. For MiniMax-H3 the accepted\n  values are `resolution` ∈ `768P` / `2K`, `duration` an integer in `4`–`15`, and `ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`. Omitting one applies the upstream default\n  (`2K`, 5 seconds) — **and bills at that default tier**.\n- Prompt length is capped at roughly 7000 characters.\n- Which values are actually supported still depends on the logical model behind `model`.\n\n## Poll a task\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nPoll answers a `task` envelope — a **different shape** from create:\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` is one of `queued` / `running` / `succeeded` / `failed`.\n- On success the artifact URL is in `task.content.url`.\n- `usage` is denominated in **seconds** (H3 is quoted per second of output), not tokens; it is\n  omitted when the upstream reports only token counts and no seconds.\n- On failure a `task.error` (`code` / `message`) is added. That field is not part of MiniMax's\n  documented success schema — it is included so a failure reason is visible at all, and a client\n  decoding the documented struct simply ignores it.\n\n## Cancel a task\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nCancelling voids the preauthorization. Note that this lane never reports MiniMax's documented\n`cancelled` status — a cancelled task is surfaced as `failed`, which is what makes its\npreauthorization be released rather than settled.\n\n## Key conventions\n\n- **`id` / `task_id` are the gateway task id**, not the upstream one; polling and cancelling only\n  accept that id.\n- The lane does not pin an upstream family; the logical model behind `model` decides who serves the\n  request, and the URL spelling plays no part in it.\n- The only content endpoint is the OpenAI-compatible one (`GET /v1/videos/{task_id}/content`); there\n  is no equivalent under the MiniMax paths.\n\nFor the most standardized experience, use [OpenAI-Compatible Video Flow](./openai-compatible).\n","international/en/models/video/openai-compatible.md":"---\ntitle: OpenAI-Compatible Video Flow\ndescription: Standard OpenAI Video-compatible endpoints for task creation, polling, and asset retrieval.\n---\n\n# OpenAI-Compatible Video Flow\n\n| Method | Path | Use |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | Create an OpenAI-compatible video task |\n| `GET` | `/v1/videos/{task_id}` | Poll video task status and result |\n| `GET` | `/v1/videos/{task_id}/content` | Fetch the produced content of a finished video task |\n\nThis set of endpoints is the platform's **standard video protocol**: the request uses OpenAI Video-compatible fields, and the platform translates it into the upstream vendor's async video task format.\n\n## Create a task\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\nA successful create returns a `task_id`. Subsequent polling and content fetches are all keyed by that `task_id`.\n\n## Poll task status\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` is one of `queued` / `in_progress` / `completed` / `failed`; on `completed`, the produced asset URL appears in `metadata.url`.\n\n## Fetch the asset\n\nOnce the task is done, you can fetch the asset bytes through the content endpoint. The gateway **streams the `video/mp4` bytes directly** (no `302` redirect to object storage), supports `Range` requests, and only the API key that owns the task (or a console session in the same tenant) may read it:\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\nContent availability depends on the backend \"media delivery\" setting:\n\n- `404` (`content_delivery_disabled`) when delivery is disabled\n- `409` (`task_not_completed`) when the task is still running\n- `404` (`content_not_available`) when the asset has expired or is missing\n\n## Key conventions\n\n- This is the standard OpenAI-compatible video entrypoint; clients do not need to understand vendor-native protocols.\n- Whether fields such as `duration` or `size` are supported, and which upstream vendor is selected, depends on the logical model referenced by `model`.\n- Video generation is asynchronous. Poll with backoff to avoid unnecessary rate-limit pressure.\n\nFor the more generic async task entrypoint, see [Generic Async Content Generation Tasks](./async-tasks). To write against a vendor's own payload style while keeping platform-managed billing and task handling, see the [Seedance Video Inbound Protocol](./ark) and the [MiniMax Video Inbound Protocol](./minimax).\n","international/en/quickstart/agent-clients.md":"---\ntitle: AI Tool Setup\ndescription: Choose an AI client or Agent and use it with ModelGo models.\n---\n\n# AI Tool Setup\n\nModelGo supports common AI coding clients and Agents. After you create an API key, use the official configuration tool for one-click setup; clients not covered by that tool can be configured manually through a custom provider.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\nSelect one or more tools when prompted. To configure every supported tool in an automated workflow, use:\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n## Supported AI tools\n\n:::agent-tools\n| Tool | Official config tool | Manual setup docs |\n| --- | --- | --- |\n| Hermes Agent | Supported | [Setup guide](../agents/hermes-agent) |\n| Claude Code | Supported | [Setup guide](../agents/claude-code) |\n| Kilo Code | Not supported | [Setup guide](../agents/kilo-code) |\n| Cline | Not supported | [Setup guide](../agents/cline) |\n| Codex | Supported | [Setup guide](../agents/codex) |\n| OpenClaw | Supported | [Setup guide](../agents/openclaw) |\n| DeepSeek Harness | Not supported | [Setup guide](../agents/deepseek-harness) |\n| ZCode | Not supported | [Setup guide](../agents/zcode) |\n| Cursor | Not supported | [Setup guide](../agents/cursor) |\n| OpenCode | Supported | [Setup guide](../agents/opencode) |\n| CC Switch | Supported | [Setup guide](../agents/cc-switch) |\n| Cherry Studio | Not supported | [Setup guide](../agents/cherry-studio) |\n| Crush | Supported | [Setup guide](../agents/crush) |\n| Factory Droid | Supported | [Setup guide](../agents/factory-droid) |\n| Copilot CLI | Supported | [Setup guide](../agents/copilot-cli) |\n| nanobot | Supported | [Setup guide](../agents/nanobot) |\n| Oh My Pi | Supported | [Setup guide](../agents/oh-my-pi) |\n| CodeBuddy | Supported | [Setup guide](../agents/codebuddy) |\n| Kilo CLI | Not supported | [Setup guide](../agents/kilo-cli) |\n:::\n\n## Before you connect\n\n1. Create an API key in the [console]({{ console_endpoint }}/api-keys).\n2. Run the command above and select the clients or Agents you want to configure.\n3. Confirm the site, Base URL, and masked API key when prompted. The configuration tool verifies the connection automatically.\n\nTo manage your ModelGo account, models, calls, and Skills from the terminal, continue to [CLI Tools](cli).\n\n## Integration guide\n\nMost tools only need the following information to connect to ModelGo:\n\n1. **API address**: Use `{{ api_endpoint }}/v1` for OpenAI-compatible APIs, or `{{ api_endpoint }}` for Anthropic-compatible APIs.\n2. **API key**: The token created in [ModelGo Console]({{ console_endpoint }}/api-keys).\n3. **Model name**: The logical model ID selected from the [Model Catalog]({{ site_endpoint }}/models).\n\nSee the setup guide for each tool above for the exact configuration steps.\n","international/en/quickstart/authentication.md":"---\ntitle: Authentication\ndescription: API key handling, supported headers, precedence, and common auth failures.\n---\n\n# Authentication\n\nAll model endpoints authenticate with an API key.\n\n## Recommended header\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic-style clients may also use:\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini-style clients may also use:\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nWhen several are present, precedence is `Authorization` > `x-api-key` > `x-goog-api-key`.\n\n## Get & manage\n\n- Console: `{{ console_endpoint }}`\n- An API key is shown in full only once, at creation time\n- Revoking or disabling a key takes effect after the auth cache expires\n\n## Common failures\n\n| HTTP | error_class | Meaning |\n| --- | --- | --- |\n| `401` | `auth` | Missing, invalid, disabled, or expired API key |\n| `403` | `policy` | Key is valid but not allowed to call the model |\n\nSee [Errors & Rate Limits](errors) for the unified error shape.\n","international/en/quickstart/cli.md":"---\ntitle: CLI Tools\ndescription: Choose the official command-line tool for your task and complete your ModelGo setup.\n---\n\n# CLI Tools\n\nModelGo provides two official command-line tools. Choose the task you want to complete and run the corresponding command.\n\n:::tools\n@model-go/config | Connect AI coding clients | Configure Claude Code, Codex, and other common clients with one command. | npx @model-go/config -r {{ region_flag }} | View npm package | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | Use the official CLI | Pair it with official ModelGo Skills so an AI agent can operate ModelGo directly. | npx @model-go/cli@latest install | View npm package | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## Connect AI coding clients `@model-go/config` {#connect-ai-clients}\n\nTo use ModelGo in Claude Code, Codex, OpenCode, or another supported AI coding client, choose guided setup or configure all clients with a single command.\n\n**Guided setup**\n\nFollow the terminal prompts to enter your API key, select clients, review the configuration, and verify connectivity after the changes are written.\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**One-command setup (non-interactive, suitable for automation)**\n\n```bash\nnpx @model-go/config -k sk-your-token -r {{ region_flag }} --only all\n```\n\n### Supported clients\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\nGuided setup lets you select one or more clients; use `--only all` to configure every supported client at once.\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Enter your [ModelGo API key]({{ console_endpoint }}/api-keys). |\n| `02` | Select one or more clients, or choose “Configure all.” |\n| `03` | Review the site, Base URL, masked API key, and selected clients. |\n| `04` | Confirm the changes, write the client configuration, and verify connectivity. |\n\n> **Setup succeeded:** the terminal reports that configuration is complete and the connectivity check passes, then shows how to start the selected client.\n\n[View @model-go/config on npm](https://www.npmjs.com/package/@model-go/config)\n\n## Let an AI agent operate ModelGo `@model-go/cli` {#install-agent-tools}\n\nInstall the official CLI and ModelGo Skills when you want an agent such as Claude Code or Codex to use ModelGo directly. The installer sets up the CLI, distributes Skills, selects the site, and optionally signs you in.\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### What happens next\n\n| Step | Prompt |\n| --- | --- |\n| `01` | Confirm installation of `@model-go/cli` when npm asks. |\n| `02` | Choose Simplified Chinese or English. The rest of the installation prompts will use your selected language. |\n| `03` | Install or upgrade the ModelGo CLI and install ModelGo Skills. |\n| `04` | Select the environment for this site (`{{ api_endpoint }}`). |\n| `05` | Choose whether to sign in through the browser now, or skip and run `modelgo auth login` later. |\n\n### Using the CLI after installation\n\nAfter installation, restart your AI agent or open a new session. ModelGo Skills lets the agent call the ModelGo CLI directly to perform queries and operations, so you can ask in natural language, for example:\n\n- “Which models does ModelGo currently support?”\n- “What is my current ModelGo account balance?”\n\nTo use the CLI yourself, run `modelgo` in your terminal to see every available command and option:\n\n```bash\nmodelgo\n```\n\nThe most common commands are grouped by task:\n\n| Task | Common commands | What they do |\n| --- | --- | --- |\n| Authentication | `modelgo auth login`, `modelgo auth status`, `modelgo auth logout` | Sign in to ModelGo, inspect the current authentication state, or clear local credentials. |\n| Environments | `modelgo env list`, `modelgo env current`, `modelgo env use <name>` | List environments, show the active environment, or switch sites. Use `env add` and `env remove` to manage custom environments. |\n| Workspaces | `modelgo tenant list`, `modelgo tenant use <slug>` | List the workspaces available to your account and use a workspace slug or ID to select the workspace for subsequent CLI commands. |\n| Account and usage | `modelgo balance`, `modelgo permissions`, `modelgo logs` | View balances and transactions, account permissions, call logs, and usage statistics. |\n| Model calls | `modelgo models`, `modelgo chat`, `modelgo embeddings`, `modelgo call` | List available models, make chat or embedding requests, or call any `/v1/*` model endpoint directly. |\n| Keys and payments | `modelgo key`, `modelgo pay` | Manage the model API key stored for the active environment or configure x402 pay-per-call payments. |\n| CLI maintenance | `modelgo update`, `modelgo --version`, `modelgo --help` | Update the CLI, print its version, or reopen the complete help output. |\n\nRun `modelgo <command> --help` to inspect the options for a specific command. For `balance`, `permissions`, and `logs`, you can also use the global `--tenant <slug\\|id>` option to target a workspace for that command only.\n\n[View @model-go/cli on npm](https://www.npmjs.com/package/@model-go/cli)\n\n:::note Security\n- Prefer the interactive API-key prompt instead of putting a key directly in a command.\n- Never commit an API key to source control or paste it into a shared script.\n- If you skipped login during CLI installation, run `modelgo auth login` later.\n:::\n\n## Continue exploring\n\n- [First API Call](quickstart): make your first model call.\n- [Authentication](authentication): learn how to use and protect your API key.\n","international/en/quickstart/errors.md":"---\ntitle: Errors & Rate Limits\ndescription: Unified error shape, common categories, and rate-limit handling.\n---\n\n# Errors & Rate Limits\n\n## Error shape\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\nBesides the `error` object, the body carries a top-level `trace_id` field (matching the `X-Trace-ID` response header; omitted when tracing is disabled) so you can grep logs by it. `metadata.reason` is an optional subtype (for example `model_not_in_catalog`). Full catalog and verified examples: [API catalog](openapi).\n\n## Common categories\n\n| error_class | HTTP | Meaning |\n| --- | --- | --- |\n| `client_invalid` | 400 | Bad request shape or parameters |\n| `model_protocol_not_offered` | 400 | The logical model does not declare this inbound protocol (`app_error_id=4005`). Switch endpoint or model |\n| `provider_invalid` | 400 | Upstream rejected the request (upstream returned a 4xx other than 401/403/408/429) |\n| `provider_unsupported` | 400 | The upstream does not support this endpoint (for example some video models reject `DELETE` cancel) |\n| `provider_timeout` | 408 | Upstream request timed out |\n| `auth` | 401 | API key authentication failed |\n| `billing_insufficient` | 402 | Insufficient balance |\n| `policy` | 403 | Model not allowed or no policy bound |\n| `quota` | 429 | Platform quota or limit hit |\n| `provider_rate_limit` | 429 | Upstream rate limit (upstream returned 429) |\n| `gateway_internal` | 500 | Gateway internal error (catch-all) |\n| `billing_system` | 502 | Billing system unavailable |\n| `provider_server` | 502 | Upstream server error |\n| `provider_unauthorized` | 502 | Upstream credential rejected (bucketed as 5xx; upstream-key issues are not exposed to callers) |\n| `provider_unavailable` | 503 | No available provider |\n| `route_unconfigured` | 503 | Model route has no upstream configured |\n\n## Billing of failed requests\n\n- Pre-authorization: every accepted request freezes balance based on an estimate; after the request ends it is settled by actual usage and any excess is released immediately.\n- Successful requests, and streaming requests that already delivered content, are settled by the usage actually returned.\n- **Requests that were dispatched to the upstream provider but ultimately failed** (upstream 4xx/5xx, upstream timeout, mid-stream disconnect, or the client closing the connection while waiting for the response) are settled at the pre-authorized amount and are not refunded. The upstream provider has already incurred cost for such requests; the platform bears it at the pre-authorized figure and bills the caller accordingly.\n- Requests rejected before reaching an upstream provider (validation, authentication, policy, quota, insufficient balance, gateway internal errors) release the full pre-authorization and incur no charge.\n- The settlement basis is visible in the console's usage transactions; records settled at the pre-authorized amount carry the failure reason.\n\n## Troubleshooting\n\n- Keep `X-Request-ID` and `X-Trace-ID` from the response headers; the error body also carries a top-level `trace_id` with the same value.\n- On `429`, honor the `Retry-After` response header and back off exponentially (the platform sets it when a platform rate limit is hit).\n- If a streaming response delivers a chunk with an `error` field, treat it as a failure (such a mid-stream break maps to `provider_stream_broken` and is not returned as a separate HTTP status).\n\nFor endpoint details see:\n\n- [Text Generation](../models/text/generation)\n- [Image Generation](../models/images/generations)\n- [OpenAI-Compatible Video Flow](../models/video/openai-compatible)\n- [Generic Async Content Generation Tasks](../models/video/async-tasks)\n- [Seedance Video Inbound Protocol](../models/video/ark)\n- [MiniMax Video Inbound Protocol](../models/video/minimax)\n","international/en/quickstart/openapi.md":"---\ntitle: API catalog\ndescription: Full customer-facing OpenAPI list, auth, protocol matching, and verified examples.\n---\n\n# API catalog\n\nThis page lists the public model-calling HTTP APIs (`mgk_` API Key, gateway `{{ api_endpoint }}`).\n\n## Before you call\n\n1. Create an API key (`mgk_`) at `{{ console_endpoint }}`. The full secret is shown once.\n2. `export MODELGO_API_KEY=\"your-key\"`.\n3. Call `GET /v1/models` for logical model names.\n4. A model only accepts endpoints listed in its `public_protocols`. Hitting any other path returns HTTP 400, `error_class=model_protocol_not_offered` (`app_error_id=4005`).\n\n## Auth\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic clients may send `x-api-key`; Gemini clients may send `x-goog-api-key`. Priority: `Authorization` > `x-api-key` > `x-goog-api-key`. See [Authentication](authentication).\n\nMissing or invalid key (HTTP 401):\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\nKeep `X-Request-ID`, `X-Trace-ID`, and body `trace_id`.\n\n## Protocol matching\n\n| Model | Endpoint | Result |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`, `POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`, `POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations` with `size` ≥ ~1920×1920 | 200 |\n\n## Catalog\n\n**Public** means the gateway mounts the route. Whether a given model accepts it still depends on `public_protocols` and the key's policy.\n\n### Text and model list\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | Public | Logical models allowed for this key |\n| `POST` | `/v1/responses` | Public | OpenAI Responses (preferred) |\n| `POST` | `/v1/chat/completions` | Public | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | Public | Legacy; most chat models do not offer it |\n| `POST` | `/v1/messages` | Public | Anthropic Messages |\n\n### Vectors / images / audio / rerank\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | Public | Text embeddings |\n| `POST` | `/v1/embeddings/multimodal` | Public | Needs a multimodal-embedding protocol |\n| `POST` | `/v1/images/generations` | Public | Image generation |\n| `POST` | `/v1/images/edits` | Public | Multipart image edits |\n| `POST` | `/v1/audio/speech` | Public | OpenAI TTS; not every speech model offers it |\n| `POST` | `/minimax/v1/t2a_v2` | Public | MiniMax native TTS; see [MiniMax audio inbound](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | Public | Multipart STT |\n| `POST` | `/v1/audio/translations` | Public | Multipart translation |\n| `POST` | `/v1/rerank` | Public | Rerank |\n| `POST` | `/v1/reranks` | Public / alias | Same as `/v1/rerank` |\n\n### Managed async video\n\n| Method | Path | Status | Notes |\n| --- | --- | --- | --- |\n| `POST`/`GET`/`DELETE` | `/v1/content_generation/tasks` and `.../{task_id}` | Public | Generic async tasks |\n| `POST`/`GET`/`DELETE` | `/ark/api/v3/contents/generations/tasks` and `.../{task_id}` | Public | Same pipeline, Ark spelling |\n| `POST`/`GET`/`DELETE` | `/minimax/v2/video_generation` and `.../{task_id}` | Public | MiniMax video V2; pricing dimensions required |\n| `POST`/`GET`/`DELETE` | `/v1/video/generations`, `/v1/videos/{task_id}`, `/v1/videos/{task_id}/content` | Public | OpenAI-compatible video; model must offer it |\n\nCancel (`DELETE`) may return `provider_unsupported` if the upstream has no cancel API.\n\n## Verified calls\n\nList models:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nChat Completions:\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":64}'\n```\n\nEmpty `{}` → HTTP 400 `client_invalid`. Unknown model → HTTP 403 `policy` / `model_not_in_catalog`.\n\nResponses: `POST /v1/responses` with `input` + `max_output_tokens`. Messages: `POST /v1/messages` with `x-api-key` and `max_tokens`. The Messages response `model` field may be an upstream id, not the logical name.\n\nEmbeddings: `text-embedding-3-small` returned 1536-d vectors.\n\nImages: `doubao-seedream-5.0-lite` rejects `1024x1024` (`provider_invalid`, min 3686400 pixels). `2048x2048` succeeded.\n\nSpeech: use [MiniMax audio inbound](../models/audio/minimax) for `speech-2.8-*`.\n\nVideo: Seedance uses `/v1/content_generation/tasks` (create returns `{\"id\",\"model\",\"status\":\"queued\"}`; poll later returns `status=succeeded`, plus `resolution` / `ratio` / `duration`). `/v1/video/generations` is `model_protocol_not_offered` for `doubao-seedance-2.0-mini`.\n\n## Streaming\n\nSet `stream: true`. OpenAI-shaped endpoints use `text/event-stream` frames `data: {json}` ending with `data: [DONE]`. `/v1/messages` keeps native Anthropic `event:` frames. A chunk with `error` is a failure even if HTTP status was 200.\n\n## Limits\n\n- Rate limits: HTTP 429 (`quota` or `provider_rate_limit`); honor `Retry-After`.\n- No client idempotency key on sync calls. Each async POST creates a new task; poll by returned `id`.\n- No pagination on this surface; `GET /v1/models` returns the full list for the key.\n\nSee [Errors](errors), [Text generation](../models/text/generation), [MiniMax audio inbound](../models/audio/minimax), [Async tasks](../models/video/async-tasks).\n","international/en/quickstart/overview.md":"---\ntitle: Overview\ndescription: Learn about ModelGo's unified model API, compatible protocols, model capabilities, and production call management.\n---\n\n# Overview\n\n## ModelGo Overview\n\nModelGo is a production-ready AI model gateway. With one API key and a unified API, you can call text, image, video, audio, embedding, and reranking models without maintaining separate integrations for each model.\n\nWhether you are evaluating models, building AI features, or taking model calls to production, you can use the same development workflow and manage permissions, usage, logs, and security policies in one platform.\n\n## One API for Multiple Models\n\nModelGo brings different model capabilities into a single development workflow. Choose the capability that fits your use case, then open the detailed documentation for endpoints, parameters, and request examples.\n\n| Model category | Capabilities | Documentation |\n| --- | --- | --- |\n| Text | Conversations, content generation, reasoning, and tool use | [Text Generation](../models/text/generation) |\n| Images | Generate images from text or edit existing images | [Image Generation](../models/images/generations) · [Image Edits](../models/images/edits) |\n| Video | Generate videos and track progress and results through async tasks | [Standard Video API](../models/video/openai-compatible) · [Async Tasks](../models/video/async-tasks) |\n| Embeddings | Generate text or multimodal embeddings for semantic search and RAG | [Embeddings](../models/vectors/embeddings) |\n| Audio | Text to speech, speech to text, and speech translation | [Speech](../models/audio/speech) · [MiniMax Audio](../models/audio/minimax) · [Transcriptions](../models/audio/transcriptions) · [Translations](../models/audio/translations) |\n| Rerank | Reorder candidate results to improve retrieval quality in search and RAG | [Rerank](../models/rerank/rerank) |\n\nYou can also browse available models in the Model Catalog, test them in the Model Playground, or call `GET /v1/models` to list the models available to the current API key.\n\n## Use Familiar Protocols and Tools\n\nModelGo supports both OpenAI and Anthropic text protocols. If your project already uses their SDKs or compatible clients, you can usually keep your existing integration and replace only the Base URL and API key.\n\nChoose the Base URL that matches your client protocol:\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\nAll requests use the same ModelGo API key for authentication. Create an API key in the [console]({{ console_endpoint }}), then see [Authentication](authentication) for request headers and security guidance.\n\n## Built for Production Calls\n\nModelGo provides the controls needed when model calls move into production, not just a unified endpoint:\n\n- **Reliable calls**: Handle routing and failover at the gateway layer to reduce the impact of a single path failure.\n- **Permissions and security**: Define access through workspaces, members, and API keys, with controls for budgets, available models, and request sources.\n- **Usage and cost**: Review request counts, token usage, and spend by time, workspace, model, member, and API key.\n- **Call tracing**: Use request IDs, status, latency, and error details to troubleshoot synchronous calls and asynchronous tasks.\n\n## Get Started\n\nIf this is your first ModelGo integration, follow these steps:\n\n- [First API Call](quickstart): Create an API key and make your first model call.\n- [API catalog](openapi): Full public path list, protocol matching, and verified examples.\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See examples for Responses, Chat Completions, and Anthropic Messages.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n\n:::note Before you start\n- The `model` request field must use a ModelGo logical model name, not an upstream provider's raw model ID.\n- `GET /v1/models` lists the logical models available to the current API key. Its response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative.\n- Streaming text responses use SSE and end with `data: [DONE]`.\n- Video and other asynchronous generation endpoints return a `task_id`; use it to query task progress and results.\n- Keep the response's `X-Request-ID` when troubleshooting a call so the request can be traced.\n:::\n","international/en/quickstart/quickstart.md":"---\ntitle: First API Call\ndescription: Create an API key, choose a model, and make your first request with the Responses API.\n---\n\n# First API Call\n\nYou can reuse an existing OpenAI or Anthropic SDK with ModelGo, or follow the three steps below to make your first request with the Responses API.\n\n## Connect with standard protocols\n\nModelGo supports both OpenAI and Anthropic standard protocols. If your project already uses either SDK, you can usually keep the existing integration and replace only the Base URL and API key.\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## Make your first API call in three steps\n\nIf this is your first ModelGo integration, complete these three steps to send a request and receive a generated result.\n\n### 1. Create an API key\n\n- Sign in to the [console]({{ console_endpoint }}).\n- Open the API Keys page and create a new API key.\n- Store it in an environment variable instead of placing it directly in your code:\n\n```bash\nexport MODELGO_API_KEY=\"your-api-key\"\n```\n\n### 2. Choose a model\n\nThe `model` request field must use a ModelGo logical model name. Browse models in the [Model Catalog]({{ site_endpoint }}/models) or use the following request to list the logical models available to the current API key:\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\nThe response is derived from the platform model catalog and API key policy, not a live probe of upstream capabilities; treat the console model page and policy configuration as authoritative. Choose a model name and replace `<model>` in the next step.\n\n### 3. Send your first request\n\nWe recommend starting with `POST /v1/responses`. Run the example in your preferred language:\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"Introduce ModelGo in three sentences.\"\n  }'\n```\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"Introduce ModelGo in three sentences.\",\n)\n\nprint(response.output_text)\n```\n\nA successful request returns the model-generated result. With the Python SDK, read the generated text from `response.output_text`.\n\n## Use other compatible protocols\n\nIf your project already uses another compatible interface, you can keep its existing request shape:\n\n- [Use Chat Completions](../models/text/generation#chat-completions): For existing OpenAI Chat Completions integrations.\n- [Use Anthropic Messages](../models/text/generation#anthropic-messages): For existing Claude SDK or Anthropic Messages integrations.\n\n## Continue exploring\n\n- [Authentication](authentication): Learn how to use API keys safely.\n- [Text Generation](../models/text/generation): See the complete Responses, Chat Completions, and Anthropic Messages documentation.\n- [Errors & Rate Limits](errors): Understand error responses, rate limits, and troubleshooting.\n","international/zh/agents/cc-switch.md":"---\ntitle: CC Switch\ndescription: 使用 ModelGo 配置 CC Switch 和 Claude Code。\n---\n\n# CC Switch\n\nCC Switch 是桌面端配置管理工具，可以统一管理 Claude Code、Codex、Gemini、OpenCode、OpenClaw 等工具的 Provider。下面以 Claude Code 为例，将 ModelGo 添加到 CC Switch 并启用。\n\n## 接入前准备\n\n- 已安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)，并能正常打开。\n- 已安装 Claude Code，并至少启动过一次。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 打开 Claude Code 配置\n\n打开 CC Switch，在顶部选择 **Claude**，点击右侧的 **+** 新增配置。\n\n![CC Switch 主界面](/images/agents/cc-switch/overview.webp)\n\n![在 CC Switch 中添加 Claude 配置](/images/agents/cc-switch/claude-add.webp)\n\n## 2. 添加 ModelGo Provider\n\n在配置编辑器中粘贴下面的 JSON。将 `你的模型名` 替换为模型广场中的逻辑模型名，将 `sk-你的token` 替换为 ModelGo API Key：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"sk-你的token\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": 1,\n    \"API_TIMEOUT_MS\": 600000,\n    \"ANTHROPIC_MODEL\": \"你的模型名\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"你的模型名\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n![在 CC Switch 中编辑 ModelGo 配置](/images/agents/cc-switch/config-global.webp)\n\n如果你的 CC Switch 版本支持环境变量占位符，可以将 Token 改为 `{env:MODELGO_API_KEY}`，并在启动 Claude Code 的终端中设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | ModelGo 控制台创建的 API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | 模型广场中的逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的逻辑模型名 |\n\n:::note\n- Anthropic Base URL 填写 ModelGo 根地址，不要追加 `/v1/messages`；Claude Code 会自动请求 `/v1/messages`。\n- API Key 只保存在本机 CC Switch 配置或环境变量中，不要提交到代码仓库。\n- CC Switch 的 Provider 名称可以填写 `ModelGo`，方便后续识别和切换。\n:::\n\n## 3. 保存并启用\n\n填写 Provider 名称 **ModelGo** 后点击 **Add** 或 **Save**。回到 Claude 配置列表，选中 ModelGo 配置并启用。\n\n![在 CC Switch 中添加 ModelGo Provider](/images/agents/cc-switch/provider-global.webp)\n\n![在 CC Switch 中启用 ModelGo 配置](/images/agents/cc-switch/use-global.webp)\n\n启动 Claude Code：\n\n```bash\nclaude\n```\n\n输入一条简单任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n## 4. 验证配置\n\n如果需要单独验证 API Key 和模型，可执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回结果中的 `id` 即可作为 `ANTHROPIC_MODEL` 和 `ANTHROPIC_SMALL_FAST_MODEL` 的逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 Token 是有效的 ModelGo API Key，且当前 CC Switch 配置没有残留的旧 Token。复制 Token 时不要带空格或换行。\n\n### 返回 404 或找不到接口\n\n确认 `ANTHROPIC_BASE_URL` 为 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages` 或完整请求路径。\n\n### 模型不可用\n\n确认模型名与[模型广场]({{ site_endpoint }}/models)中的逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n### 修改后 Claude Code 仍使用旧配置\n\n在 CC Switch 中确认 ModelGo 配置已启用，然后完全退出并重新打开终端，再运行 `claude`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [CC Switch 官方快速开始](https://cc-switch.cc/docs/getting-started/quick-start/)：了解界面和配置切换流程。\n- [CC Switch Provider 配置教程](https://cc-switch.cc/en/tutorials/provider-setup)：了解自定义 Provider 字段和凭据管理。\n","international/zh/agents/cherry-studio.md":"---\ntitle: Cherry Studio\ndescription: 通过自定义服务商将 Cherry Studio 接入 ModelGo 国际站。\n---\n\n# Cherry Studio\n\nCherry Studio 已内置多个官方服务商，但 ModelGo 不在预置列表中。请使用“自定义服务商”创建一个 ModelGo Provider，再获取并添加模型。ModelGo 同时提供 OpenAI 兼容接口和 Anthropic 兼容接口，可按使用场景选择。\n\n## 接入前准备\n\n- 已安装 Cherry Studio，并能打开设置页面。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的逻辑模型名。\n\n## 1. 打开模型服务设置\n\n打开 Cherry Studio 的“设置”，进入“模型服务”，点击左侧底部的“+ 添加服务商”。\n\n![在 Cherry Studio 中打开添加服务商](/images/agents/cherry-studio/add-provider.webp)\n\n## 2. 添加自定义服务商\n\n在“添加自定义提供商”窗口中填写：\n\n| 配置项 | ModelGo 国际站填写内容 |\n| --- | --- |\n| 提供商名称 | `ModelGo` |\n| API 密钥 | ModelGo 控制台创建的 API Key |\n| OpenAI 地址 | `{{ api_endpoint }}/v1` |\n| Anthropic 地址 | `{{ api_endpoint }}`（仅在使用 Anthropic 兼容模型或 Agent 模式时填写） |\n\n点击“添加”保存。OpenAI 地址用于普通聊天和模型列表；Anthropic 地址不要追加 `/v1`，Cherry Studio 会按协议补全请求路径。\n\n![添加 ModelGo 自定义提供商](/images/agents/cherry-studio/custom-provider-global.webp)\n\n:::note\n- 不要把完整的 `/chat/completions` 或 `/messages` 写进地址。\n- OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`，Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n:::\n\n## 3. 获取并添加模型\n\n回到 ModelGo 服务商页面，点击“获取模型列表”。Cherry Studio 会从 ModelGo 的模型接口读取当前 API Key 可用的逻辑模型。\n\n![在 Cherry Studio 中获取 ModelGo 模型列表](/images/agents/cherry-studio/fetch-models-global.webp)\n\n模型列表弹窗打开后，可以按需点击单个模型右侧的“+”，也可以点击“添加全部模型”。\n\n![在 Cherry Studio 中添加全部 ModelGo 模型](/images/agents/cherry-studio/model-picker.webp)\n\n添加完成后，模型会出现在 ModelGo 服务商的模型区域。只添加自己需要的模型可以让选择器更简洁。\n\n![ModelGo 服务商中的模型列表](/images/agents/cherry-studio/model-list-global.webp)\n\n## 4. 启用并开始对话\n\n在 ModelGo 服务商右上角打开开关，确认 API 密钥检测通过。新建对话时选择 **ModelGo** 及刚添加的模型，然后发送一条简单消息验证调用。\n\n如果只使用 OpenAI 兼容模型，保留 OpenAI 地址即可；使用 Claude 等 Anthropic 兼容模型或 Cherry Studio Agent 模式时，再配置 Anthropic 地址并添加对应模型。\n\n## 验证配置\n\n可以在终端检查 API Key 是否能读取模型列表：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是 Cherry Studio 中应添加的 ModelGo 逻辑模型名。\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认服务商右上角开关已打开。\n\n### 返回 404 或接口路径错误\n\nOpenAI 地址应为 `{{ api_endpoint }}/v1`，Anthropic 地址应为 `{{ api_endpoint }}`。不要填写完整的 `/v1/chat/completions` 或 `/v1/messages`。\n\n### 获取模型列表为空\n\n先用上面的 `curl` 验证 `/v1/models`，再确认模型已在模型广场开通。获取列表后还要点击模型右侧的“+”或“添加全部模型”，仅获取列表不会自动加入选择器。\n\n### Agent 模式无法调用\n\n确认已填写 Anthropic 地址 `{{ api_endpoint }}`，并添加支持 Anthropic 兼容协议的模型。普通 OpenAI 兼容聊天不需要填写该地址。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cherry Studio 自定义服务商文档](https://docs.cherry-studio-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang)：查看官方的自定义服务商流程。\n- [Cherry Studio Provider 设置说明](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/cherry-studio/preview/settings/providers)：了解 Base URL、模型管理和连通性检测规则。\n","international/zh/agents/claude-code.md":"---\ntitle: Claude Code\ndescription: 使用 ModelGo 的 Anthropic 兼容接口配置 Claude Code。\n---\n\n# Claude Code\n\nClaude Code 是运行在终端中的 AI 编程助手。通过配置 Anthropic 兼容接口，你可以让 Claude Code 使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 Node.js。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Claude Code\n\n在终端执行：\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n安装完成后检查版本：\n\n```bash\nclaude --version\n```\n\n## 2. 配置 ModelGo\n\n### macOS / Linux\n\n创建并编辑 Claude Code 配置文件：\n\n```bash\nmkdir -p ~/.claude\n$EDITOR ~/.claude/settings.json\n```\n\n### Windows\n\n在 PowerShell 中执行：\n\n```powershell\nmkdir $env:USERPROFILE\\.claude\nnotepad $env:USERPROFILE\\.claude\\settings.json\n```\n\n将下面内容写入 `settings.json`。把 `YOUR_MODELGO_API_KEY` 和 `YOUR_MODELGO_MODEL` 替换为真实的 ModelGo API Key 与逻辑模型名：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_MODELGO_API_KEY\",\n    \"ANTHROPIC_BASE_URL\": \"{{ api_endpoint }}\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"API_TIMEOUT_MS\": \"600000\",\n    \"ANTHROPIC_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_SMALL_FAST_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"YOUR_MODELGO_MODEL\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"YOUR_MODELGO_MODEL\"\n  },\n  \"permissions\": {\n    \"allow\": [],\n    \"deny\": []\n  }\n}\n```\n\n`ANTHROPIC_BASE_URL` 填写 ModelGo 的根地址，不要追加 `/v1/messages`。Claude Code 会自动请求 ModelGo 的 `POST /v1/messages` 接口。\n\n:::note\n- 如果你只使用一个模型，建议将五个模型变量都设置为同一个 ModelGo 逻辑模型名，避免辅助模型未授权导致启动失败。\n- API Key 仅写入本机配置，不要将 `settings.json` 提交到代码仓库或分享给他人。\n:::\n\n## 3. 可选：跳过官方账号初始化\n\n如果首次输入 `claude` 时卡在官方账号登录引导，可以在用户目录创建 `.claude.json`，写入已完成初始化标识。\n\nmacOS / Linux：\n\n```bash\nprintf '%s\\n' '{\"hasCompletedOnboarding\": true}' > ~/.claude.json\n```\n\nWindows PowerShell：\n\n```powershell\n'{\"hasCompletedOnboarding\": true}' | Set-Content -Encoding utf8 $env:USERPROFILE\\.claude.json\n```\n\n## 4. 启动 Claude Code\n\n进入你的项目目录并启动：\n\n```bash\ncd /path/to/your/project\nclaude\n```\n\n首次进入项目时，选择 **Trust This Folder**，允许 Claude Code 访问项目文件。然后输入一条简单的编码需求，能够正常返回结果即表示接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `ANTHROPIC_AUTH_TOKEN` | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| `ANTHROPIC_BASE_URL` | `{{ api_endpoint }}` |\n| `ANTHROPIC_MODEL` | ModelGo 平台逻辑模型名 |\n| `ANTHROPIC_SMALL_FAST_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 同一个可调用的 ModelGo 逻辑模型名 |\n\n模型名可以通过[模型广场]({{ site_endpoint }}/models)确认，也可以查询当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的 ModelGo API Key，复制时不要带多余空格。\n\n### 返回 403 或模型不可用\n\n确认五个模型变量使用的都是当前 API Key 策略允许调用的 ModelGo 逻辑模型名。\n\n### 返回 404 或找不到接口\n\n`ANTHROPIC_BASE_URL` 应填写 `{{ api_endpoint }}`，不要填写 `{{ api_endpoint }}/v1/messages`；Claude Code 会自动补充 `/v1/messages`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)：查看最新安装与配置说明。\n","international/zh/agents/cline.md":"---\ntitle: Cline\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cline。\n---\n\n# Cline\n\nCline 是 VS Code 中的 AI 编程助手。选择 `OpenAI Compatible` Provider 后，可以通过 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 VS Code。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cline\n\n打开 VS Code 扩展市场，搜索 **Cline** 并安装扩展。\n\n![在 VS Code 扩展市场安装 Cline](/images/agents/cline/cline-market.webp)\n\n## 2. 配置 ModelGo\n\n安装完成后，点击 VS Code 左侧工具栏中的 Cline 图标，打开 **API Configuration**。\n\n![打开 Cline API Configuration](/images/agents/cline/cline-config-global.webp)\n\n按下表填写：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | ModelGo API Key |\n| Model ID | ModelGo 平台逻辑模型名 |\n\n点击 **Done** 保存。\n\n:::note\n- Base URL 使用 `{{ api_endpoint }}/v1`，不要填写 `/chat/completions`；Cline 会自动拼接接口路径。\n- Model ID 使用模型广场中当前 API Key 可调用的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 只保存在本机 Cline 设置中，不要提交到代码仓库或截图分享。\n:::\n\n如需先确认当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 3. 开始使用\n\n在 Cline 面板输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n![Cline 完成一次对话](/images/agents/cline/cline-chat.webp)\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写在 API Key 字段。\n\n### 返回 403 或模型不可用\n\n确认 Model ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应为 `{{ api_endpoint }}/v1`，不要粘贴完整的 `/chat/completions` URL。\n\n### 模型列表为空\n\n先请求 `GET {{ api_endpoint }}/v1/models` 验证接口；若 Cline 下拉列表不显示模型，可直接手动输入 Model ID。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Cline OpenAI Compatible 文档](https://github.com/cline/cline/blob/main/docs/provider-config/openai-compatible.mdx)：查看 Cline 官方 Provider 配置说明。\n","international/zh/agents/codebuddy.md":"---\ntitle: CodeBuddy\ndescription: 通过 ModelGo 接入 CodeBuddy。\n---\n\n# CodeBuddy\n\nCodeBuddy Code 是腾讯云的终端 AI 编程工具。它支持用环境变量覆盖 API 地址、Key 和模型，因此无需修改项目代码即可接入 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已安装 CodeBuddy CLI，并能执行 `codebuddy --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 CodeBuddy\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\ncodebuddy --version\n```\n\n## 2. 配置 ModelGo 环境变量\n\n在启动 CodeBuddy 的同一终端设置：\n\n```bash\nexport CODEBUDDY_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport CODEBUDDY_API_KEY=\"sk-你的token\"\nexport CODEBUDDY_MODEL=\"你的模型名\"\n```\n\n`CODEBUDDY_BASE_URL` 覆盖请求地址，`CODEBUDDY_API_KEY` 用于模型调用，`CODEBUDDY_MODEL` 指定 ModelGo 逻辑模型。不要将 `CODEBUDDY_AUTH_TOKEN` 与 ModelGo API Key 混用；前者是 CodeBuddy 平台登录凭据。\n\n:::note\n- Base URL 填 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- 若使用非交互模式 `codebuddy -p`，必须设置 `CODEBUDDY_API_KEY`。\n- API Key 和模型名建议写进本地 shell profile 或密钥管理器，不要提交到仓库。\n:::\n\n## 3. 启动并验证\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $CODEBUDDY_API_KEY\"\ncodebuddy\n```\n\n在会话中让 CodeBuddy 执行一个只读任务；非交互调用示例：\n\n```bash\ncodebuddy -p \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 仍然使用默认模型或地址\n\n确认环境变量在当前终端可见，并完全退出后重新启动 `codebuddy`。检查变量名拼写是否为大写形式。\n\n### 401 或 404\n\n检查 `CODEBUDDY_API_KEY`、`CODEBUDDY_MODEL` 和 `CODEBUDDY_BASE_URL`，不要把完整接口路径写进 Base URL。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [CodeBuddy CLI 快速开始](https://www.codebuddy.ai/docs/cli/quickstart)：查看安装、登录和首次运行流程。\n- [CodeBuddy CLI 环境变量](https://www.codebuddy.ai/docs/cli/env-vars)：查看 `CODEBUDDY_BASE_URL`、`CODEBUDDY_API_KEY` 和模型变量。\n","international/zh/agents/codex.md":"---\ntitle: Codex\ndescription: 使用 ModelGo 的 Responses API 配置 Codex CLI。\n---\n\n# Codex\n\nCodex 是 OpenAI 的命令行 AI 编程助手。通过自定义 `model_provider`，可以将 Codex CLI 的 Responses API 请求发送到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Codex\n\n在 macOS、Linux 或 Windows 终端中执行：\n\n```bash\nnpm install -g @openai/codex\n```\n\n安装完成后检查版本：\n\n```bash\ncodex --version\n```\n\n首次启动时，如果 Codex 提示有新版本可用，可以选择 **Skip**，先完成 ModelGo 配置。\n\n![跳过 Codex 升级提示](/images/agents/codex/codex-start.webp)\n\n## 2. 配置 ModelGo\n\nCodex 从用户目录下的 `~/.codex/config.toml` 读取模型和 Provider 配置。先创建目录和配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.codex\ntouch ~/.codex/config.toml\n${EDITOR:-vi} ~/.codex/config.toml\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\"\nnotepad \"$env:USERPROFILE\\.codex\\config.toml\"\n```\n\n将下面内容粘贴到 `config.toml`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中当前 API Key 可调用的逻辑模型名：\n\n```toml\nmodel_provider = \"modelgo\"\nmodel = \"YOUR_MODELGO_MODEL\"\n\n[model_providers.modelgo]\nname = \"ModelGo\"\nbase_url = \"{{ api_endpoint }}/v1\"\nenv_key = \"MODELGO_API_KEY\"\nwire_api = \"responses\"\n```\n\n其中，`base_url` 使用 ModelGo 的 OpenAI 兼容根地址，Codex 会自动请求 `/v1/responses`。\n\n## 3. 设置 API Key\n\n将 ModelGo API Key 保存到系统环境变量 `MODELGO_API_KEY`。不要把真实 API Key 直接写入 `config.toml`。\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n检查变量是否已生效（只输出是否存在，不要打印 Key 内容）：\n\n```bash\ntest -n \"$MODELGO_API_KEY\" && echo \"MODELGO_API_KEY is set\"\n```\n\n:::note\n- `MODELGO_API_KEY` 只应保存在本机环境变量中，不要提交到代码仓库或分享终端截图。\n- `model` 必须填写 ModelGo 逻辑模型名；截图中的 `gpt-5.6-sol` 仅为示例，请替换为你实际可调用的模型。\n- `wire_api = \"responses\"` 是当前 Codex 配置要求；不要使用已经弃用的 `wire_api = \"chat\"`。\n:::\n\n:::note 切换 API Key 或服务地址后请新建会话\n- Codex 在多轮对话中会继续携带之前的 Responses 上下文，其中可能包含只能由原上游账号继续处理的加密推理内容。\n- 如果你更换了 `MODELGO_API_KEY`、`base_url`，或者代理、号池将同一会话切换到其他上游账号，请新建 Codex 会话，不要继续或恢复原会话，否则请求可能返回 `400 invalid_encrypted_content`。\n:::\n\n## 4. 启动并验证\n\n进入一个本地项目目录，执行：\n\n```bash\ncd /path/to/your/project\ncodex\n```\n\n首次进入项目时，按提示选择信任当前目录。看到 Codex 欢迎界面后，输入一条简单的编码需求，例如“用三句话介绍这个项目”。\n\n![Codex 首次进入项目的欢迎界面](/images/agents/codex/codex-skip.webp)\n\n能够正常返回模型结果，即表示 ModelGo 接入成功。\n\n![Codex 开始对话](/images/agents/codex/codex-chat.webp)\n\n如需先确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 启动后提示找不到 Provider\n\n确认配置文件路径是用户目录下的 `~/.codex/config.toml`，并检查 `model_provider = \"modelgo\"` 与 `[model_providers.modelgo]` 的名称一致。\n\n### 返回 401 或认证失败\n\n检查当前终端是否已设置 `MODELGO_API_KEY`，并确认 API Key 没有多余空格或换行。\n\n### 返回 403 或模型不可用\n\n确认 `model` 使用模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`base_url` 应填写 `{{ api_endpoint }}/v1`。不要填写完整的 `/responses` 或 `/v1/responses`，Codex 会自动拼接路径。\n\n### 出现 Chat wire API 弃用提示\n\n在 `[model_providers.modelgo]` 中加入 `wire_api = \"responses\"`，并升级到最新 Codex CLI：\n\n```bash\nnpm install -g @openai/codex@latest\n```\n\n### 返回 `400 invalid_encrypted_content`\n\n这通常说明当前会话携带了原上游账号生成的加密上下文，但本轮请求被另一个上游账号处理。\n\n先检查是否更换过 API Key、Base URL，或者代理、号池是否切换了上游账号。发生过切换时，请新建会话，不要继续或恢复原会话。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [Codex 配置参考](https://developers.openai.com/codex/config-reference/)：查看当前 Codex 的 `config.toml` 字段说明。\n","international/zh/agents/copilot-cli.md":"---\ntitle: Copilot CLI\ndescription: 通过 ModelGo 接入 Copilot CLI。\n---\n\n# Copilot CLI\n\nGitHub Copilot CLI 支持 BYOK（Bring Your Own Key）。设置 Provider 环境变量后，Copilot CLI 会把模型请求发送到 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 GitHub Copilot CLI，并能执行 `copilot --help`。\n- 已完成 GitHub 登录或组织要求的 Copilot 认证。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认支持工具调用和流式输出的逻辑模型。\n\n## 1. 配置 ModelGo BYOK\n\n在启动 Copilot CLI 的同一终端设置：\n\n```bash\nexport COPILOT_PROVIDER_TYPE=openai\nexport COPILOT_PROVIDER_BASE_URL=\"{{ api_endpoint }}/v1\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\nexport COPILOT_MODEL=\"你的模型名\"\ncopilot\n```\n\n如果还没有通用环境变量，可直接设置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\nexport COPILOT_PROVIDER_API_KEY=\"$MODELGO_API_KEY\"\n```\n\n`openai` Provider 类型用于 OpenAI Chat Completions 兼容服务；`COPILOT_MODEL` 填 ModelGo 逻辑模型 ID。\n\n:::note\n- Copilot CLI 仍可能需要 GitHub 登录；登录身份与模型请求所用的 ModelGo Key 是两套凭据。\n- Base URL 填 `{{ api_endpoint }}/v1`，不要写 `/chat/completions`。\n- 建议选择支持 tool calling、streaming 且上下文窗口较大的模型。\n:::\n\n## 2. 验证模型\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ncopilot\n```\n\n在会话中让 Copilot CLI 执行一个只读任务，例如“列出项目入口文件”，确认能正常返回结果。\n\n## 常见问题\n\n### Copilot CLI 仍调用默认模型\n\n确认 `COPILOT_MODEL` 与 `COPILOT_PROVIDER_BASE_URL` 在当前终端可见，并重新启动 `copilot`。\n\n### 返回 401、404 或不支持工具调用\n\n检查 API Key、Base URL 和逻辑模型名；如果模型不支持工具调用或流式响应，请在模型广场更换模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [GitHub Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)：查看 Provider 环境变量和模型要求。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","international/zh/agents/crush.md":"---\ntitle: Crush\ndescription: 通过 ModelGo 接入 Crush。\n---\n\n# Crush\n\nCrush 是 Charmbracelet 提供的终端 AI 编程 Agent。它支持 OpenAI 兼容 Provider，可通过 `crushrc` 将请求转发到 ModelGo。\n\n## 接入前准备\n\n- 已安装 Node.js 18+、Go 或 Homebrew。\n- 已安装 Crush，并能执行 `crush --version`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Crush\n\n```bash\nbrew install charmbracelet/tap/crush\ncrush --version\n```\n\n也可以使用 `npm install -g @charmland/crush`、`go install github.com/charmbracelet/crush@latest`，Windows 用户可执行 `winget install charmbracelet.crush`。\n\n## 2. 添加 ModelGo Provider\n\nCrush 的项目配置放在项目根目录的 `.crushrc` 或 `crushrc`，全局配置放在 `~/.config/crush/crushrc`（Windows：`%USERPROFILE%\\\\.config\\\\crush\\\\crushrc`）。推荐使用 CLI 写入配置：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\ncrush provider add modelgo --type openai-compat \\\n  --base-url \"{{ api_endpoint }}/v1\" \\\n  --api-key \"$MODELGO_API_KEY\"\ncrush model add modelgo/你的模型名 --name \"你的模型名\"\n```\n\n将 `你的模型名` 替换为模型广场中的逻辑模型 ID。`openai-compat` 表示使用 OpenAI Chat Completions 兼容协议。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- API Key 建议通过 `MODELGO_API_KEY` 环境变量提供，不要写入仓库。\n- `modelgo/你的模型名` 是 Crush 的 Provider/模型标识，Provider ID 可按需修改。\n:::\n\n## 3. 启动并验证\n\n```bash\ncrush\n```\n\n在模型选择器中选择 ModelGo 模型，发送一条简单请求。也可先验证目录接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 找不到 Provider\n\n确认 `crushrc` 路径和文件名正确，并重新启动 Crush。项目配置会覆盖全局配置。\n\n### 返回 401 或 404\n\n检查 `MODELGO_API_KEY` 是否生效，Base URL 是否为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Crush 官方仓库](https://github.com/charmbracelet/crush)：查看安装、Provider 和命令参考。\n- [Crush 配置 Schema](https://github.com/charmbracelet/crush/blob/main/schema.json)：查看 `crushrc` 字段定义。\n","international/zh/agents/cursor.md":"---\ntitle: Cursor\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Cursor。\n---\n\n# Cursor\n\nCursor 是一款 AI 编程编辑器。通过自定义 OpenAI Base URL，Cursor 可以调用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 [Cursor](https://www.cursor.com/)。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Cursor\n\n访问 [Cursor 官网](https://www.cursor.com/)，下载并安装适合你操作系统的版本。\n\n![Cursor 官网下载页面](/images/agents/cursor/install.webp)\n\n## 2. 打开 Cursor 模型设置\n\n打开 Cursor 设置，进入 **Models** 页面。\n\n![打开 Cursor Settings 的 Models](/images/agents/cursor/settings.webp)\n\n## 3. 添加并启用模型\n\n点击 **Add model**，输入[模型广场]({{ site_endpoint }}/models)中的逻辑模型名，然后保存。\n\n![在 Cursor 中添加模型](/images/agents/cursor/add-model.webp)\n\n在 **Model Names** 列表中保留需要使用的模型，并关闭不需要的模型。\n\n![在 Cursor 中启用目标模型](/images/agents/cursor/model-list.webp)\n\n## 4. 配置 ModelGo 接口\n\n在 **Settings → Models → API Keys** 中配置 OpenAI 兼容接口：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| OpenAI API Key | ModelGo API Key |\n| Override OpenAI Base URL | `{{ api_endpoint }}/v1` |\n| Model Names | ModelGo 模型广场中的逻辑模型名 |\n\n![在 Cursor 中配置 ModelGo 接口](/images/agents/cursor/config-global.webp)\n\n如果你的 Cursor 使用另一版设置界面，可参考下面的布局，填写相同的 ModelGo 参数。\n\n![Cursor 另一版设置界面](/images/agents/cursor/config-cn.webp)\n\n点击 **Verify** 或 **Save** 保存配置。Cursor 的不同版本可能会调整设置项名称，但 Base URL、API Key 和模型名的含义不变。\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- 模型名必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图里的示例。\n- 如果 Verify 无法完成，可先在聊天窗口直接发送请求，或用下方命令检查接口和 Key。\n:::\n\n## 5. 测试连接\n\n回到 Cursor 聊天窗口，选择刚添加的模型，发送一条简单消息。能够正常返回结果，即表示接入成功。\n\n![在 Cursor 中测试 ModelGo 模型](/images/agents/cursor/chat.webp)\n\n也可以在终端查看当前 API Key 可调用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或认证失败\n\n确认 API Key 复制完整且没有多余空格，并检查是否填入 **OpenAI API Key** 字段。\n\n### 返回 404 或接口路径错误\n\n确认 Base URL 为 `{{ api_endpoint }}/v1`，不要把 `/chat/completions` 拼到 Base URL 后面。\n\n### Verify 失败或模型不可用\n\n确认模型名是 ModelGo 模型广场中的逻辑模型名，并检查该模型是否已对当前 API Key 开通。\n\n### 聊天窗口没有返回内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 验证网络和 Key，再确认 Cursor 的 Model Names 列表中已启用目标模型。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Cursor 官方文档](https://docs.cursor.com/)：查看 Cursor 设置、模型和自定义 API 配置说明。\n","international/zh/agents/deepseek-harness.md":"---\ntitle: DeepSeek Harness\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 DeepSeek Harness。\n---\n\n# DeepSeek Harness\n\nDeepSeek Harness（DSH）是 DeepSeek AI 开源的智能体框架，可以将模型、工具、文件系统、终端、会话和 Web UI 组合成可运行的 Agent。通过自定义提供方，DSH 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已安装 pnpm 11 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装并启动 DeepSeek Harness\n\nDeepSeek Harness 当前推荐从源码安装：\n\n```bash\ngit clone https://github.com/deepseek-ai/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm run build\npnpm dsh web\n```\n\n![从源码启动 DeepSeek Harness](/images/agents/deepseek-harness/install.webp)\n\n终端会打印 Web UI 地址，默认是 `http://127.0.0.1:3080`。如果端口已被占用，请以终端实际打印的地址为准。\n\n如果只想快速体验，也可以直接运行：\n\n```bash\nnpx @deepseek-ai/dsh web\n```\n\n## 2. 配置 ModelGo\n\n在浏览器打开终端打印的地址，点击左上角侧边栏按钮，然后点击 **设置**。\n\n![打开 DeepSeek Harness 设置](/images/agents/deepseek-harness/settings.webp)\n\n在设置中选择 **模型**，点击 **添加自定义提供方**。\n\n![添加自定义提供方](/images/agents/deepseek-harness/model-picker.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider ID | `modelgo` |\n| 显示名称 | `ModelGo` |\n| API 地址 | `{{ api_endpoint }}/v1` |\n| API 协议 | `openai-completions` |\n| API 密钥 | ModelGo API Key |\n| 模型 ID | 模型广场中的逻辑模型名 |\n| 显示名称 | 可填写与模型 ID 相同的名称 |\n\n![填写 ModelGo 自定义提供方](/images/agents/deepseek-harness/provider-config.webp)\n\n点击 **创建提供方** 保存配置。配置时请注意：\n\n:::note\n- API 地址填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`；DSH 会根据 `openai-completions` 协议拼接请求路径。\n- 模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例模型。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 开始会话\n\n回到主界面，选择一个工作区，再选择刚刚添加的 ModelGo 模型。\n\n![选择 ModelGo 模型开始会话](/images/agents/deepseek-harness/session.webp)\n\n输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 已接入成功。\n\n## 常见问题\n\n### Web UI 无法打开\n\n确认 `pnpm dsh web` 进程仍在运行，并访问终端打印的实际端口。默认端口是 `3080`，端口冲突时 DSH 可能会自动使用其他端口。\n\n### 返回 401 或认证失败\n\n检查 API Key 是否完整、无多余空格，并确认填写的是 ModelGo 控制台创建的 API Key。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\nAPI 地址应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。API 协议请选择 `openai-completions`。\n\n### 模型列表为空\n\n检查模型 ID 是否填写，并确认 DSH 的自定义提供方已保存。必要时可以先用下面的命令验证 ModelGo 接口：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [DeepSeek Harness 官方网站](https://www.deepseek.com/harness/)：查看最新安装方式和产品说明。\n- [DeepSeek Harness GitHub 仓库](https://github.com/deepseek-ai/deepseek-harness)：查看源码和版本信息。\n","international/zh/agents/factory-droid.md":"---\ntitle: Factory Droid\ndescription: 通过 ModelGo 接入 Factory Droid。\n---\n\n# Factory Droid\n\nFactory Droid 是 Factory 的终端 Agent。通过 BYOK 自定义模型，可以让 Droid 使用 ModelGo 的 OpenAI 兼容接口。\n\n## 接入前准备\n\n- 已安装 Node.js 18+ 和 Droid CLI。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装并启动 Droid\n\n```bash\nnpm install -g droid\ndroid --version\ndroid\n```\n\n也可以使用 Factory 官方安装器。进入 Droid 后输入 `/settings` 可打开设置。\n\n## 2. 配置 ModelGo 自定义模型\n\n编辑 `~/.factory/settings.json`（Windows：`%USERPROFILE%\\\\.factory\\\\settings.json`），合并以下 `customModels` 配置：\n\n```json\n{\n  \"customModels\": [\n    {\n      \"model\": \"你的模型名\",\n      \"displayName\": \"ModelGo / 你的模型名\",\n      \"baseUrl\": \"{{ api_endpoint }}/v1\",\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"provider\": \"openai\"\n    }\n  ]\n}\n```\n\n先设置 Key：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n重新启动 Droid，在 `/models` 或模型选择器中选择 `ModelGo / 你的模型名`。\n\n:::note\n- `baseUrl` 填 `{{ api_endpoint }}/v1`，不要附加 `/chat/completions`。\n- `model` 必须使用 ModelGo 模型广场中的逻辑模型 ID。\n- 保留原有 `settings.json` 字段，只合并 `customModels`，不要覆盖其他个人设置。\n:::\n\n## 3. 验证请求\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\ndroid exec --model \"你的模型名\" \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### 模型没有出现在列表中\n\n检查 JSON 是否有效、`customModels` 是否位于文件顶层，并完全退出后重新启动 Droid。\n\n### 认证失败或接口路径错误\n\n确认环境变量已在启动 Droid 的同一终端中设置，且 `baseUrl` 没有重复的 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Factory Droid 设置](https://docs.factory.ai/droid-cli/settings)：查看 `settings.json` 的位置和设置入口。\n- [Factory BYOK](https://docs.factory.ai/model-independence/byok)：了解自定义模型字段和模型独立性。\n","international/zh/agents/hermes-agent.md":"---\ntitle: Hermes Agent\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Hermes Agent。\n---\n\n# Hermes Agent\n\nHermes Agent 是一款运行在终端中的 AI Agent。通过自定义 Provider，Hermes 可以使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认要使用的 ModelGo 逻辑模型名。\n\n## 1. 安装 Hermes Agent\n\nmacOS 或 Linux：\n\n```bash\ncurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash\n```\n\nWindows PowerShell：\n\n```powershell\niex (irm https://hermes-agent.nousresearch.com/install.ps1)\n```\n\n重新打开终端后，检查安装是否成功：\n\n```bash\nhermes --version\n```\n\n## 2. 配置 ModelGo\n\n先把 API Key 放入当前终端的环境变量。不要把真实 Key 提交到代码仓库或公开脚本中：\n\n```bash\nexport MODELGO_API_KEY=\"你的-ModelGo-API-Key\"\nexport MODELGO_MODEL=\"你的-ModelGo-逻辑模型名\"\n```\n\n如果还不确定模型名，可以先查询当前 API Key 可用的模型：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n然后使用 `hermes config set` 写入自定义 Provider。将 `<model>` 替换为模型广场或 `GET /v1/models` 返回的逻辑模型名：\n\n```bash\nhermes config set model.provider custom\nhermes config set model.base_url {{ api_endpoint }}/v1\nhermes config set model.api_mode chat_completions\nhermes config set model.api_key \"$MODELGO_API_KEY\"\nhermes config set model.default \"$MODELGO_MODEL\"\n```\n\n如果你的 Hermes 版本通过 `hermes model` 提供配置向导，也可以运行：\n\n```bash\nhermes model\n```\n\n选择 **Custom endpoint**，依次填写下方配置表中的 ModelGo Base URL、API Key 和模型名，并选择 **Chat Completions** 协议。\n\n:::note\n- 部分旧版本将 Chat Completions 协议显示为 `openai_messages`。如果 `chat_completions` 被提示为无效，请升级 Hermes，或在 `hermes model` 向导中选择 Chat Completions。\n:::\n\n## 3. 检查配置并开始对话\n\n检查 Hermes 配置：\n\n```bash\nhermes config check\n```\n\n检查通过后启动 Hermes：\n\n```bash\nhermes\n```\n\n输入一条消息，例如“用三句话介绍 ModelGo”。如果能返回模型结果，说明接入成功。\n\n## ModelGo 配置项\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Provider | `custom` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API 模式 | `chat_completions` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model ID | ModelGo 的平台逻辑模型名，不是上游厂商原始模型 ID |\n\nHermes 会将非敏感配置保存到 `~/.hermes/config.yaml`，API Key 等敏感信息保存到 `~/.hermes/.env`。不要分享或提交 `~/.hermes/` 下包含密钥的文件。\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n确认 API Key 没有被撤销或过期，并重新执行：\n\n```bash\nhermes config set model.api_key \"$MODELGO_API_KEY\"\n```\n\n### 返回 403 或模型不可用\n\n确认 `model.default` 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要再拼接 `/chat/completions`；Hermes 会在请求时补充具体路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs)：查看安装器、配置项和 CLI 的最新说明。\n","international/zh/agents/kilo-cli.md":"---\ntitle: Kilo CLI\ndescription: 通过 ModelGo 接入 Kilo CLI。\n---\n\n# Kilo CLI\n\nKilo CLI 是终端 AI 编程 Agent。它支持自定义 OpenAI 兼容 Provider；由于 ModelGo CLI 尚未提供官方自动配置，本文采用 Kilo 的 `/connect` 与配置文件方式。\n\n## 接入前准备\n\n- 已安装 Node.js 18+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Kilo CLI\n\n```bash\nnpm install -g @kilocode/cli\nkilo --version\n```\n\n进入项目目录后运行 `kilo`，首次启动可使用 `/connect` 添加 Provider。\n\n## 2. 添加 ModelGo Provider\n\n在项目根目录创建 `kilo.jsonc`（或编辑全局配置），加入 OpenAI 兼容 Provider：\n\n```jsonc\n{\n  \"$schema\": \"https://app.kilo.ai/config.json\",\n  \"model\": \"modelgo/你的模型名\",\n  \"provider\": {\n    \"modelgo\": {\n      \"options\": {\n        \"apiKey\": \"{env:MODELGO_API_KEY}\",\n        \"baseURL\": \"{{ api_endpoint }}/v1\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"ModelGo / 你的模型名\",\n          \"tool_call\": true\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n也可以在 TUI 中选择 `/connect` → `OpenAI Compatible`，填写同样的 Base URL、API Key 和模型 ID。\n\n:::note\n- Provider ID 使用小写 `modelgo`；模型选择格式为 `modelgo/你的模型名`。\n- `baseURL` 只填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- Kilo CLI 的模型 ID 必须与 ModelGo 模型广场逻辑模型名一致。\n:::\n\n## 3. 验证配置\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nkilo\n```\n\n在模型选择器中选中 ModelGo 模型，发送一条只读任务确认连接。\n\n## 常见问题\n\n### Provider 没有出现在选择器\n\n检查 `kilo.jsonc` 的 JSONC 格式、Provider ID 和 `model` 路径，并重新启动 Kilo。\n\n### 401 或 404\n\n确认 `MODELGO_API_KEY` 已导出，`baseURL` 为 `{{ api_endpoint }}/v1`，不要填写完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Kilo CLI 官方文档](https://kilo.ai/docs/code-with-ai/platforms/cli)：查看安装、`/connect` 和 CLI 命令。\n- [Kilo 自定义模型](https://kilo.ai/docs/code-with-ai/agents/custom-models)：查看 OpenAI Compatible Provider 字段和模型格式。\n","international/zh/agents/kilo-code.md":"---\ntitle: Kilo Code\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 Kilo Code。\n---\n\n# Kilo Code\n\nKilo Code 是一款支持 VS Code 和 JetBrains 的 AI 编程助手。通过 OpenAI 兼容 Provider，你可以在 Kilo Code 中使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 VS Code 或 JetBrains IDE。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 Kilo Code\n\n### VS Code\n\n打开 VS Code 扩展市场，搜索 **Kilo Code**，确认发布者后安装扩展。安装完成后，打开左侧 Kilo Code 面板。\n\n![在 VS Code 扩展市场安装 Kilo Code](/images/agents/kilo-code/vscode-market.webp)\n\n首次安装时，VS Code 会要求确认是否信任发布者。确认发布者为 Kilo Code 后，点击 **Trust Publisher & Install**。\n\n![确认信任 Kilo Code 发布者](/images/agents/kilo-code/vscode-panel.webp)\n\n### JetBrains\n\n打开 Settings / Preferences → Plugins，在 Marketplace 搜索 **Kilo Code** 并安装。安装完成后重启 IDE，使扩展生效。\n\n![在 JetBrains Marketplace 安装 Kilo Code](/images/agents/kilo-code/jetbrains-market.webp)\n\n安装第三方插件时，JetBrains 会显示插件声明。确认后点击 **接受**，完成安装。\n\n![确认 JetBrains 第三方插件声明](/images/agents/kilo-code/jetbrains-panel.webp)\n\n## 2. 在 VS Code 中配置 ModelGo\n\n打开 Kilo Code 的设置，进入 **Providers**，选择 **OpenAI Compatible**，填写以下信息：\n\n先在 Kilo Code 的欢迎页选择 **Bring my own Key**：\n\n![选择 Bring my own Key](/images/agents/kilo-code/vscode-byok.webp)\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| API Provider | `OpenAI Compatible` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在[控制台]({{ console_endpoint }}/api-keys)创建的 ModelGo API Key |\n| Model | ModelGo 平台逻辑模型名 |\n\n![Kilo Code VS Code 配置界面](/images/agents/kilo-code/vscode-config-global.webp)\n\n保存后，Kilo Code 会尝试从兼容的 `/v1/models` 接口获取模型。如果下拉列表中没有目标模型，可以选择 **Use custom**，手动输入模型广场中的逻辑模型名。\n\n:::note\n- Base URL 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。Kilo Code 会自动拼接标准路径。\n- 截图中的模型名仅为界面示例，请替换为当前 API Key 可调用的 ModelGo 逻辑模型名。\n- API Key 只填写在本机的 Kilo Code 设置中，不要提交到代码仓库或截图分享。\n:::\n\n## 3. 在 JetBrains 中配置 ModelGo\n\n打开 Kilo Code 设置，点击 **Bring my own Key**，选择 **OpenAI Compatible**，然后填写与 VS Code 相同的配置：\n\n![在 JetBrains 中选择 Bring my own Key](/images/agents/kilo-code/jetbrains-byok.webp)\n\n1. **Base URL**：`{{ api_endpoint }}/v1`\n2. **API Key**：ModelGo API Key\n3. **Model**：ModelGo 逻辑模型名\n4. 点击 **Save** 保存。\n\n![JetBrains 中的 ModelGo Provider 配置](/images/agents/kilo-code/jetbrains-config-global.webp)\n\n如果模型下拉列表为空，先确认 Base URL 可访问，再选择自定义模型并手动输入逻辑模型名。\n\n![在 JetBrains 中完成一次编码任务](/images/agents/kilo-code/jetbrains-start.webp)\n\n## 4. 检查配置并开始对话\n\n进入一个本地项目，在 Kilo Code 面板中输入一条简单的编码需求，例如“用三句话介绍这个项目”。能够正常返回模型结果，即表示接入成功。\n\n![Kilo Code 完成一次编码任务](/images/agents/kilo-code/vscode-start.webp)\n\n如需检查当前 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整，确认没有多余空格，并确认填写在 **API Key** 而不是 Base URL 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 **Model** 使用的是 ModelGo 模型广场中、且当前 API Key 策略允许调用的逻辑模型名。不要直接填写上游厂商原始模型 ID，除非模型广场明确提供该名称。\n\n### 返回 404 或找不到接口\n\nBase URL 应填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址。Kilo Code 会在请求时补充具体接口路径。\n\n### 模型下拉列表没有内容\n\n先用 `GET {{ api_endpoint }}/v1/models` 检查 API Key 和接口是否可用；如果接口正常，使用 **Use custom** 手动输入逻辑模型名。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [Kilo Code 官方文档](https://kilo.ai/docs)：查看最新的扩展安装和 Provider 配置说明。\n","international/zh/agents/nanobot.md":"---\ntitle: nanobot\ndescription: 通过 ModelGo 接入 nanobot。\n---\n\n# nanobot\n\nnanobot 是轻量级终端 Agent。它通过 JSON 配置 Provider 和模型预设，可直接使用 ModelGo 的 OpenAI 兼容 API。\n\n## 接入前准备\n\n- 已安装 Python 3.11+。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 nanobot\n\n```bash\npython -m pip install nanobot-ai\nnanobot onboard --wizard\n```\n\n配置文件默认位于 `~/.nanobot/config.json`。\n\n## 2. 配置 ModelGo Provider\n\n编辑 `~/.nanobot/config.json`，合并以下字段：\n\n```json\n{\n  \"providers\": {\n    \"modelgo\": {\n      \"apiKey\": \"${MODELGO_API_KEY}\",\n      \"apiBase\": \"{{ api_endpoint }}/v1\"\n    }\n  },\n  \"modelPresets\": {\n    \"ModelGo\": {\n      \"provider\": \"modelgo\",\n      \"model\": \"你的模型名\",\n      \"maxTokens\": 4096,\n      \"contextWindowTokens\": 65536,\n      \"temperature\": 0.1\n    }\n  },\n  \"agents\": { \"defaults\": { \"modelPreset\": \"ModelGo\" } }\n}\n```\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nnanobot 对 OpenAI 兼容自定义端点无需额外填写 `apiType`；`apiBase` 使用带 `/v1` 的根地址。\n\n:::note\n- 保留原配置中的 channels、tools 等字段，只合并 providers、modelPresets 和 agents.defaults。\n- API Key 使用环境变量，不要把真实 Key 写进 JSON 或提交到仓库。\n- 模型名必须是 ModelGo 模型广场中的逻辑模型 ID。\n:::\n\n## 3. 验证连接\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\nnanobot agent -m \"请用一句话介绍当前项目\"\n```\n\n## 常见问题\n\n### `nanobot` 找不到模型\n\n确认 `modelPresets.ModelGo.provider` 与 `providers.modelgo` 的 ID 一致，并检查 JSON 格式。\n\n### 401 或请求地址错误\n\n确认 API Key 环境变量已导出，`apiBase` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [nanobot OpenAI 兼容 Provider 指南](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-openai-compatible-provider.md)：查看完整 JSON 配置说明。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n","international/zh/agents/oh-my-pi.md":"---\ntitle: Oh My Pi\ndescription: 通过 ModelGo 接入 Oh My Pi。\n---\n\n# Oh My Pi\n\nOh My Pi（命令 `omp`）是终端 AI 编程 Agent。它支持在 `models.yml` 中声明 OpenAI 兼容 Provider，并按 `provider-id/model-id` 选择模型。\n\n## 接入前准备\n\n- 已安装 Bun 或使用官方安装脚本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认逻辑模型名。\n\n## 1. 安装 Oh My Pi\n\n```bash\nbun install -g @oh-my-pi/pi-coding-agent\nomp --version\n```\n\nmacOS/Linux 也可以执行官方安装脚本：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh\n```\n\n## 2. 添加 ModelGo Provider\n\n编辑 `~/.omp/agent/models.yml`，加入：\n\n```yaml\nproviders:\n  modelgo:\n    baseUrl: {{ api_endpoint }}/v1\n    api: openai-completions\n    apiKey: MODELGO_API_KEY\n    models:\n      - id: 你的模型名\n        name: ModelGo / 你的模型名\n        contextWindow: 128000\n        maxTokens: 8192\n```\n\n`apiKey` 填环境变量名，而不是 Key 本身：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\n:::note\n- `api` 使用 `openai-completions`，`baseUrl` 使用 `{{ api_endpoint }}/v1`。\n- 模型选择格式为 `modelgo/你的模型名`。\n- 不要把真实 API Key 写入 `models.yml`，并确认文件权限仅当前用户可读。\n:::\n\n## 3. 选择模型并验证\n\n```bash\nomp --list-models\nomp --model modelgo/你的模型名\n```\n\n进入会话后发送一条简单任务；也可先检查 ModelGo 模型目录：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 模型列表没有 ModelGo\n\n确认文件路径为 `~/.omp/agent/models.yml`，YAML 缩进正确，并重新启动 `omp`。\n\n### 401 或接口路径错误\n\n确认 `MODELGO_API_KEY` 已导出，`baseUrl` 没有重复 `/v1` 或完整接口路径。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [Oh My Pi Provider 文档](https://github.com/can1357/oh-my-pi/blob/main/docs/providers.md)：查看 Provider、API 类型和密钥配置。\n- [Oh My Pi 模型文档](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md)：查看模型选择和 `models.yml` 结构。\n","international/zh/agents/openclaw.md":"---\ntitle: OpenClaw\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenClaw。\n---\n\n# OpenClaw\n\nOpenClaw 是一款开源、自托管的个人 AI 助手。通过自定义 Provider，可以让 OpenClaw 使用 ModelGo 的 OpenAI 兼容接口调用模型。\n\n## 接入前准备\n\n- 已安装 Node.js 22.22.3 或更高版本。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenClaw\n\n### macOS / Linux\n\n```bash\ncurl -fsSL https://openclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell\n\n```powershell\niwr -useb https://openclaw.ai/install.ps1 | iex\n```\n\n检查安装是否成功：\n\n```bash\nopenclaw --version\n```\n\n## 2. 设置 API Key\n\nOpenClaw 配置支持从环境变量读取 Provider API Key。将 ModelGo API Key 设置为 `MODELGO_API_KEY`：\n\n### macOS / Linux（zsh）\n\n```bash\necho 'export MODELGO_API_KEY=\"YOUR_MODELGO_API_KEY\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n如果使用 Bash，将 `~/.zshrc` 替换为 `~/.bashrc` 或 `~/.bash_profile`。\n\n### Windows PowerShell\n\n```powershell\n[Environment]::SetEnvironmentVariable(\"MODELGO_API_KEY\", \"YOUR_MODELGO_API_KEY\", \"User\")\n$env:MODELGO_API_KEY = [Environment]::GetEnvironmentVariable(\"MODELGO_API_KEY\", \"User\")\n```\n\n## 3. 配置 ModelGo Provider\n\n创建并打开 OpenClaw 配置文件：\n\n### macOS / Linux\n\n```bash\nmkdir -p ~/.openclaw\n${EDITOR:-vi} ~/.openclaw/openclaw.json\n```\n\n### Windows PowerShell\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.openclaw\"\nnotepad \"$env:USERPROFILE\\.openclaw\\openclaw.json\"\n```\n\n将下面内容粘贴到 `openclaw.json`，并将 `YOUR_MODELGO_MODEL` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"models\": {\n    \"mode\": \"merge\",\n    \"providers\": {\n      \"modelgo\": {\n        \"baseUrl\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"${MODELGO_API_KEY}\",\n        \"api\": \"openai-completions\",\n        \"models\": [\n          {\n            \"id\": \"YOUR_MODELGO_MODEL\",\n            \"name\": \"YOUR_MODELGO_MODEL\",\n            \"reasoning\": false,\n            \"input\": [\"text\"],\n            \"contextWindow\": 128000,\n            \"maxTokens\": 8192\n          }\n        ]\n      }\n    }\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"modelgo/YOUR_MODELGO_MODEL\"\n      }\n    }\n  }\n}\n```\n\n配置项说明：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `baseUrl` | `{{ api_endpoint }}/v1` |\n| `apiKey` | `${MODELGO_API_KEY}` |\n| `api` | `openai-completions` |\n| `models[].id` | ModelGo 逻辑模型名 |\n| `agents.defaults.model.primary` | `modelgo/<逻辑模型名>` |\n\n:::note\n- `baseUrl` 填写 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n- `contextWindow` 和 `maxTokens` 应与所选模型的限制匹配；上方数值是通用示例，请以模型广场信息为准。\n- 如果模型支持推理，可将对应模型的 `reasoning` 改为 `true`。\n- API Key 通过环境变量注入，不要把真实 Key 写入配置文件或提交到仓库。\n:::\n\n## 4. 启动并验证\n\n保存配置后，在终端执行：\n\n```bash\nopenclaw onboard --install-daemon\n```\n\n查看当前模型和 Provider 状态：\n\n```bash\nopenclaw models status\n```\n\n如果状态正常，启动 Gateway：\n\n```bash\nopenclaw gateway start\n```\n\n在 OpenClaw 对话界面发送一条简单消息，例如“用三句话介绍这个项目”。能够正常返回结果，即表示 ModelGo 接入成功。\n\n## 常见问题\n\n### 找不到模型\n\n确认 `models.providers.modelgo.models[].id` 与 `agents.defaults.model.primary` 中的模型名一致，并使用 `modelgo/<模型名>` 格式。\n\n### 返回 401 或认证失败\n\n检查当前终端是否存在 `MODELGO_API_KEY`，并确认 `apiKey` 使用 `${MODELGO_API_KEY}`，没有多余空格。\n\n### 返回 403 或模型不可用\n\n确认模型 ID 是模型广场中、且当前 API Key 策略允许调用的逻辑模型名。\n\n### 返回 404 或接口路径错误\n\n`baseUrl` 应为 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；OpenClaw 会按 `openai-completions` 协议拼接路径。\n\n### Gateway 没有加载新配置\n\n修改配置后重启 Gateway：\n\n```bash\nopenclaw gateway restart\n```\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 使用方式。\n- [OpenClaw 自定义 Provider 文档](https://docs.openclaw.ai/gateway/config-tools)：查看 Provider、Base URL 和模型列表配置说明。\n","international/zh/agents/opencode.md":"---\ntitle: OpenCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 OpenCode。\n---\n\n# OpenCode\n\nOpenCode 是一个开源终端 AI 编程 Agent，支持通过自定义 Provider 接入 OpenAI 兼容接口。配置 ModelGo 后，可以在终端、IDE 或桌面端使用 ModelGo 的逻辑模型。\n\n## 接入前准备\n\n- 已安装 Node.js 18 或更高版本。\n- 已安装 OpenCode，并能在终端执行 `opencode -v`。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建或复制 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 OpenCode\n\n在终端执行：\n\n```bash\nnpm install -g opencode-ai\nopencode -v\n```\n\nWindows 用户也可以使用 OpenCode 官方提供的安装方式。安装完成后，执行 `opencode -v`，看到版本号即表示安装成功。\n\n## 2. 配置 ModelGo Provider\n\nOpenCode 默认从以下位置读取用户配置：\n\n- macOS/Linux：`~/.config/opencode/opencode.json`\n- Windows：`%USERPROFILE%\\\\.config\\\\opencode\\\\opencode.json`\n\n创建或编辑 `opencode.json`，将 `你的模型名` 替换为模型广场中的逻辑模型名：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"modelgo\": {\n      \"npm\": \"@ai-sdk/openai-compatible\",\n      \"name\": \"ModelGo\",\n      \"options\": {\n        \"baseURL\": \"{{ api_endpoint }}/v1\",\n        \"apiKey\": \"{env:MODELGO_API_KEY}\"\n      },\n      \"models\": {\n        \"你的模型名\": {\n          \"name\": \"你的模型名\"\n        }\n      }\n    }\n  }\n}\n```\n\n设置环境变量：\n\n```bash\nexport MODELGO_API_KEY=\"sk-你的token\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:MODELGO_API_KEY = \"sk-你的token\"\n```\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| `name` | `ModelGo`，用于界面显示 |\n| `options.baseURL` | `{{ api_endpoint }}/v1` |\n| `options.apiKey` | `{env:MODELGO_API_KEY}` |\n| `models` | 模型广场中的逻辑模型 ID 和显示名称 |\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 路径。\n- `modelgo` 是本地 Provider ID，可以按需修改；修改后选择模型时使用新的 Provider ID。\n- API Key 通过环境变量读取，不要把真实 Key 直接写入配置文件或提交到仓库。\n- 模型 ID 必须是 ModelGo 模型广场中的逻辑模型名，不要直接照抄示例。\n:::\n\n## 3. 选择模型并开始对话\n\n启动 OpenCode：\n\n```bash\nopencode\n```\n\n输入 `/models` 打开模型选择器，搜索并选择 **ModelGo** Provider 下的模型。\n\n![在 OpenCode 中打开模型选择器](/images/agents/opencode/model-search.webp)\n\n模型列表中显示 **ModelGo** 的条目，即表示 Provider 已被识别。\n\n![在 OpenCode 模型列表中识别 ModelGo](/images/agents/opencode/provider-name.webp)\n\n也可以在模型选择器中输入 `ModelGo` 进行筛选：\n\n![在 OpenCode 中筛选 ModelGo 模型](/images/agents/opencode/provider-filter.webp)\n\n选择模型后输入一条简单任务，例如“用三句话介绍这个项目”。\n\n![在 OpenCode 中使用 ModelGo 开始对话](/images/agents/opencode/chat.webp)\n\n## 4. 验证配置\n\n如果模型列表为空，可以先确认 API Key 能访问 ModelGo：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n返回的 `id` 就是可填入 `models` 配置的逻辑模型名。\n\n## 常见问题\n\n### OpenCode 找不到配置文件\n\n确认文件名为 `opencode.json`，并放在 `~/.config/opencode/`（Windows 为 `%USERPROFILE%\\\\.config\\\\opencode\\\\`）目录下。也可以在项目目录放置同名配置覆盖用户配置。\n\n### 返回 401 或认证失败\n\n确认当前终端已设置 `MODELGO_API_KEY`，且 API Key 没有多余空格。重新打开终端后再启动 OpenCode。\n\n### 返回 404 或接口路径错误\n\n确认 `baseURL` 为 `{{ api_endpoint }}/v1`，不要追加 `/chat/completions`。\n\n### 模型列表为空或模型不可用\n\n确认 `models` 中的 ID 与模型广场逻辑模型名完全一致，并检查该模型是否已对当前 API Key 开通。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：创建 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [OpenCode 官方 Providers 文档](https://opencode.ai/docs/providers)：查看 Provider、凭据和自定义 Base URL 的配置方式。\n- [OpenCode 官方配置文档](https://opencode.ai/docs/config/)：了解配置文件结构及模型选项。\n","international/zh/agents/zcode.md":"---\ntitle: ZCode\ndescription: 使用 ModelGo 的 OpenAI 兼容接口配置 ZCode。\n---\n\n# ZCode\n\nZCode 是智谱 AI 推出的桌面 AI 编程工具，支持 Windows、macOS 和 Linux。ZCode 支持自定义 OpenAI 兼容供应商，配置后可以直接使用 ModelGo 的模型和 API Key。\n\n## 接入前准备\n\n- 已安装 ZCode 桌面客户端。\n- 已在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n- 已在[模型广场]({{ site_endpoint }}/models)确认一个当前 API Key 可调用的逻辑模型名。\n\n## 1. 安装 ZCode\n\n访问 [ZCode 官方下载页](https://zcode.z.ai/cn/docs/install)，根据操作系统下载对应安装包。ZCode 提供 macOS、Windows 和 Linux 版本，Linux 用户可以选择 `.deb`、`.rpm` 或 AppImage。\n\n![ZCode 官方下载页](/images/agents/zcode/install.webp)\n\n下载完成后，按系统提示完成安装并启动 ZCode。首次启动时可以选择工作区；完成引导后进入主界面。\n\n![ZCode 全平台安装包](/images/agents/zcode/setup.webp)\n\n## 2. 添加 ModelGo 供应商\n\n在 ZCode 左下角点击设置图标，进入 **Model settings**，然后在供应商列表底部点击 **Add provider**。\n\n![打开 ZCode Model settings 并添加供应商](/images/agents/zcode/provider-fields.webp)\n\n填写以下配置：\n\n| 配置项 | ModelGo 填写内容 |\n| --- | --- |\n| Name | `ModelGo` |\n| Base URL | `{{ api_endpoint }}/v1` |\n| API Key | 在 [控制台]({{ console_endpoint }}/api-keys) 创建的 ModelGo API Key |\n| API format | `Chat completions (/chat/completions)` |\n| Model list | 点击 **Add model**，填写模型广场中的逻辑模型名 |\n| Context window | 按模型实际上下文长度填写；不确定时可先填 `200000` |\n\n![ModelGo 供应商配置示例](/images/agents/zcode/provider-saved-global.webp)\n\n点击 **Add provider** 保存。配置时请注意：\n\n:::note\n- Base URL 只填写 `{{ api_endpoint }}/v1`，不要填写完整的 `/chat/completions` 地址；ZCode 会根据 API format 自动拼接路径。\n- Name 是本机显示名称，填写 `ModelGo` 即可，不需要填写上游厂商名称。\n- Model list 中的模型 ID 必须使用 ModelGo 模型广场中的逻辑模型名，不要直接照抄截图中的示例。\n- API Key 仅用于本机配置，不要提交到代码仓库或公开截图。\n:::\n\n## 3. 添加模型并开始对话\n\n点击 **Add model**，输入一个 ModelGo 逻辑模型名并保存。可以按需添加多个模型。\n\n![ZCode 中选择 ModelGo 模型](/images/agents/zcode/chat.webp)\n\n回到对话界面，在模型下拉菜单中选择 **ModelGo** 和刚添加的模型，输入一条简单的任务，例如“用三句话介绍这个项目”。能够正常返回结果，即表示接入成功。\n\n如需确认 API Key 可调用的模型，可以执行：\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n## 常见问题\n\n### 返回 401 或提示认证失败\n\n检查 API Key 是否复制完整、没有多余空格，并确认填写在 **API Key** 输入框中。\n\n### 返回 403 或模型不可用\n\n确认 Model list 中填写的是模型广场中的逻辑模型名，且当前 API Key 策略允许调用该模型。\n\n### 返回 404 或接口路径错误\n\nBase URL 应为 `{{ api_endpoint }}/v1`，API format 请选择 **Chat completions (/chat/completions)**，不要把完整接口路径填入 Base URL。\n\n### 模型列表为空或无法保存\n\n确认至少添加了一个模型，并检查 Base URL 是否可以访问。必要时先用 `GET {{ api_endpoint }}/v1/models` 验证 API Key 和接口。\n\n## 相关文档\n\n- [首次调用](../quickstart/quickstart)：获取 API Key、查询模型并验证 ModelGo 接口。\n- [认证鉴权](../quickstart/authentication)：了解 API Key 的安全使用方式。\n- [ZCode 安装文档](https://zcode.z.ai/cn/docs/install)：查看最新安装说明。\n- [ZCode 连接模型文档](https://zcode.z.ai/cn/docs/configuration)：查看自定义供应商和模型配置说明。\n","international/zh/models/audio/minimax.md":"---\ntitle: MiniMax 音频\ndescription: 用 MiniMax T2A 原厂请求体与响应体做平台托管的同步语音合成。\n---\n\n# MiniMax 音频\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v1/t2a_v2` | 目录公示的 MiniMax T2A 入站 |\n| `POST` | `/v1/t2a_v2` | MiniMax SDK 别名，语义相同 |\n\n这是 **MiniMax 同步语音合成（T2A V2）** 的原厂入站协议。请求体按 MiniMax `T2aV2Req` 原样接收（`model`、`text`、`voice_setting`、`audio_setting`、`stream` 等），**响应体也按 MiniMax `T2aV2Resp` 渲染**，照 MiniMax 官方文档写的客户端可以直接解析。\n\n`model` 填写平台逻辑模型名，策略、路由与计费照常生效。逻辑模型必须在 `public_protocols` 中声明 `minimax_t2a`，否则网关返回协议不匹配。\n\n只需要 OpenAI 形态的二进制音频时，见[语音合成](./speech)。\n\n## 合成\n\n两条路径等价，任选其一：\n\n```bash\ncurl {{ api_endpoint }}/minimax/v1/t2a_v2 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"text\": \"你好，欢迎使用 ModelGo。\",\n    \"voice_setting\": { \"voice_id\": \"female-shaonv\", \"speed\": 1, \"vol\": 1, \"pitch\": 0 },\n    \"audio_setting\": { \"sample_rate\": 32000, \"bitrate\": 128000, \"format\": \"mp3\", \"channel\": 1 }\n  }'\n```\n\n非流式成功响应是 MiniMax JSON，音频在 `data.audio`，为**十六进制字符串**（不是 `audio/mpeg` 直出）：\n\n```json\n{\n  \"base_resp\": { \"status_code\": 0, \"status_msg\": \"success\" },\n  \"data\": { \"audio\": \"<hex mp3 bytes>\", \"status\": 2, \"ced\": \"\" },\n  \"extra_info\": {\n    \"audio_length\": 2448,\n    \"audio_sample_rate\": 32000,\n    \"audio_size\": 40884,\n    \"bitrate\": 128000,\n    \"word_count\": 16,\n    \"usage_characters\": 22,\n    \"audio_format\": \"mp3\",\n    \"audio_channel\": 1\n  }\n}\n```\n\n2026-09-10 国内生产用 `speech-2.8-turbo` 打 `POST /minimax/v1/t2a_v2` 得到上述形态（hex 已截断）。同一模型打 `POST /v1/audio/speech` 返回 `model_protocol_not_offered`。\n\n`base_resp.status_code` **只有数字 `0` 表示成功**。HTTP 200 但 `status_code != 0` 仍按调用失败处理。\n\n### 流式\n\n请求里加 `\"stream\": true`，响应为 SSE，每帧仍是 MiniMax JSON（含增量 hex 音频），不是 OpenAI chat 的 `choices[].delta`。\n\n### 失败与 HTTP\n\n带内错误会把 MiniMax JSON 回传给调用方，并按 `status_code` 映射 HTTP 状态：\n\n| MiniMax `status_code` | HTTP |\n| --- | --- |\n| `1004` | `401` |\n| `1002` / `1039` | `429` |\n| `2013` / `1042` | `400` |\n| 其余非 `0` | `502` |\n\n### 计费\n\n按上游报告的 **字符数** 计量（`usage.characters`，否则 `extra_info.usage_characters`），不会用 `text` 的字符串长度估算。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；是否可走本通道以该模型的 `public_protocols` 为准。\n- 路径不参与选路：由逻辑模型的路由决定 MiniMax 直连或百炼等 adaptor。\n- 路由上的 Provider 必须声明支持 MiniMax T2A；仅 OpenAI 兼容中继时会返回 `provider_unsupported`。\n","international/zh/models/audio/speech.md":"---\ntitle: 语音合成\ndescription: OpenAI 兼容 text-to-speech 接口说明。\n---\n\n# 语音合成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/speech` |\n\n请求体为 JSON（OpenAI `{input, voice}`），响应体为二进制音频，`Content-Type` 由上游决定并原样返回。\n\n**先确认模型声明了 OpenAI TTS 协议。** 国内生产上的 `speech-2.8-hd` / `speech-2.8-turbo` 当前走 MiniMax T2A，打本接口会返回 `model_protocol_not_offered`。这两款模型请用 [MiniMax 音频入站协议](./minimax)。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/speech \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<openai-speech-model>\",\"input\":\"你好，欢迎使用 ModelGo。\",\"voice\":\"alloy\"}' \\\n  --output speech.mp3\n```\n\n需要 MiniMax 原厂字段（音色、字幕、hex JSON、SSE）时，见[MiniMax 音频入站协议](./minimax)。\n","international/zh/models/audio/transcriptions.md":"---\ntitle: 语音转文本\ndescription: OpenAI 兼容 speech-to-text 接口说明。\n---\n\n# 语音转文本\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/transcriptions` |\n\n该接口通常以 `multipart/form-data` 上传音频文件和 `model` 字段，响应为 JSON，包含识别出的 `text`。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/zh/models/audio/translations.md":"---\ntitle: 语音翻译\ndescription: OpenAI 兼容语音翻译接口说明。\n---\n\n# 语音翻译\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/audio/translations` |\n\n上传方式与语音转文本一致，响应为 JSON。适合把音频内容翻译为目标文本输出。\n\n```bash\ncurl {{ api_endpoint }}/v1/audio/translations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"file=@./speech.m4a\"\n```\n","international/zh/models/images/edits.md":"---\ntitle: 图像编辑\ndescription: OpenAI 兼容图像编辑接口说明。\n---\n\n# 图像编辑\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/edits` |\n\n该接口使用 `multipart/form-data` 上传原图和 `model` 字段。网关会保留原始 body 与 `Content-Type` 向上游透传，因此调用时应直接使用 `POST /v1/images/edits` 的 multipart 方式。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/edits \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -F \"model=<model>\" \\\n  -F \"prompt=add a neon background\" \\\n  -F \"image=@./cat.png\"\n```\n\n如果上游模型不支持图像编辑，平台会返回 `provider_unsupported`。\n","international/zh/models/images/generations.md":"---\ntitle: 图像生成\ndescription: OpenAI 兼容图像生成接口说明。\n---\n\n# 图像生成\n\n| 方法 | 路径 |\n| --- | --- |\n| `POST` | `/v1/images/generations` |\n\n请求体遵循 OpenAI Images 兼容格式，平台将其透传到支持图像生成的上游 Provider。核心入口是 `POST /v1/images/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a cat in neon city\"}'\n```\n\n常见可选字段包括 `size`、`quality`、`n` 等，是否生效取决于实际路由到的上游模型能力。\n\n## 已验证限制（Seedream）\n\n`doubao-seedream-5.0-lite` 在 `size=1024x1024` 时上游拒绝：HTTP 400、`error_class=provider_invalid`，要求像素总数至少 3686400（约 1920×1920）。改用 `2048x2048` 后于 2026-09-10 国内生产返回 200。完整 curl 见[接口清单](../../../quickstart/openapi)。\n","international/zh/models/images/qwen-image.md":"---\ntitle: 千问图像\ndescription: 调用 qwen-image-3.0 / qwen-image-3.0-pro：OpenAI 兼容与百炼 DashScope 原生两条同步入站通道、文生图与图生图（1-3 张参考图）、size 的两种分隔符写法与 1k / 2k 分辨率档位。百炼官方 SDK 改 base_url 即可直连。\n---\n\n# 千问图像\n\n## 模型\n\n| 模型 | 输出分辨率 | 说明 |\n| --- | --- | --- |\n| `qwen-image-3.0-pro` | 总像素 512×512 – 2048×2048 | Pro 系列，2k 档单价高于 1k 档 |\n| `qwen-image-3.0` | 同上 | 标准版，两个档位同价 |\n\n> **可用性与价格按区域不同。** 接入前请先确认该区域是否提供这两个模型 —— 见[接口清单](../../../quickstart/openapi)。\n\n两个模型都同时支持**文生图（T2I）**和**图生图 / 图像编辑（I2I）**：不传参考图是文生图，传 1–3 张参考图是图生图。图像**同步返回**，无需轮询。\n\n> **不支持异步任务通道。** 这一族只在同步接口上服务；打 `/v1/content_generation/tasks` 会被拒。\n\n## 两条入站通道\n\n同一个模型有两种调用写法，能力完全一致，按你现有代码的形状选：\n\n| 通道 | 路径 | 适合谁 |\n| --- | --- | --- |\n| OpenAI 兼容 | `POST /v1/images/generations` | 已按 OpenAI Images 协议或 OpenAI SDK 开发的应用，只改 `base_url` 与 `model` |\n| 百炼原生 | `POST /api/v1/services/aigc/multimodal-generation/generation` | 已在用百炼 DashScope SDK 的应用，只改 `base_url` |\n\n> **两条通道的 `size` 分隔符不同，且互不接受**：OpenAI 兼容通道用字母 `x`（`1024x1024`），百炼原生通道用星号 `*`（`1024*1024`）。写错的那一侧会返回 `400` 并点名正确的分隔符，**不会**被静默改写 —— 这是为了让协议混用尽早显形，而不是在别处出更难查的问题。\n\n## 1. OpenAI 兼容通道\n\n`POST {{ api_endpoint }}/v1/images/generations`\n\n### 文生图\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"一只毛茸茸的橘猫坐在阳光下的窗台上，午后光线，胶片质感\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n### 图生图 / 图像编辑\n\n不用 multipart，参考图放在请求体顶层的 `image` 字段：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"prompt\": \"保留这位女性的面部特征，把服装换成香槟色真丝衬衫与深灰西装外套\",\n    \"image\": [\"https://example-cdn.com/portrait.png\"],\n    \"size\": \"1024x1024\",\n    \"prompt_extend\": true\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"created\": 1788339600,\n  \"data\": [{\"url\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}],\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 0, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  }\n}\n```\n\n- 图像格式为 PNG，**链接有效期 24 小时**，请及时下载，不要持久化该 URL。\n- `usage` 是**图片张数与档位**，不是 token 用量 —— 这一族的计费完全按张，见「计费口径」。\n- 传 `response_format: \"b64_json\"` 不会报错，但会被忽略，响应中仍是图像 URL。\n\n### 使用 OpenAI SDK\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n    timeout=600.0,   # 出图耗时较长，实测单张 40-60 秒\n)\n\nresp = client.images.generate(\n    model=\"qwen-image-3.0-pro\",\n    prompt=\"一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感\",\n    size=\"1024x1024\",\n    n=1,\n    extra_body={\"prompt_extend\": True},   # 扩展字段走 extra_body\n)\nprint(resp.data[0].url)\n```\n\n`image` / `negative_prompt` / `seed` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark` 不是 OpenAI 官方参数，用 OpenAI SDK 时通过 `extra_body` 传入；直接发 HTTP 请求时放在请求体顶层即可。\n\n## 2. 百炼原生通道\n\n`POST {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation`\n\n请求与响应两头都是百炼原样的形状，网关不做翻译。\n\n```bash\ncurl {{ api_endpoint }}/api/v1/services/aigc/multimodal-generation/generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen-image-3.0-pro\",\n    \"input\": {\n      \"messages\": [\n        {\n          \"role\": \"user\",\n          \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫\"}\n          ]\n        }\n      ]\n    },\n    \"parameters\": {\"size\": \"1024*1024\", \"n\": 1, \"prompt_extend\": true}\n  }'\n```\n\n### 响应\n\n```json\n{\n  \"output\": {\n    \"choices\": [\n      {\n        \"finish_reason\": \"stop\",\n        \"message\": {\n          \"role\": \"assistant\",\n          \"content\": [{\"image\": \"https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx\"}]\n        }\n      }\n    ]\n  },\n  \"usage\": {\n    \"output_width\": 1024, \"output_height\": 1024,\n    \"input_image_count\": 1, \"input_image_type\": \"qima_input_1k\",\n    \"output_image_count\": 1, \"output_image_type\": \"qima_output_1k\"\n  },\n  \"request_id\": \"571ae02f-5c9d-436c-83c2-f221e6df0xxx\"\n}\n```\n\n### 这条通道的约束\n\n- `input.messages` **有且只有一个**对象，`role` 必须是 `user`（仅支持单轮对话）。\n- `content` 里**有且只有一个** `{\"text\": ...}`，不传或传多个都会 `400`。\n- `{\"image\": ...}` 0–3 个：0 个是文生图，1–3 个是图生图。\n- 生成参数放在 `parameters` 下（不是顶层）：`size` / `n` / `seed` / `negative_prompt` / `prompt_extend` / `prompt_extend_mode` / `enable_thinking` / `watermark`。\n- 使用百炼官方 SDK（`dashscope`）时，把 `dashscope.base_http_api_url` 指向 `{{ api_endpoint }}/api/v1`、`api_key` 换成 ModelGo API Key 即可。\n\n## 3. 参数说明\n\n| 字段 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | `qwen-image-3.0-pro` / `qwen-image-3.0` |\n| `prompt`（兼容通道）/ `content[].text`（原生通道） | string | 必填，非空。支持中英文，建议不超过 4500 token |\n| `image`（兼容通道）/ `content[].image`（原生通道） | string / string[] | 参考图，1–3 张。**不能传 `null` 或空数组** |\n| `size` | string | 兼容通道 `宽x高`，原生通道 `宽*高`；不传则由模型按提示词自动推荐分辨率 |\n| `n` | int | 输出张数 1–6，缺省 1。**必须是整数**，传字符串形式（如 `\"1\"`）返回 `400` |\n| `negative_prompt` | string | 反向提示词 |\n| `seed` | int | 随机数种子，`0` – `2147483647`。固定种子可让结果相对稳定 |\n| `prompt_extend` | boolean | 是否开启提示词智能改写，缺省 `true`（建议开启） |\n| `prompt_extend_mode` | string | `direct`（缺省，T2I / I2I 均支持）/ `agent`（更精细，**仅文生图**） |\n| `enable_thinking` | boolean | 思考模式，缺省 `true`。提升出图质量但增加耗时。仅在 `prompt_extend=true` 时生效 |\n| `watermark` | boolean | 是否加水印，缺省 `false` |\n\n### 参数校验在调用前完成\n\n下列请求在**创建时**就被拒（HTTP `400`），不会打到上游、不产生费用：\n\n- `n` 不是 1–6 的整数，或写成了字符串 / 小数；\n- `size` 的总像素不在 512×512 – 2048×2048 之间，或宽高比超出 1:8 – 8:1；\n- `size` 用了另一条通道的分隔符（错误信息会点名该用 `x` 还是 `*`）；\n- `image` 为 `null`、空数组，或超过 3 张；\n- `prompt_extend_mode: \"agent\"` 与 `image` 同时出现（APE 仅支持文生图）；\n- `seed` 超出 `0` – `2147483647`；\n- 原生通道上 `messages` 不是恰好一个、或 `content` 里的 `text` 不是恰好一个。\n\n### 参考图的要求\n\n- 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF。\n- 建议宽高均在 384 – 2048 像素之间，单张不超过 10 MB。\n- 支持公网 URL（HTTP / HTTPS）或 Base64（`data:{MIME_type};base64,{base64_data}`）。\n- 公网 URL 必须是上游能直接 `GET` 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。部分站点对非浏览器抓取返回 403，会导致请求失败。\n\n## 4. 计量口径\n\n**这一族按张计量，不按 token。** `usage` 里给的是图片张数与档位，不是 token 用量：\n\n| 字段 | 含义 |\n| --- | --- |\n| `output_image_count` | 本次实际交付的图片张数 |\n| `output_image_type` | 本次命中的输出档位：`qima_output_1k` 或 `qima_output_2k` |\n| `input_image_count` | 请求提供的参考图张数（文生图为 0） |\n| `input_image_type` | 输入档位：`qima_input_1k` 或 `qima_input_2k` |\n\n**档位按「输出」像素面积判定**：面积 ≤ 2,250,000（即 1500×1500）为 `1k`，更大为 `2k`。**输入图的档位同样按输出面积判定**，不是按参考图自己的尺寸 —— 这是上游的口径。\n\n文生图没有参考图，`input_image_count` 为 0，只计量交付的图片。请求 `n` 张就计量 `n` 张，不是一张。\n\n## 5. 完整示例（Python，百炼官方 SDK）\n\n```python\nimport os\nimport dashscope\nfrom dashscope import MultiModalConversation\n\ndashscope.base_http_api_url = \"{{ api_endpoint }}/api/v1\"\n\nresponse = MultiModalConversation.call(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    model=\"qwen-image-3.0-pro\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"image\": \"https://example-cdn.com/portrait.png\"},\n            {\"text\": \"把服装换成香槟色真丝衬衫，背景换成现代简约咖啡店\"},\n        ],\n    }],\n    prompt_extend=True,\n)\n\nif response.status_code == 200:\n    print(response.output.choices[0].message.content[0][\"image\"])\nelse:\n    print(f\"Error: {response.code} - {response.message}\")\n```\n","international/zh/models/realtime/api.md":"---\ntitle: Realtime API 参考\ndescription: GET /api-ws/v1/realtime（WebSocket）的握手、事件与音频格式说明。\n---\n\n# Realtime API 参考：`GET /api-ws/v1/realtime`\n\n本接口是一个 WebSocket 长连接。网关把百炼 **Qwen-Omni-Realtime** 协议原样双向转发，**不做协议转换**；事件字段的完整定义与工具调用（Function Calling / MCP）事件以百炼官方[客户端事件](https://help.aliyun.com/zh/model-studio/client-events)与[服务端事件](https://help.aliyun.com/zh/model-studio/server-events)为准。本页覆盖接入所需的握手、鉴权、事件清单与音频约定。\n\n## 请求\n\n| 项 | 值 |\n| --- | --- |\n| 方法 | `GET`（WebSocket 升级） |\n| 路径 | `/api-ws/v1/realtime` |\n| 完整地址 | `{{ ws_endpoint }}/api-ws/v1/realtime?model=<逻辑模型名>` |\n| Query | `model`（必填）——平台逻辑模型名，不是上游模型名 |\n| Header | `Authorization: Bearer <mgk_ API Key>`（必填） |\n| Header | `X-Request-ID`（可选）——透传到调用日志，`request_id` 以 `gw_rt_` 开头 |\n\n只有 `public_protocols` 声明了 `dashscope_realtime` 的逻辑模型才能走本入口。\n\n## 握手错误码 {#handshake-errors}\n\n握手（升级为 WebSocket 之前）失败时，以 HTTP 状态码返回，body 为：\n\n```json\n{\"error\":{\"type\":\"invalid_request_error\",\"code\":\"unauthorized\",\"message\":\"unauthorized: api_key_not_found\"}}\n```\n\n| HTTP | `code` | 触发条件 | 实测 message（cn 生产，2026-10-08） |\n| --- | --- | --- | --- |\n| 401 | `unauthenticated` | 未携带 API Key | `missing api key` |\n| 401 | `unauthorized` | Key 无效 / 已禁用 | `unauthorized: api_key_not_found` |\n| 404 | `model_not_found` | 模型不在目录 | `unknown model: <model>` |\n| 403 | `model_protocol_not_offered` | 模型未声明 `dashscope_realtime` | `model <model> is not offered on the realtime protocol` |\n| 404 | `no_route` | 策略（含回落链）中没有该模型的路由 | `no route for model <model>` |\n| 503 | `no_provider` | 有路由但无可用上游实例 | `no provider available for <model>` |\n| 402 | `insufficient_funds` / `budget_exceeded` | 预授权失败（余额/预算不足） | `billing: insufficient funds` |\n\n握手通过（HTTP 101）后再出现的问题，会以带内 `error` 事件下发，然后关闭连接：\n\n```json\n{\"type\":\"error\",\"error\":{\"type\":\"upstream_error\",\"code\":\"provider_unavailable\",\"message\":\"upstream connection failed\"}}\n```\n\n## 会话配置 `session.update`\n\n建连后服务端先发 `session.created`，客户端用 `session.update` 覆盖配置，配置合法则回 `session.updated`。常用字段：\n\n| 字段 | 可选值 | 默认 |\n| --- | --- | --- |\n| `modalities` | `[\"text\",\"audio\"]` / `[\"text\"]` | `[\"text\",\"audio\"]` |\n| `voice` / `audio.output.voice` | 见百炼音色列表 | `Tina` |\n| `turn_detection` | `{\"type\":\"server_vad\"}` / `{\"type\":\"semantic_vad\"}` / `null` | 服务端 VAD |\n| `audio.input.format` | `{\"type\":\"pcm\",\"sample_rate\":16000}` | `pcm` / 16000 |\n| `audio.output.format` | `{\"type\":\"pcm\",\"sample_rate\":24000}` | `pcm` / 24000 |\n| `instructions` | 任意文本 | 空 |\n| `input_audio_transcription` | `{\"model\":\"qwen3-asr-flash-realtime\"}` / `null` | 开启 |\n\n`turn_detection: null` 表示关闭服务端 VAD，改由客户端手动提交与触发响应。\n\n## 客户端事件\n\n| 事件 | 作用 |\n| --- | --- |\n| `session.update` | 更新会话配置（模态、音色、音频格式、VAD、instructions 等） |\n| `input_audio_buffer.append` | 追加 Base64 音频到输入缓冲区 |\n| `input_image_buffer.append` | 追加 Base64 图片（JPG/JPEG，需先发过音频） |\n| `input_audio_buffer.commit` | 手动模式下提交音频缓冲区（提交不触发响应） |\n| `input_audio_buffer.clear` | 清空音频缓冲区 |\n| `conversation.item.create` | 创建对话项：纯文本输入、`function_call_output`、`mcp_approval_response` |\n| `response.create` | 触发一次模型响应 |\n| `response.cancel` | 取消正在进行的响应（打断） |\n\n## 服务端事件\n\n| 事件 | 说明 |\n| --- | --- |\n| `session.created` / `session.updated` | 会话建立 / 配置生效 |\n| `input_audio_buffer.speech_started` / `speech_stopped` | VAD 检测到用户开始 / 停止说话（打断依据） |\n| `input_audio_buffer.committed` / `cleared` | 音频缓冲区提交 / 清空 |\n| `conversation.item.created` | 对话项已创建 |\n| `conversation.item.input_audio_transcription.delta` / `.completed` | 输入语音转写（流式预览 / 最终结果） |\n| `response.created` | 一轮响应开始 |\n| `response.output_item.added` / `response.content_part.added` | 输出项 / 内容片段开始 |\n| `response.text.delta` / `response.text.done` | 仅文本模式的流式 / 完整文本 |\n| `response.audio_transcript.delta` / `.done` | 含音频模式下，音频对应的文本 |\n| `response.audio.delta` / `response.audio.done` | Base64 输出音频（24 kHz PCM）/ 音频结束 |\n| `response.output_item.done` / `response.content_part.done` | 输出项 / 内容片段完成 |\n| `response.done` | 一轮响应结束，`response.usage` 携带分模态 token 用量 |\n\n工具调用（`response.function_call_arguments.delta` / `.done`）与 MCP 相关事件（`mcp_*`）字段见百炼服务端事件文档。\n\n一次完整语音问答的实测事件序（cn 生产，2026-10-08）：\n\n```text\nsession.created\nsession.updated\ninput_audio_buffer.speech_started\ninput_audio_buffer.speech_stopped\ninput_audio_buffer.committed\nconversation.item.input_audio_transcription.completed\nresponse.created\nresponse.output_item.added\nresponse.audio_transcript.delta …\nresponse.audio.delta …\nresponse.done\n```\n\n## 音频格式\n\n| 方向 | 格式 | 事件 / 字段 |\n| --- | --- | --- |\n| 上行（输入） | 16000 Hz、16-bit 小端、单声道 PCM，Base64 | `input_audio_buffer.append` 的 `audio` |\n| 下行（输出） | 24000 Hz、16-bit 小端、单声道 PCM，Base64 | `response.audio.delta` 的 `delta` |\n\n实测满 100 ms 一包推送输入音频（3200 字节 / 帧）最稳。`input_audio_buffer.append` 只入缓冲，不触发响应；是否提交由 VAD 或客户端 `input_audio_buffer.commit` 决定。\n\n## VAD 与打断\n\n- `turn_detection` 非 `null` 时，服务端自动检测语音起止并在静音 `silence_duration_ms`（默认 800ms）后自动提交、触发响应。\n- 用户再次说话：服务端下发 `input_audio_buffer.speech_started` → 客户端**停止播放**并发 `response.cancel` → 收到 `response.done`（cancelled）→ 新一轮。\n- `turn_detection: null` 为手动模式：客户端在录音结束后依次发送 `input_audio_buffer.commit`（等 `input_audio_buffer.committed`）与 `response.create`。\n\n## 用量与计费\n\n每轮响应的 `response.done.response.usage` 携带分模态 token：\n\n```json\n{\n  \"type\": \"response.done\",\n  \"response\": {\n    \"status\": \"completed\",\n    \"usage\": {\n      \"total_tokens\": 843,\n      \"input_tokens\": 693,\n      \"output_tokens\": 150,\n      \"input_tokens_details\": { \"text_tokens\": 693 },\n      \"output_tokens_details\": { \"text_tokens\": 28, \"audio_tokens\": 122 }\n    }\n  }\n}\n```\n\n网关按整段连接的累计用量在关闭时结算：连接时按会话级预估预授权（当前约 ¥1.2，余额不足则握手 `402`），关闭连接后按实际用量多退少补，无用量则释放预授权。详见[使用指南](./guide#billing)。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 上游限流 | 60 RPM |\n\n## 相关\n\n- [实时语音（Realtime）模型使用指南](./guide)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","international/zh/models/realtime/guide.md":"---\ntitle: 实时语音（Realtime）模型\ndescription: 通过 WebSocket 接入 Qwen-Omni-Realtime，实现实时语音对话、打断与全模态输入。\n---\n\n# 实时语音（Realtime）模型\n\nRealtime 类模型**不走** `/v1/chat/completions`，只能通过 WebSocket 长连接调用。网关把百炼 Qwen-Omni-Realtime 协议**原样双向转发**，不做任何协议转换：你按百炼协议发事件，也按百炼协议收事件。本文给出接入方式、可运行的最小示例与计费口径；逐字段的事件与错误定义见[API 参考](./api)。\n\n## 能做什么\n\n- **实时语音对话**：边说边回，端到端流式返回文本与音频。\n- **语音打断**：用户再次开口时，服务端下发 `input_audio_buffer.speech_started`；客户端停播并发 `response.cancel` 打断当前回复。\n- **全模态输入**：流式音频、图片（可由视频抽帧实时采集）、纯文本。\n- **文本 + 音频输出**：模型同时产出文本与语音。\n\n## 适用模型\n\n一个逻辑模型要能走本入口，必须在模型目录的 `public_protocols` 中声明 `dashscope_realtime`。目前上架的 realtime 模型是 `qwen3.8-omni-flash-realtime`（以模型广场实际上架为准）。可在 [{{ console_endpoint }}]({{ console_endpoint }}) 的模型广场确认某个模型是否提供了该协议。\n\n## 接入\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `{{ ws_endpoint }}/api-ws/v1/realtime` |\n| Query | `model=<逻辑模型名>`（必填） |\n| 鉴权 | `Authorization: Bearer <mgk_ API Key>` |\n| 请求 ID | 可选 `X-Request-ID`；调用日志里 `request_id` 以 `gw_rt_` 开头 |\n\n握手阶段的失败会直接返回 HTTP 状态码（如 Key 无效 `401 unauthorized`、模型未声明 realtime 协议 `403 model_protocol_not_offered`、余额不足 `402`），完整清单见[API 参考](./api#handshake-errors)。\n\n## 最小示例\n\n下面示例在**服务端**运行：用 `mgk_` API Key 建连，配置会话，推送一段 16 kHz PCM 语音，提交后请求回复，并把返回的 24 kHz PCM 写入 `reply.pcm`。\n\n:::note\n- 浏览器原生 `WebSocket` 构造器**不能携带 `Authorization` 头**，所以不能把 API Key 直接放进浏览器连接。\n- 浏览器采集麦克风后，需经你自己的服务端中转（服务端持有 Key 并建连转发），或使用具备鉴权的服务端代理。\n- 下面 Python / Node.js 示例均为服务端代码，可直接复制运行。\n:::\n\n准备输入：把麦克风录音或一段 **16 kHz、16-bit 小端、单声道、无文件头**的 PCM 存为 `input.pcm`。若手上是 WAV，先提取裸 PCM：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"input.wav\", \"rb\") as f:\n    assert (f.getnchannels(), f.getframerate(), f.getsampwidth(), f.getcomptype()) == (1, 16000, 2, \"NONE\")\n    Path(\"input.pcm\").write_bytes(f.readframes(f.getnframes()))\n```\n\nPython（`pip install websocket-client`）：\n\n```python\nimport base64\nimport json\nimport os\nfrom pathlib import Path\nimport websocket\n\nAPI_KEY = os.environ[\"MODELGO_API_KEY\"]\nMODEL = \"qwen3.8-omni-flash-realtime\"\nURL = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL\n\naudio = Path(\"input.pcm\").read_bytes()  # 16 kHz / 16-bit LE / mono / headerless\nif not audio or len(audio) % 2:\n    raise ValueError(\"provide non-empty 16-bit mono PCM audio\")\n\nws = websocket.create_connection(\n    URL, header=[\"Authorization: Bearer \" + API_KEY], timeout=30\n)\n\ndef recv():\n    ev = json.loads(ws.recv())\n    if ev[\"type\"] == \"error\":\n        raise RuntimeError(ev[\"error\"])\n    return ev\n\ntry:\n    while recv()[\"type\"] != \"session.created\":\n        pass\n    ws.send(json.dumps({\n        \"type\": \"session.update\",\n        \"session\": {\n            \"modalities\": [\"text\", \"audio\"],\n            \"turn_detection\": None,\n            \"audio\": {\n                \"input\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 16000}},\n                \"output\": {\"format\": {\"type\": \"pcm\", \"sample_rate\": 24000}},\n            },\n        },\n    }))\n    while recv()[\"type\"] != \"session.updated\":\n        pass\n    for i in range(0, len(audio), 3200):  # 100ms per frame\n        ws.send(json.dumps({\n            \"type\": \"input_audio_buffer.append\",\n            \"audio\": base64.b64encode(audio[i:i + 3200]).decode(\"ascii\"),\n        }))\n    ws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))\n    while recv()[\"type\"] != \"input_audio_buffer.committed\":\n        pass\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n    with open(\"reply.pcm\", \"wb\") as out:  # 24 kHz / 16-bit LE / mono\n        while True:\n            ev = recv()\n            if ev[\"type\"] == \"response.audio.delta\":\n                out.write(base64.b64decode(ev[\"delta\"]))\n            elif ev[\"type\"] in (\"response.audio_transcript.delta\", \"response.text.delta\"):\n                print(ev[\"delta\"], end=\"\", flush=True)\n            elif ev[\"type\"] == \"response.done\":\n                print(\"\\nusage:\", ev[\"response\"].get(\"usage\"))\n                break\nfinally:\n    ws.close()\n```\n\nJavaScript / Node.js（`npm install ws`）：\n\n```js\nimport fs from \"node:fs\";\nimport WebSocket from \"ws\";\n\nconst API_KEY = process.env.MODELGO_API_KEY;\nconst MODEL = \"qwen3.8-omni-flash-realtime\";\nconst url = \"{{ ws_endpoint }}/api-ws/v1/realtime?model=\" + MODEL;\n\nconst audio = fs.readFileSync(\"input.pcm\"); // 16 kHz / 16-bit LE / mono\nconst out = fs.createWriteStream(\"reply.pcm\"); // 24 kHz / 16-bit LE / mono\nconst ws = new WebSocket(url, { headers: { Authorization: `Bearer ${API_KEY}` } });\n\nws.on(\"message\", (raw) => {\n  const ev = JSON.parse(raw.toString());\n  switch (ev.type) {\n    case \"session.created\":\n      ws.send(JSON.stringify({\n        type: \"session.update\",\n        session: {\n          modalities: [\"text\", \"audio\"],\n          turn_detection: null,\n          audio: {\n            input: { format: { type: \"pcm\", sample_rate: 16000 } },\n            output: { format: { type: \"pcm\", sample_rate: 24000 } },\n          },\n        },\n      }));\n      break;\n    case \"session.updated\":\n      for (let i = 0; i < audio.length; i += 3200) {\n        ws.send(JSON.stringify({\n          type: \"input_audio_buffer.append\",\n          audio: audio.subarray(i, i + 3200).toString(\"base64\"),\n        }));\n      }\n      ws.send(JSON.stringify({ type: \"input_audio_buffer.commit\" }));\n      break;\n    case \"input_audio_buffer.committed\":\n      ws.send(JSON.stringify({ type: \"response.create\" }));\n      break;\n    case \"response.audio.delta\":\n      out.write(Buffer.from(ev.delta, \"base64\"));\n      break;\n    case \"response.audio_transcript.delta\":\n    case \"response.text.delta\":\n      process.stdout.write(ev.delta);\n      break;\n    case \"response.done\":\n      console.log(\"\\nusage:\", JSON.stringify(ev.response.usage));\n      ws.close();\n      out.end();\n      break;\n    case \"error\":\n      console.error(\"error:\", ev.error);\n      ws.close();\n      break;\n  }\n});\nws.on(\"error\", console.error);\n```\n\n把返回的 `reply.pcm`（24 kHz、16-bit、单声道）封装成可播放的 WAV：\n\n```python\nimport wave\nfrom pathlib import Path\n\nwith wave.open(\"reply.wav\", \"wb\") as f:\n    f.setnchannels(1)\n    f.setsampwidth(2)\n    f.setframerate(24000)\n    f.writeframes(Path(\"reply.pcm\").read_bytes())\n```\n\n只想验证链路时，也可以不传音频：发送一条 `conversation.item.create`（`content` 为 `input_text`），再发 `response.create`，即可只拿文本回复。\n\n## 会话配置\n\n建连后服务端先发 `session.created`（含默认配置），客户端用 `session.update` 覆盖。常用字段：\n\n| 字段 | 说明 |\n| --- | --- |\n| `modalities` | `[\"text\",\"audio\"]`（默认，文本+音频）或 `[\"text\"]`（仅文本） |\n| `voice` | 输出音色，默认 `Tina`；建议使用 `audio.output.voice` |\n| `turn_detection` | 服务端 VAD：`{\"type\":\"server_vad\"}` 或 `{\"type\":\"semantic_vad\"}`；设为 `null` 由客户端手动 commit |\n| `audio.input.format` | 输入音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":16000}` |\n| `audio.output.format` | 输出音频格式，如 `{\"type\":\"pcm\",\"sample_rate\":24000}` |\n| `instructions` | 系统人设 |\n| `audio.input.transcription` | 输入转写，服务端会自动开启（模型 `qwen3-asr-flash-realtime`） |\n\n历史兼容字段 `input_audio_format` / `output_audio_format` 仍可用，但新接入建议使用 `audio.input.format` / `audio.output.format`。\n\n## 打断\n\n`turn_detection` 非 `null` 时由服务端 VAD 驱动轮次。用户再次开口会触发：\n\n1. 服务端下发 `input_audio_buffer.speech_started`；\n2. 客户端**停止播放**已缓冲的回复音频，并发送 `response.cancel`；\n3. 服务端随后下发 `response.done`（状态为 cancelled），开始新一轮。\n\n手动模式（`turn_detection: null`）下，客户端负责在录音结束后发送 `input_audio_buffer.commit` 与 `response.create`。\n\n## 计费 {#billing}\n\n- **按 token 分模态计价**：输入分文本/图片/视频与音频两档，输出分文本与音频两档。输出语音时，音频与其对应的文本**分别**计费。\n- **连接时预授权**：建连时按一个会话级预估冻结一笔余额（当前配置约 ¥1.2）。余额不足以覆盖预授权时，握手直接返回 `402`，不建立连接。\n- **关闭连接后按实际用量结算**：按本次连接内所有 `response.done` 的 `usage` 累计结算，多退少补；整段会话没有产生任何用量时释放预授权、不扣费。\n\n价格以控制台模型页为准；例如国内生产 `qwen3.8-omni-flash-realtime` 的单价（元/百万 token）：输入 文本/图片/视频 `1.5`、输入音频 `6`、输出文本 `4.5`、输出音频 `12`。\n\n## 限制\n\n| 项 | 值 |\n| --- | --- |\n| 单连接最长时长 | **30 分钟**（网关强制；到达上限即关闭连接并结算） |\n| 全部输入 Token 上限 | 196,608 |\n| 最大输出 Token | 65,536 |\n| 音频历史 | 最多 100 轮 / 累计 600 秒 |\n| 视频历史 | 最多 50 轮 / 累计 240 秒 |\n| 上游限流 | 60 RPM |\n\n## 下一步\n\n- [API 参考：`GET /api-ws/v1/realtime`](./api)\n- [认证鉴权](../../quickstart/authentication)\n- [错误码与限流](../../quickstart/errors)\n","international/zh/models/rerank/rerank.md":"---\ntitle: Rerank\ndescription: 对候选文档按相关性重排序的 Rerank 接口。\n---\n\n# Rerank\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/rerank` | 对文档按与查询的相关性重排序 |\n| `POST` | `/v1/reranks` | 同上（别名，等价于 `/v1/rerank`） |\n\nRerank 接口接收一段查询与若干候选文档，按相关性返回排序后的结果，常用于检索增强（RAG）场景的精排。`/v1/rerank` 与 `/v1/reranks` 是同一能力的两条等价路径。\n\n```bash\ncurl {{ api_endpoint }}/v1/rerank \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"query\":\"ModelGo 支持哪些协议\",\n    \"documents\":[\n      \"兼容 OpenAI 与 Anthropic 协议\",\n      \"今天的天气不错\",\n      \"支持图像、视频、向量、音频能力\"\n    ],\n    \"top_n\":3\n  }'\n```\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名；请求体按上游 Rerank 协议透传，具体字段（如 `top_n`、`return_documents`）是否生效取决于路由到的上游模型。\n- 返回结果通常包含每条文档的相关性得分与排序序号。\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","international/zh/models/text/generation.md":"---\ntitle: 文本生成\ndescription: OpenAI Responses、Chat Completions 兼容入口与 Anthropic Messages 的统一说明。\n---\n\n# 文本生成\n\n文本能力当前覆盖以下公开入口，推荐优先使用 `POST /v1/responses`，其余入口用于兼容已有 SDK 和原生 Claude 客户端。\n\n| 协议 | 方法与路径 | 用途 |\n| --- | --- | --- |\n| OpenAI | `POST /v1/responses` | 新项目优先使用的统一文本生成接口 |\n| OpenAI | `POST /v1/chat/completions` | 兼容大量现有 OpenAI SDK 的对话补全接口 |\n| OpenAI | `POST /v1/completions` | 旧版文本补全接口，仅用于兼容历史调用链 |\n| Anthropic | `POST /v1/messages` | Claude 原生消息格式接口 |\n| OpenAI | `GET /v1/models` | 查询当前路由可用的逻辑模型清单 |\n\n## OpenAI Responses\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"input\":\"用三句话介绍 ModelGo。\"\n  }'\n```\n\n适合新接入和统一封装场景。请求体、流式返回和 `usage` 字段遵循 OpenAI Responses 兼容格式。\n\n## OpenAI Chat Completions 兼容入口 {#chat-completions}\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合已经绑定 OpenAI SDK 或历史对话补全调用链的客户端。推荐新项目优先迁移到 `POST /v1/responses`。\n\n## OpenAI Completions（旧版补全）\n\n```bash\ncurl {{ api_endpoint }}/v1/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"prompt\":\"用三句话介绍 ModelGo。\",\n    \"max_tokens\":256\n  }'\n```\n\n旧版文本补全接口，仅用于兼容仍在使用 `prompt` 的历史调用链，新项目请使用上面的 Responses / Chat Completions。`stream` 同样以 SSE 返回。多数当前对话模型未声明此协议：`qwen3.6-flash` 实测 HTTP 400、`model_protocol_not_offered`。\n\n## Anthropic Messages {#anthropic-messages}\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"<model>\",\n    \"max_tokens\":1024,\n    \"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]\n  }'\n```\n\n适合直接复用 Claude 原生消息格式的客户端。该入口保持 `/v1/messages` 的事件流语义，不会在网关侧改造成 OpenAI SSE 帧。\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n`GET /v1/models` 返回该 API Key 绑定策略所允许的逻辑模型（结合平台模型目录），不会在请求时实时探测上游能力，可能与控制台展示略有差异；计费、策略以控制台和绑定策略为准。\n\n## 关键约定\n\n- `model` 填写平台逻辑模型名\n- `GET /v1/models` 可用，清单由 API Key 绑定的策略与平台模型目录决定\n- OpenAI 与 Anthropic 协议都可能返回上游原样 `usage`\n- 流式失败时可能不会发送 `data: [DONE]`，请以数据块中的 `error` 判断\n- 如果上游或路由不支持当前协议，平台会返回 `provider_unsupported` 或协议不兼容错误\n\n详见[认证鉴权](../../../quickstart/authentication) 与 [错误码与限流](../../../quickstart/errors)。\n","international/zh/models/vectors/embeddings.md":"---\ntitle: Embeddings\ndescription: OpenAI 兼容向量嵌入接口说明。\n---\n\n# Embeddings\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/embeddings` | 文本向量嵌入 |\n| `POST` | `/v1/embeddings/multimodal` | 多模态（图文等）向量嵌入 |\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":\"hello\"}'\n```\n\n`input` 可以是单条字符串，也可以是字符串数组。返回结果遵循 OpenAI Embeddings 兼容格式。\n\n## 多模态 Embeddings\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings/multimodal \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"input\":[{\"type\":\"text\",\"text\":\"a cat\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/cat.png\"}}]}'\n```\n\n面向同时包含文本与图像等内容的向量嵌入场景。`input` 结构与具体模型的多模态能力相关，是否生效取决于路由到的上游模型。\n","international/zh/models/video/ark.md":"---\ntitle: Seedance\ndescription: 用 Ark 原厂路径调用平台托管的 Seedance 异步视频任务，请求体与响应体都按 Ark 内容生成协议书写。\n---\n\n# Seedance\n\n豆包 Seedance 系列（`doubao-seedance-*`）除标准视频协议外，还可以用**火山方舟（Ark）原厂路径**调用，\n请求体与响应体按 Ark 内容生成协议书写：\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 创建内容生成任务（视频） |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见下） |\n\n这是**平台托管**通道：路径是 Ark 自己的，但请求走的是网关标准的异步任务流水线，与\n[通用异步内容生成任务](./async-tasks)完全同一条链路，只是换了 Ark 的路径拼写。因此它同样享受\n维度计费、任务落库、产物持久化与预扣/结算的全部保障。\n\n## 创建任务\n\n请求体按 Ark 内容生成协议书写，`model` 填**平台逻辑模型名**（如 `doubao-seedance-2.0-mini`）：\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一只霓虹都市里的猫\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5\n  }'\n```\n\n`content` 里除文本外还可以带图片/视频，元素用 `role` 标明用途；**素材组合决定生成模式，生成模式又决定哪些参数合法**：\n\n| content 元素 | `role` | 生成模式 |\n| --- | --- | --- |\n| 只有 `text` | — | 文生视频（t2v） |\n| `image_url` | `first_frame` | 首帧图生视频（i2v） |\n| `image_url` | `first_frame` + `last_frame` | 首尾帧（flf2v） |\n| `image_url` / `video_url` | `reference_image` / `reference_video` | 多模态参考生视频 |\n\n### 参数与生成模式约束\n\n`resolution` / `ratio` / `duration` 的合法取值**随模型而异**（例如 Seedance 2.0 的 Fast 与 Mini 不支持\n`1080p`，`duration` 下限是 4 秒）；`camera_fixed`、`generate_audio`、`return_last_frame`、`watermark`\n等 Ark 扩展参数**还随生成模式而异**。携带当前模型/模式不支持的参数，会在创建时被上游拒绝\n（`400` `provider_invalid`）。已知一例：\n\n- **`camera_fixed` 在首尾帧（同时带 `first_frame` + `last_frame`）场景不被支持**，携带它会被上游拒\n  （`camera_fixed ... must be empty`）。首尾帧本身已约束镜头；确需固定镜头请改用文生 / 单首帧等\n  支持该参数的模式。\n\n因为本通道**不锁定上游 family**（同一逻辑模型由多家供应商承接），某参数是否被接受还取决于实际\n承接的供应商与其模型版本。请以「模型能力说明 + 上述模式约束」为准，**不要假定某模式可用的参数在\n另一种模式同样可用**。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与查询返回的就是[通用异步内容生成任务](./async-tasks)那一种 Ark 任务对象——同一条流水线，\n响应报文与字段语义（`status` 取值、`content.video_url`、`error`、`usage` 缺省规则）与那一页完全一致，\n此处不再重复。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/ark/api/v3/contents/generations/tasks/{task_id} \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消成功后预扣会被退回（void），不产生结算。\n\n**但取消不是所有上游都支持。** 能否取消取决于承接该任务的供应商是否实现了取消能力，而这条通道\n不锁定上游 family，所以同一个逻辑模型的两次调用可能一次能取消、一次不能。两种失败：\n\n| 情况 | 响应 |\n| --- | --- |\n| 承接该任务的供应商不支持取消 | `400` / `4003` `provider_unsupported`，`endpoint not supported by provider` |\n| 任务已到终态（`succeeded` / `failed`） | `409` `task_already_terminal`，`task already finished; nothing to cancel` |\n\n取消失败时预扣不会提前退回，会等任务到终态或预扣过期后按正常结算/释放流程处理。所以**不要把\n「先创建、再取消」当成一种可靠的止损手段**。\n\n## 关键约定\n\n- **`id` 是网关任务 ID，不是上游任务 ID。** 查询、取消都只认这个 ID，请以创建响应里的 `id` 为准。\n- **响应形态是固定的。** 无论实际由哪家上游承接，创建与查询都返回同一种 Ark 任务对象，\n  不会因为路由到不同供应商而变形。\n- **该通道不锁定上游 family。** 路径拼写不参与选路：`model` 对应的逻辑模型路由到谁，就由谁承接。\n  Seedance 在平台上由多家供应商共同承接，同一个逻辑模型的两次调用可能落到不同上游，这是正常的。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），Ark 路径下没有对应端点；\n  直接使用响应里的 `content.video_url` 即可。\n- 该模型是否开放本通道，取决于它在模型目录里声明的 `public_protocols` 是否含\n  `content_generation`；未声明则返回 `4005`。可用 `GET {{ api_endpoint }}/v1/models` 核对。\n\n如果你不需要 Ark 的路径与字段风格，[OpenAI 兼容视频流](./openai-compatible)是更标准化的选择。\n","international/zh/models/video/async-tasks.md":"---\ntitle: 异步任务\ndescription: 平台统一的异步任务入口，覆盖图像、视频等需要任务式处理的内容生成能力。\n---\n\n# 异步任务\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 创建通用异步内容生成任务（图像 / 视频等） |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 轮询通用内容生成任务状态与结果 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 取消未完成的任务并退回预扣（**取决于上游是否支持**，见[Seedance 视频入站协议](./ark)的「取消任务」） |\n\n`/v1/content_generation/tasks` 是比标准 OpenAI 视频流更通用的异步任务入口，覆盖图像、视频等需要后台任务执行的生成能力。\n\n## 创建任务\n\n请求体遵循对应上游的通用生成格式，至少需要 `model`：\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"doubao-seedance-2.0-mini\",\"content\":[{\"type\":\"text\",\"text\":\"a red apple on a table\"}]}'\n```\n\n2026-09-10 国内生产：创建返回 `status=queued`、`id` 形如 `gw_…`；轮询同一 `id` 最终为 `succeeded`，并带 `resolution=720p`、`ratio=16:9`、`duration=5`。同一模型打 `POST /v1/video/generations` 为 `model_protocol_not_offered`。`DELETE` 取消在该上游上返回 `provider_unsupported`。\n\n## 轮询任务\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n创建与轮询都返回**同一种** Ark 形态的任务对象，不随实际承接的上游变化：\n\n```json\n{\n  \"id\": \"task_123\",\n  \"model\": \"<model>\",\n  \"status\": \"succeeded\",\n  \"created_at\": 1756600000,\n  \"updated_at\": 1756600120,\n  \"content\": { \"video_url\": \"https://.../video.mp4\" },\n  \"usage\": { \"completion_tokens\": 123, \"total_tokens\": 123 },\n  \"error\": null,\n  \"resolution\": \"1080p\",\n  \"ratio\": \"16:9\",\n  \"duration\": 5\n}\n```\n\n`status` 取值为 `queued` / `running` / `succeeded` / `failed`；`id` 是**网关任务 ID**，轮询与取消都只认它。\n\n## 三种拼法，同一条流水线\n\n同一条托管异步流水线有三个入站拼写，选哪个只取决于你想按谁的报文风格写客户端：\n\n| 入口 | 请求体 | 响应体 |\n| --- | --- | --- |\n| `/v1/content_generation/tasks` | 通用生成格式 | Ark 任务对象（上表） |\n| [`/ark/api/v3/contents/generations/tasks`](./ark) | Ark 内容生成原生体 | Ark 任务对象 |\n| [`/minimax/v2/video_generation`](./minimax) | MiniMax 视频生成 V2 原生体 | MiniMax 形态（`{\"task_id\"}` / `{\"task\":{…}}`） |\n\n三者的计费、任务落库、产物持久化与预扣/结算行为完全一致。\n\n## 适用场景\n\n- 你要调用的平台能力本身是异步任务，但不走 OpenAI Video 标准形态\n- 你希望统一使用平台托管的「创建任务 → 轮询结果」模型，而不是自行管理厂商原生协议\n- 你调用的是即梦等仅提供托管异步入口的视频模型\n\n## 关键约定\n\n- `model` 仍填写平台逻辑模型名，由平台决定最终路由到哪个上游实现。\n- 请求体字段取决于路由到的具体能力；响应形态则是固定的，见上文。\n- 如果你不想自己处理厂商侧的多种原生轮询协议，优先使用这一入口。\n\n如需标准 OpenAI 视频协议，见[OpenAI 兼容视频流](./openai-compatible)。\n","international/zh/models/video/minimax.md":"---\ntitle: MiniMax 视频\ndescription: 用 MiniMax 视频生成 V2 的原厂请求体与响应体调用平台托管的异步视频任务，适用于 MiniMax-H3 系列。\n---\n\n# MiniMax 视频\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/minimax/v2/video_generation` | 创建视频生成任务 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 查询任务状态与结果 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 取消未完成的任务并退回预扣 |\n\n这是 **MiniMax 视频生成 V2** 的原厂入站协议，主要面向 MiniMax-H3 系列视频模型。和 Ark 通道一样，\n它跑在平台托管的异步任务流水线上——请求体是 MiniMax 自己的形状，**响应体也按 MiniMax 的形状渲染**，\n所以照着 MiniMax 官方文档写的客户端可以直接解析。\n\n任务落在平台侧，维度计费、产物持久化、预扣/结算都照常生效。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"一个男孩在海边打篮球\" },\n      { \"type\": \"image_url\", \"image_url\": { \"url\": \"https://example.com/first.jpg\" }, \"role\": \"first_frame\" }\n    ],\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\"\n  }'\n```\n\n创建响应就是 MiniMax 文档里的裸任务句柄：\n\n```json\n{ \"task_id\": \"424010985738629\" }\n```\n\n### 请求体字段\n\n`content[]` 是多模态数组，每项由 `type` 与 `role` 共同决定它的用途：\n\n| `type` | 可用 `role` | 含义 |\n| --- | --- | --- |\n| `text` | —— | 提示词 |\n| `image_url` | `first_frame` / `last_frame` | 首帧 / 尾帧图 |\n| `image_url` | `reference_image` | 参考图 |\n| `video_url` | `reference_video` | 参考视频 |\n| `audio_url` | `reference_audio` | 参考音频 |\n\n- **首尾帧与参考素材不能混用**：带了 `first_frame` / `last_frame` 就不能再带任何 `reference_*`，\n  反之亦然——它们对应上游两种不同的生成任务。\n- `resolution`、`duration`、`ratio` 与 `content` 平级。对 MiniMax-H3，取值范围为\n  `resolution` ∈ `768P` / `2K`，`duration` 为 `4`–`15` 的整数，`ratio` ∈\n  `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`；不传时按上游缺省（`2K`、`5` 秒）执行**并按该缺省档计费**。\n- 提示词长度上限约 7000 字符。\n- 具体支持哪些取值仍以 `model` 对应的逻辑模型配置为准。\n\n## 查询任务\n\n```bash\ncurl {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n查询响应是 `task` 信封，与创建响应**形状不同**：\n\n```json\n{\n  \"task\": {\n    \"id\": \"424010985738629\",\n    \"model\": \"<model>\",\n    \"status\": \"succeeded\",\n    \"created_at\": 1756600000,\n    \"updated_at\": 1756600120,\n    \"content\": { \"url\": \"https://.../video.mp4\" },\n    \"resolution\": \"2K\",\n    \"duration\": 5,\n    \"ratio\": \"16:9\",\n    \"usage\": {\n      \"total_seconds\": 5,\n      \"input_seconds\": 0,\n      \"output_seconds\": 5,\n      \"input_image_count\": 1\n    },\n    \"task_type\": \"generation\",\n    \"modality\": \"video\"\n  }\n}\n```\n\n- `status` 取值为 `queued` / `running` / `succeeded` / `failed`。\n- 成功后产物地址在 `task.content.url`。\n- `usage` 以**秒**计量（H3 按输出秒数定价），不是 token 数；上游只报告 token 而没有秒数时该字段缺省。\n- 失败时追加 `task.error`（`code` / `message`）。这一项不在 MiniMax 官方成功响应结构里，\n  是为了让失败原因可见而额外补上的，按官方结构解析的客户端会自然忽略它。\n\n## 取消任务\n\n```bash\ncurl -X DELETE {{ api_endpoint }}/minimax/v2/video_generation/424010985738629 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n取消后预扣退回。注意本通道**不会**返回 MiniMax 文档中的 `cancelled` 状态——已取消的任务统一以\n`failed` 呈现，以保证预扣被退回而不是结算。\n\n## 关键约定\n\n- **`id` / `task_id` 都是网关任务 ID**，不是上游任务 ID；查询与取消只认它。\n- 该通道不锁定上游 family，由 `model` 对应逻辑模型的路由决定实际承接方，路径拼写不参与选路。\n- 产物内容接口只有 OpenAI 兼容那一条（`GET /v1/videos/{task_id}/content`），MiniMax 路径下没有对应端点。\n\n标准化入口见[OpenAI 兼容视频流](./openai-compatible)。\n","international/zh/models/video/openai-compatible.md":"---\ntitle: OpenAI 兼容视频流\ndescription: 标准 OpenAI Video 兼容接口，包括创建任务、轮询状态与拉取产物内容。\n---\n\n# OpenAI 兼容视频流\n\n| 方法 | 路径 | 用途 |\n| --- | --- | --- |\n| `POST` | `/v1/video/generations` | 创建 OpenAI 兼容视频任务 |\n| `GET` | `/v1/videos/{task_id}` | 轮询视频任务状态与结果 |\n| `GET` | `/v1/videos/{task_id}/content` | 拉取已完成视频任务的产物内容 |\n\n这组接口是平台定义的**标准视频协议**：请求体使用 OpenAI Video 兼容字段，平台负责识别并转换成对应上游的视频异步任务格式。\n\n## 创建任务\n\n```bash\ncurl {{ api_endpoint }}/v1/video/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"<model>\",\"prompt\":\"a neon city cat\",\"duration\":4}'\n```\n\n创建成功后返回 `task_id`。后续轮询与产物拉取都围绕该 `task_id` 进行。\n\n## 轮询任务状态\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123 \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n```json\n{\n  \"id\": \"task_123\",\n  \"object\": \"video\",\n  \"status\": \"completed\",\n  \"progress\": 100,\n  \"metadata\": { \"url\": \"https://.../video.mp4\", \"duration\": 4, \"resolution\": \"...\" }\n}\n```\n\n`status` 取值为 `queued` / `in_progress` / `completed` / `failed`；为 `completed` 时，`metadata.url` 中会给出产物地址。\n\n## 拉取产物内容\n\n任务完成后，也可以通过内容接口直接拿视频文件。该接口由网关**直接回传 `video/mp4` 字节流**（不再 `302` 跳转到对象存储），支持 `Range` 断点续传，且只有任务所属 API Key（或同租户控制台登录态）可访问：\n\n```bash\ncurl {{ api_endpoint }}/v1/videos/task_123/content \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -o video.mp4\n```\n\n内容接口的可用性取决于后台「媒体交付」配置：\n\n- 未启用时返回 `404`（`content_delivery_disabled`）\n- 任务尚未完成时返回 `409`（`task_not_completed`）\n- 产物已过期或不存在时返回 `404`（`content_not_available`）\n\n## 关键约定\n\n- 这是标准 OpenAI 兼容视频入口，客户端不需要理解厂商原生协议。\n- 是否支持 `duration`、`size` 等字段，以及最终落到哪个上游，取决于 `model` 对应的逻辑模型配置。\n- 视频任务属于异步模型，轮询时请带退避，避免高频请求触发限流。\n\n如需更通用的异步任务入口，见[通用异步内容生成任务](./async-tasks)；想按厂商原厂报文书写、但仍要平台托管的计费与任务管理，见[Seedance 视频入站协议](./ark)与[MiniMax 视频入站协议](./minimax)。\n","international/zh/quickstart/agent-clients.md":"---\ntitle: AI 工具接入\ndescription: 选择 AI 客户端或 Agent，通过 ModelGo 调用模型。\n---\n\n# AI 工具接入\n\nModelGo 支持常用的 AI 编程客户端和 Agent。创建 API Key 后，推荐使用 ModelGo CLI 自动完成接入；未接入 CLI 的客户端可通过自定义 Provider 手动配置。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n运行后选择一个或多个工具；如需自动化配置全部支持的工具，可使用：\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n## 支持的 AI 工具\n\n:::agent-tools\n| 工具 | ModelGo CLI自动接入 | 手动接入文档 |\n| --- | --- | --- |\n| Hermes Agent | 支持 | [接入文档](../agents/hermes-agent) |\n| Claude Code | 支持 | [接入文档](../agents/claude-code) |\n| Kilo Code | 暂不支持 | [接入文档](../agents/kilo-code) |\n| Cline | 暂不支持 | [接入文档](../agents/cline) |\n| Codex | 支持 | [接入文档](../agents/codex) |\n| OpenClaw | 支持 | [接入文档](../agents/openclaw) |\n| DeepSeek Harness | 暂不支持 | [接入文档](../agents/deepseek-harness) |\n| ZCode | 暂不支持 | [接入文档](../agents/zcode) |\n| Cursor | 暂不支持 | [接入文档](../agents/cursor) |\n| OpenCode | 支持 | [接入文档](../agents/opencode) |\n| CC Switch | 支持 | [接入文档](../agents/cc-switch) |\n| Cherry Studio | 暂不支持 | [接入文档](../agents/cherry-studio) |\n| Crush | 支持 | [接入文档](../agents/crush) |\n| Factory Droid | 支持 | [接入文档](../agents/factory-droid) |\n| Copilot CLI | 支持 | [接入文档](../agents/copilot-cli) |\n| nanobot | 支持 | [接入文档](../agents/nanobot) |\n| Oh My Pi | 支持 | [接入文档](../agents/oh-my-pi) |\n| CodeBuddy | 支持 | [接入文档](../agents/codebuddy) |\n| Kilo CLI | 暂不支持 | [接入文档](../agents/kilo-cli) |\n:::\n\n## 接入前准备\n\n1. 在[控制台]({{ console_endpoint }}/api-keys)创建 API Key。\n2. 运行上方命令并选择需要接入的客户端或 Agent。\n3. 按终端提示确认站点、Base URL 和脱敏后的 API Key；配置工具会完成连通性验证。\n\n如果你希望用命令行管理 ModelGo 账户、模型、调用和 Skills，继续阅读[命令行工具](cli)。\n\n## 集成指南\n\n大多数工具只需要配置以下信息，即可连接 ModelGo：\n\n1. **API 地址**：OpenAI 兼容接口填写 `{{ api_endpoint }}/v1`；Anthropic 兼容接口填写 `{{ api_endpoint }}`。\n2. **API Key**：在 [ModelGo 控制台]({{ console_endpoint }}/api-keys)创建的令牌。\n3. **模型名称**：在[模型广场]({{ site_endpoint }}/models)选择的逻辑模型名。\n\n具体配置步骤请参考上方各工具对应的接入文档。\n","international/zh/quickstart/authentication.md":"---\ntitle: 认证鉴权\ndescription: API Key 的获取、传递方式、优先级与常见认证失败处理。\n---\n\n# 认证鉴权\n\n所有模型调用接口都通过 API Key 认证。\n\n## 推荐请求头\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nAnthropic 风格客户端也可使用：\n\n```http\nx-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\nGemini 风格客户端也可使用：\n\n```http\nx-goog-api-key: $MODELGO_API_KEY\nContent-Type: application/json\n```\n\n当多个头同时出现时，优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。\n\n## 获取与管理\n\n- 控制台：`{{ console_endpoint }}`\n- API Key 仅在创建时完整展示一次\n- 吊销或停用后会在鉴权缓存失效后生效\n\n## 认证失败\n\n常见错误：\n\n| HTTP | error_class | 说明 |\n| --- | --- | --- |\n| `401` | `auth` | 缺少、无效、停用或过期的 API Key |\n| `403` | `policy` | Key 有效，但不允许调用该模型或未绑定策略 |\n\n更多错误结构见[错误码与限流](errors)。\n","international/zh/quickstart/cli.md":"---\ntitle: 命令行工具\ndescription: 选择适合你的官方命令行工具，完成 ModelGo 配置。\n---\n\n# 命令行工具\n\nModelGo 提供两个官方命令行工具。选择你要完成的任务，运行对应命令即可开始。\n\n:::tools\n@model-go/config | 接入 AI 编程客户端 | 一条命令配置 Claude Code、Codex 等常用客户端。 | npx @model-go/config -r {{ region_flag }} | 查看 npm 包 | https://www.npmjs.com/package/@model-go/config\n@model-go/cli | 使用官方 CLI | 配合官方 ModelGo Skills，让 AI Agent 直接操作 ModelGo。 | npx @model-go/cli@latest install | 查看 npm 包 | https://www.npmjs.com/package/@model-go/cli\n:::\n\n## 接入 AI 编程客户端 `@model-go/config` {#connect-ai-clients}\n\n如果你想在 Claude Code、Codex、OpenCode 等 AI 编程客户端中使用 ModelGo，可以选择引导式配置，也可以通过一条命令完成全部客户端配置。\n\n**引导式配置**\n\n根据终端提示输入 API Key、选择客户端并预览配置，确认后自动写入并验证连接。\n\n```bash\nnpx @model-go/config -r {{ region_flag }}\n```\n\n**一键式配置（非交互，适合自动化）**\n\n```bash\nnpx @model-go/config -k sk-你的token -r {{ region_flag }} --only all\n```\n\n### 支持的客户端\n\n:::clients\nClaude Code\nCodex\nOpenClaw\nHermes\nFactory Droid\nCC Switch\nCopilot CLI\nnanobot\nCrush\nOpenCode\nOh My Pi\nCodeBuddy\n:::\n\n引导式配置支持勾选一个或多个客户端；使用 `--only all` 可一次配置全部客户端。\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | 输入你的 [ModelGo API Key]({{ console_endpoint }}/api-keys)。 |\n| `02` | 勾选需要配置的客户端，也可以选择“全部配置”。 |\n| `03` | 预览站点、Base URL、脱敏后的 API Key 和目标客户端。 |\n| `04` | 确认后写入客户端配置，并自动验证连接。 |\n\n> **配置成功：** 终端会显示“配置完成”和“链路验证通过”，并给出启动所选客户端的命令。\n\n[查看 @model-go/config npm 包](https://www.npmjs.com/package/@model-go/config)\n\n## 让 AI Agent 操作 ModelGo `@model-go/cli` {#install-agent-tools}\n\n如果你希望 Claude Code、Codex 等 Agent 直接使用 ModelGo，安装官方 CLI 和 ModelGo Skills。安装向导会完成 CLI 设置、Skills 分发、站点选择和可选登录。\n\n```bash\nnpx @model-go/cli@latest install\n```\n\n### 运行后会发生什么\n\n| 步骤 | 引导内容 |\n| --- | --- |\n| `01` | npm 首次运行时，确认安装 `@model-go/cli`。 |\n| `02` | 选择安装向导语言，支持中文和英文，后续安装提示将使用所选语言。 |\n| `03` | 安装或升级 ModelGo CLI，并安装 ModelGo Skills。 |\n| `04` | 在向导中选择当前站点环境（`{{ api_endpoint }}`）。 |\n| `05` | 选择是否立即通过浏览器登录；也可以跳过并稍后运行 `modelgo auth login`。 |\n\n### 安装后如何使用\n\n安装完成后，重新启动 AI Agent 或新建会话。ModelGo Skills 会让 AI Agent 直接调用 ModelGo CLI 完成查询和操作，你可以用自然语言向它提问，例如：\n\n- “当前 ModelGo 支持的模型有哪些？”\n- “当前 ModelGo 的账户余额还剩多少？”\n\n如果你希望自己在终端操作，输入 `modelgo` 即可查看全部可用命令和参数说明：\n\n```bash\nmodelgo\n```\n\n常用能力按使用场景分为以下几类：\n\n| 使用场景 | 常用命令 | 说明 |\n| --- | --- | --- |\n| 登录与身份 | `modelgo auth login`、`modelgo auth status`、`modelgo auth logout` | 登录 ModelGo、查看当前登录状态或清除本地登录信息。 |\n| 站点环境 | `modelgo env list`、`modelgo env current`、`modelgo env use <name>` | 查看可用环境、确认当前环境或切换站点；也可以通过 `env add` 和 `env remove` 管理自定义环境。 |\n| 工作空间 | `modelgo tenant list`、`modelgo tenant use <slug>` | 查看当前账号可用的工作空间，并通过工作空间 slug 或 ID 切换 CLI 后续操作使用的工作空间。 |\n| 账户与用量 | `modelgo balance`、`modelgo permissions`、`modelgo logs` | 查看余额和交易记录、账号权限、调用日志及用量统计。 |\n| 模型调用 | `modelgo models`、`modelgo chat`、`modelgo embeddings`、`modelgo call` | 查询可用模型，发起对话或向量请求，或直接调用任意 `/v1/*` 模型接口。 |\n| Key 与支付 | `modelgo key`、`modelgo pay` | 管理当前环境保存的模型 API Key，或管理 x402 按次支付配置。 |\n| CLI 维护 | `modelgo update`、`modelgo --version`、`modelgo --help` | 更新 CLI、查看版本或重新打开完整帮助。 |\n\n需要查看某个命令的参数时，运行 `modelgo <command> --help`。对于 `balance`、`permissions` 和 `logs`，还可以使用全局参数 `--tenant <slug\\|id>` 临时指定本次查询的工作空间。\n\n[查看 @model-go/cli npm 包](https://www.npmjs.com/package/@model-go/cli)\n\n:::note 安全提示\n- 推荐通过交互提示输入 API Key，不要把 Key 直接写进命令。\n- 不要把 API Key 提交到代码仓库或粘贴到共享脚本。\n- 如果安装 CLI 时跳过登录，稍后运行 `modelgo auth login`。\n:::\n\n## 继续探索\n\n- [首次调用](quickstart)：发起第一次模型调用。\n- [认证鉴权](authentication)：了解 API Key 的使用方式和安全建议。\n","international/zh/quickstart/errors.md":"---\ntitle: 错误码与限流\ndescription: 统一错误结构、常见错误分类与限流处理建议。\n---\n\n# 错误码与限流\n\n## 错误响应结构\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"request_id\": \"req_xxx\",\n      \"error_class\": \"auth\",\n      \"app_error_id\": 4011\n    }\n  },\n  \"trace_id\": \"...\"\n}\n```\n\n错误响应体除了 `error` 对象外，还带一个与 `X-Trace-ID` 响应头一致的顶层 `trace_id` 字段（链路追踪关闭时省略），便于按日志检索。`metadata.reason` 是可选细分原因（例如 `model_not_in_catalog`）。完整清单与已验证示例见[接口清单](openapi)。\n\n## 常见错误分类\n\n| error_class | HTTP | 含义 |\n| --- | --- | --- |\n| `client_invalid` | 400 | 请求格式或参数无效 |\n| `model_protocol_not_offered` | 400 | 该逻辑模型未声明当前入口对应的 `public_protocols`（`app_error_id=4005`）。换入口或换模型，不要改写请求体撞协议 |\n| `provider_invalid` | 400 | 上游拒绝请求（上游返回非 401/403/408/429 的 4xx） |\n| `provider_unsupported` | 400 | 上游不支持该接口（例如部分视频模型不支持 `DELETE` 取消） |\n| `provider_timeout` | 408 | 上游请求超时 |\n| `auth` | 401 | API Key 认证失败 |\n| `billing_insufficient` | 402 | 余额不足 |\n| `policy` | 403 | 无权调用该模型或未绑定策略 |\n| `quota` | 429 | 触发平台配额或限流 |\n| `provider_rate_limit` | 429 | 上游触发限流（上游返回 429） |\n| `gateway_internal` | 500 | 网关内部错误（兜底分类） |\n| `billing_system` | 502 | 计费系统不可用 |\n| `provider_server` | 502 | 上游服务错误 |\n| `provider_unauthorized` | 502 | 上游凭证被拒（统一归为 5xx，不向调用方暴露上游 Key 问题） |\n| `provider_unavailable` | 503 | 无可用模型供应方 |\n| `route_unconfigured` | 503 | 模型路由未配置上游 |\n\n## 失败请求的计费规则\n\n- 预扣：每次请求受理后按预估用量冻结余额，请求结束后按实际用量结算，多冻结的部分立即释放。\n- 成功请求与已交付部分内容的流式请求：按实际返回的用量结算。\n- **请求已发往上游供应方但最终失败**（上游 4xx/5xx、上游超时、流中途断开，以及客户端在等待响应期间主动断开）：按本次请求的预扣金额结算，不再退回。上游供应方对这类请求已产生实际成本，平台按预扣口径承担并向调用方收取。\n- 请求尚未发往上游即被平台拒绝（参数校验、鉴权、策略、配额、余额不足、网关内部错误）：预扣全额释放，不产生费用。\n- 结算依据可在控制台用量明细的交易记录中查看，按预扣结算的记录会标注失败原因。\n\n## 排障建议\n\n- 保留响应头中的 `X-Request-ID` 与 `X-Trace-ID`；错误响应体也会带同值的顶层 `trace_id` 字段\n- 遇到 `429` 时结合 `Retry-After` 响应头做退避重试（平台限流命中时会下发该头）\n- 流式请求若收到带 `error` 字段的数据块，应按失败处理（此类流中断对应 `provider_stream_broken`，不会再以独立的 HTTP 状态码返回）\n\n能力接口的细节见：\n\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n","international/zh/quickstart/openapi.md":"---\ntitle: 接口清单\ndescription: 客户模型调用面的全量 OpenAPI 清单、鉴权、协议匹配规则与已验证示例。\n---\n\n# 接口清单\n\n本页列出当前对外开放的模型调用 HTTP 接口（`mgk_` API Key，网关 `{{ api_endpoint }}`）。\n\n## 接入前置\n\n1. 在 `{{ console_endpoint }}` 创建 API Key（`mgk_` 前缀），完整明文只展示一次。\n2. `export MODELGO_API_KEY=\"你的-API-Key\"`。\n3. 调用 `GET /v1/models` 确认该 Key 能用的**逻辑模型名**。\n4. 选接口前先确认该模型是否声明了对应协议：打到模型未提供的入口，网关返回 HTTP 400、`error_class=model_protocol_not_offered`（`app_error_id=4005`），而不是帮你改写成别的协议。\n\n## 鉴权\n\n所有下列接口都用同一套 API Key：\n\n```http\nAuthorization: Bearer $MODELGO_API_KEY\n```\n\nAnthropic 客户端可用 `x-api-key`，Gemini 客户端可用 `x-goog-api-key`。多头同时出现时优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。详见[认证鉴权](authentication)。\n\n缺 Key 或 Key 无效时的真实响应（HTTP 401）：\n\n```json\n{\n  \"error\": {\n    \"code\": 401,\n    \"message\": \"unauthorized\",\n    \"metadata\": {\n      \"app_error_id\": 4011,\n      \"error_class\": \"auth\",\n      \"request_id\": \"gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b\"\n    }\n  },\n  \"trace_id\": \"bbaf7b379c1dbb4b42adbabf65f5f530\"\n}\n```\n\n排障请同时保留响应头 `X-Request-ID`、`X-Trace-ID` 与 body 里的 `trace_id`。\n\n## 协议匹配（必读）\n\n平台按模型目录里的 `public_protocols` 决定一个逻辑模型能打哪些入口。文档里的 curl **不能**对任意模型复制粘贴。\n\n| 模型 | 入口 | 结果 |\n| --- | --- | --- |\n| `qwen3.6-flash` | `POST /v1/chat/completions`、`POST /v1/responses` | 200 |\n| `qwen3.6-flash` | `POST /v1/completions` | 400 `model_protocol_not_offered` |\n| `claude-fable-5` | `POST /v1/messages` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings` | 200 |\n| `text-embedding-3-small` | `POST /v1/embeddings/multimodal` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /v1/audio/speech` | 400 `model_protocol_not_offered` |\n| `speech-2.8-turbo` | `POST /minimax/v1/t2a_v2` | 200 |\n| `doubao-seedance-2.0-mini` | `POST /v1/video/generations` | 400 `model_protocol_not_offered` |\n| `doubao-seedance-2.0-mini` | `POST /v1/content_generation/tasks`、`POST /ark/api/v3/contents/generations/tasks` | 200 |\n| `doubao-seedream-5.0-lite` | `POST /v1/images/generations`（`size` 至少约 1920×1920） | 200 |\n\n## 全量清单\n\n状态含义：\n\n- **正式对外**：网关已挂载，客户可调；能否对某个模型调通，仍取决于该模型的 `public_protocols` 与 Key 策略。\n- **正式对外 / 别名**：与上一行行为相同。\n\n### 文本与模型目录\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `GET` | `/v1/models` | 正式对外 | 列出当前 Key 策略允许的逻辑模型 |\n| `POST` | `/v1/responses` | 正式对外 | OpenAI Responses，新项目优先 |\n| `POST` | `/v1/chat/completions` | 正式对外 | OpenAI Chat Completions |\n| `POST` | `/v1/completions` | 正式对外 | 旧版 Completions；多数对话模型未声明此协议 |\n| `POST` | `/v1/messages` | 正式对外 | Anthropic Messages |\n\n### 向量 / 图像 / 音频 / 重排\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/embeddings` | 正式对外 | 文本向量 |\n| `POST` | `/v1/embeddings/multimodal` | 正式对外 | 多模态向量；需模型声明对应协议 |\n| `POST` | `/v1/images/generations` | 正式对外 | 图像生成 |\n| `POST` | `/v1/images/edits` | 正式对外 | 图像编辑，`multipart/form-data` |\n| `POST` | `/v1/audio/speech` | 正式对外 | OpenAI TTS；**不是**所有语音模型都提供此协议 |\n| `POST` | `/minimax/v1/t2a_v2` | 正式对外 | MiniMax 原生同步语音合成，见[MiniMax 音频入站协议](../models/audio/minimax) |\n| `POST` | `/v1/audio/transcriptions` | 正式对外 | 语音转文本，multipart |\n| `POST` | `/v1/audio/translations` | 正式对外 | 语音翻译，multipart |\n| `POST` | `/v1/rerank` | 正式对外 | 重排序 |\n| `POST` | `/v1/reranks` | 正式对外 / 别名 | 与 `/v1/rerank` 等价 |\n\n### 视频与异步任务（托管）\n\n| 方法 | 路径 | 状态 | 说明 |\n| --- | --- | --- | --- |\n| `POST` | `/v1/content_generation/tasks` | 正式对外 | 通用异步任务创建 |\n| `GET` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/v1/content_generation/tasks/{task_id}` | 正式对外 | 取消；上游不支持时返回 `provider_unsupported` |\n| `POST` | `/ark/api/v3/contents/generations/tasks` | 正式对外 | 与上一组同一托管流水线，Ark 路径拼写 |\n| `GET` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上轮询 |\n| `DELETE` | `/ark/api/v3/contents/generations/tasks/{task_id}` | 正式对外 | 同上取消 |\n| `POST` | `/minimax/v2/video_generation` | 正式对外 | MiniMax 视频 V2 托管入口，请求需带齐计费维度 |\n| `GET` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 轮询 |\n| `DELETE` | `/minimax/v2/video_generation/{task_id}` | 正式对外 | 取消 |\n| `POST` | `/v1/video/generations` | 正式对外 | OpenAI 兼容视频创建；需模型声明该协议 |\n| `GET` | `/v1/videos/{task_id}` | 正式对外 | 轮询 |\n| `GET` | `/v1/videos/{task_id}/content` | 正式对外 | 302 拉产物 |\n| `DELETE` | `/v1/videos/{task_id}` | 正式对外 | 取消 |\n\n## 查询模型清单\n\n```bash\ncurl {{ api_endpoint }}/v1/models \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\"\n```\n\n真实响应形态（条目已截断）：\n\n```json\n{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"claude-fable-5\",\n      \"object\": \"model\",\n      \"created\": 1735689600,\n      \"context_length\": 1000000,\n      \"input_modalities\": [\"file\", \"image\", \"text\"],\n      \"output_modalities\": [\"text\"]\n    }\n  ]\n}\n```\n\n`id` 就是请求里的 `model`。清单**不包含** `public_protocols`；某个模型能不能打某个入口，以实际调用结果和控制台模型页为准。\n\n## 文本调用（已验证）\n\n### `POST /v1/chat/completions`\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}],\n    \"max_tokens\": 64\n  }'\n```\n\n成功时 HTTP 200，`object` 为 `chat.completion`，含 `choices[0].message` 与 `usage`。部分推理模型会额外返回 `reasoning_content`，且 `usage.completion_tokens` 可能远大于 `max_tokens`（实测 `max_tokens: 64` 时 completion 仍可达上千）。\n\n流式：同一路径加 `\"stream\": true`，响应 `Content-Type: text/event-stream`，每行 `data: {chunk}`，以 `data: [DONE]` 结束。\n\n空 body `{}` 的真实错误（HTTP 400）：\n\n```json\n{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"invalid request\",\n    \"metadata\": {\n      \"app_error_id\": 4001,\n      \"error_class\": \"client_invalid\",\n      \"request_id\": \"gw_a542461f-fe16-4f72-88d7-4c67b4bc9d7c\"\n    }\n  },\n  \"trace_id\": \"d6630b36c387a9e1e2d7bc9b6aa89020\"\n}\n```\n\n模型不在目录（HTTP 403）：\n\n```json\n{\n  \"error\": {\n    \"code\": 403,\n    \"message\": \"model is not registered or enabled in catalog\",\n    \"metadata\": {\n      \"app_error_id\": 4031,\n      \"error_class\": \"policy\",\n      \"reason\": \"model_not_in_catalog\",\n      \"request_id\": \"gw_ecc21066-c4a9-4eb1-97e7-799c4b1290\"\n    }\n  }\n}\n```\n\n### `POST /v1/responses`\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"qwen3.6-flash\",\n    \"input\": \"用一句话介绍 ModelGo。\",\n    \"max_output_tokens\": 64\n  }'\n```\n\n成功时 `object` 为 `response`，`output` 为数组（可能含 `reasoning` 与 `message`），并带 `output_text`。\n\n### `POST /v1/messages`\n\n```bash\ncurl {{ api_endpoint }}/v1/messages \\\n  -H \"x-api-key: $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"claude-fable-5\",\n    \"max_tokens\": 64,\n    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍 ModelGo。\"}]\n  }'\n```\n\n成功时 Anthropic 消息形态：`type: \"message\"`，`content[].type: \"text\"`。响应里的 `model` 可能是上游内部名（实测为 `pa/venus-cathedral-5`），与请求里的逻辑名不同，请以请求 `model` 和控制台为准。\n\n## 向量 / 图像 / 语音（已验证）\n\n### `POST /v1/embeddings`\n\n```bash\ncurl {{ api_endpoint }}/v1/embeddings \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"text-embedding-3-small\",\"input\":\"hello ModelGo\"}'\n```\n\n成功：`data[0].embedding` 为浮点数组（`text-embedding-3-small` 实测维度 1536），`usage.prompt_tokens` 为计费 token。\n\n### `POST /v1/images/generations`\n\n`doubao-seedream-5.0-lite` 拒绝过小的 `size`。`1024x1024` 实测 HTTP 400、`error_class=provider_invalid`，上游要求像素总数至少 3686400（约 1920×1920）。用 `2048x2048` 可通过：\n\n```bash\ncurl {{ api_endpoint }}/v1/images/generations \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5.0-lite\",\n    \"prompt\": \"a tiny red apple on white background, simple\",\n    \"size\": \"2048x2048\"\n  }'\n```\n\n成功响应含 `data[0].url`（对象存储地址，有时效）和 `usage.generated_images`。响应 `model` 可能是上游名（实测 `doubao-seedream-5-0-260128`）。\n\n### `POST /minimax/v1/t2a_v2`\n\n见[MiniMax 音频入站协议](../models/audio/minimax)。`speech-2.8-turbo` / `speech-2.8-hd` 当前声明的是这条 MiniMax 原生协议，不是 OpenAI `/v1/audio/speech`。\n\n## 异步视频（已验证）\n\nSeedance 类模型走托管异步任务，而不是 OpenAI `/v1/video/generations`。\n\n```bash\ncurl {{ api_endpoint }}/v1/content_generation/tasks \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"doubao-seedance-2.0-mini\",\n    \"content\": [{\"type\": \"text\", \"text\": \"a red apple on a table\"}]\n  }'\n```\n\n创建成功（HTTP 200）：\n\n```json\n{\n  \"id\": \"gw_c731f504-5a53-4e37-a972-30653a8ee390\",\n  \"model\": \"doubao-seedance-2.0-mini\",\n  \"status\": \"queued\",\n  \"created_at\": 1789012940,\n  \"error\": null\n}\n```\n\n同一 `id` 也可在 `GET /ark/api/v3/contents/generations/tasks/{id}` 轮询，状态会变为 `running`，完成后为 **`succeeded`**（实测 `resolution=720p`、`ratio=16:9`、`duration=5`）。`DELETE` 取消在该上游上实测返回 HTTP 400、`error_class=provider_unsupported`、`endpoint not supported by provider`——不要假设所有视频模型都支持取消。\n\n`POST /minimax/v2/video_generation` 若缺少计费维度，返回 HTTP 400、`client_invalid`（`billing_error_code=4223`）。按 MiniMax 视频文档补齐 `duration` / `resolution` 等字段后再试。\n\n## 流式约定\n\n- 文本流式接口（`/v1/chat/completions`、`/v1/responses`、`/v1/messages`）在请求体设 `stream: true`（Anthropic 为 `stream: true`）。\n- OpenAI 形态：`Content-Type: text/event-stream`，帧为 `data: <json>`，正常结束带 `data: [DONE]`。\n- Anthropic `/v1/messages` 保持原生 `event:` 帧，网关不会改写成 OpenAI SSE。\n- 流中若出现带 `error` 的数据块，按失败处理；此时可能没有独立的 HTTP 错误状态码。\n\n## 限流、超时、幂等、分页\n\n- 限流：HTTP 429，`error_class` 为 `quota` 或 `provider_rate_limit`；平台限流时会带 `Retry-After`。\n- 超时：客户端自行设置；上游超时为 `provider_timeout`（408）。\n- 幂等：同步文本/图像/语音请求没有客户侧幂等键。异步视频任务以返回的 `id` / `task_id` 为后续轮询主键；重复 POST 会再创建新任务。\n- 分页：模型调用面没有 cursor/page 列表接口。`GET /v1/models` 一次返回当前 Key 可见的全部逻辑模型。\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [错误码与限流](errors)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [MiniMax 音频入站协议](../models/audio/minimax)\n- [通用异步内容生成任务](../models/video/async-tasks)\n","international/zh/quickstart/overview.md":"---\ntitle: 平台概览\ndescription: ModelGo 模型网关的能力范围、兼容协议、接入地址与认证方式总览。\n---\n\n# 平台概览\n\n{{ platform_name }} 模型网关提供统一的模型调用入口，对外兼容 OpenAI 与 Anthropic 文本协议，并补齐图像、视频、向量和音频等能力页。客户端通常只需要替换 `base_url` 和 API Key，就能沿用现有 SDK 或 HTTP 调用逻辑。\n\n## 接入地址\n\n```text\n{{ api_endpoint }}/v1\n```\n\n控制台地址：\n\n```text\n{{ console_endpoint }}\n```\n\n## 当前公开能力\n\n| 一级分类 | 能力页 | 主要接口 |\n| --- | --- | --- |\n| 快速开始 | 平台概览 / 首次调用 / AI 工具接入 / 认证鉴权 / 错误码与限流 | 接入与排障说明 |\n| 模型 / 文本 | 文本生成 | `POST /v1/responses` `POST /v1/chat/completions` `POST /v1/completions` `POST /v1/messages` `GET /v1/models` |\n| 模型 / 图像 | 图像生成 / 图像编辑 | `POST /v1/images/generations` `POST /v1/images/edits` |\n| 模型 / 视频 | OpenAI 兼容视频流 / 通用异步内容生成任务 / Seedance 与 MiniMax 入站 | `POST /v1/video/generations` `GET /v1/videos/{task_id}` `GET /v1/videos/{task_id}/content` `POST /v1/content_generation/tasks` `GET /v1/content_generation/tasks/{task_id}` |\n| 模型 / 向量 | Embeddings | `POST /v1/embeddings` `POST /v1/embeddings/multimodal` |\n| 模型 / 音频 | 语音合成 / MiniMax 音频 / 语音转文本 / 语音翻译 | `POST /v1/audio/speech` `POST /minimax/v1/t2a_v2` `POST /v1/t2a_v2` `POST /v1/audio/transcriptions` `POST /v1/audio/translations` |\n| 模型 / 重排 | Rerank | `POST /v1/rerank` `POST /v1/reranks` |\n\n## 关键约定\n\n- `model` 必须填写平台逻辑模型名，而不是上游厂商原始模型 ID。\n- 平台提供 `GET /v1/models` 查询入口，返回的清单由该 API Key 绑定的策略所允许的逻辑模型（结合平台模型目录）决定，并非实时探测上游能力，最终以控制台模型页与策略配置为准。\n- 流式文本接口通过 SSE 返回，以 `data: [DONE]` 结束。\n- 视频 / 异步内容生成走异步任务模型，创建任务后需按 `task_id` 轮询。\n- 错误响应使用统一结构，排障时请保留 `X-Request-ID`。\n\n## 下一步\n\n- [首次调用](quickstart)\n- [接口清单](openapi)\n- [认证鉴权](authentication)\n- [文本生成](../models/text/generation)\n- [图像生成](../models/images/generations)\n- [OpenAI 兼容视频流](../models/video/openai-compatible)\n- [通用异步内容生成任务](../models/video/async-tasks)\n- [Seedance 视频入站协议](../models/video/ark)\n- [MiniMax 视频入站协议](../models/video/minimax)\n- [MiniMax 音频](../models/audio/minimax)\n- [Rerank](../models/rerank/rerank)\n- [错误码与限流](errors)\n","international/zh/quickstart/quickstart.md":"---\ntitle: 首次调用\ndescription: 获取 API Key、确认模型名并完成第一次调用。\n---\n\n# 首次调用\n\n你可以复用现有 OpenAI 或 Anthropic SDK 接入 ModelGo，也可以按下面三步完成第一次 Responses API 调用。\n\n## 使用标准协议接入\n\nModelGo 同时兼容 OpenAI 与 Anthropic 标准协议。如果项目已经使用对应 SDK，通常只需替换 Base URL 和 API Key，无需重写调用逻辑。\n\n:::endpoints\nOpenAI | {{ api_endpoint }}/v1\nAnthropic | {{ api_endpoint }}\n:::\n\n## 三步完成第一次 API 调用\n\n如果是第一次接入 ModelGo，完成下面三步即可发起请求并获得生成结果。\n\n### 第 1 步：获取 API Key\n\n1. 登录控制台：`{{ console_endpoint }}`。\n2. 在「API Key」页面创建新的 Key。\n3. 使用环境变量注入：\n\n```bash\nexport MODELGO_API_KEY=\"你的-API-Key\"\n```\n\n### 第 2 步：确认模型名称\n\n请求中的 `model` 使用平台逻辑模型名。可调用 `GET /v1/models` 查询当前可用的逻辑模型清单，返回结果由该 API Key 绑定的策略所允许的逻辑模型（结合平台模型目录）决定，请以[模型广场]({{ site_endpoint }}/models)和已绑定策略为准。\n\n### 第 3 步：发起第一次调用\n\n推荐把第一次调用落在 `POST /v1/responses`：\n\n```bash\ncurl {{ api_endpoint }}/v1/responses \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"input\": \"用三句话介绍 ModelGo。\"\n  }'\n```\n\n如果你已经接入旧版 OpenAI Chat Completions SDK，也可以继续调用 `POST /v1/chat/completions`：\n\n```bash\ncurl {{ api_endpoint }}/v1/chat/completions \\\n  -H \"Authorization: Bearer $MODELGO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model>\",\n    \"messages\": [\n      {\"role\": \"system\", \"content\": \"你是一个简洁的助手。\"},\n      {\"role\": \"user\", \"content\": \"用三句话介绍 ModelGo。\"}\n    ]\n  }'\n```\n\nPython（OpenAI SDK，推荐走 Responses）：\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"MODELGO_API_KEY\"],\n    base_url=\"{{ api_endpoint }}/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"<model>\",\n    input=\"用三句话介绍 ModelGo。\",\n)\n\nprint(response.output_text)\n```\n\n## 下一步\n\n- [认证鉴权](authentication)\n- [文本生成](../models/text/generation)\n- [错误码与限流](errors)\n"}
 export const DOCS_METAS = {"china/en/about/meta.json":{"title":"About ModelGo","description":"Learn what ModelGo is and what it provides for developers.","items":[{"type":"page","slug":"quickstart/overview","file":"overview.md"}]},"china/en/agents/meta.json":{"title":"Tool Integrations","description":"ModelGo setup guides for popular AI clients and Agents.","items":[{"type":"page","slug":"agents/hermes-agent","file":"hermes-agent.md"},{"type":"page","slug":"agents/claude-code","file":"claude-code.md"},{"type":"page","slug":"agents/kilo-code","file":"kilo-code.md"},{"type":"page","slug":"agents/cline","file":"cline.md"},{"type":"page","slug":"agents/codex","file":"codex.md"},{"type":"page","slug":"agents/openclaw","file":"openclaw.md"},{"type":"page","slug":"agents/deepseek-harness","file":"deepseek-harness.md"},{"type":"page","slug":"agents/zcode","file":"zcode.md"},{"type":"page","slug":"agents/cursor","file":"cursor.md"},{"type":"page","slug":"agents/opencode","file":"opencode.md"},{"type":"page","slug":"agents/cc-switch","file":"cc-switch.md"},{"type":"page","slug":"agents/cherry-studio","file":"cherry-studio.md"},{"type":"page","slug":"agents/crush","file":"crush.md"},{"type":"page","slug":"agents/factory-droid","file":"factory-droid.md"},{"type":"page","slug":"agents/copilot-cli","file":"copilot-cli.md"},{"type":"page","slug":"agents/nanobot","file":"nanobot.md"},{"type":"page","slug":"agents/oh-my-pi","file":"oh-my-pi.md"},{"type":"page","slug":"agents/codebuddy","file":"codebuddy.md"},{"type":"page","slug":"agents/kilo-cli","file":"kilo-cli.md"}]},"china/en/meta.json":{"title":"MODELGO DOCS","description":"Getting started and model capability docs for the ModelGo model gateway.","items":[{"type":"section","slug":"about","file":"about/meta.json"},{"type":"section","slug":"quickstart","file":"quickstart/meta.json"},{"type":"section","slug":"models","file":"models/meta.json"},{"type":"section","slug":"agents","file":"agents/meta.json"}]},"china/en/models/audio/meta.json":{"title":"Audio","description":"Speech, MiniMax T2A, transcription, and translation endpoints.","items":[{"type":"page","slug":"models/audio/speech","file":"speech.md"},{"type":"page","slug":"models/audio/minimax","file":"minimax.md"},{"type":"page","slug":"models/audio/transcriptions","file":"transcriptions.md"},{"type":"page","slug":"models/audio/translations","file":"translations.md"}]},"china/en/models/images/meta.json":{"title":"Images","description":"OpenAI-compatible image generation and edit endpoints, plus the GPT Image (gpt-image-2 / gpt-image-1.5), Gemini image, Seedream family (5.0 pro / 5.0 lite / 5.0 / 4.5) and Qwen Image 3.0 (qwen-image-3.0 / 3.0-pro) vendor inbound protocols.","items":[{"type":"page","slug":"models/images/generations","file":"generations.md"},{"type":"page","slug":"models/images/edits","file":"edits.md"},{"type":"page","slug":"models/images/gpt-image-2","file":"gpt-image-2.md"},{"type":"page","slug":"models/images/gemini-image","file":"gemini-image.md"},{"type":"page","slug":"models/images/seedream","file":"seedream.md"},{"type":"page","slug":"models/images/qwen-image","file":"qwen-image.md"}]},"china/en/models/meta.json":{"title":"Model Calls","description":"Capability-oriented API docs for text, images, video, vectors, audio, and rerank.","items":[{"type":"section","slug":"models/text","file":"text/meta.json"},{"type":"section","slug":"models/images","file":"images/meta.json"},{"type":"section","slug":"models/video","file":"video/meta.json"},{"type":"section","slug":"models/vectors","file":"vectors/meta.json"},{"type":"section","slug":"models/audio","file":"audio/meta.json"},{"type":"section","slug":"models/realtime","file":"realtime/meta.json"},{"type":"section","slug":"models/rerank","file":"rerank/meta.json"}]},"china/en/models/realtime/meta.json":{"title":"Realtime (WebSocket)","description":"Guide and API reference for calling Qwen-Omni-Realtime over WebSocket.","items":[{"type":"page","slug":"models/realtime/guide","file":"guide.md"},{"type":"page","slug":"models/realtime/api","file":"api.md"}]},"china/en/models/rerank/meta.json":{"title":"Rerank","description":"Rerank endpoint for relevance re-ordering.","items":[{"type":"page","slug":"models/rerank/rerank","file":"rerank.md"}]},"china/en/models/text/meta.json":{"title":"Text","description":"Text generation and dialogue protocols.","items":[{"type":"page","slug":"models/text/generation","file":"generation.md"}]},"china/en/models/vectors/meta.json":{"title":"Vectors","description":"Embedding endpoint.","items":[{"type":"page","slug":"models/vectors/embeddings","file":"embeddings.md"}]},"china/en/models/video/meta.json":{"title":"Video","description":"OpenAI-compatible video flow, generic async content generation tasks, and the Seedance and MiniMax vendor inbound protocols.","items":[{"type":"page","slug":"models/video/openai-compatible","file":"openai-compatible.md"},{"type":"page","slug":"models/video/wan27","file":"wan27.md"},{"type":"page","slug":"models/video/kling-v3","file":"kling-v3.md"},{"type":"page","slug":"models/video/veo31","file":"veo31.md"},{"type":"page","slug":"models/video/async-tasks","file":"async-tasks.md"},{"type":"page","slug":"models/video/ark","file":"ark.md"},{"type":"page","slug":"models/video/minimax","file":"minimax.md"}]},"china/en/quickstart/meta.json":{"title":"Get Started","description":"First API call, AI tool setup, authentication, and error handling.","items":[{"type":"page","slug":"quickstart/quickstart","file":"quickstart.md"},{"type":"page","slug":"quickstart/cli","file":"cli.md"},{"type":"page","slug":"quickstart/agent-clients","file":"agent-clients.md"},{"type":"page","slug":"quickstart/authentication","file":"authentication.md"},{"type":"page","slug":"quickstart/openapi","file":"openapi.md"},{"type":"page","slug":"quickstart/errors","file":"errors.md"}]},"china/zh/about/meta.json":{"title":"关于ModelGo","description":"了解 ModelGo 的平台定位与核心能力。","items":[{"type":"page","slug":"quickstart/overview","file":"overview.md"}]},"china/zh/agents/meta.json":{"title":"接入工具","description":"常用 AI 客户端与 Agent 的 ModelGo 接入说明。","items":[{"type":"page","slug":"agents/hermes-agent","file":"hermes-agent.md"},{"type":"page","slug":"agents/claude-code","file":"claude-code.md"},{"type":"page","slug":"agents/kilo-code","file":"kilo-code.md"},{"type":"page","slug":"agents/cline","file":"cline.md"},{"type":"page","slug":"agents/codex","file":"codex.md"},{"type":"page","slug":"agents/openclaw","file":"openclaw.md"},{"type":"page","slug":"agents/deepseek-harness","file":"deepseek-harness.md"},{"type":"page","slug":"agents/zcode","file":"zcode.md"},{"type":"page","slug":"agents/cursor","file":"cursor.md"},{"type":"page","slug":"agents/opencode","file":"opencode.md"},{"type":"page","slug":"agents/cc-switch","file":"cc-switch.md"},{"type":"page","slug":"agents/cherry-studio","file":"cherry-studio.md"},{"type":"page","slug":"agents/crush","file":"crush.md"},{"type":"page","slug":"agents/factory-droid","file":"factory-droid.md"},{"type":"page","slug":"agents/copilot-cli","file":"copilot-cli.md"},{"type":"page","slug":"agents/nanobot","file":"nanobot.md"},{"type":"page","slug":"agents/oh-my-pi","file":"oh-my-pi.md"},{"type":"page","slug":"agents/codebuddy","file":"codebuddy.md"},{"type":"page","slug":"agents/kilo-cli","file":"kilo-cli.md"}]},"china/zh/meta.json":{"title":"MODELGO DOCS","description":"ModelGo 模型网关的接入指南与模型能力文档","items":[{"type":"section","slug":"about","file":"about/meta.json"},{"type":"section","slug":"quickstart","file":"quickstart/meta.json"},{"type":"section","slug":"models","file":"models/meta.json"},{"type":"section","slug":"agents","file":"agents/meta.json"}]},"china/zh/models/audio/meta.json":{"title":"音频","description":"语音合成、MiniMax 原厂 T2A、语音转文本与语音翻译接口。","items":[{"type":"page","slug":"models/audio/speech","file":"speech.md"},{"type":"page","slug":"models/audio/minimax","file":"minimax.md"},{"type":"page","slug":"models/audio/transcriptions","file":"transcriptions.md"},{"type":"page","slug":"models/audio/translations","file":"translations.md"}]},"china/zh/models/images/meta.json":{"title":"图像","description":"OpenAI 兼容图像生成与编辑接口，以及 GPT Image（gpt-image-2 / gpt-image-1.5）、Gemini 图像、Seedream 系列（5.0 pro / 5.0 lite / 5.0 / 4.5）、千问图像 3.0（qwen-image-3.0 / 3.0-pro）的原厂入站协议。","items":[{"type":"page","slug":"models/images/generations","file":"generations.md"},{"type":"page","slug":"models/images/edits","file":"edits.md"},{"type":"page","slug":"models/images/gpt-image-2","file":"gpt-image-2.md"},{"type":"page","slug":"models/images/gemini-image","file":"gemini-image.md"},{"type":"page","slug":"models/images/seedream","file":"seedream.md"},{"type":"page","slug":"models/images/qwen-image","file":"qwen-image.md"}]},"china/zh/models/meta.json":{"title":"模型调用","description":"按文本、图像、视频、向量、音频、重排能力组织的接口说明。","items":[{"type":"section","slug":"models/text","file":"text/meta.json"},{"type":"section","slug":"models/images","file":"images/meta.json"},{"type":"section","slug":"models/video","file":"video/meta.json"},{"type":"section","slug":"models/vectors","file":"vectors/meta.json"},{"type":"section","slug":"models/audio","file":"audio/meta.json"},{"type":"section","slug":"models/realtime","file":"realtime/meta.json"},{"type":"section","slug":"models/rerank","file":"rerank/meta.json"}]},"china/zh/models/realtime/meta.json":{"title":"实时语音（Realtime）","description":"通过 WebSocket 接入 Qwen-Omni-Realtime 的使用指南与 API 参考。","items":[{"type":"page","slug":"models/realtime/guide","file":"guide.md"},{"type":"page","slug":"models/realtime/api","file":"api.md"}]},"china/zh/models/rerank/meta.json":{"title":"重排","description":"Rerank 重排序接口。","items":[{"type":"page","slug":"models/rerank/rerank","file":"rerank.md"}]},"china/zh/models/text/meta.json":{"title":"文本","description":"文本生成与对话协议。","items":[{"type":"page","slug":"models/text/generation","file":"generation.md"}]},"china/zh/models/vectors/meta.json":{"title":"向量","description":"向量嵌入接口。","items":[{"type":"page","slug":"models/vectors/embeddings","file":"embeddings.md"}]},"china/zh/models/video/meta.json":{"title":"视频","description":"OpenAI 兼容视频流、通用异步内容生成任务、Seedance 与 MiniMax 原厂入站协议。","items":[{"type":"page","slug":"models/video/openai-compatible","file":"openai-compatible.md"},{"type":"page","slug":"models/video/wan27","file":"wan27.md"},{"type":"page","slug":"models/video/kling-v3","file":"kling-v3.md"},{"type":"page","slug":"models/video/veo31","file":"veo31.md"},{"type":"page","slug":"models/video/async-tasks","file":"async-tasks.md"},{"type":"page","slug":"models/video/ark","file":"ark.md"},{"type":"page","slug":"models/video/minimax","file":"minimax.md"}]},"china/zh/quickstart/meta.json":{"title":"快速开始","description":"首次调用、AI 工具接入、鉴权与错误处理。","items":[{"type":"page","slug":"quickstart/quickstart","file":"quickstart.md"},{"type":"page","slug":"quickstart/cli","file":"cli.md"},{"type":"page","slug":"quickstart/agent-clients","file":"agent-clients.md"},{"type":"page","slug":"quickstart/authentication","file":"authentication.md"},{"type":"page","slug":"quickstart/openapi","file":"openapi.md"},{"type":"page","slug":"quickstart/errors","file":"errors.md"}]},"international/en/about/meta.json":{"title":"About ModelGo","description":"Learn what ModelGo is and what it provides for developers.","items":[{"type":"page","slug":"quickstart/overview","file":"../quickstart/overview.md"}]},"international/en/agents/meta.json":{"title":"Tool Integrations","description":"ModelGo setup guides for popular AI clients and Agents.","items":[{"type":"page","slug":"agents/hermes-agent","file":"hermes-agent.md"},{"type":"page","slug":"agents/claude-code","file":"claude-code.md"},{"type":"page","slug":"agents/kilo-code","file":"kilo-code.md"},{"type":"page","slug":"agents/cline","file":"cline.md"},{"type":"page","slug":"agents/codex","file":"codex.md"},{"type":"page","slug":"agents/openclaw","file":"openclaw.md"},{"type":"page","slug":"agents/deepseek-harness","file":"deepseek-harness.md"},{"type":"page","slug":"agents/zcode","file":"zcode.md"},{"type":"page","slug":"agents/cursor","file":"cursor.md"},{"type":"page","slug":"agents/opencode","file":"opencode.md"},{"type":"page","slug":"agents/cc-switch","file":"cc-switch.md"},{"type":"page","slug":"agents/cherry-studio","file":"cherry-studio.md"},{"type":"page","slug":"agents/crush","file":"crush.md"},{"type":"page","slug":"agents/factory-droid","file":"factory-droid.md"},{"type":"page","slug":"agents/copilot-cli","file":"copilot-cli.md"},{"type":"page","slug":"agents/nanobot","file":"nanobot.md"},{"type":"page","slug":"agents/oh-my-pi","file":"oh-my-pi.md"},{"type":"page","slug":"agents/codebuddy","file":"codebuddy.md"},{"type":"page","slug":"agents/kilo-cli","file":"kilo-cli.md"}]},"international/en/meta.json":{"title":"MODELGO DOCS","description":"Getting started and model capability docs for the ModelGo model gateway.","items":[{"type":"section","slug":"about","file":"about/meta.json"},{"type":"section","slug":"quickstart","file":"quickstart/meta.json"},{"type":"section","slug":"models","file":"models/meta.json"},{"type":"section","slug":"agents","file":"agents/meta.json"}]},"international/en/models/audio/meta.json":{"title":"Audio","description":"Speech, MiniMax T2A, transcription, and translation endpoints.","items":[{"type":"page","slug":"models/audio/speech","file":"speech.md"},{"type":"page","slug":"models/audio/minimax","file":"minimax.md"},{"type":"page","slug":"models/audio/transcriptions","file":"transcriptions.md"},{"type":"page","slug":"models/audio/translations","file":"translations.md"}]},"international/en/models/images/meta.json":{"title":"Images","description":"Image generation and edit endpoints, plus the Qwen Image 3.0 (qwen-image-3.0 / 3.0-pro) vendor inbound protocol.","items":[{"type":"page","slug":"models/images/generations","file":"generations.md"},{"type":"page","slug":"models/images/edits","file":"edits.md"},{"type":"page","slug":"models/images/qwen-image","file":"qwen-image.md"}]},"international/en/models/meta.json":{"title":"Model Calls","description":"Capability-oriented API docs for text, images, video, vectors, audio, and rerank.","items":[{"type":"section","slug":"models/text","file":"text/meta.json"},{"type":"section","slug":"models/images","file":"images/meta.json"},{"type":"section","slug":"models/video","file":"video/meta.json"},{"type":"section","slug":"models/vectors","file":"vectors/meta.json"},{"type":"section","slug":"models/audio","file":"audio/meta.json"},{"type":"section","slug":"models/realtime","file":"realtime/meta.json"},{"type":"section","slug":"models/rerank","file":"rerank/meta.json"}]},"international/en/models/realtime/meta.json":{"title":"Realtime (WebSocket)","description":"Guide and API reference for calling Qwen-Omni-Realtime over WebSocket.","items":[{"type":"page","slug":"models/realtime/guide","file":"guide.md"},{"type":"page","slug":"models/realtime/api","file":"api.md"}]},"international/en/models/rerank/meta.json":{"title":"Rerank","description":"Rerank endpoint for relevance re-ordering.","items":[{"type":"page","slug":"models/rerank/rerank","file":"rerank.md"}]},"international/en/models/text/meta.json":{"title":"Text","description":"Text generation and dialogue protocols.","items":[{"type":"page","slug":"models/text/generation","file":"generation.md"}]},"international/en/models/vectors/meta.json":{"title":"Vectors","description":"Embedding endpoint.","items":[{"type":"page","slug":"models/vectors/embeddings","file":"embeddings.md"}]},"international/en/models/video/meta.json":{"title":"Video","description":"OpenAI-compatible video flow, generic async content generation tasks, and the Seedance and MiniMax vendor inbound protocols.","items":[{"type":"page","slug":"models/video/openai-compatible","file":"openai-compatible.md"},{"type":"page","slug":"models/video/async-tasks","file":"async-tasks.md"},{"type":"page","slug":"models/video/ark","file":"ark.md"},{"type":"page","slug":"models/video/minimax","file":"minimax.md"}]},"international/en/quickstart/meta.json":{"title":"Get Started","description":"First API call, AI tool setup, authentication, and error handling.","items":[{"type":"page","slug":"quickstart/quickstart","file":"quickstart.md"},{"type":"page","slug":"quickstart/cli","file":"cli.md"},{"type":"page","slug":"quickstart/agent-clients","file":"agent-clients.md"},{"type":"page","slug":"quickstart/authentication","file":"authentication.md"},{"type":"page","slug":"quickstart/openapi","file":"openapi.md"},{"type":"page","slug":"quickstart/errors","file":"errors.md"}]},"international/zh/agents/meta.json":{"title":"接入工具","description":"常用 AI 客户端与 Agent 的 ModelGo 接入说明。","items":[{"type":"page","slug":"agents/hermes-agent","file":"hermes-agent.md"},{"type":"page","slug":"agents/claude-code","file":"claude-code.md"},{"type":"page","slug":"agents/kilo-code","file":"kilo-code.md"},{"type":"page","slug":"agents/cline","file":"cline.md"},{"type":"page","slug":"agents/codex","file":"codex.md"},{"type":"page","slug":"agents/openclaw","file":"openclaw.md"},{"type":"page","slug":"agents/deepseek-harness","file":"deepseek-harness.md"},{"type":"page","slug":"agents/zcode","file":"zcode.md"},{"type":"page","slug":"agents/cursor","file":"cursor.md"},{"type":"page","slug":"agents/opencode","file":"opencode.md"},{"type":"page","slug":"agents/cc-switch","file":"cc-switch.md"},{"type":"page","slug":"agents/cherry-studio","file":"cherry-studio.md"},{"type":"page","slug":"agents/crush","file":"crush.md"},{"type":"page","slug":"agents/factory-droid","file":"factory-droid.md"},{"type":"page","slug":"agents/copilot-cli","file":"copilot-cli.md"},{"type":"page","slug":"agents/nanobot","file":"nanobot.md"},{"type":"page","slug":"agents/oh-my-pi","file":"oh-my-pi.md"},{"type":"page","slug":"agents/codebuddy","file":"codebuddy.md"},{"type":"page","slug":"agents/kilo-cli","file":"kilo-cli.md"}]},"international/zh/meta.json":{"title":"MODELGO DOCS","description":"ModelGo 模型网关的接入指南与模型能力文档","items":[{"type":"section","slug":"quickstart","file":"quickstart/meta.json"},{"type":"section","slug":"models","file":"models/meta.json"},{"type":"section","slug":"agents","file":"agents/meta.json"}]},"international/zh/models/audio/meta.json":{"title":"音频","description":"语音合成、MiniMax 原厂 T2A、语音转文本与语音翻译接口。","items":[{"type":"page","slug":"models/audio/speech","file":"speech.md"},{"type":"page","slug":"models/audio/minimax","file":"minimax.md"},{"type":"page","slug":"models/audio/transcriptions","file":"transcriptions.md"},{"type":"page","slug":"models/audio/translations","file":"translations.md"}]},"international/zh/models/images/meta.json":{"title":"图像","description":"图像生成与图像编辑接口，以及千问图像 3.0（qwen-image-3.0 / 3.0-pro）的原厂入站协议。","items":[{"type":"page","slug":"models/images/generations","file":"generations.md"},{"type":"page","slug":"models/images/edits","file":"edits.md"},{"type":"page","slug":"models/images/qwen-image","file":"qwen-image.md"}]},"international/zh/models/meta.json":{"title":"模型","description":"按文本、图像、视频、向量、音频、重排能力组织的接口说明。","items":[{"type":"section","slug":"models/text","file":"text/meta.json"},{"type":"section","slug":"models/images","file":"images/meta.json"},{"type":"section","slug":"models/video","file":"video/meta.json"},{"type":"section","slug":"models/vectors","file":"vectors/meta.json"},{"type":"section","slug":"models/audio","file":"audio/meta.json"},{"type":"section","slug":"models/realtime","file":"realtime/meta.json"},{"type":"section","slug":"models/rerank","file":"rerank/meta.json"}]},"international/zh/models/realtime/meta.json":{"title":"实时语音（Realtime）","description":"通过 WebSocket 接入 Qwen-Omni-Realtime 的使用指南与 API 参考。","items":[{"type":"page","slug":"models/realtime/guide","file":"guide.md"},{"type":"page","slug":"models/realtime/api","file":"api.md"}]},"international/zh/models/rerank/meta.json":{"title":"重排","description":"Rerank 重排序接口。","items":[{"type":"page","slug":"models/rerank/rerank","file":"rerank.md"}]},"international/zh/models/text/meta.json":{"title":"文本","description":"文本生成与对话协议。","items":[{"type":"page","slug":"models/text/generation","file":"generation.md"}]},"international/zh/models/vectors/meta.json":{"title":"向量","description":"向量嵌入接口。","items":[{"type":"page","slug":"models/vectors/embeddings","file":"embeddings.md"}]},"international/zh/models/video/meta.json":{"title":"视频","description":"OpenAI 兼容视频流、通用异步内容生成任务、Seedance 与 MiniMax 原厂入站协议。","items":[{"type":"page","slug":"models/video/openai-compatible","file":"openai-compatible.md"},{"type":"page","slug":"models/video/async-tasks","file":"async-tasks.md"},{"type":"page","slug":"models/video/ark","file":"ark.md"},{"type":"page","slug":"models/video/minimax","file":"minimax.md"}]},"international/zh/quickstart/meta.json":{"title":"快速开始","description":"平台概览、首次调用、AI 工具接入、鉴权与错误处理。","items":[{"type":"page","slug":"quickstart/overview","file":"overview.md"},{"type":"page","slug":"quickstart/quickstart","file":"quickstart.md"},{"type":"page","slug":"quickstart/cli","file":"cli.md"},{"type":"page","slug":"quickstart/agent-clients","file":"agent-clients.md"},{"type":"page","slug":"quickstart/authentication","file":"authentication.md"},{"type":"page","slug":"quickstart/openapi","file":"openapi.md"},{"type":"page","slug":"quickstart/errors","file":"errors.md"}]}}
 export const DOCS_CHANGELOG = "---\ntitle: 更新日志 Changelog\nlayout: page\n---\n\n# 更新日志 · Changelog\n\n## v1.0 · 启程 / The Beginning\n\n> 万物有始。这是 ModelGo 的第一章。\n> Every story has its first page. This is ours.\n\n我们想做的事其实很简单——**让每一次模型调用，都清晰、可控、可信**。\n1.0 把这件事，落成了你眼前的控制台与 API 网关。\n\n### 控制台 · Console\n\n- **API Keys** —— 一处掌管所有密钥，按个人 / 工作区 / 成员分级授权\n- **用量分析** —— 调用、Token、花费，尽收眼底\n- **账单计费** —— 充值与消费，一笔一笔看得分明\n- **安全护栏** —— 为每一把钥匙划定预算与边界\n- **可观测性** —— 每一次调用的来龙去脉，皆可回溯\n- **模型体验** —— 在浏览器里先与模型对谈，而后落地\n- **推荐计划** —— 邀同行同路，共享生长\n\n### API 网关 · Gateway\n\n- **统一入口** —— 一个 `base_url`，以 OpenAI 兼容协议接入上百模型\n- **自由切换** —— 一次接入，模型随心\n- **实时计量** —— 每次调用，实时计费、实时入账\n\n---\n\n> 序章既启，来日方长。\n> The prologue is written; the story is long.\n> 谢谢你，与我们一同从 1.0 出发。\n> Thank you for starting at 1.0 with us.\n"