小啡一键成片 · API 接入手册

1. 产品 API 思路

小啡不是把“一键成片”做成一条不可修改的黑盒流水线，而是把 剧本、资产、导演片段、图片、视频、任务状态 都变成可读、可改、可批量、可并发的业务对象。

2. 5 分钟快速开始

{{
  "status": "ok",
  "version": "0.11.0-alpha.4",
  "release": "v0.11.0-alpha.4-RC15.8.6.2-ToAPIsEnvMigrationHotfix",
  "timestamp": "2026-08-28T00:00:00.000Z"
}}

curl -X POST "{{BASE_URL}}/v1/projects" \
  -H "Authorization: Bearer sk-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "title":"金毛卧底",
    "contentType":"short_drama",
    "sourceType":"screenplay",
    "settings":{{"episodeCount":80,"aspectRatio":"9:16"}}
  }'

{{
  "id":"project_xxx",
  "title":"金毛卧底",
  "status":"draft",
  "contentType":"short_drama"
}}

3. 鉴权与 API Key

UI 操作示意：API Key / 权限。依据当前 RC 客户端与 API Key DTO 绘制，非像素级产品截图。

正式 v1 生产接口使用统一 Header：

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

当前 UserOrApiKeyAuthGuard 的规则是：Bearer 值以 sk- 开头时按 API Key 校验，否则按用户 JWT 校验。

{{
  "name":"我的生产客户端",
  "scopes":["production:read","production:write"],
  "rateLimit":60,
  "ipAllowlist":[],
  "allowedProviders":[],
  "allowedModels":[],
  "quotaLimit":"0"
}}

{{
  "code":200,
  "msg":"success",
  "data":{{
    "id":"key_xxx",
    "key":"sk-完整密钥仅此一次",
    "scopes":["production:read","production:write"]
  }}
}}

4. 响应格式、Trace 与错误

