开发者指南
通过智能体使用 FayBai
将 MCP 客户端或脚本接入 FayBai,查看作品、编辑场景、规划并确认生成、查询进度和导出成片
FayBai 为智能体提供两个入口:
- MCP:
/mcp,可查看完整作品、编辑场景、规划和执行生成并导出,适用于 Claude、Cursor 等 MCP 客户端。 - REST:
/api/v1,可一次调用根据剧本创建作品,再轮询状态,详见公开 API。在无 MCP 支持或需要创建作品时使用(MCP 尚不能创建作品)。
连接
除 whoami 外,所有工具名称均带 openstory. 前缀,例如 openstory.get_scene。本指南为简洁起见省略前缀。
| 项目 | 值 |
|---|---|
| 服务器网址 | https://<your-openstory-host>/mcp(Streamable HTTP,仅 POST,无会话) |
| 协议版本 | 2026-07-28;仍以 initialize 开始的客户端使用 2025 握手。两种方式均无会话,各请求独立处理,可到达任一服务器实例。使用官方 SDK 时,设置 versionNegotiation: { mode: 'auto' },或固定 2026-07-28。 |
| OAuth(推荐) | 在 /.well-known/oauth-protected-resource/mcp 发现服务,支持动态客户端注册、授权码 + PKCE,resource = https://<host>/mcp。未认证请求返回 401,并通过 WWW-Authenticate 指向该发现文档。 |
| 静态请求头 | 使用“设置 → 开发者”创建的 API 密钥:Authorization: Bearer osk_…。API 密钥没有权限范围限制。 |
| 获取密钥 | 无浏览器重定向时,使用 REST 设备码登录:POST /api/v1/device/code,向用户显示设备码,并轮询返回链接直至获得密钥。 |
权限范围(仅 OAuth)
| 权限范围 | 授权内容 |
|---|---|
sequences:read | 全部读取工具和资源。 |
sequences:write | update_scene、update_sequence、archive_sequence、unarchive_sequence;场景和镜头的创建、排序、删除、恢复;update_shot;镜头提示词、设定及对白编辑;选择图片、片段、对白版本或配音版本;角色、地点和元素编辑;音色与设定图选择;音乐提示词和音轨;upload_media 及 set_*_from_upload;select_sequence_model;工作室收藏和删除;取消视频渲染、对白录制、音色设计或待完成的提示词/静帧;plan_export、start_export。 |
generate | create_sequence;工作室生成、编辑、最终版和提示词起草;regenerate_storyboard、rebuild_shot_prompts、plan_generation、execute_generation、retry_failed_work;单镜头静帧、变体、片段及预览版的高质量渲染;add_model_to_sequence、add_element / replace_element;参考图、重新选角、音色设计、音乐和对白等所有可能消耗额度的操作。 |
缺少权限范围时,工具返回 INSUFFICIENT_SCOPE 错误,details.scope 指明需重新授权的范围。工具发现和 whoami 不需要范围。
标识符
- 每部作品工具都需要
sequenceId,并据此校验所有下级对象。 - 场景 ID(
sceneId)与镜头 ID(shotId)不同。get_scene只接受场景 ID,get_shot只接受镜头 ID。镜头携带父级sceneId,始终可向上导航。 - 场景或镜头展示的是所选版本,包括剧本、提示词、静帧和片段。读取返回所选版本及 ID;
update_scene要求提交你读取到的所选剧本版本,避免覆盖未见过的版本。 - 其他组织、其他作品或已删除记录的 ID 均返回未找到。
读取、分页与限制
- 从
list_sequences开始,再调用get_sequence获取摘要和数量,或使用成本更低的get_sequence_status查看失败情况。 list_scenes和list_shots通过limit与不透明的nextCursor分页。提示词和媒体需要显式启用includePrompts、includeAssets。get_production_bible一次返回风格、角色、地点、元素及每个场景的叙事。无法容纳全部内容时,*Truncated字段会给出继续读取的列表工具和游标。- 成功结果同时提供结构化内容和相同 JSON 的文本版本;带错误码的错误位于
structuredContent.error,含code、message、details。超过 256 KiB 的读取会明确拒绝并提示分页,不会静默截断。写入已完成但结果无法返回时,会以RESULT_NOT_RETURNED返回已写对象 ID。此时勿重复写入,应重新读取对象。
资源
适用于通过附加上下文而非调用工具工作的宿主:
openstory://sequences/{sequenceId}/summary— 与get_sequence相同。openstory://sequences/{sequenceId}/bible— 与get_production_bible相同。openstory://sequences/{sequenceId}/scenes/{sceneId}— 与get_scene相同。
resources/templates/list 返回模板,resources/list 返回最近 50 部作品的摘要和设定。每个资源都有对应工具,因此不依赖宿主是否支持资源。
内嵌视图(MCP Apps)
get_sequence 会关联 MCP Apps 视图(ui://openstory/sequence-card.html)。支持的宿主会内嵌展示海报、状态、数量和音乐,并提供打开应用中作品的链接。任务运行时卡片会自行更新,结束后向聊天发送消息,让智能体无需轮询即可继续。不支持 MCP Apps 的宿主获得普通结构化结果,视图不会改变结果内容。
作品制作流程
智能体应遵循以下循环,也可将该流程放入智能体技能中。
- 创建(可选)。 使用
create_sequence提交剧本开始新作品,输入与POST /api/v1/sequences相同。轮询get_sequence_status直到分镜完成。regenerate_storyboard会替换整个剧本、风格或画面比例并重建所有场景,因此应先征求同意。 - 检查。 使用
get_sequence_status查看就绪和失败项目,使用get_production_bible查看故事与角色。对准备修改的场景调用get_scene,记录script.id。 - 编辑。 调用
update_scene,提供sequenceId、sceneId、expectedScriptVersionId(读取到的script.id)及需要更改的字段(scriptExtract、title、location、timeOfDay、storyBeat、continuity)。CONFLICT表示场景在读取后变化,也可能是你此前编辑的响应丢失;details.selectedScriptVersionId为当前版本。应重新读取,仅在仍需要时重新编辑。changed: false表示没有差异。 结构操作:create_scene(可带剧本)、reorder_scenes、delete_scene/restore_scene、create_shot、reorder_shots、delete_shot/restore_shot、update_shot(时长、首帧开关)、update_sequence(标题、目标时长、音乐开关、默认视频模型)。删除是可撤销的软删除,list_deleted和list_archived_sequences显示可恢复内容。这些操作均不启动生成。 镜头内容:get_shot_storyboard(仅参考图镜头的草图、是否需要更新及其历史记录)、get_shot_spec/update_shot_spec(免费按镜头设定重建提示词)、update_shot_prompt(手写提示词在后续重建中保留)、restore_shot_prompt_version、rebuild_shot_prompts(镜头设定无需更新时免费;需要更新时执行消耗额度的 AI 改写)、list_shot_dialogue/update_shot_dialogue/select_shot_dialogue_version、select_shot_dialogue_reading/discard_shot_dialogue_reading、select_shot_image_version、select_shot_video_version(ID 来自list_versions)。 角色与音乐:create_character/update_character/delete_character/replace_character/restore_character、set_character_voice_enabled、list_character_voices/select_character_voice_version、select_character_sheet_version、discard_/undiscard_character_sheet_version;使用create_/update_/remove_/restore_character_look、list_character_look_versions/select_character_look_version管理服装,通过update_scene的continuity.characterLooks为场景选择造型;地点采用相同模式(create_location…select_location_sheet_version);另有set_element_description、rename_element_token、delete_element/restore_element、update_music_prompt、restore_music_prompt_version、select_music_track、discard_music_track/undiscard_music_track。list_deleted_cast显示可恢复的角色。这些操作均不启动生成。 单镜头、单张设定图和单音轨操作都消耗额度,须先征求用户同意,且不经过计划:generate_shot_image、generate_shot_image_variants→get_shot_variant_grid→select_shot_image_variant、regenerate_shot_storyboard、generate_shot_video(cancel_video_render停止等待某次渲染)、lipsync_shot(为成片匹配台词口型,5 秒约 $0.67)、Ark 预览版的render_shot_at_quality/render_sequence_drafts_at_quality、add_model_to_sequence后接select_sequence_model、regenerate_character_sheet/regenerate_location_sheet、recast_location、generate_character_voice(首个版本成为当前音色;cancel_character_voice可取消)、generate_music、rewrite_music_prompt、regenerate_shot_dialogue(list_shot_dialogue_claims/cancel_shot_dialogue)、cancel_pending_shot_artifact。模型 ID 来自list_models。调用在任务启动后即返回,之后重新读取镜头、角色或音乐以查看结果。 文件:用户附加图片、片段或音频后,通过upload_media提供url或 base64data(8 MB)及use,再使用返回的upload调用set_shot_image_from_upload、set_shot_video_from_upload、set_music_from_upload、set_scene_dialogue_from_upload(使用dialogue,上传整场对话的 WAV)、set_character_sheet_from_upload、set_location_sheet_from_upload、add_element或replace_element。真实人物图片在用户确认持有使用权前会被拒绝(ATTESTATION_REQUIRED);确认后带portraitAttestation重新上传。 - 查看影响。 编辑返回场景 ID、新剧本版本 ID、镜头 ID 和首批镜头的待更新状态。
get_scene重新读取场景,list_shot_staleness分页读取其余镜头。编辑不启动生成。 - 规划。
plan_generation可使用mode: "stale"和depth(prompts、images、dialogue、video、music),决定更新到哪一级,范围可为整部作品、sceneIds或shotIds;也可使用mode: "missing",提供stopAt及可选startFrames、draftMotion,继续未完成的作品,仅支持整部作品,未提供的开关沿用原设置;失败后可用retry_failed_work。计划不启动任务,返回各阶段镜头 ID、跳过项、模型、美元估算(组件无价格时为null)及blockers。 - 请求批准。 向用户展示计划中的具体工作及费用,得到明确同意后再执行。
- 执行。 调用
execute_generation,提供planToken和confirm: true。工作或价格变化时会返回CONFLICT,且details.code: "PLAN_CHANGED",须重新规划。有进行中的任务、阻断条件或额度不足时也会拒绝,但计划仍可执行。超时后可安全重试,重复调用返回相同workflowRunIds,不会重复收费。重试时返回PLAN_CHANGED或GENERATION_IN_PROGRESS说明此前调用已启动任务,应检查get_sequence_status。 - 轮询。 每隔
pollAfterSeconds,用workflowRunIds调用get_operation_status。它仅报告这些任务,包括各镜头失败、跳过和terminal标记。partially_failed列出失败项,可为其规划重试。execute_generation返回LAUNCH_INCOMPLETE时会列出已启动的任务,应轮询它们,不要重新规划相同工作。 - 检查并导出。 重新读取镜头。
plan_export预览导出内容,start_export渲染 MP4,无需计划或确认,因为不消耗额度,且会复用同一剪辑已有的 MP4。轮询get_export_status。MP4 渲染器仅运行于生产环境,预览、本地开发和通过部署按钮自行安装的环境不会渲染导出。
工作室
工作室在作品之外生成独立图片和视频。每次生成都会消耗额度,因此应先向用户确认。
- 选择模型。
list_models中带studio的条目可用于工作室,studio描述其视频模式、时长、参考素材限制、尾帧和音频能力。 - 附加文件(可选)。 调用
upload_media,设置use: "studio"且不提供sequenceId。返回的upload可作为参考图片、音频、首尾帧,上传的视频参考片段则使用{ url }。来自list_generated_assets且source: "studio"的片段须使用{ assetId },即 ID 而非网址。网址始终视为上传。真实人物上传仍须提供上述portraitAttestation。 - 编写提示词(可选)。
draft_studio_prompt根据参考素材编写提示词,会消耗额度。 - 生成。 调用
create_studio_assets,提供activity(image或video)、模型、aspectRatio和提示词。视频还需要duration、mode(text、reference或frames),一次最多 4 个。 - 轮询。 对返回的每个 ID 调用
get_generated_asset,直到status为completed或failed。 - 优化。
edit_studio_asset根据提示词改写完成的 Seedance 片段,get_studio_edit_history展示编辑链。render_studio_asset_at_quality将完成的预览版转为 1080p 正式版。set_studio_asset_favorite标记收藏,delete_studio_asset永久删除,须先确认。
watch_clip 让 Gemini 观看任意已存储片段(镜头视频、工作室素材或上传文件),回答一个问题;除非组织自带 Gemini 密钥,否则会消耗额度。
MCP 尚不支持的功能
- 选择其他已设计的候选音色或选用音色库中的音色,两者都会写入 ElevenLabs 账号共享的音色槽位。
- 发布到社交平台。
- 取消由
execute_generation启动的整个操作;单个渲染和生成任务的更新资格(claim)可取消,见上文。
客户端兼容性
| 客户端 | 状态 |
|---|---|
官方 MCP SDK 客户端 2.1.0(versionNegotiation: auto) | CI 已对服务端处理器测试(身份验证使用桩,HTTP 身份验证层另有测试):发现、读取、整部作品及按场景筛选的镜头分页、场景与镜头导航、资源和缺失权限范围。 |
| 仅支持 2025 握手的客户端 | 无会话服务,每个请求独立,工具和资源均如此;已用官方 SDK 旧版模式测试。 |
| Claude Code | 尚未对实际部署验证。 |
| Claude.ai 自定义连接器 | 尚未验证。 |
| Cursor | 尚未验证。 |
| Codex、ChatGPT | 尚未验证。 |
“尚未验证”表示尚无人将该客户端连接到实际部署并运行上述流程,验证后会在此记录结果。