小啡一键成片 FAQ

能力上可理解为：API（能力中心）、Admin（总后台与核心资产管理）、Customer Web（官方客户端）。客户端只通过 XiaoFei API 工作，不直连 Provider、数据库或对象存储。

是。客户端不应直接连接 EasyRouter、ToAPIs、MiniMax、数据库或 OSS。浏览器只调用 XiaoFei API；Provider 请求、密钥、网络出口、任务和媒体持久化都由服务端负责。

剧本库、人物/场景/道具/产品资产库、白膜库、Prompt 库、Skills 库，以及未来的爆款库、质量数据和生产经验。长期壁垒是可持续积累的生产系统，不是某一个视频模型。

• Canonical：稳定业务事实与对象。
• Runtime：确定性编排、任务和状态。
• Prompt / Skill：创作策略与可组合能力。
• Provider：外部模型/中转站适配。
• Client：交互与展示。

不要让 Provider 输出反过来定义 Canonical。

Provider 决定请求发给谁，Egress 决定网络出口策略。两者解耦后，可独立做健康检查与故障切换，客户端无需感知底层网络细节。

由 Scheduler 切批，例如每 10 集一批，再由 Provider Router 按健康度、成本、并发和限流分配到多个视频通道。客户端只提交业务任务，不负责手工维护几十个 Provider 队列。

正式媒体不应长期依赖 API 容器本地磁盘。角色图、场景图、故事板、参考图、分段视频和最终成片都应进入 OSS，数据库保存 Media 记录和 Object Key。

Provider 返回后，应完成下载/接收、上传 OSS、写 Media 记录，全部成功后才能标记 ready，避免“数据库成功但文件打不开”的幽灵成功。

生成耗时经常超过浏览器或 API 同步等待时间。正确模式是先返回 taskId，再轮询/订阅任务状态，完成后读取 Media。

504 只代表某一层等待上游超时，不等于模型一定失败。日志要区分 API、网络出口、Provider、Storage，并记录 preparation、upload、provider round trip、persist、total 等阶段耗时。

进入 Prompt Center / Prompt Registry，带版本、状态和适用模块。不要把长期 Prompt 散落硬编码到 Controller 或 Vue 页面。

Skill 负责可组合的创作策略，不承担确定性业务状态。应有明确输入/输出契约、版本、启停和适用范围，由 Runtime/Planner 决定何时加载。

资产识别、规范化和可见性属于资产/Canonical/Runtime 层；用于生成某张图的视觉描述属于 Prompt/Skill。不要把资产事实藏进 Provider Prompt。

部分旧测试检查源码字符串或历史实现细节，而不是行为。后续门禁优先行为测试、契约测试和目标容器测试，减少“测代码长相”。

先定位阶段：客户端、API、Runtime、Provider、Storage、DB。日志必须保留 stage、errorCode、taskId/runId 和关键耗时。不要看到一个错误就去改 Canonical 或 Prompt。

获取 API Key → 创建/选择项目 → 上传故事/剧本和 Production Settings → 生成/确认文本 → 资产/图片 → 视频任务 → 查询 task/run → 获取最终 Media/成片 URL。

放在客户自己的安全后端或受控环境中，不要写死在公开前端源码。不要把完整 Key 放进报错截图、工单或日志。

可以。官方客户端只是 XiaoFei API 的一个 Client。第三方可以用同一套 API 自己做短剧、剧情带货、产品视频或定制工作台。

可以，但入口类型要明确。已经是 screenplay/拍摄剧本的内容不应再次依赖 LLM 才能“承认它是剧本”，系统应做确定性解析和必要补全。

通常包括内容类型、集数/时长、画幅、视觉风格、视频模型、参考模式、Provider/BYOK 等。高级客户可获得更多自主性，但不能绕过服务端安全和权限边界。

可以。API 应支持只做剧本、只做资产、只出图、只做视频，不强迫所有客户走唯一线性流程。

正式生产建议异步：提交任务后返回 taskId，后续查询任务和 Media。调试接口可以更直接，但不应把长时间同步等待作为长期公共契约。

不是。当前设计允许 Storyboard Reference 与 Direct Reference 两条视频路径。Direct 模式可以使用人物、场景、道具/产品参考图直接生成视频。

不应由浏览器用一个旧 referenceMediaId 决定。服务器 Runtime 应根据 Segment、场景和资产状态解析 Reference Bundle，预览和正式提交使用同一解析逻辑。

客户提交项目或批次任务，后端 Scheduler 负责拆批和分配 Provider。客户端只需要显示 episode/segment/task 级状态，不需要自己维护几十个视频队列。

不应该。文本、资产、图片、已成功视频都应保留。失败只标记对应 task/segment，并允许最小单位重试。

公共 API 建议统一为 queued / running / succeeded / failed，同时返回 taskId、runId、progress、errorCode、errorMessage 和必要阶段信息。

504 表示网关等待上游超时，不等于模型一定失败。客户应记录 taskId/requestId 并查询任务状态；平台再判断是 Proxy、Provider、API 还是网关超时。

429 通常是限流或配额。客户端不要高频无脑重试，应遵循后端重试策略；平台 Router 可切换其他健康通道。

使用幂等键/去重策略。同一业务任务重复提交时，服务端应识别已有或正在运行的任务，并明确返回 deduplicated/已有 taskId。

不必须。客户可以使用平台集合，也可以绑定自己的 Provider/BYOK。可用范围由权限和 Production Settings 决定。

不应该。代理、出口 IP、账号密码和网络拓扑属于服务端运维信息。客户端只看到 Provider/模型能力和必要状态。

应保存在服务端受保护的凭据存储中，前端只提交/更新，不回显完整密钥。

正式环境统一进入对象存储，规划为阿里云 OSS。数据库保存 Media 与 Object Key；客户端通过 API 获取可访问地址。

私有 OSS 建议使用签名 URL，因此链接可能有时效。客户应保存 Media ID/Object Key 语义，不要把临时签名 URL 当永久主键。

至少包括项目/Run 状态、最终 Media ID、可访问 URL、时长/尺寸/格式、相关 task/run，以及必要的 JSON 元数据入口。

不建议。RC 阶段会保留兼容门禁和调试接口。正式公共 API 应逐步收敛为稳定的 /v1/projects、/v1/assets、/v1/images、/v1/videos、/v1/tasks、/v1/runs 等资源。

这是当前 Alpha/RC 兼容门禁，不应成为长期对外契约。正式版应采用标准 API Version / Capability Negotiation。

至少提供 requestId/taskId/runId、接口路径、HTTP 状态码、errorCode/errorMessage、发生时间和最小请求摘要。不要直接发送完整 API Key。