常见问题(FAQ)

接入 iModelSpace 网关过程中的高频问题。

API Key 相关

Q: 创建了 Key 但请求返回 401 unauthorized?

• 确认 Authorization 头格式:Bearer <KEY>(注意 Bearer 后空格)
• Key 只能创建时完整展示一次,如未保存需删除重建
• 部分模型(如 minimax-h3)需在「API KEY → 权限」里单独勾选才可访问,默认权限不覆盖全部模型

Q: Key 泄露了怎么办?

立即在控制台「API KEY」列表删除/禁用该 Key,然后新建一个。删除后旧 Key 立即失效,所有正在进行的请求都会中断。

Q: 一个 Key 能用在多个项目吗?

可以。Key 与账户绑定,只要账户下有足够灵石,任意项目复用同一 Key 即可。建议按环境分 Key(dev / prod)便于限流与配额管理。

计费相关

Q: 任务失败会扣费吗?

不会。网关仅在任务 succeeded 后才扣除灵石。failed / cancelled / timeout 会触发冻结金额退还,frozen→refunded 全程无损失。

Q: 怎么查实时用量?

GET https://api.imodel.space/api/user/usage 返回最近 30 天按模型 / 日分组的明细,响应字段含义见 计费说明。

Q: 单价在哪里查?

权威来源是 GET /v1/models 接口的 meta.rates 字段——见 资费查询。前端定价展示均来自此接口。

任务相关

Q: 视频生成任务卡在 queued / scaling 很久?

queued → 调度等待实例;scaling → 自部署 GPU 启动中(2~4 分钟属正常,首次冷启 + 模型加载)。running 后一般 30s~2min 出片。如果持续 5min+ 卡 scaling,请检查上游平台是否在维护。

Q: 怎么取消还在排队的任务?

调 POST /v1/tasks/{task_no}/cancel。任务进入 running 后无法取消,需等其自然完成或失败。

Q: 异步任务怎么拿产物?

轮询 GET /v1/tasks/{task_no} 直到 status="succeeded",响应里 outputs[] 即产物 URL(走 gapi 代理,不会暴露上游 ComfyUI 地址)。完整流程见 任务查询。

Q: 提示词优化失败会阻塞视频提交吗?

不会。提示词优化走 fail-open:上游 8s 超时/失败时,网关返回 mode="none" + optimized_prompt = 原 prompt,前端直接拿原 prompt 提交即可。

素材相关

Q: 上传的素材能跨任务复用吗?

可以。所有素材在 用户素材上传 后入 assets 表,cdn_url 永久有效,后续任意接口的 image / image_urls / mask 字段都可直接传这个 URL 引用。

Q: 移动端拍照能直接传给图片生成吗?

可以。image / image_urls / mask 三个字段均支持 data:image/...;base64,... 内嵌图,网关自动落 COS + 入素材表(2026-09-11 新增)。详见 图片生成。

Q: 素材有大小 / 数量限制?

• 单张 base64 解码后 ≤ 16 MB
• 单次请求 image_urls ≤ 10 张
• COS 上传单文件 ≤ 50 MB(腾讯云 COS 限制)

控制台相关

Q: 控制台进不去 / 加载慢?

控制台地址是 imodel.space,首次访问会做一次设备指纹验证。如持续加载异常,清浏览器缓存或换浏览器试试。

Q: 在哪里看任务历史?

控制台「工作台 → 我的任务」按模型分组展示当前账户全部任务,支持状态过滤、产物预览、重新生成、删除等操作。

文档更新记录

日期	更新内容
2026-09-17	新增常见问题页(API Key / 计费 / 任务 / 素材 / 控制台 五大类高频问题)