常见问题
接入与认证
为什么返回 401？
- 检查 API Key 是否以
Authorization: Bearer sk-...请求头正确传入（注意拼写Bearer与密钥之间有一个空格）。 - 检查 Key 是否已被删除、禁用或过期（控制台「令牌」页面可查看状态）；这些场景都返回
401。 - 确认粘贴的是 Key 明文本身，而不是令牌名称。
为什么返回 insufficient_user_quota（额度不足）？
账号余额不足，无法覆盖本次请求的预估费用。前往控制台充值或等待额度发放即可，错误会随余额恢复自动消失，无需改代码。注意它与 429 不同：额度不足返回的是 403。如果你为令牌单独设置了额度上限，还需检查该令牌自身的剩余额度。
Base URL 应该填什么？
| 客户端 | Base URL |
|---|---|
| OpenAI 格式 | https://confluia.com/v1 |
| Anthropic 格式 | https://confluia.com（根地址，不要带 /v1） |
以控制台「API 配置」页面展示的地址为准。文档中的 confluia.com 是占位符。
我可以用现有的 OpenAI SDK 吗？
可以。绝大多数 OpenAI 兼容 SDK、LangChain、各类 Chat 客户端只需把 base_url 指向 https://confluia.com/v1、把 Key 换成你的 sk- 密钥即可，详见接入指南。
模型问题
为什么提示模型不存在（model_not_found）？
- 确认
model与GET /v1/models返回的模型 ID 完全一致（大小写敏感）。 - 该模型可能未对你的账号 / 令牌分组开放，或暂未配置上游渠道（此时返回
503）。如需开通请咨询客服。 - 也可能触发的是令牌级模型白名单限制（
403），检查控制台该 Key 的可用模型配置。
如何查看我能用的模型？
调用 GET /v1/models，或在控制台「价格 / 模型列表」页面查看。
请求会真的走指定的模型吗？
会。网关按你的令牌分组自动选择可用渠道把请求路由到目标模型，你无需关心具体上游；对外始终是统一的兼容接口。
视频生成
为什么提交后立即返回、没有视频结果？
视频生成是异步任务：提交接口只返回 task_id，生成需要数十秒到数分钟。请轮询 GET /v1/videos/{task_id} 直至 status 变为 completed，再从 metadata.url 下载成片，详见视频生成。
视频结果下载链接失效怎么办？
成片链接为限时有效（由上游生成）。过期后重新查询任务获取新链接，或使用平台代理下载接口 GET /v1/videos/{task_id}/content（该接口不受链接时效影响，但要求任务已完成）。
为什么用 minimax-h3-768p 与 minimax-h3-2k 生成的视频几乎一样？
展示别名只决定按哪一档单价计费，不会自带分辨率。 两个别名映射到同一个上游模型，若请求里都没有显式传 resolution / size，两次请求的生成参数就完全相同，默认按 768P 生成。
- 想按分辨率区分：在请求里显式给
size（如1920x1080）或resolution（2K）； - 反之，如果两个请求"本该不同却得到同一条视频"，先核对两边参数是否真的不同——这是最有用的诊断信号。
详见视频生成 · 计费说明。
size 该填什么？报 invalid_size 怎么办？
size 支持两种写法（MiniMax H3）：
- 像素尺寸：
768p、2k、768x768、1024x1024、1280x720、720x1280、1792x1024、1920x1080、1024x1792、1080x1920； - 画幅比例串：
21:9、16:9、4:3、1:1、3:4、9:16（只决定比例，分辨率取默认768P）。
两者都不填时默认 16:9 + 768P；显式传入的 resolution（768P / 2K）优先于 size 推导。invalid_size 表示 size 不在上述列表（例如写成了 1920x1081 这类非标准尺寸）。像素尺寸与分辨率 / 比例的对应关系见视频生成 · 主要参数。
图生视频到底该用哪个字段？
MiniMax H3 的 "首帧" 有三种等价写法：image、input_reference、first_frame_image，任选其一。同时提供多个时按 multipart 文件 > first_frame_image > input_reference > image 取用：
- 首帧：
"image": "https://..."； - 首尾帧：
first_frame_image+last_frame_image配对使用； - 角色参考（多张）：用
images: [...]（≤9 张）；提供首/尾帧时参考图会被忽略，不要混用； - 本地图片：multipart 表单上传
input_reference=@frame.png。
提供首帧后画幅比例跟随输入图片（按 adaptive 处理），无需再传 ratio。
Seedance 模型使用 images 数组或 image 单图字段均可（image 等价于单元素 images）；分辨率与画幅只在 metadata.resolution / metadata.ratio 中指定，顶层 size 不生效。
控制台任务状态和接口返回的状态对不上？
两者数据来源不同：接口在任务提交成功后立即按"已受理"报告 queued；控制台任务日志读的是任务表状态列，由后台轮询更新（约 15 秒一轮）。提交后的几十秒内出现"接口已 queued、控制台仍显示未开始"是正常的，等一轮轮询后即自动对齐。
另外 progress 不是上游真实进度，它是按状态推导的近似值（数值随模型不同：MiniMax H3 排队 20 / 生成中 30 / 完成 100；Seedance 排队 10 / 生成中 50 / 完成 100），判断进展请看 status。
视频任务失败会扣费吗？
视频类采用「提交时预扣 + 完成后结算」：
- 成功：按上游返回的实际用量多退少补；
- 上游失败：上游通常不返回用量，此时预扣额度保留（不自动退款）；
- 超时未出结果：判定为失败并退还预扣额度。
具体以控制台日志中的预扣 / 结算明细为准；有异议请携带 task_id 提交工单核对。
提交视频任务返回 429？
按响应体区分两种来源：
- 异步任务并发达到上限（
code为async_task_concurrency_limit）：你名下"排队中 + 生成中"的任务达到上限，等已有任务完成后再提交，或联系客服调整上限； - 上游繁忙：提示"当前分组上游负载已饱和"类信息时，稍后指数退避重试即可。重试前请确认上一次请求没有已经拿到
task_id，避免重复生成与重复计费。
计费与额度
为什么扣费和我估算的不一样？
- 实际扣费以服务端统计的用量（
usage）为准，不同模型的折算系数不同。 - 文本类请求采用「先预扣、后结算」，日志里可能先后出现预扣与结算两条记录（含负向调整）。
- 图像 / 语音 / 视频不按 token 计价，请对照控制台「价格」页的计费基元核算。
请求失败了还会扣费吗？
- 对话 / 图像 / 语音：未到达上游或被拒绝的请求不扣费；已到达上游并产生用量的按实际用量计费。
- 视频等异步任务：见上文「视频任务失败会扣费吗？」。
以消费记录为准，如有疑问提交工单。
如何查看消费记录？
控制台「日志」页面可按时间 / 模型 / 令牌筛选；「钱包 / 余额」页面展示充值与余额变动。
限流与稳定性
返回 429 怎么办？
429 有三种常见来源，按响应处理：
| 响应特征 | 来源 | 处理 |
|---|---|---|
无响应体、带 Retry-After 头 | 全局 IP 保护性限流 | 按 Retry-After 等待后重试 |
OpenAI 错误体，message 提示限流原因 | 账号 / 分组请求限流 | 降低调用频率、指数退避 |
code 为 async_task_concurrency_limit | 异步任务并发上限 | 等已有视频 / 音乐任务完成 |
提示"上游负载已饱和"类信息时同样属于临时性失败，稍后重试。
返回 5xx 怎么办？
多为上游服务临时波动，短退避后重试；持续失败请联系客服，并提供 message 末尾的 request id 与发生时间点。
我该用流式还是非流式？
需要首字低延迟或生成长文本时建议 stream: true。计费按实际 token 结算，两种方式无差异。
安全与账号
API Key 泄露了怎么办？
立即在控制台删除该 Key 并新建；给新 Key 设置额度上限与 IP 白名单，缩小损失面。
如何保护我的 Key？
Key 只应保存在你信任的后端服务或环境变量中；任何客户端代码、代码仓库、聊天记录、截图都不要出现明文 Key。
忘记密码怎么办？
登录页点击「忘记密码」，按邮件指引重置。
其他
网站无法访问 / 接口超时怎么办？
先排查本地网络与代理；确认 API 域名与 Base URL 配置正确；仍有问题请联系在线客服或者销售。
如何联系支持？
控制台右下角客服 / 工单入口，或官网公布的联系邮箱，或者联系销售。