常见问题
基础问题
ClawdRouter 是什么？
ClawdRouter 是一个 AI 大模型聚合平台，提供统一的 API 接口（支持 OpenAI 协议和 Anthropic 原生协议），让你通过一个端点访问来自 OpenAI、Anthropic、Google 等多家厂商的大语言模型。
支持哪些模型？
目前支持以下厂商的模型：
- OpenAI：GPT-4o、GPT-4.1、GPT-5 系列、o1/o3/o4 推理模型等
- Anthropic：Claude 3/3.5/3.7/4/4.5/4.6 系列
- Google：Gemini 2.5/3/3.1 系列
完整列表请查看模型列表。
与直接调用官方 API 有什么区别？
- 统一接口：所有模型使用相同的 API 格式，无需适配不同厂商的接口
- 简化接入：只需一个 API Key，即可访问所有厂商的模型
- 无缝切换：更改
model参数即可在不同模型间切换，无需修改代码
什么是 BYOK（自带 Key）？
BYOK（Bring Your Own Key）允许你将自有的供应商 API Key 接入平台，享受统一的 API 管理和路由能力，同时使用自己的供应商资源。详见 BYOK 文档。
API 与协议
API 请求的基础 URL 是什么？
__DOCS_API_ORIGIN__/v1
支持哪些 API 端点？
目前支持以下端点：
| 端点 | 方法 | 协议 | 说明 |
|---|---|---|---|
/v1/chat/completions | POST | OpenAI | 聊天补全，支持所有厂商模型 |
/v1/responses | POST | OpenAI | Responses API，适合 GPT-5.5 等新模型 |
/v1/images/generations | POST | OpenAI | 图片生成 |
/v1/messages | POST | Anthropic | Anthropic 原生协议，支持 Claude 系列模型 |
/v1beta/models/{model}:{method} | POST | Gemini 原生多模态和图片生成 | |
/v1/video/generations | POST | Video API | Veo 视频生成，异步返回任务结果 |
是否兼容 OpenAI SDK？
是的，ClawdRouter 完全兼容 OpenAI SDK。你只需将 base_url 修改为 __DOCS_API_ORIGIN__/v1，即可使用官方 SDK 的所有功能。
此外，还支持 Anthropic SDK，将 base_url 修改为 __DOCS_API_ORIGIN__ 即可通过原生协议调用 Claude 模型。
是否支持流式输出？
是的，所有模型均支持流式输出。在请求中设置 stream: true 即可启用。
是否支持 Function Calling / Tool Use？
是的，支持 Function Calling 的模型均可通过 tools 和 tool_choice 参数使用此功能。
视频与异步任务
视频接口为什么返回 202 Accepted？
因为 Veo 视频生成属于异步任务。202 Accepted 代表平台已经成功受理请求，但模型侧可能仍在生成中。最终是否成功，需要结合任务状态和结果状态判断。
提交视频请求后去哪里看结果？
请到控制台任务中心下载生成结果。建议保留好 task_id 和 request_id，它们分别对应任务排查和请求排查。
任务中心、日志管理、下载中心有什么区别？
- 任务中心看“这个异步任务后来怎么样了”
- 日志管理看“这次调用发生了什么”
- 下载中心看“导出的文件是否已生成”
如果是视频生成结果、过期提醒、下载链接或失败任务，请优先进入任务中心。
为什么日志里显示成功，任务中心却显示失败？
这通常说明请求层已经成功受理，但任务层最终执行失败。视频等异步能力需要同时看请求状态和任务状态，这也是日志管理和任务中心要分开的原因。
结果过期后还能恢复吗？
通常不能直接恢复，需要根据原始调用参数重新发起生成。建议优先处理任务中心里“待下载”和“即将过期”的任务。
火山方舟素材库
上传成功，但列表里查不到该素材
素材列表接口在未传 Filter.Statuses 时只返回 Active 素材。刚上传的素材仍在处理中（Processing），因此查不到。请用查询素材详情按素材 ID 查看状态，或查询时显式传入 Processing、Failed。
素材一直停留在 Processing
入库需要排队下载源文件、解析元信息并做内容审核。视频与音频明显慢于图片，高峰期更慢。建议使用指数退避轮询（如 5 秒、10 秒、20 秒、40 秒），并设置业务侧超时上限；不要固定高频轮询，否则容易触发 429。
素材状态是 Failed
按顺序排查：
- 源地址是否仍可公开访问（用不带任何鉴权的请求试一次），是否返回 4xx 或发生重定向。
- 链接有效期是否覆盖了入库所需时间，特别是对象存储的临时签名链接。
- 文件是否损坏，扩展名与实际格式是否一致。
- 内容是否符合内容合规要求。
排查后删除该素材并重新上传；重新上传不会修改素材的源地址，因此建议先排查失败原因再重试。
素材已 active，但生成时提示素材不可用
- 确认传的是素材 ID，而不是预览地址（后者 1 小时过期）。
- 确认生成请求使用的凭证与素材归属于同一账号。
- 确认所用模型支持参考素材输入。
提示词里能直接写素材 ID 吗
不能。素材 ID 只用于请求体中的素材字段，提示词中需要用「图片1」「视频1」这类序号指代。
预览地址为什么会失效
预览地址是临时地址，有效期 1 小时。需要展示时，请在每次展示前重新查询素材详情获取，不要把它当作素材的永久地址保存。
删除素材有什么影响
删除素材与删除素材组均不可恢复，删除后无法再引用对应素材。批量删除接口是部分成功语义，返回的失败列表需要逐条比对，不能只看外层是否成功。
需要特别注意：删除素材组会连带删除组内的全部素材。只想解散分组时，请先把素材移到其他分组或移出分组，再删除空分组。
素材的归属与可见范围是怎样的
素材归属于上传它的账号，素材的查询与管理接口只返回当前凭证所属账号下的素材。生成时请使用与素材归属账号一致的凭证。
认证与安全
如何获取 API Key？
登录 ClawdRouter 控制台，在 密钥管理页面创建新的 Key。
如何获取 Access Key 和 Secret Key？
开放 API 的 Access Key / Secret Key 不是控制台的 API Key，需联系运营人员获取。
API Key 泄露了怎么办？
请立即在控制台禁用该 Key 并创建新的 Key。被禁用的 Key 将立即失效。
请求是否加密？
所有 API 请求均通过 HTTPS 传输，数据在传输过程中是加密的。
常见错误
401 Unauthorized
API Key 无效或缺失。请检查：
AuthorizationHeader 是否存在- 格式是否为
Bearer YOUR_API_KEY - API Key 是否有效（未过期、未禁用）
500 Internal Server Error
服务端出现异常。请：
- 稍后重试
- 如果持续出现，请携带
traceId提交工单联系技术支持
计费相关
如何计费？
按照实际使用的 Token 数量计费，不同模型有不同的单价。具体价格请在控制台查看。
什么是 Token？
Token 是模型处理文本的基本单位。大致上，1 个中文字约等于 1-2 个 Token，1 个英文单词约等于 1 个 Token。每次请求的 Token 用量包含在响应的 usage 字段中。
如何查看用量？
在控制台的用量统计页面可以查看历史调用记录和 Token 消耗情况。