/v1/* 路由通常直接返回业务对象；传统 /user/* 路由经过全局 TransformInterceptor，通常包在 {code,msg,data,traceId} 中。

{{
  "code":200,
  "msg":"success",
  "data":{{...}},
  "traceId":"trace_xxx"
}}

{{
  "code":10000,
  "msg":"参数错误",
  "data":null,
  "traceId":"trace_xxx"
}}

常用错误码

5. Project 项目

Project 是生产链的顶层业务容器。正式 API 支持 API Key 与 JWT。

{{
  "title":"80集营销短剧",
  "contentType":"short_drama",
  "sourceType":"idea",
  "settings":{{}}
}}

{{
  "title":"新标题",
  "settings":{{
    "productionProfile":{{"episodeCount":80,"aspectRatio":"9:16"}}
  }}
}}

6. Source / Runtime / Gate

UI 操作示意：批量文字与 Gate 1。

Runtime 保存最新 Source、Proposal、Canonical Script 与确定性生产结构。大文本推荐使用分块传输，当前 Customer Console 也采用 4096 字符分块。

curl -X POST "{{BASE_URL}}/v1/projects/PROJECT_ID/runtime/source/chunked/init" \
 -H "Authorization: Bearer sk-..." \
 -H "X-XiaoFei-Client-Release: a4-rc15-8-6-2-toapis-env-migration-hotfix" \
 -H "Content-Type: application/json" \
 -d '{{"sourceType":"screenplay","totalChars":18420,"totalChunks":5,"filename":"script.txt"}}'

{{"uploadId":"upload_xxx", "accepted":true}}

{{"index":0,"chunk":"第1集……"}}

{{}}

{{
  "stage":"proposal_ready",
  "llmCalls":0,
  "receipt":{{
    "sourceId":"src_xxx",
    "scriptId":"script_xxx",
    "proposalId":"proposal_xxx"
  }}
}}

7. Production Settings

UI 操作示意：生产设置。客户可以用自己的客户端暴露更多高级参数。

Production Profile 是客户默认生产参数；项目可通过 project.settings.productionProfile 覆盖；Runtime 可再接受单次运行覆盖。优先级建议保持：平台默认 < 客户默认 < 项目覆盖 < 本次运行。

{{
  "contentType":"short_drama",
  "language":"zh-CN",
  "aspectRatio":"9:16",
  "episodeCount":80,
  "episodeDuration":60,
  "storyboardCharacterReferenceEnabled":true,
  "wardrobePolicy":"script_first",
  "assetMaterializationThreshold":2,
  "defaultTextProviderProfileId":"pp_text",
  "defaultImageProviderProfileId":"pp_image",
  "defaultVideoProviderProfileId":"pp_video",
  "extra":{{"visualReferenceMode":"direct_reference","visualStyle":"真人电影感"}}
}}

8. 一键自动生产

Auto Production 使用 Bull 队列创建 Run + Task，不应要求 HTTP 一直等待整个 80 集完成。

{{"storyboardEnabled":false}}

{{
  "taskId":"task_xxx",
  "runId":"run_xxx",
  "status":"queued",
  "progress":0
}}

{{
  "latest":{{"taskId":"task_xxx","status":"running","progress":42}},
  "history":[...]
}}

9. Run / Task

建议所有媒体长任务最终收敛到统一状态：queued → running → succeeded / failed，并带 progress、errorCode、errorMessage、stage 与日志指针。

async function waitTask(taskId) {{
  while (true) {{
    const r = await fetch(`${{BASE_URL}}/v1/tasks/${{taskId}}`, {{
      headers: {{ Authorization: `Bearer ${{API_KEY}}` }}
    }}).then(r => r.json());
    if (r.status === 'succeeded') return r;
    if (r.status === 'failed') throw new Error(r.errorMessage || r.errorCode);
    await new Promise(x => setTimeout(x, 2000));
  }}
}}

10. 最终成片与剪辑

当前 Final Film 会选择每个 Segment 最新成功视频，并进入 media-postprocess 队列。未来字幕、转场、片头尾、BGM、色调统一都应继续接在这一层，而不是塞回视频 Provider。

{{"title":"金毛卧底 · 完整版"}}

{{"taskId":"task_final","status":"queued","progress":0}}

{{
  "latest":{{"status":"succeeded","progress":100}},
  "artifacts":[{{
    "id":"media_final",
    "mediaType":"final_film",
    "playbackPath":"/v1/media/media_final/play?token=..."
  }}]
}}

11. 剧本库 / 资产库 / 白膜库 / Skills

这些不是附属配置，而是小啡总后台的长期核心资产。客户端目前有只读/检索接口，写入与审核主要由 Admin 控制面完成。

12. 图片与故事板（客户端调试 API）

UI 操作示意：资产图 / 故事板确认。

{{"projectId":"project_xxx"}}

{{
  "projectId":"project_xxx",
  "providerProfileId":"image_profile",
  "assetKey":"ap-character-xxx",
  "promptOverride":"可选：人工调整后的提示词"
}}

{{"projectId":"project_xxx"}}

{{
  "projectId":"project_xxx",
  "providerProfileId":"i2i_profile",
  "segmentNo":1,
  "useReferences":true
}}

13. 视频生成

UI 操作示意：Runtime 统一组装多参考图后提交 MiniMax-H3。

RC15.8.6 的关键边界是：浏览器不再决定单张参考图，Server Runtime 才是 reference bundle 权威。 Storyboard Route 包含故事板 + 匹配资产；Direct Reference 只包含匹配资产；最多 9 张。

{{"projectId":"project_xxx"}}

{{
  "projectId":"project_xxx",
  "providerProfileId":"video_profile",
  "segmentNo":1,
  "videoMode":"direct_reference"
}}

{{"taskId":"provider_task_xxx"}}

14. Media Playback 与阿里云 OSS

当前 RC 的 /v1/media/:id/play?token=… 支持 HTTP Range 播放。正式媒体建议走对象存储；对外保持媒体授权契约，存储实现可抽象为 MediaStorage Adapter。

15. 中转站 / Provider / BYOK

UI 操作示意：Credential 与 Provider Profile 分层。

Credential 与 Profile 必须分开：Credential 管密钥/Base URL；Profile 管用途、模型、Endpoint、超时和 Provider options。

{{
  "name":"我的 ToAPIs",
  "providerType":"openai_compatible",
  "baseUrl":"https://example-provider.invalid",
  "apiKey":"SECRET",
  "enabled":true
}}

{{
  "credentialId":"credential_xxx",
  "purpose":"video",
  "model":"MiniMax-H3",
  "endpointPath":"/v1/video_generation",
  "timeoutMs":180000,
  "maxPromptChars":7000,
  "enabled":true
}}

16. 80 集并发与 Provider Router

未来“80 集，每 10 集走一个视频通道”不应该由前端 for-loop 硬编码，而应由 Server Scheduler 根据 Provider Capability、并发槽、健康度、价格和客户策略分配。

建议未来公共 API 暴露 routingPolicy / providerPoolId / maxConcurrency 等高阶设置，但不直接暴露内部秘密 Credential。

17. 调试、日志与 504 定位

客户调试版每一步都应有日志。当前 Product Parity 提供 GET /user/product/debug-logs（JWT），媒体生成也记录 Provider/Task 信息。

18. 完整调用范例

cURL：创建项目 → 导入短剧 → 确认 → 自动生产

复制API="{{BASE_URL}}"
KEY="sk-REPLACE_ME"
REL="a4-rc15-8-6-2-toapis-env-migration-hotfix"

# 1. 创建项目
PROJECT_ID=$(curl -s -X POST "$API/v1/projects" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title":"Demo","contentType":"short_drama","sourceType":"screenplay"}' | jq -r '.id')

# 2. 小文本可直接 Source；长文本建议使用 chunked API
curl -X POST "$API/v1/projects/$PROJECT_ID/runtime/source" \
  -H "Authorization: Bearer $KEY" \
  -H "X-XiaoFei-Client-Release: $REL" \
  -H "Content-Type: application/json" \
  -d '{"sourceType":"screenplay","text":"# 第1集\n……"}'

# 3. 确认 Gate 1
curl -X POST "$API/v1/projects/$PROJECT_ID/runtime/proposal/confirm" \
  -H "Authorization: Bearer $KEY"

# 4. 启动自动生产
curl -X POST "$API/v1/projects/$PROJECT_ID/auto-production" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"storyboardEnabled":false}'

# 5. 查看状态
curl "$API/v1/projects/$PROJECT_ID/auto-production" \
  -H "Authorization: Bearer $KEY"

JavaScript：安全轮询

复制const headers = {{ Authorization: `Bearer ${{API_KEY}}` }};

async function getAutoProduction(projectId) {{
  const r = await fetch(`${{BASE_URL}}/v1/projects/${{projectId}}/auto-production`, {{ headers }});
  if (!r.ok) throw new Error(`HTTP ${{r.status}}`);
  return r.json();
}}

async function waitAuto(projectId) {{
  for (;;) {{
    const state = await getAutoProduction(projectId);
    const t = state.latest;
    renderProgress(t?.progress ?? 0, t?.status ?? 'queued');
    if (t?.status === 'succeeded') return t;
    if (t?.status === 'failed') throw new Error(t.errorMessage || t.errorCode || 'failed');
    await new Promise(r => setTimeout(r, 2000));
  }}
}}

19. RC15.8.6.2 当前客户侧路由索引

下面按当前源码 Controller + Customer Console 调用整理。Admin 总后台写接口没有全部列入本页，避免客户误用。

20. UI → API 对照

21. 版本、兼容与下一阶段