[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-detail-video":3},{"tree":4,"doc":154,"breadcrumbs":172,"path":108},[5,12,47,77,106,141],{"title":6,"path":7,"order":8,"requiredFlags":9,"content":10,"children":11},"快速开始","getting-started",1,[],"# 快速开始\n\n本指南帮助你在 5 分钟内发出第一个 API 请求。\n\n## 1. 获取 API Key\n\n1. 注册账号后，在控制台创建组织。\n2. 进入 **API Keys** 页面创建一个 API Key。Key 格式为 `sk_live_` 开头的字符串，**仅在创建时显示一次**，请妥善保存。\n3. 建议将 Key 存为环境变量：\n\n```bash\nexport SILVAMUX_API_KEY=\"sk_live_YOUR_API_KEY\"\n```\n\n## 2. 发送第一个请求\n\nSilvaMux 的对话 API 兼容 OpenAI 格式。如果你已有 OpenAI SDK 代码，只需修改 Base URL 和 API Key 即可。\n\n> **关于 `model` 字段**：填**调用名**（即模型 `id` 或 `alias`），优先用 alias（更稳定，不带日期版本号）。例如 `minimax-m2.5`、`kimi-k2.5`、`doubao-seedance-1.5-pro`。完整清单调 `GET \u002Fbilling\u002Fmodels` 接口。\n\n### curl\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"用一句话介绍你自己\"}\n    ]\n  }'\n```\n\n### Python (OpenAI SDK)\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"SILVAMUX_API_KEY\"],\n    base_url=\"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\",\n)\n\nresponse = client.chat.completions.create(\n    model=\"minimax-m2.5\",\n    messages=[{\"role\": \"user\", \"content\": \"用一句话介绍你自己\"}],\n)\n\nprint(response.choices[0].message.content)\n```\n\n### Node.js (OpenAI SDK)\n\n```javascript\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  apiKey: process.env.SILVAMUX_API_KEY,\n  baseURL: \"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\",\n});\n\nconst response = await client.chat.completions.create({\n  model: \"minimax-m2.5\",\n  messages: [{ role: \"user\", content: \"用一句话介绍你自己\" }],\n});\n\nconsole.log(response.choices[0].message.content);\n```\n\n## 3. 流式输出\n\n设置 `stream: true` 即可获得流式响应（SSE）：\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"写一首五言绝句\"}],\n    \"stream\": true\n  }'\n```\n\n流式响应格式为 Server-Sent Events，每个事件的 `data` 字段包含一个 JSON chunk，最后一个事件为 `data: [DONE]`。流式的完整用法见 [对话补全 API](\u002Fdocs\u002Fchat\u002Foverview#流式输出)。\n\n## 4. 使用 Anthropic 格式\n\n如果你更熟悉 Anthropic 的 Messages API，SilvaMux 同样支持：\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fanthropic\u002Fv1\u002Fmessages \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"max_tokens\": 1024,\n    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]\n  }'\n```\n\n## 下一步\n\n- [对话补全 API](\u002Fdocs\u002Fchat\u002Foverview)：对话接口完整字段\n- [计费说明](\u002Fdocs\u002Fcommon\u002Fbilling)：充值、折扣、账单",[],{"title":13,"path":14,"order":15,"requiredFlags":16,"content":17,"children":18},"通用信息","common",10,[],"# 通用信息\n\n跨功能的通用信息。\n\n- [计费说明](\u002Fdocs\u002Fcommon\u002Fbilling)\n- [客户查询 API](\u002Fdocs\u002Fcommon\u002Fcustomer-api)\n- [错误处理](\u002Fdocs\u002Fcommon\u002Ferrors)\n- [常见问题](\u002Fdocs\u002Fcommon\u002Ffaq)",[19,26,33,40],{"title":20,"path":21,"order":22,"requiredFlags":23,"content":24,"children":25},"计费说明","common\u002Fbilling",3,[],"# 计费说明\n\nSilvaMux 按实际用量计费，支持充值、折扣与账单导出。\n\n## 余额与充值\n\n- 余额不足时模型请求返回 `INSUFFICIENT_BALANCE`（HTTP 402），需充值后重试。\n- 充值：控制台「充值」页，或 `POST \u002Fbilling\u002Forders` 创建充值订单。\n- 充值记录：控制台或 `GET \u002Fbilling\u002Ftopups`。\n\n## 折扣\n\n平台支持按组织、按模型分组配置折扣，由管理员设置。未配置折扣时按原价计费。\n\n## 账单与导出\n\n- 实时账单：控制台「账单」页，或 `GET \u002Fbilling\u002Fledger`、`GET \u002Fbilling\u002Fusage-summaries`。\n- 账单导出：`POST \u002Fbilling\u002Fexports` 创建导出任务，完成后 `GET \u002Fbilling\u002Fexports\u002F{id}\u002Fdownload` 下载（CSV），有过期时间。\n\n## 模型价目\n\n完整模型价目调 `GET \u002Fbilling\u002Fmodels` 接口，返回每个模型的定价信息。各能力的计费方式：\n\n- 对话：按 token 用量（输入 + 输出）计费。\n- 图片生成：按生成张数计费。\n- 视频生成：按模型与视频参数（分辨率、时长、是否配音）计费。",[],{"title":27,"path":28,"order":29,"requiredFlags":30,"content":31,"children":32},"客户查询 API","common\u002Fcustomer-api",4,[],"# 客户查询 API\n\n客户可通过 API Key（`sk_live_` 开头）程序化查询组织余额与项目消耗，无需登录态。所有接口仅接受 API Key 鉴权，消耗数据自动限定到该 Key 所属的项目。\n\n## 鉴权\n\n在请求头携带 API Key：\n\n```\nAuthorization: Bearer sk_live_YOUR_API_KEY\n```\n\nAPI Key 在控制台「API Keys」页面创建，绑定到某个组织与项目。查询消耗时只能看到该 Key 所属项目的数据，不能跨项目查询；余额为组织级。\n\n## 查询余额\n\n```\nGET https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fcustomer\u002Fbalance\n```\n\n返回当前组织余额。\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fcustomer\u002Fbalance \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\"\n```\n\n响应：\n\n```json\n{\n  \"balance_points\": \"42.5\"\n}\n```\n\n| 字段 | 说明 |\n|---|---|\n| `balance_points` | 当前余额（points） |\n\n## 查询消耗\n\n```\nGET https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fcustomer\u002Fusage?from={from}&to={to}\n```\n\n返回指定时间段内、该 API Key 所属项目的消耗汇总：总额与按模型分项。\n\n- `from`、`to`：RFC3339 时间，左闭右开 `[from, to)`，`from` 必须早于 `to`。\n- 时间范围以 UTC 为准。\n\n```bash\ncurl \"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fcustomer\u002Fusage?from=2026-07-08T00:00:00Z&to=2026-07-09T00:00:00Z\" \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\"\n```\n\n响应：\n\n```json\n{\n  \"from\": \"2026-07-08T00:00:00Z\",\n  \"to\": \"2026-07-09T00:00:00Z\",\n  \"project_id\": \"PROJ-1\",\n  \"totals\": {\n    \"cost_points\": \"1.5\",\n    \"prompt_tokens\": 100,\n    \"cached_tokens\": 0,\n    \"billable_prompt_tokens\": 100,\n    \"completion_tokens\": 50,\n    \"cache_creation_tokens\": 0,\n    \"total_tokens\": 150,\n    \"generated_artifacts\": 0,\n    \"request_count\": 2\n  },\n  \"by_model\": [\n    {\n      \"model\": \"deepseek-v4-pro@tune\",\n      \"cost_points\": \"1.5\",\n      \"prompt_tokens\": 100,\n      \"cached_tokens\": 0,\n      \"billable_prompt_tokens\": 100,\n      \"completion_tokens\": 50,\n      \"cache_creation_tokens\": 0,\n      \"total_tokens\": 150,\n      \"generated_artifacts\": 0,\n      \"request_count\": 2\n    }\n  ]\n}\n```\n\n| 字段 | 说明 |\n|---|---|\n| `project_id` | 该 API Key 绑定的项目 |\n| `totals` | 时间范围内所有模型的汇总 |\n| `by_model` | 按模型分项，按 `cost_points` 降序 |\n\n## 错误处理\n\n| HTTP 状态 | 错误码 | 说明 |\n|---|---|---|\n| 401 | `INVALID_TOKEN` | API Key 缺失或无效 |\n| 400 | `INVALID_FROM_DATETIME` | `from` 缺失或格式非 RFC3339 |\n| 400 | `INVALID_TO_DATETIME` | `to` 缺失或格式非 RFC3339 |\n| 400 | `INVALID_TIME_RANGE` | `from` 不早于 `to` |\n\n> 通用错误处理见 [错误处理](\u002Fdocs\u002Fcommon\u002Ferrors)。",[],{"title":34,"path":35,"order":36,"requiredFlags":37,"content":38,"children":39},"错误处理","common\u002Ferrors",5,[],"# 错误处理\n\nSilvaMux 的错误格式取决于接口类型。本页介绍通用错误格式与重试建议，各模块的具体错误码见：\n\n- [对话错误码](\u002Fdocs\u002Fchat\u002Ferrors)\n- [图片生成错误码](\u002Fdocs\u002Fimages\u002Ferrors)\n- [视频生成错误码](\u002Fdocs\u002Fvideo\u002Ferrors)\n\n## Gateway API 错误（模型调用）\n\n对话、图片、视频等模型调用接口的错误格式由模型协议决定，分 OpenAI \u002F Anthropic \u002F Gemini \u002F Volcengine 四种渲染形状，`code` 字符串统一。\n\n```json\n{\n  \"error\": {\n    \"message\": \"具体错误信息\",\n    \"type\": \"gateway_error\",\n    \"code\": \"ERROR_CODE\"\n  }\n}\n```\n\n模型侧返回 4xx\u002F5xx 时，SilvaMux 会脱敏后透传错误响应，HTTP 状态码保持一致，此时不会产生扣费。\n\n## Billing \u002F Business API 错误（管理接口）\n\n账户、计费、自有素材等管理接口使用 RFC 7807 风格：\n\n```json\n{\n  \"status\": 400,\n  \"detail\": \"具体错误信息\",\n  \"type\": \"tag:hub,2026-03:ERROR_CODE\"\n}\n```\n\n验证错误包含 `errors` 数组：\n\n```json\n{\n  \"status\": 422,\n  \"detail\": \"validation failed\",\n  \"type\": \"tag:hub,2026-03:VALIDATION_FAILED\",\n  \"errors\": [{\"location\": \"body.email\", \"message\": \"required\"}]\n}\n```\n\n## 重试建议\n\n| HTTP 状态码 | 建议 |\n| --- | --- |\n| 400 | 不要重试，修正请求参数 |\n| 401 | 不要重试，检查认证信息 |\n| 402 | 不要重试，充值后再试 |\n| 403 | 不要重试，联系管理员 |\n| 429 | 等待后重试，建议指数退避 |\n| 500 | 可以重试，建议间隔 1-5 秒 |\n| 502 | 可以重试，模型侧暂时不可用 |\n\n## 请求 ID\n\n每个请求返回 `X-Request-Id` header（格式 `REQ-xxxx`）。排查问题时提供此 ID。你也可以在请求中自行设置 `X-Request-Id`，系统会沿用。",[],{"title":41,"path":42,"order":43,"requiredFlags":44,"content":45,"children":46},"常见问题","common\u002Ffaq",7,[],"# 常见问题\n\n## Base URL 是什么？在哪查？\n\nBase URL 是接入域名，构建时按部署自动填入文档示例。例如中文站 API Base URL 形如 `https:\u002F\u002Fwww.silvamux.com`。文档中的 `https:\u002F\u002Fwww.silvamux.com` 占位符在站点构建时自动替换为实际域名，复制示例时无需手动改。\n\n- 对话统一入口（推荐）：`https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\u002Fchat\u002Fcompletions`\n- 对话（OpenAI 格式）：`https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions`\n- 对话（Anthropic 格式）：`https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fanthropic\u002Fv1\u002Fmessages`\n- 图片\u002F视频\u002F3D：`https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002F...`\n\n## API Key 在哪创建？格式是什么？\n\n控制台 **API Keys** 页面创建，格式 `sk_live_` 开头，仅创建时显示一次。建议存为环境变量 `SILVAMUX_API_KEY`。\n\n## `model` 字段填什么？\n\n填**调用名**（模型 `id` 或 `alias`），优先用 alias。如 `minimax-m2.5`、`doubao-seedance-1-5-pro-251215`。完整清单调 `GET \u002Fbilling\u002Fmodels` 接口（hidden 不显示）。\n\n## `供应商\u002F模型` 格式还能用吗？\n\n能。历史 `供应商\u002F模型` 格式仍兼容，但建议用 alias（更简洁）。\n\n## 什么是 Standard \u002F Pro 档位？要加 `@tune` 吗？\n\n平台支持按档位区分同模型的不同供给侧（`@tune` 后缀表示标准档），但当前所有模型均为单档，直接用 alias 调用，无需加 `@tune`。后续上线双档模型时会在模型清单标注。\n\n## 余额不足怎么办？\n\n充值：控制台「充值」页，或 `POST \u002Fbilling\u002Forders` 创建充值订单。余额不足时模型请求返回 `INSUFFICIENT_BALANCE`（402）。详见 [计费说明](\u002Fdocs\u002Fcommon\u002Fbilling)。\n\n## 没配置折扣是免费吗？\n\n不是。未配置折扣时按原价计费（系数为 1）。折扣由管理员按组织 × pricing_group 配置。\n\n## 401 Unauthorized\n\n检查 API Key 是否正确、是否过期。Gateway 接口用 `Authorization: Bearer sk_live_...` 或 `x-api-key: sk_live_...`。\n\n## 429 RATE_LIMITED\n\n触发限流，等待后重试（建议指数退避）。视频\u002F图片生成并发上限会返回 `CONCURRENCY_LIMIT_EXCEEDED`。\n\n## 502 UPSTREAM_*\n\n模型侧异常，可重试。持续失败联系平台。\n\n## 还没找到答案？\n\n- [错误处理](\u002Fdocs\u002Fcommon\u002Ferrors)：完整错误码\n- 联系销售：见页面底部",[],{"title":48,"path":49,"order":50,"requiredFlags":51,"content":52,"children":53},"对话","chat",20,[],"# 对话\n\n对话补全接口，兼容 OpenAI \u002F Anthropic \u002F Volcengine v3 \u002F Responses 格式，支持流式与多模态输入。\n\n- [对话补全 API](\u002Fdocs\u002Fchat\u002Foverview)\n- [多模态](\u002Fdocs\u002Fchat\u002Fmultimodal)\n- [错误码](\u002Fdocs\u002Fchat\u002Ferrors)\n- [常见问题](\u002Fdocs\u002Fchat\u002Ffaq)",[54,60,66,71],{"title":55,"path":56,"order":8,"requiredFlags":57,"content":58,"children":59},"对话补全 API","chat\u002Foverview",[],"# 对话补全 API\n\nSilvaMux 提供一个**统一入口**和多种**格式兼容入口**。新接入推荐用统一入口；已有官方 SDK 代码或旧接入可继续用格式兼容入口，互不影响。\n\n## 统一入口（推荐）\n\n`POST \u002Fapi\u002Fv0\u002Fchat\u002Fcompletions` 是统一入口，按 `model` 自动选上游并转换格式，响应\u002FSSE\u002F错误统一吐回 OpenAI Chat 格式。一条入口调任意模型（OpenAI \u002F Anthropic \u002F 火山 \u002F 智谱 \u002F Responses 等均支持），无需按模型选端点。\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv0\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]\n  }'\n```\n\n> OpenAI SDK 配 `base_url=\"\u003C接入域名>\u002Fapi\u002Fv0\"` 即可直接用（SDK 自动拼 `\u002Fchat\u002Fcompletions`），`\u003C接入域名>` 即文档示例中 `https:\u002F\u002Fwww.silvamux.com` 替换后的实际域名。\n>\n> 统一入口支持 tool calling、reasoning、多模态，按模型能力自动处理。响应恒为 OpenAI Chat 格式，即使上游是 Anthropic \u002F Volcengine \u002F Responses 模型。\n\n## 格式兼容入口（旧模式 \u002F 官方迁移）\n\n下列端点各自收原生格式，请求体**原样透传**给模型侧，适合已有官方 SDK 代码或需要字段级透传的场景。所有端点均保留，向前兼容。\n\n| 格式 | 端点 | 适用 |\n| --- | --- | --- |\n| OpenAI | `POST \u002Fapi\u002Fv1\u002Fchat\u002Fcompletions` | 兼容 OpenAI SDK |\n| Anthropic | `POST \u002Fapi\u002Fanthropic\u002Fv1\u002Fmessages` | 兼容 Anthropic SDK |\n| Volcengine v3 | `POST \u002Fapi\u002Fv3\u002Fchat\u002Fcompletions` | 兼容火山方舟 SDK |\n| Responses | `POST \u002Fapi\u002Fv1\u002Fresponses` | 兼容 OpenAI Responses API |\n| 智谱 | `POST \u002Fapi\u002Fpaas\u002Fv4\u002Fchat\u002Fcompletions` | 兼容智谱官方 SDK，配 `base_url=\"\u003C接入域名>\u002Fapi\u002Fpaas\u002Fv4\"` 不改代码迁入，`model` 用智谱官方名（如 `glm-5`） |\n\n> 统一入口与格式兼容入口区别：统一入口经过格式转换层（OpenAI Chat ↔ 上游格式），能跨格式调用但会规范化请求\u002F响应结构；格式兼容入口原样透传，字段保真但只能调对应格式的模型。\n\n**认证：** `Authorization: Bearer \u003CAPI_KEY>` 或 `x-api-key: \u003CAPI_KEY>`。\n\n## 关键参数\n\n| 参数 | 类型 | 说明 |\n| --- | --- | --- |\n| `model` | string | 必填。模型调用名（`id` 或 `alias`），如 `minimax-m2.5`、`doubao-seed-2.0-pro` |\n| `messages` | array | 必填。对话消息列表，格式同 OpenAI（`role` + `content`） |\n| `stream` | boolean | 是否流式返回，默认 `false` |\n| `temperature` | number | 采样温度，默认 1.0 |\n| `max_tokens` | integer | 最大生成 token 数 |\n\n> 完整参数与 OpenAI \u002F Anthropic 官方 API 一致，透传给模型侧。`model` 调用名调 `GET \u002Fbilling\u002Fmodels` 获取（hidden 不显示）。\n\n## OpenAI 格式示例\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"messages\": [\n      {\"role\": \"system\", \"content\": \"你是一个有帮助的助手\"},\n      {\"role\": \"user\", \"content\": \"你好\"}\n    ],\n    \"stream\": false\n  }'\n```\n\n响应（OpenAI 格式）：\n\n```json\n{\n  \"id\": \"chatcmpl-xxxx\",\n  \"choices\": [\n    {\n      \"message\": {\"role\": \"assistant\", \"content\": \"你好！有什么可以帮你的吗？\"},\n      \"finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\"prompt_tokens\": 20, \"completion_tokens\": 15, \"total_tokens\": 35}\n}\n```\n\n## Anthropic 格式示例\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fanthropic\u002Fv1\u002Fmessages \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"max_tokens\": 1024,\n    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]\n  }'\n```\n\n响应（Anthropic 格式）：\n\n```json\n{\n  \"id\": \"msg_xxxx\",\n  \"type\": \"message\",\n  \"role\": \"assistant\",\n  \"content\": [{\"type\": \"text\", \"text\": \"你好！有什么可以帮你的吗？\"}],\n  \"usage\": {\"input_tokens\": 10, \"output_tokens\": 15}\n}\n```\n\n## Volcengine v3 格式示例\n\n兼容火山方舟 OpenAI 兼容接口，可用于豆包 Seed 系列等走火山 v3 协议的模型。\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seed-2.0-pro\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]\n  }'\n```\n\n> `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3` 即接入域名下的 `\u002Fapi\u002Fv3`，对应路由 `\u002Fapi\u002Fv3\u002Fchat\u002Fcompletions`。\n\n## Responses 格式示例\n\n兼容 OpenAI Responses API，适用于支持的模型（如 codex 系列）。\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fresponses \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"gpt-5.3-codex-maple\",\n    \"input\": \"用一句话介绍你自己\"\n  }'\n```\n\n## 流式输出\n\n设置 `stream: true` 即可获得流式响应（SSE）：\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m2.5\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"写一首五言绝句\"}],\n    \"stream\": true\n  }'\n```\n\n响应为 `text\u002Fevent-stream`，每个事件以 `data: ` 开头，最后一个为 `data: [DONE]`，最终 chunk 含 `usage` 用量。Anthropic 格式流式遵循 Anthropic SSE 规范。\n\nPython SDK 流式：\n\n```python\nstream = client.chat.completions.create(\n    model=\"minimax-m2.5\",\n    messages=[{\"role\": \"user\", \"content\": \"写一首五言绝句\"}],\n    stream=True,\n)\nfor chunk in stream:\n    delta = chunk.choices[0].delta.content\n    if delta:\n        print(delta, end=\"\", flush=True)\n```\n\n## 多模态输入\n\n`messages` 中可传入图片（`image_url`，OpenAI vision 格式）和音频（`input_audio`），平台透传给模型侧，能否处理取决于模型。\n\n## 可用模型\n\n样例模型：`minimax-m2.5`、`kimi-k2.5`、`glm-5.1`、`deepseek-v4-pro`、`doubao-seed-2.0-pro` 等。\n\n> 完整模型清单见[模型广场](\u002Fmodels)。\n\n## 计费\n\n对话按 token 用量计费（输入 + 输出），流式与非流式计费一致，具体单价调 `GET \u002Fbilling\u002Fmodels` 接口。",[],{"title":61,"path":62,"order":22,"requiredFlags":63,"content":64,"children":65},"多模态","chat\u002Fmultimodal",[],"# 多模态\n\n本页说明对话接口的多模态输入能力。SilvaMux 对多模态内容**透传**给模型侧，能否处理取决于模型本身。\n\n## 图片输入（vision）\n\n支持 OpenAI vision 格式，在 `messages` 的 `content` 中传入 `image_url`：\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"minimax-m3\",\n    \"messages\": [\n      {\n        \"role\": \"user\",\n        \"content\": [\n          {\"type\": \"text\", \"text\": \"这张图里有什么？\"},\n          {\"type\": \"image_url\", \"image_url\": {\"url\": \"https:\u002F\u002Fexample.com\u002Fcat.jpg\"}}\n        ]\n      }\n    ]\n  }'\n```\n\n- `image_url.url` 可以是公网 URL，或 base64 编码（`data:image\u002Fjpeg;base64,...`）。\n- 平台不解析也不剥离图片内容，原样转发给模型侧。\n- 是否支持图片输入由模型决定（如部分多模态模型支持，纯文本模型会报错）。\n\n## 音频输入\n\n支持 OpenAI audio 格式，在 `content` 中传入 `input_audio`：\n\n```json\n{\n  \"type\": \"input_audio\",\n  \"input_audio\": {\"data\": \"\u003Cbase64>\", \"format\": \"wav\"}\n}\n```\n\n- 平台透传，能否处理由模型决定。\n- 音频 token 按普通输入 token 计价（无独立多模态单价）。",[],{"title":41,"path":67,"order":29,"requiredFlags":68,"content":69,"children":70},"chat\u002Ffaq",[],"# 常见问题\n\n### 流式响应中断了会重复计费吗？\n\n不会。已结算的 token 不会重复扣；中断后重新请求按新请求的用量计费。\n\n### 401 Unauthorized\n\n检查 API Key 是否正确、是否过期。用 `Authorization: Bearer sk_live_...` 或 `x-api-key: sk_live_...`。\n\n### 429 RATE_LIMITED\n\n触发限流，等待后重试（建议指数退避）。\n\n### 502 UPSTREAM_*\n\n模型侧异常，可重试。持续失败联系平台。",[],{"title":72,"path":73,"order":36,"requiredFlags":74,"content":75,"children":76},"错误码","chat\u002Ferrors",[],"# 错误码\n\n对话接口（Gateway API）使用 OpenAI 兼容错误格式：\n\n```json\n{\n  \"error\": {\n    \"message\": \"具体错误信息\",\n    \"type\": \"gateway_error\",\n    \"code\": \"ERROR_CODE\"\n  }\n}\n```\n\nAnthropic \u002F Volcengine 格式的错误形状各有差异，但 `code` 字段一致。\n\n## 常见错误码\n\n| 错误码 | HTTP | 说明 |\n| --- | --- | --- |\n| `MODEL_REQUIRED` | 400 | 请求体缺少 `model` 字段 |\n| `MODEL_NOT_FOUND` | 400 | 模型不存在或不可用 |\n| `INVALID_REQUEST` | 400 | 请求参数无效 |\n| `INVALID_REQUEST_BODY` | 400 | 请求体解析失败 |\n| `UNAUTHORIZED` | 401 | 认证失败（API Key\u002FJWT 无效） |\n| `MODEL_ACCESS_DENIED` | 403 | 组织缺少该模型所需权限标志 |\n| `INSUFFICIENT_BALANCE` | 402 | 余额不足 |\n| `PRE_DEDUCT_FAILED` | 400\u002F402 | 预扣费失败（参数错误=400，落库失败=402） |\n| `RATE_LIMITED` | 429 | 触发限流 |\n| `UPSTREAM_UNAVAILABLE` | 502 | 模型侧请求发送失败 |\n| `UPSTREAM_HTTP_ERROR` | 502 | 模型侧返回 4xx\u002F5xx |\n| `UPSTREAM_PROVIDER_ERROR` | 502 | 模型侧业务错误 |\n| `UPSTREAM_INVALID_RESPONSE` | 502 | 模型侧响应无法解析 |\n| `INTERNAL` | 500 | 内部错误 |\n\n## 模型侧错误透传\n\n模型侧返回 4xx\u002F5xx 时，SilvaMux 会脱敏后透传错误响应，HTTP 状态码保持一致，此时不会产生扣费。\n\n## 重试建议\n\n| HTTP 状态码 | 建议 |\n| --- | --- |\n| 400 | 不要重试，修正请求参数 |\n| 401 | 不要重试，检查认证信息 |\n| 402 | 不要重试，充值后再试 |\n| 403 | 不要重试，联系管理员 |\n| 429 | 等待后重试，建议指数退避 |\n| 500 | 可以重试，建议间隔 1-5 秒 |\n| 502 | 可以重试，模型侧暂时不可用 |\n\n每个请求返回 `X-Request-Id` header（格式 `REQ-xxxx`），排查问题时提供此 ID。",[],{"title":78,"path":79,"order":80,"requiredFlags":81,"content":82,"children":83},"图片生成","images",30,[],"# 图片生成\n\n图片生成支持文生图与图生图（图片编辑）。\n\n- [图片生成](\u002Fdocs\u002Fimages\u002Ftext-to-image)\n- [图片编辑](\u002Fdocs\u002Fimages\u002Fimage-edit)\n- [错误码](\u002Fdocs\u002Fimages\u002Ferrors)\n- [常见问题](\u002Fdocs\u002Fimages\u002Ffaq)",[84,89,96,101],{"title":78,"path":85,"order":8,"requiredFlags":86,"content":87,"children":88},"images\u002Ftext-to-image",[],"# 图片生成\n\n文生图接口根据模型分为两种风格：OpenAI Images API 风格（豆包 Seedream）和 Gemini `generateContent` 风格。\n\n## OpenAI 风格（Seedream）\n\n```\nPOST \u002Fapi\u002Fv3\u002Fimages\u002Fgenerations\n```\n\n**认证：** `Authorization: Bearer \u003CAPI_KEY>` 或 `x-api-key: \u003CAPI_KEY>`\n\n### 关键参数\n\n| 参数 | 类型 | 必填 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 是 | 模型调用名，如 `doubao-seedream-5-0-260128` |\n| `prompt` | string | 是 | 图片描述 |\n| `n` | integer | 否 | 图片数量，默认 1 |\n| `size` | string | 否 | 尺寸，如 `1024x1024`，具体支持尺寸因模型而异 |\n| `stream` | boolean | 否 | 是否开启 SSE 流式返回中间图 |\n\n> `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3` 即接入域名下的 `\u002Fapi\u002Fv3`，对应路由 `\u002Fapi\u002Fv3\u002Fimages\u002Fgenerations`。\n\n### 示例\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fimages\u002Fgenerations \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seedream-5-0-260128\",\n    \"prompt\": \"一只戴墨镜的柴犬坐在咖啡馆里\",\n    \"size\": \"1024x1024\",\n    \"n\": 1\n  }'\n```\n\n响应：\n\n```json\n{\n  \"created\": 1234567890,\n  \"data\": [{\"url\": \"https:\u002F\u002F...\"}],\n  \"usage\": {\"output_images\": 1}\n}\n```\n\n## Gemini 风格\n\nGemini `generateContent` 风格，适合 Gemini 图像模型。\n\n```\nPOST \u002Fapi\u002Fv1\u002Fgemini\u002Fv1beta\u002Fmodels\u002F{model}:generateContent\n```\n\n**认证：** `Authorization: Bearer \u003CAPI_KEY>` 或 `x-api-key: \u003CAPI_KEY>`\n\n### 示例\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv1\u002Fgemini\u002Fv1beta\u002Fmodels\u002Fgemini-3.1-flash-image:generateContent \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"contents\": [\n      {\"role\": \"user\", \"parts\": [{\"text\": \"画一只坐在窗台上的猫\"}]}\n    ],\n    \"generationConfig\": {\n      \"responseModalities\": [\"TEXT\", \"IMAGE\"],\n      \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}\n    }\n  }'\n```\n\n响应保持 Gemini 格式，计费字段在 `usageMetadata` 中。\n\n## 上传限制\n\n请求体大小不超过 64 MB。超出返回 `413`（`REQUEST_TOO_LARGE`）。\n\n## 可用模型\n\n样例模型：`doubao-seedream-5-0-260128`（Seedream）、`gemini-3.1-flash-image`（Gemini）。\n\n> 完整模型清单见[模型广场](\u002Fmodels)。\n\n## 计费\n\n文生图按生成张数计费，具体单价调 `GET \u002Fbilling\u002Fmodels` 接口。",[],{"title":90,"path":91,"order":92,"requiredFlags":93,"content":94,"children":95},"图片编辑","images\u002Fimage-edit",2,[],"# 图片编辑\n\n图生图（图片编辑）接口兼容 OpenAI Images Edits 风格，使用 `multipart\u002Fform-data` 上传图片并按提示词编辑。\n\n```\nPOST \u002Fapi\u002Fv3\u002Fimages\u002Fedits\n```\n\n**认证：** `Authorization: Bearer \u003CAPI_KEY>` 或 `x-api-key: \u003CAPI_KEY>`\n\n## 关键参数\n\n| 参数 | 类型 | 必填 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 是 | 模型调用名，如 `gpt-image-2` |\n| `image` | file | 是 | 输入图片，最多 16 张（重复传入 `image=@...`） |\n| `prompt` | string | 是 | 编辑指令 |\n| `size` | string | 否 | 尺寸，如 `1024x1024` |\n| `mask` | file | 否 | 蒙版图 |\n| `n` | integer | 否 | 输出图片数量 |\n| `stream` | boolean | 否 | 是否开启 SSE 流式返回中间图 |\n\n> `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3` 即接入域名下的 `\u002Fapi\u002Fv3`，对应路由 `\u002Fapi\u002Fv3\u002Fimages\u002Fedits`。\n\n## 示例\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fimages\u002Fedits \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -F \"model=gpt-image-2\" \\\n  -F \"image=@photo.png\" \\\n  -F \"prompt=给图片加上一些装饰文字\" \\\n  -F \"size=1024x1024\"\n```\n\n`background`、`partial_images` 等字段透传给模型侧。\n\n## 上传限制\n\n请求体大小不超过 64 MB。超出返回 `413`（`REQUEST_TOO_LARGE`）。\n\n## 可用模型\n\n样例模型：`gpt-image-2`。\n\n> 完整模型清单见[模型广场](\u002Fmodels)。\n\n## 计费\n\n图生图按生成张数计费，具体单价调 `GET \u002Fbilling\u002Fmodels` 接口。",[],{"title":41,"path":97,"order":22,"requiredFlags":98,"content":99,"children":100},"images\u002Ffaq",[],"# 常见问题\n\n### 文生图和图生图用同一个接口吗？\n\n不同。文生图用 `POST \u002Fapi\u002Fv3\u002Fimages\u002Fgenerations`，图生图用 `POST \u002Fapi\u002Fv3\u002Fimages\u002Fedits`（`multipart\u002Fform-data`）。\n\n### 413 REQUEST_TOO_LARGE\n\n请求体超过 64MB 上限。压缩图片或减少输入图数量后重试。\n\n### 429 CONCURRENCY_LIMIT_EXCEEDED\n\n图片生成并发上限。等待后重试。",[],{"title":72,"path":102,"order":29,"requiredFlags":103,"content":104,"children":105},"images\u002Ferrors",[],"# 错误码\n\n图片生成接口的错误格式与对话接口一致（OpenAI 兼容）。常见错误码：\n\n| 错误码 | HTTP | 说明 |\n| --- | --- | --- |\n| `MODEL_NOT_FOUND` | 400 | 模型不存在或不可用 |\n| `INVALID_REQUEST` | 400 | 请求参数无效 |\n| `UNAUTHORIZED` | 401 | 认证失败 |\n| `INSUFFICIENT_BALANCE` | 402 | 余额不足 |\n| `PRE_DEDUCT_FAILED` | 400\u002F402 | 预扣费失败 |\n| `CONCURRENCY_LIMIT_EXCEEDED` | 429 | 图片生成并发上限 |\n| `RATE_LIMITED` | 429 | 触发限流 |\n| `REQUEST_TOO_LARGE` | 413 | 请求体超过 64MB |\n| `UPSTREAM_HTTP_ERROR` | 502 | 模型侧返回 4xx\u002F5xx |\n| `UPSTREAM_PROVIDER_ERROR` | 502 | 模型侧业务错误 |\n| `INTERNAL` | 500 | 内部错误 |\n\n完整错误码与重试建议见 [通用错误处理](\u002Fdocs\u002Fcommon\u002Ferrors)。",[],{"title":107,"path":108,"order":109,"requiredFlags":110,"content":111,"children":112},"视频生成","video",40,[],"# 视频生成\n\n视频与 3D 生成，异步任务模式，含素材管理与选用指南。\n\n- [视频生成 API](\u002Fdocs\u002Fvideo\u002Foverview)\n- [素材选用指南](\u002Fdocs\u002Fvideo\u002Fmaterial-guide)\n- [素材管理](\u002Fdocs\u002Fvideo\u002Fassets)\n- [错误码](\u002Fdocs\u002Fvideo\u002Ferrors)\n- [常见问题](\u002Fdocs\u002Fvideo\u002Ffaq)",[113,119,125,131,136],{"title":114,"path":115,"order":8,"requiredFlags":116,"content":117,"children":118},"视频生成 API","video\u002Foverview",[],"# 视频生成 API\n\n视频生成采用异步任务模式：创建任务 → 轮询状态 → 取结果。视频与 3D 共用同一个任务接口，按 `model` 字段分流。\n\n> 视频生成走自有接口 + API Key，不是火山 AK\u002FSK 签名。火山兼容接口仅用于素材管理（见 [素材管理](\u002Fdocs\u002Fvideo\u002Fassets)）。\n\n## 关键参数\n\n| 参数 | 类型 | 必填 | 说明 |\n| --- | --- | --- | --- |\n| `model` | string | 是 | 模型调用名，如 `doubao-seedance-1-5-pro-251215` |\n| `content` | array | 是 | 输入内容，支持 `text`、`image_url`、`video_url`、`audio_url` |\n| `resolution` | string | 否 | `480p` \u002F `720p` \u002F `1080p`，默认因模型而异 |\n| `ratio` | string | 否 | `16:9` \u002F `9:16` \u002F `4:3` \u002F `3:4` \u002F `1:1` \u002F `21:9`，默认 `16:9` |\n| `duration` | integer | 否 | 时长（秒），默认 5；`-1` 用最大时长 |\n| `frames` | integer | 否 | 帧数，与 `duration` 二选一 |\n| `generate_audio` | boolean | 否 | 是否生成音频（配音），默认 true |\n| `tools` | array | 否 | 工具配置。`tools.type=web_search` 开启联网搜索（仅文生视频支持） |\n\n**认证：** `Authorization: Bearer \u003CAPI_KEY>` 或 `x-api-key: \u003CAPI_KEY>`\n\n> `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3` 即接入域名下的 `\u002Fapi\u002Fv3`，对应路由 `\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks`。\n\n## 文生视频\n\n```bash\ncurl -X POST https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seedance-1-5-pro-251215\",\n    \"content\": [{\"type\": \"text\", \"text\": \"一只金毛犬在海滩上奔跑\"}],\n    \"resolution\": \"720p\",\n    \"ratio\": \"16:9\",\n    \"duration\": 5,\n    \"generate_audio\": true\n  }'\n```\n\n## 图生视频\n\n图生视频分首帧、首尾帧两种场景（互斥）。\n\n### 首帧\n\n```bash\ncurl -X POST https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seedance-1-5-pro-251215\",\n    \"content\": [\n      {\"type\": \"image_url\", \"image_url\": {\"url\": \"https:\u002F\u002Fexample.com\u002Ffirst.jpg\"}, \"role\": \"first_frame\"},\n      {\"type\": \"text\", \"text\": \"镜头缓缓拉远\"}\n    ]\n  }'\n```\n\n### 首尾帧\n\n```bash\ncurl -X POST https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seedance-1-5-pro-251215\",\n    \"content\": [\n      {\"type\": \"image_url\", \"image_url\": {\"url\": \"https:\u002F\u002Fexample.com\u002Ffirst.jpg\"}, \"role\": \"first_frame\"},\n      {\"type\": \"image_url\", \"image_url\": {\"url\": \"https:\u002F\u002Fexample.com\u002Flast.jpg\"}, \"role\": \"last_frame\"},\n      {\"type\": \"text\", \"text\": \"镜头从白天过渡到夜晚\"}\n    ]\n  }'\n```\n\n## 多模态参考生视频\n\n参考图片（1~9）+ 参考视频（0~3）+ 参考音频（0~3）+ 文本提示词（可选）生成视频，支持全新生成、编辑、延长。\n\n```bash\ncurl -X POST https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"doubao-seedance-1-5-pro-251215\",\n    \"content\": [\n      {\"type\": \"image_url\", \"image_url\": {\"url\": \"asset:\u002F\u002FAST-XXXX\"}, \"role\": \"reference_image\"},\n      {\"type\": \"text\", \"text\": \"让画面中的角色跳舞\"}\n    ]\n  }'\n```\n\n> 不可单独输入音频，应至少包含 1 个参考视频或图片。三种图生视频场景（首帧\u002F首尾帧\u002F多模态参考）互斥。\n\n## content 字段\n\n### 文本（text）\n\n| 字段 | 必选 | 说明 |\n| --- | --- | --- |\n| `type` | 是 | `text` |\n| `text` | 是 | 提示词，支持中英文。建议中文 ≤500 字，英文 ≤1000 词 |\n\n### 图片（image_url）\n\n| 字段 | 必选 | 说明 |\n| --- | --- | --- |\n| `type` | 是 | `image_url` |\n| `image_url.url` | 是 | 图片 URL、Base64 编码（`data:image\u002Fpng;base64,...`）或素材 ID（`asset:\u002F\u002F\u003CASSET_ID>`） |\n| `role` | 条件 | `first_frame`、`last_frame`、`reference_image` |\n\n图片要求：格式 jpeg\u002Fpng\u002Fwebp\u002Fbmp\u002Ftiff\u002Fgif；宽高比 (0.4, 2.5)；宽高 300–6000px；单张 ≤30MB。\n\n### 视频（video_url）\n\n| 字段 | 必选 | 说明 |\n| --- | --- | --- |\n| `type` | 是 | `video_url` |\n| `video_url.url` | 是 | 视频 URL 或素材 ID |\n| `role` | 条件 | 当前仅支持 `reference_video` |\n\n视频要求：格式 mp4\u002Fmov；分辨率 480p\u002F720p\u002F1080p；时长 ≤15s，最多 3 个参考视频，总时长 ≤15s；单个 ≤50MB；帧率 4–60fps。\n\n### 音频（audio_url）\n\n不可单独输入音频。\n\n| 字段 | 必选 | 说明 |\n| --- | --- | --- |\n| `type` | 是 | `audio_url` |\n| `audio_url.url` | 是 | 音频 URL、Base64 编码或素材 ID |\n| `role` | 条件 | 当前仅支持 `reference_audio` |\n\n音频要求：格式 wav\u002Fmp3；时长 ≤15s，最多 3 段，总时长 ≤15s；单个 ≤15MB。\n\n## 响应\n\n创建任务返回任务 ID：\n\n```json\n{\n  \"id\": \"VTK-01JXXXXXXXXXXXXXX\",\n  \"model\": \"doubao-seedance-1-5-pro-251215\",\n  \"status\": \"queued\",\n  \"created_at\": \"2026-03-31T12:00:00Z\"\n}\n```\n\n## 查询任务\n\n```\nGET \u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks\u002F:id\n```\n\n```bash\ncurl https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks\u002FVTK-01JXXXXXXXXXXXXXX \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\"\n```\n\n成功响应：\n\n```json\n{\n  \"id\": \"VTK-01JXXXXXXXXXXXXXX\",\n  \"status\": \"succeed\",\n  \"result\": {\"video_url\": \"https:\u002F\u002F...\"}\n}\n```\n\n任务状态：`queued`（排队）→ `running`（生成中）→ `succeed` \u002F `failed` \u002F `cancelled` \u002F `expired`。\n\n## 取消任务\n\n```\nDELETE \u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks\u002F:id\n```\n\n仅 `queued` 状态可取消。\n\n## 生成样例\n\n多模态参考生视频（背景图 + 妆造三视图 + 面部特写图 + 提示词）：\n\n![](https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F1a.webp)\n\n提示词：\n\n> 背景参考图片 1，月白虚影闪过，公子（妆造参考图片 2；人物形象严格参考图片 3）旋身开合折扇，鎏金扇刃弹出，墨竹扇面翻飞，慢鼓重响 1 声；特写：折扇刃格挡反派长刀，扇骨与刀身相击，公子唇角勾轻佻笑意，眼神却冷冽，指腹轻转扇柄。慢镜：公子侧身贴地滑步，折扇刃贴反派腿侧划过，带起一道浅痕，锦袍下摆扫过地面，玉簪轻晃。快切：公子旋身抬手，折扇刃飞射而出，擦过反派脖颈，钉入身后木柱，反派僵立不敢动。反转：身后突然传来掌风，公子旋身接掌，指尖相触时借力后跳，折扇刃从木柱飞回手中，眼神警惕。慢镜高光：公子折扇半开，扇刃抵唇侧，抬眸望向身后，碎发被风吹起，眉梢微扬，带一丝桀骜。拉镜：公子立于庭院石台上，折扇轻摇，镜头拉远，庭院四角同时浮现戴面具的黑影（持弯刀，呈合围之势）。定格：公子折扇合起一半，扇刃露鎏金锋芒，抬步向前，画面压暗，只留他的侧影和扇刃光，音效骤停。音效：折扇开合脆响 + 刃风切割声 + 慢鼓卡点（偏沉稳）。\n\n\u003Cvideo style=\"max-width: 480px; margin: 0 auto;\" src=\"https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F1a-h265.mp4\" controls>\u003C\u002Fvideo>\n\n> 素材准备与上传方式对生成效果影响显著，详见 [素材选用指南](\u002Fdocs\u002Fvideo\u002Fmaterial-guide)。\n\n## 可用模型\n\n样例模型：`doubao-seedance-1-5-pro-251215`（视频）、`doubao-seed3d-2.0`（3D）。\n\n> 完整模型清单见[模型广场](\u002Fmodels)。部分模型需要权限标志，由管理员配置。\n\n## 计费\n\n视频生成按模型与视频参数（分辨率、时长、是否配音）计费，具体单价调 `GET \u002Fbilling\u002Fmodels` 接口。\n\n## 与火山官方接口的差异\n\nSilvaMux 的 Seedance 接口与火山官方接口字段相似（同款模型），但：\n\n- **鉴权**：用平台 API Key（`sk_live_`），不是火山 AK\u002FSK。\n- **Base URL**：`https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fv3`（平台域名），不是火山方舟域名。\n- **model**：用平台调用名（如 `doubao-seedance-1-5-pro-251215`），不是火山 endpoint ID。\n- **任务查询**：通过轮询 `GET \u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks\u002F:id` 查询任务状态。",[],{"title":120,"path":121,"order":92,"requiredFlags":122,"content":123,"children":124},"素材选用指南","video\u002Fmaterial-guide",[],"# 素材选用指南\n\n视频生成支持参考图片、视频、音频等多种素材。本页通过对比案例说明如何准备和上传素材，以获得更理想的生成效果。\n\n> ⚠️ 上传素材时，**若将目标人脸图、全身参考图及细节参考图合并为同一张图片**，可能导致各参考元素在画面中占比较小，增加模型识别难度，造成生成视频中的人物形象与所上传素材出现偏差，或触发风控拦截。\n\n建议将人物面部特写、服装细节等关键内容**独立分割为单独的图片**上传。\n\n## 案例对比：3D 动画亲子\n\n### 案例 A（推荐）\n\n输入：背景参考图 + 人物妆造三视图 + **人物面部无表情特写图** + 提示词\n\n![](https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2a.webp)\n\n提示词：\n\n> 3d 动画风格，背景参考图片 1。人物 A（妆造参考图片 2；面部特征严格参考图片 3）和人物 B（妆造参考图片 4；面部特征严格参考图片 5）手牵手走在花园的小径上，镜头处于人物背后。镜头切到前面，人物 A 拿起一朵鲜花，轻轻递给人物 B。背景音效：轻柔的风吹动树叶和花朵，鸟鸣声。人物 B 微笑接过花，轻轻闻了闻花香，然后蹲下低头与人物 A 微笑对视，轻轻拍拍人物 A 的头，说：\"thank you\"。背景音效：风铃轻响。\n\n\u003Cvideo style=\"max-width: 480px; margin: 0 auto;\" src=\"https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2a-h265.mp4\" controls>\u003C\u002Fvideo>\n\n### 案例 B\n\n输入：背景参考图 + 人物妆造三视图 + 提示词（**缺少人物面部特写图**）\n\n![](https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2b.webp)\n\n\u003Cvideo style=\"max-width: 480px; margin: 0 auto;\" src=\"https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2b-h265.mp4\" controls>\u003C\u002Fvideo>\n\n### 案例 C\n\n输入：背景参考图 + **人物妆造正视图**（非三视图）+ 提示词\n\n![](https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2c.webp)\n\n\u003Cvideo style=\"max-width: 480px; margin: 0 auto;\" src=\"https:\u002F\u002Fsilvamux-docs.tingyutech.com\u002Fcases\u002F2c-h265.mp4\" controls>\u003C\u002Fvideo>\n\n### 对比\n\n- 案例 A（三视图 + 面部特写图）：人物面部特征还原最佳。\n- 案例 B（三视图，无面部特写图）：面部特征一致性较差。\n- 案例 C（正视图，非三视图）：妆造与面部特征一致性均较差。\n\n## 小结\n\n| 素材组合 | 效果 |\n| --- | --- |\n| 背景图 + 妆造三视图 + 面部特写图 | 最佳 |\n| 背景图 + 妆造三视图（无面部特写） | 面部一致性差 |\n| 背景图 + 妆造正视图 | 妆造与面部都差 |\n\n素材上传与管理接口见 [素材管理](\u002Fdocs\u002Fvideo\u002Fassets)。",[],{"title":126,"path":127,"order":22,"requiredFlags":128,"content":129,"children":130},"素材管理","video\u002Fassets",[],"# 素材管理\n\n素材管理用于在视频生成等场景中引用图片\u002F视频\u002F音频素材。平台提供**两套**素材接口：\n\n| 接口 | 路径 | 鉴权 | 适用 |\n| --- | --- | --- | --- |\n| 自有素材库 | `\u002Fapi\u002Fbusiness\u002Fv1\u002Fassets` | API Key 或 JWT | 新接入推荐 |\n| 火山兼容素材 | `\u002Fapi\u002Fark\u002F*` | 火山 V4 签名 | 火山引擎 SDK 迁移 |\n\n> 新接入建议用自有素材库（API Key 鉴权，更简单）。火山兼容接口主要为火山迁移用户保留。\n\n本页内容：\n- [自有素材库](#自有素材库)\n- [火山兼容接口](#火山兼容接口)\n- [在视频生成中引用素材](#在视频生成中引用素材)\n\n## 自有素材库\n\n基础路径 `\u002Fapi\u002Fbusiness\u002Fv1`，认证 `Authorization: Bearer sk_live_...` 或 JWT。\n\n### 数据模型（AssetView）\n\n```json\n{\n  \"id\": \"AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y\",\n  \"url\": \"https:\u002F\u002Fexample.com\u002Fimage.png\",\n  \"asset_type\": \"Image\",\n  \"name\": \"cover-image\",\n  \"asset_url\": \"asset:\u002F\u002Fasset-123456\",\n  \"status\": \"processing\",\n  \"created_at\": \"2026-03-27T10:00:00Z\"\n}\n```\n\n| 字段 | 说明 |\n| --- | --- |\n| `id` | 素材 ID |\n| `url` | 原始素材 URL |\n| `asset_type` | 素材类型（`Image`\u002F`Video`\u002F`Audio`） |\n| `name` | 素材名称 |\n| `asset_url` | 素材引用地址，格式 `asset:\u002F\u002F\u003C素材ID>`，用于视频生成引用 |\n| `status` | `processing`、`active`、`failed`；仅 `active` 可用 |\n\n### 端点\n\n| 方法 | 路径 | 说明 |\n| --- | --- | --- |\n| `POST` | `\u002Fassets` | 创建素材（注册公网 URL） |\n| `GET` | `\u002Fassets` | 列出素材（分页） |\n| `GET` | `\u002Fassets\u002F{asset_id}` | 获取单个素材 |\n\n### 创建素材\n\n```bash\ncurl -X POST https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fassets \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"url\": \"https:\u002F\u002Fexample.com\u002Fimage.png\",\n    \"asset_type\": \"Image\",\n    \"name\": \"cover-image\"\n  }'\n```\n\n| 字段 | 必填 | 说明 |\n| --- | --- | --- |\n| `url` | 是 | 素材的公开 URL |\n| `asset_type` | 是 | `Image`、`Video`、`Audio` |\n| `name` | 是 | 素材名称 |\n\n成功返回 `201`，响应体为 AssetView。新建后通常先 `processing`，后续变为 `active` 或 `failed`。\n\n### 列出素材\n\n```bash\ncurl \"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fassets?limit=20\" \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\"\n```\n\n| 参数 | 说明 |\n| --- | --- |\n| `limit` | 每页数量，1-100，默认 20 |\n| `cursor` | 分页游标，首次不传 |\n\n### 获取单个素材\n\n```bash\ncurl \"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fbusiness\u002Fv1\u002Fassets\u002FAST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y\" \\\n  -H \"Authorization: Bearer $SILVAMUX_API_KEY\"\n```\n\n常用于轮询素材状态，直到 `status` 变为 `active`。\n\n### 最小调用流程\n\n1. 准备一个外网可访问的素材 URL\n2. `POST \u002Fassets` 创建，拿到 `id`、`asset_url`\n3. 轮询 `GET \u002Fassets\u002F{id}`，直到 `status` 变为 `active`\n4. 用 `asset_url` 在视频生成中引用\n\n## 火山兼容接口\n\n与火山引擎素材管理 API 完全兼容。**从火山引擎迁移的客户可继续使用火山引擎官方 SDK，仅需将接入地址指向本平台、凭证换成平台签发的 AK\u002FSK，原有代码无需改动。**\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fark` |\n| Region | `cn-beijing` |\n| Service | `ark` |\n| 鉴权 | 火山 V4 签名，使用平台签发的 AK\u002FSK |\n| 调用方式 | `POST \u002Fapi\u002Fark?Action=\u003CAction>&Version=2024-01-01` |\n\n### 接入准备\n\n1. 控制台 → 凭据管理 → 创建 **Volcengine 兼容 (AK\u002FSK)** 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。\n2. AK\u002FSK 绑定组织，项目通过 `ProjectName` 字段指定。\n\n### 配置 SDK\n\n将火山引擎 SDK 的 Endpoint 改为 `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fark`，Region 保持 `cn-beijing`，凭证填入平台签发的 AK\u002FSK，其余调用代码不变。\n\n```python\nclient = ArkAssetClient(\n    endpoint=\"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fark\",\n    access_key_id=\"\u003C平台签发的 AK>\",\n    secret_access_key=\"\u003C平台签发的 SK>\",\n    region=\"cn-beijing\",\n)\n# CreateAssetGroup \u002F CreateAsset \u002F GetAsset ... 调用代码不变\n```\n\n### 支持的操作\n\n请求体字段名与火山引擎一致（驼峰、首字母大写）。\n\n素材组（AssetGroup）：`CreateAssetGroup`、`GetAssetGroup`、`ListAssetGroups`、`UpdateAssetGroup`、`DeleteAssetGroup`。\n\n素材（Asset）：`CreateAsset`（`GroupId`+`URL`+`AssetType`+`Name`）、`GetAsset`、`ListAssets`、`UpdateAsset`、`DeleteAsset`。`AssetType` 可选 `Image`\u002F`Video`\u002F`Audio`。\n\n`ProjectName` 为空或填 `default` 用默认项目，填其它值按项目名精确匹配。\n\n### 重要限制\n\n- **历史素材不可见**：之前通过火山引擎控制台或其它账号上传的素材无法通过本接口访问，需重新上传。\n- 仅支持 `AIGC` 类型（图片\u002F视频\u002F音频），不支持真人素材（LivenessFace）。\n- `CreateAsset` 需提供公网可访问的素材 URL，平台拉取入库。\n\n### 错误码\n\n| Code | 含义 |\n| --- | --- |\n| `InvalidSignature` | 签名校验失败（AK\u002FSK 错、请求被篡改、时钟偏移过大） |\n| `InvalidAction` | 不支持的 Action |\n| `MissingParameter.*` | 缺少必填字段 |\n| `InvalidParameter.*` | 字段值非法 |\n| `NotFound.asset_id` \u002F `NotFound.project` | 素材 \u002F 项目不存在 |\n| `SubscriptionRequired` | 组织未开通相应能力 |\n| `InternalError` | 服务内部错误，记录 `RequestId` 联系支持 |\n\n## 在视频生成中引用素材\n\n素材 `active` 后，用 `asset_url`（`asset:\u002F\u002F...`）在视频生成的 `content` 中引用：\n\n```json\n{\n  \"model\": \"doubao-seedance-1-5-pro-251215\",\n  \"content\": [\n    {\"type\": \"video_url\", \"video_url\": \"asset:\u002F\u002Fasset-123456\"},\n    {\"type\": \"text\", \"text\": \"让画面中的角色跳舞\"}\n  ]\n}\n```\n\n### 迁移要点（火山引擎 → SilvaMux）\n\n| 能力 | 火山引擎 | SilvaMux | 说明 |\n| --- | --- | --- | --- |\n| 对话（豆包） | `\u002Fapi\u002Fv3\u002Fchat\u002Fcompletions` | `POST \u002Fapi\u002Fv3\u002Fchat\u002Fcompletions` | 协议兼容，改 Base URL + Key，model 用平台调用名 |\n| 视频生成 | `\u002Fcontents\u002Fgenerations\u002Ftasks` | `POST \u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks` | **自有接口 + API Key**，不走 V4 签名 |\n| 素材管理 | 火山官方接口 | `POST \u002Fapi\u002Fark\u002F*`（本页）或 `\u002Fapi\u002Fbusiness\u002Fv1\u002Fassets` | 两套可选 |\n\n- 视频生成走 API Key，不走 V4 签名。V4 签名仅用于本页素材接口。\n- API Key（`sk_live_`）与 AK\u002FSK 在控制台分别创建，不同。\n- `model` 用平台调用名（如 `doubao-seedance-1-5-pro-251215`），不是火山 endpoint ID。\n- 视频生成不支持任务列表\u002F回调，用轮询查询。",[],{"title":41,"path":132,"order":29,"requiredFlags":133,"content":134,"children":135},"video\u002Ffaq",[],"# 常见问题\n\n### 视频生成用火山 AK\u002FSK 吗？\n\n不用。视频生成走自有接口 + API Key。火山 V4 签名仅用于素材管理的火山兼容接口。\n\n### 视频任务怎么查结果？\n\n轮询 `GET \u002Fapi\u002Fv3\u002Fcontents\u002Fgenerations\u002Ftasks\u002F:id`，直到 `status` 变为 `succeed`（取 `result.video_url`）或 `failed`。\n\n### 403 MODEL_ACCESS_DENIED\n\n组织缺少该模型所需的权限标志。联系管理员开通。\n\n### 429 CONCURRENCY_LIMIT_EXCEEDED\n\n视频生成并发上限。等待后重试。\n\n### 任务状态 expired 是什么意思？\n\n任务长时间未查询或超时未完成会过期，需重新创建。",[],{"title":72,"path":137,"order":36,"requiredFlags":138,"content":139,"children":140},"video\u002Ferrors",[],"# 错误码\n\n视频生成接口的错误格式与对话接口一致（OpenAI 兼容）。常见错误码：\n\n| 错误码 | HTTP | 说明 |\n| --- | --- | --- |\n| `MODEL_NOT_FOUND` | 400 | 模型不存在或不可用 |\n| `INVALID_REQUEST` | 400 | 请求参数无效 |\n| `INVALID_CALLBACK_URL` | 400 | 回调 URL 无效 |\n| `UNAUTHORIZED` | 401 | 认证失败 |\n| `MODEL_ACCESS_DENIED` | 403 | 组织缺少模型权限标志 |\n| `INSUFFICIENT_BALANCE` | 402 | 余额不足 |\n| `PRE_DEDUCT_FAILED` | 400\u002F402 | 预扣费失败 |\n| `CONCURRENCY_LIMIT_EXCEEDED` | 429 | 视频生成并发上限 |\n| `RATE_LIMITED` | 429 | 触发限流 |\n| `UPSTREAM_HTTP_ERROR` | 502 | 模型侧返回 4xx\u002F5xx |\n| `UPSTREAM_PROVIDER_ERROR` | 502 | 模型侧业务错误 |\n| `UPSTREAM_INVALID_RESPONSE` | 502 | 模型侧响应无法解析 |\n| `INTERNAL` | 500 | 内部错误 |\n\n取消任务的错误：\n\n| HTTP | 错误码 | 说明 |\n| --- | --- | --- |\n| 404 | `NOT_FOUND` | 任务不存在 |\n| 409 | `INVALID_STATE` | 任务不在 queued 状态 |\n| 502 | `UPSTREAM_CANCEL_FAILED` | 模型侧取消失败 |\n\n完整错误码与重试建议见 [通用错误处理](\u002Fdocs\u002Fcommon\u002Ferrors)。",[],{"title":142,"path":143,"order":144,"requiredFlags":145,"content":146,"children":147},"即梦AI","dreamina",50,[],"# 即梦AI\n\n- [OmniHuman 数字人](\u002Fdocs\u002Fdreamina\u002Fomni-human)",[148],{"title":149,"path":150,"order":15,"requiredFlags":151,"content":152,"children":153},"OmniHuman 1.5","dreamina\u002Fomni-human",[],"# 即梦 OmniHuman 1.5\n\nOmniHuman1.5（即梦同源数字人模型），该模型可根据用户上传的单张图片+音频，生成与图片对应的视频效果。支持输入任意画幅包含人物或其他主体（宠物、动漫等）的图片，结合音频，生成高质量的视频。\n\n人物的情绪、动作与音频具有强关联性，支持通过提示词（prompt）对画面、动作、运镜进行调整。同时OmniHuman1.5对动漫、宠物等形象支持较好，允许指定讲话人\u002F主体，可广泛应用于内容表达、唱歌和表演等场景。\n\n相较于上一代模型，OmniHuman1.5 在运动自然度和结构稳定性提升明显，在人物\u002F主体的运动表现力和画面质量上更优。可以广泛应用于制作剧情对话、多人对话\u002F对唱、商品交互、漫剧等内容。对比其他视频通用模型，OmniHuman 数字人大模型在人物\u002F主体的剧情演绎效果上极具优势。\n\n具体模型介绍细节，可参考[火山文档](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F85621\u002F1834143?lang=zh)。\n\n## 调用示例\n\n千木提供与火山相同的即梦 OmniHuman 1.5 API，您可以使用火山 SDK 或是通过自研 API 接入即梦 OmniHuman 1.5。\n\n以火山 Python SDK 为例，使用 `pip install 'volcengine-python-sdk[ark]'` 安装火山 SDK 后，运行如下示例脚本：\n\n```python\n# coding:utf-8\nimport json\nimport threading\nfrom time import sleep\n\nfrom volcengine.ApiInfo import ApiInfo\nfrom volcengine.Credentials import Credentials\nfrom volcengine.base.Service import Service\nfrom volcengine.ServiceInfo import ServiceInfo\nfrom volcengine.visual.VisualService import VisualService\n\nclass SilvaMuxVisualService(VisualService):\n    def __new__(cls, *args, **kwargs):\n        return object.__new__(cls, *args, **kwargs)\n\n    def __init__(self):\n        self.service_info = SilvaMuxVisualService.get_service_info()\n        self.api_info = SilvaMuxVisualService.get_api_info()\n        super(VisualService, self).__init__(self.service_info, self.api_info)\n\n    def get_service_info():\n        service_info = ServiceInfo(\"www.silvamux.com\", # 如需使用海外版，请替换为 www.silvamux.io\n                                   {}, Credentials('', '', 'cv', 'cn-north-1'), 30, 30, 'https')\n        return service_info\n\n    def get_api_info():\n        api_info = {\n            \"CVGetResult\": ApiInfo(\"POST\", \"\u002Fapi\u002Fark\", {\"Action\": \"CVGetResult\", \"Version\": \"2022-08-31\"}, {}, {}),\n            \"CVSubmitTask\": ApiInfo(\"POST\", \"\u002Fapi\u002Fark\", {\"Action\": \"CVSubmitTask\", \"Version\": \"2022-08-31\"}, {}, {}),\n            \"CVProcess\": ApiInfo(\"POST\", \"\u002Fapi\u002Fark\", {\"Action\": \"CVProcess\", \"Version\": \"2022-08-31\"}, {}, {}),\n        }\n        return api_info\n\n\ndef get_result(req_key, task_id):\n    i = 0\n    while True:\n        i += 1\n        result_resp = visual_service.cv_get_result({\n            \"req_key\": req_key,\n            \"task_id\": task_id\n        })\n        result_status = result_resp['data']['status']\n        print(f\"  第 {i} 次查询结果，状态: {result_status}\")\n        if result_status == \"in_queue\" or result_status == \"generating\":\n            sleep(3)\n            continue\n        if result_status == \"done\":\n            if 'data' in result_resp and 'resp_data' in result_resp['data']:\n                return json.loads(result_resp['data']['resp_data'])\n            elif 'data' in result_resp and 'video_url' in result_resp['data']:\n                return result_resp['data']['video_url']\n            else:\n                print(f\"  解析失败：{result_resp}\")\n                raise Exception(\"result parse failed\")\n        raise Exception(f\"task {result_status}\")\n\nif __name__ == '__main__':\n    image_url = \"https:\u002F\u002Fportal.volccdn.com\u002Fobj\u002Fvolcfe\u002Fcloud-universal-doc\u002Fupload_7297f5f099cee6b48f5417e47ac8291b.png\"\n    audio_url = \"https:\u002F\u002Fp9-arcosite.byteimg.com\u002Fobj\u002Ftos-cn-i-goo7wpa0wc\u002F64c66c987973400491c0b487d832537c\"\n    mask_urls = []\n\n    visual_service = SilvaMuxVisualService()\n\n    # 请使用千木后台生成的兼容“凭据”以调用火山兼容 API\n    visual_service.set_ak('AKexampleReplaceWithRealAK')\n    visual_service.set_sk('SKexampleReplaceWithRealSK')\n\n    print(\"第一步：主体识别 如果确认图片中有人类主体，可以跳过该步骤\")\n    step1_resp = visual_service.cv_submit_task({\n        \"req_key\": \"jimeng_realman_avatar_picture_create_role_omni_v15\",\n        \"image_url\": image_url\n    })\n    step1_resp_task_id = step1_resp['data']['task_id']\n    print(f\"  任务ID: {step1_resp_task_id}\")\n\n    step1_result = get_result(\"jimeng_realman_avatar_picture_create_role_omni_v15\", step1_resp_task_id)\n    if step1_result['status'] != 1:\n        raise Exception(\"没有检测到主体，任务失败，请更换图片尝试\")\n\n    print(\"第二步：主体检测 如果在视频生成时不需要指定主体说话，可以跳过该步骤\")\n    step2_resp = visual_service.cv_process({\n        \"req_key\": \"jimeng_realman_avatar_object_detection\",\n        \"image_url\": image_url\n    })\n    step2_data = json.loads(step2_resp['data']['resp_data'])\n    mask_urls = step2_data['object_detection_result']['mask']['url']\n    print(f\"  遮罩列表: {mask_urls}\")\n\n    print(\"第三步：视频生成\")\n    step3_resp = visual_service.cv_submit_task({\n        \"req_key\": \"jimeng_realman_avatar_picture_omni_v15\",\n        \"image_url\": image_url,\n        \"mask_url\": mask_urls,\n        \"audio_url\": audio_url,\n    })\n    step3_resp_task_id = step3_resp['data']['task_id']\n    print(f\"  任务ID: {step3_resp_task_id}\")\n\n    step3_result = get_result(\"jimeng_realman_avatar_picture_omni_v15\", step3_resp_task_id)\n    print(f\"  结果： {step3_result}\")\n```\n\n具体 API 文档如下：\n\n- [调用步骤1：主体识别](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F85621\u002F1828975?lang=zh)\n- [调用步骤2：主体检测](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F85621\u002F1829011?lang=zh)\n- [调用步骤3：视频生成](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F85621\u002F1829013?lang=zh)",[],{"title":107,"path":108,"order":109,"requiredFlags":155,"content":111,"children":156},[],[157,160,163,166,169],{"title":114,"path":115,"order":8,"requiredFlags":158,"content":117,"children":159},[],[],{"title":120,"path":121,"order":92,"requiredFlags":161,"content":123,"children":162},[],[],{"title":126,"path":127,"order":22,"requiredFlags":164,"content":129,"children":165},[],[],{"title":41,"path":132,"order":29,"requiredFlags":167,"content":134,"children":168},[],[],{"title":72,"path":137,"order":36,"requiredFlags":170,"content":139,"children":171},[],[],[173,176],{"title":174,"path":175},"文档","",{"title":107,"path":108}]