PRINTFILM: AI short-video marketing and AI short-drama creation platform
API 接入与中文文档
接口定义由 FastAPI 路由和 Pydantic 模型实时生成,请以运行中服务的 OpenAPI 为准。
文档入口
本地后端默认地址为 http://127.0.0.1:8000。
| 入口 | 用途 |
|---|---|
| /docs | Swagger 在线调试,可按中文分组浏览和搜索接口 |
| /redoc | ReDoc 阅读视图 |
| /openapi.json | OpenAPI 定义,供客户端生成及接口工具导入 |
这些地址由后端提供。通过前端站点访问时,需要网关显式转发对应文档路径;当前用户端 nginx 的 /api/ 代理不包含 /docs、/redoc 和 /openapi.json。
登录与调用
- 使用
POST /api/auth/register注册,或使用POST /api/auth/login登录。 - 从响应读取
access_token;token_type为bearer。 - 在 Swagger 的 Authorize 中填写令牌,或在请求头携带
Authorization: Bearer <access_token>。 - 管理端
/api/admin/...要求账号角色为admin,普通登录令牌不会自动获得管理权限。
登录请求示例:
POST /api/auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "your-password"
}
登录响应结构:
{
"access_token": "<login-jwt>",
"token_type": "bearer"
}
查询个人漫剧项目示例:
GET /api/drama/projects?workflow=script&page=1&page_size=9
Authorization: Bearer <login-jwt>
短片创作与历史项目
当前新建短片采用 /api/projects 分步创作流程:准备文案、创建或更新项目、生成分镜与素材,再由用户确认后合成成片。
POST /api/projects 与 PATCH /api/projects/{project_id} 使用 pipeline_mode 区分制作方式:
| 模式 | 素材与生成顺序 |
|---|---|
full |
分镜脚本 → 参考图模式生成分镜图片 → 图片生成镜头视频 → 合成成片 |
image_text |
分镜脚本 → 参考图模式生成分镜图片与配音 → 静图合成成片 |
当前新建页面默认选择 full,仍可选择 image_text。图片沿用选定模板的画风参考图、项目 ref_image_url 及已有镜头参考,锁定画风和角色;镜头视频以本镜图片作为首帧,并参考上一镜尾帧保持衔接。image_model / video_model 分别选择图片与视频模型,image_resolution / video_resolution 保存相应清晰度,target_duration_sec 为 15~180 秒的目标时长。完整视频模式沿用原有视频内置口播逻辑;静图模式保留外部配音。
画风图优先取模板 seedream_config.style_ref_urls,未配置时取模板封面;四个内置画风的旧模板行即使封面为空,也使用随代码提供的封面图。历史 ref_images 继续作为主体参考,用户图优先;后镜另加上一镜图片,画风参考独立传递。真实生成时,本地图片需同步发布到 OSS 或通过公网 PUBLIC_BASE_URL/static/... 访问,无法访问时返回明确错误,避免静默变成纯文字生图。镜头图片与视频参考均跳过需要鉴权的 TokenFree 产物地址,使用已保存的媒体。
调用 POST /api/projects/{project_id}/generate 每次只提交当前待执行的一段任务,阶段由后端素材就绪状态判定:script、assets、videos。素材阶段完成后,完整模式再次调用生成接口才进入视频阶段;静图模式跳过视频阶段。全部素材就绪时生成接口返回 409,改用 POST /api/projects/{project_id}/compose 合成。各阶段仅预扣本次尚未完成的媒体费用,已有图片和视频会复用。
单镜调整可使用 POST /api/projects/{project_id}/shots/{shot_id}/regen-image 与 .../regen-video;后者仅支持 full,并要求该镜已有图片。生成期间不能切换制作模式;通过 PATCH 切换模式会保留原分镜素材,作废原成片并按新模式回到待生成或待合成阶段。若要重新拆分镜,可调用生成接口并设置 restart=true,这会清除原分镜和素材。
旧版对话创作会话的创建、列表、详情、消息、取消、重试与 SSE 接口已删除,访问这些旧入口返回 404。其前端会话状态与轮询代码也已移除。
仅保留 POST /api/creation-sessions/{session_id}/open-editor,归入“科普项目与作品”分组,用于将历史项目转入当前工作台。该接口会先等待旧任务停止并结算,再交接原项目及素材;历史任务执行与恢复代码、数据库记录保留。
团队空间与编辑租约
支持空间切换的列表和创建接口通过 X-Team-Id 请求头或 team_id 查询参数选择团队空间;两者同时提供时必须一致。未指定时使用个人空间。资源详情和写入的权限依据数据库中的真实归属判定,切换请求头不能改变资源归属。
创建漫剧项目还可在请求体设置 team_id,与显式选中的团队空间不一致时返回 422。
团队漫剧内容写入通常先获取编辑租约:
POST /api/teams/12/edit-locks/acquire
Authorization: Bearer <login-jwt>
Content-Type: application/json
{
"project_id": 34,
"resource_type": "structure",
"resource_id": 0,
"session_id": "editor-tab-001",
"force": false
}
项目和团队编号为示例,请替换为实际可访问资源。获取成功后保存响应中的 token、version,写入时携带:
PATCH /api/drama/projects/34
Authorization: Bearer <login-jwt>
Content-Type: application/json
X-Edit-Session: editor-tab-001
X-Edit-Token: <acquire 返回的 token>
X-Edit-Version: <acquire 返回的 version>
{
"title": "新的项目名称"
}
structure、script、canvas 的 resource_id 为 0。已有资产使用资产编号;创建资产或未绑定既有资产的生成入口使用 asset/0,以具体接口为准。分集优先使用稳定集号,历史数据缺少集号时使用分集数据库编号。按实际写入范围申请租约,成功获取的租约默认有效期为 120 秒,可通过 /renew 续租、/release 释放;两者请求体为 token 和 session_id。续租不会再次返回原始 token,客户端应保留首次获取的凭证。
其他会话占用可返回 423;缺少租约返回 428;租约失效、版本变化或目标不匹配返回 409。强制接管人工占用仅团队所有者和管理员可用,不能绕过系统任务写入占用。取消生成入口等例外以具体接口说明为准。
漫剧项目字段约定
| 字段或参数 | 说明 |
|---|---|
source |
原始创意,去除首尾空白后至少 20 字 |
workflow |
script 为剧本分集流程,canvas 为自由画布 |
episode_count |
创建请求中的目标集数为 1~120;返回详情中的同名字段是已建立的分集数量 |
params |
创建时与工作流配置一起保存;PATCH 时整体替换原配置,请保留仍需使用的键 |
content |
PATCH 时整体替换对象或数组,不做增量合并 |
q |
标题子串搜索,忽略首尾空白及大小写;%、_ 按普通字符匹配 |
status |
项目列表进度筛选,依据剧本、资产与分集数量判断,不表示后台任务状态 |
usage |
当前空间可见用量;团队所有者查看团队合计,其他成员仅查看本人用量 |
列表 status=running 和 status=done 可以重叠:漫剧有剧本且至少 1 集即符合 running,有剧本且至少 8 集符合 done;自由画布已有资产符合 running,不进入 done。draft 表示无资产的画布或无剧本的漫剧。详细规则见 Swagger 参数说明。
GET /api/drama/canvas/{project_id} 返回节点时,已有资产的 mediaUrl、url、cover 以服务端当前资产为准。POST /api/drama/canvas 保存布局时不会用客户端旧节点覆盖已有资产的视频、图片或封面地址;个人节点名称、提示词与布局仍按提交内容保存,上传和明确更换媒体继续使用资产接口。
分页、任务与错误
分页通常使用 page(从 1 开始)与 page_size,返回 items 和 meta.page、meta.page_size、meta.total。部分接口使用平铺分页字段或直接返回数组,请以各自响应结构为准。漫剧项目列表会将超出范围的页码修正为最后一页。
生成接口可能在请求内完成,也可能提交后台任务。异步接口返回成功表示任务已受理,最终结果需查询 /api/tasks/{task_id}、/api/tasks/generations/{task_id} 或对应业务状态接口。SSE 接口使用 text/event-stream,事件名和数据内容见接口说明。任务调度与状态详见 TASK_SCHEDULING.md。
错误响应的 detail 可能是中文字符串、结构化对象或字段校验数组。客户端应同时检查 HTTP 状态码和 detail,不要假定所有接口共用成功响应封装。
| HTTP 状态 | 常见含义 |
|---|---|
| 400 | 业务参数或当前操作不符合要求 |
| 401 | 未登录或登录令牌失效 |
| 403 | 当前账号没有操作权限 |
| 404 | 资源不存在、不可访问或对应模块未启用 |
| 409 | 状态、版本或编辑权限冲突 |
| 410 | 接口已停用,例如团队钱包充值与调账兼容入口 |
| 422 | 字段、参数组合或媒体参数校验失败 |
| 423 | 资源正在被其他成员或任务占用 |
| 428 | 缺少团队内容编辑租约 |
金额字段 *_fen 的单位为人民币分,*_yuan 为人民币元;其他价格与 Token 费率以字段说明为准。团队创作当前由所有者个人钱包付费,历史团队钱包入口不代表仍支持团队充值。详见 BILLING.md 和 TEAM_MODE.md。
数字资产市场为可选模块。GET /api/marketplace/capabilities 可查询开关;市场关闭时其他市场业务接口返回 404。配置就绪状态不等于已完成真实存储或支付联调,详见 MARKETPLACE.md。
文档维护
- 路由维护中文
summary、description和response_description,描述实际权限、同步或异步行为、返回结果及关键错误。 - 请求和响应模型使用
Field(description=...)说明含义、单位与空值行为,参数使用Query、Path、Header等声明说明。 - 通用中文分组、分页提示和 FastAPI 默认响应描述由
backend/app/openapi_docs.py统一提供。 - 更新接口后直接重新生成 OpenAPI,不维护独立的静态接口清单;业务约束以实现和生成的模型为准。