车库

Studio API 参考

契约归属：不受车库双契约管辖

请先读这一节，再读下面的端点清单。platform/studio/api 是一个独立的 Python FastAPI 服务，不受 docs/openapi/openapi.yaml 和 docs/openapi/baas-app-v1.yaml 这两份车库主契约管辖，也不受 internal/contracttest 校验——那两份契约管的是 platform/server（Go）的 /api/v1/admin/*、/api/v1/app/* 等路径。本页描述的所有 Studio 自身接口直接依据源码 platform/studio/api/src/apps/studio/api.py、src/apps/playground/api.py，源码是唯一真相。

唯一的例外：POST /api/v1/admin/studio-imports*（Go 后端把 Studio 成片导入车库 catalog 的那一步）仍然归主契约 openapi.yaml 管辖，字段与路径以该文件为准，本页不重复定义，只在下文"与车库主平台的集成"一节说明它的作用。

"不受管辖"不等于"没有 schema"：platform/studio/api 是 FastAPI，路由签名 + Pydantic 模型本身就能推导出完整 OpenAPI schema，天然不会跟实现脱节。api/scripts/export_openapi.py 把这份 schema 冻结成 api/openapi.json（api/tests/test_openapi_export.py 保证它没有过期），web 侧用 pnpm generate:api-types 据此生成 web/src/generated/api-types.ts 供前端标注请求/响应类型。这条路径是"运行时反推契约、机器保证不漂移"，跟车库 Go 侧"手写 YAML 契约、先立约再实现"的方向相反——详见 已知问题 里对这个选择的分析，以及 platform/studio/README.md「接口契约」一节的具体命令。

鉴权

请求需带 Authorization: Bearer <token>，token 二选一：

  • Admin JWT：车库 admin 登录后签发的会话 token。Studio 本地验签（ADMIN_SESSION_SECRET 优先于 ADMIN_JWT_SECRET，与 Go 侧优先级一致）通过后，还会向 Go 服务发起 GET {MOTORPOOL_API_URL}/api/v1/auth/me 做一次 introspection 确认账号仍然有效，结果缓存 STUDIO_INTROSPECT_TTL_SECONDS 秒（默认 30）。Go 服务不可达时按未授权处理（fail closed）。
  • STUDIO_SERVICE_TOKEN：标识"车库服务本身"发起的编排调用（如成片导入），跳过 introspection。

GET/HEAD /files/*（媒体文件）有一个例外：因为 <img>/<video> 标签发不出自定义请求头，这类请求改读 authorized-token cookie 里的 accessToken，仍然走同一条 JWT 校验路径，不是弱化校验。

STUDIO_AUTH_DISABLED=true 仅限本地调试；鉴权开启但一个凭证都没配时，进程启动直接失败。详见 Studio 架构总览 的双向鉴权一节。

端点分组一览

按功能分组，studio 主 app 145+ 路由 + playground 子 app 11 路由。具体路径/请求体字段以源码为准，这里只给分组和依赖的 AI provider。

分组做什么依赖的 AI provider
系统/诊断健康检查、日志尾部、环境自检—
文件上传通用上传 + 项目资产上传—
项目（Script）CRUD创建/查询/删除项目，重新解析剧本LLM 实体抽取（DashScope/OpenAI 兼容）
Series（剧集）CRUD 与共享资产系列增删查、集数管理、prompt/model 配置、共享角色场景道具—
全局资产库跨项目复用的资产（角色/场景/道具），支持从项目"提升"进库—
文件导入/剧集拆分上传 txt/md，LLM 拆集预览后确认建 Series+EpisodesLLM
跨集资产复用（Reconcile）新集里抽取出的实体与 Series 共享库做名字比对，给合并建议—
前情提要与悬念钩子生成"上一集摘要""下集预告"LLM
角色/场景/道具 CRUD（项目内）——
素材生成参考图（T2I）、运动参考视频DashScope Wanx / MuleRouter GPT-Image-2
分镜（Storyboard）分镜分析、prompt 润色、生成分镜图Wanx + LLM
视频生成与任务队列生成、批量提交、取消、轮询任务状态Wan2.7/HappyHorse（经 DashScope）、Kling、Vidu、Seedance 2.0（经 MuleRouter），由 provider_registry 按模型名前缀路由
配音 TTS台词配音、音色克隆/设计DashScope CosyVoice / Qwen3-TTS
人声分离配音（Dub）分离原片背景音后叠加新配音Demucs（可选依赖，缺失时退化为直接叠加）
BGM/SFX/混音背景音乐、音效生成、音轨混合DashScope Fun-Music（需 DASHSCOPE_WORKSPACE_ID）/ ElevenLabs
分镜编辑帧的增删改/锁定/复制/重排—
合成/导出ffmpeg concat + 混音，导出成片—
美术风格（Art Direction）风格分析、预设、保存LLM
Prompt 润色视频生成 prompt 优化LLM
运行时配置环境变量读写、MuleRouter 登录—
结构化脚本编辑器Tiptap 文档的保存/快照/导入导出/派生同步LLM（部分）
Playground（/playground 前缀）脱离项目流程的单发式生成沙盒，复用主流程的 provider 路由同"视频生成"分组

任务与轮询模型

视频/图像生成是异步任务：提交后拿到 task_id，客户端轮询 GET /tasks/{id} 获取状态。进程重启后的孤儿任务不会自动重跑——因为可能已经跟 provider 扣过费，需要人工判断后处理。

与车库主平台的集成

Go 后端用 STUDIO_SERVICE_TOKEN 拉 Studio：

  • 单集：GET /projects/{id} → POST /api/v1/admin/studio-imports
  • 整剧：GET /series/{id} 与 GET /series/{id}/episodes → POST /api/v1/admin/studio-imports/series

这是 Studio 与车库内容中台的耦合点，方向永远是「Go 主动拉」，Studio 不会主动推送。详见 架构。

已知限制

  • 单实例假设：数据落在 STUDIO_DATA_DIR 下的扁平 JSON 文件，进程启动时 chdir 到该目录，不支持多进程共享同一份数据。
  • 魔改未做：从已上架剧派生新 Series、写 remix_of 的后台入口尚未交付。

更完整的问题清单见 已知问题。

相关页面