开发者指南

通过智能体使用 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:writeupdate_scene、update_sequence、archive_sequence、unarchive_sequence;场景和镜头的创建、排序、删除、恢复;update_shot;镜头提示词、设定及对白编辑;选择图片、片段、对白版本或配音版本;角色、地点和元素编辑;音色与设定图选择;音乐提示词和音轨;upload_media 及 set_*_from_upload;select_sequence_model;工作室收藏和删除;取消视频渲染、对白录制、音色设计或待完成的提示词/静帧;plan_export、start_export。
generatecreate_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 的宿主获得普通结构化结果,视图不会改变结果内容。

作品制作流程

智能体应遵循以下循环,也可将该流程放入智能体技能中。

  1. 创建(可选)。 使用 create_sequence 提交剧本开始新作品,输入与 POST /api/v1/sequences 相同。轮询 get_sequence_status 直到分镜完成。regenerate_storyboard 会替换整个剧本、风格或画面比例并重建所有场景,因此应先征求同意。
  2. 检查。 使用 get_sequence_status 查看就绪和失败项目,使用 get_production_bible 查看故事与角色。对准备修改的场景调用 get_scene,记录 script.id。
  3. 编辑。 调用 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 或 base64 data(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 重新上传。
  4. 查看影响。 编辑返回场景 ID、新剧本版本 ID、镜头 ID 和首批镜头的待更新状态。get_scene 重新读取场景,list_shot_staleness 分页读取其余镜头。编辑不启动生成。
  5. 规划。 plan_generation 可使用 mode: "stale" 和 depth(prompts、images、dialogue、video、music),决定更新到哪一级,范围可为整部作品、sceneIds 或 shotIds;也可使用 mode: "missing",提供 stopAt 及可选 startFrames、draftMotion,继续未完成的作品,仅支持整部作品,未提供的开关沿用原设置;失败后可用 retry_failed_work。计划不启动任务,返回各阶段镜头 ID、跳过项、模型、美元估算(组件无价格时为 null)及 blockers。
  6. 请求批准。 向用户展示计划中的具体工作及费用,得到明确同意后再执行。
  7. 执行。 调用 execute_generation,提供 planToken 和 confirm: true。工作或价格变化时会返回 CONFLICT,且 details.code: "PLAN_CHANGED",须重新规划。有进行中的任务、阻断条件或额度不足时也会拒绝,但计划仍可执行。超时后可安全重试,重复调用返回相同 workflowRunIds,不会重复收费。重试时返回 PLAN_CHANGED 或 GENERATION_IN_PROGRESS 说明此前调用已启动任务,应检查 get_sequence_status。
  8. 轮询。 每隔 pollAfterSeconds,用 workflowRunIds 调用 get_operation_status。它仅报告这些任务,包括各镜头失败、跳过和 terminal 标记。partially_failed 列出失败项,可为其规划重试。execute_generation 返回 LAUNCH_INCOMPLETE 时会列出已启动的任务,应轮询它们,不要重新规划相同工作。
  9. 检查并导出。 重新读取镜头。plan_export 预览导出内容,start_export 渲染 MP4,无需计划或确认,因为不消耗额度,且会复用同一剪辑已有的 MP4。轮询 get_export_status。MP4 渲染器仅运行于生产环境,预览、本地开发和通过部署按钮自行安装的环境不会渲染导出。

工作室

工作室在作品之外生成独立图片和视频。每次生成都会消耗额度,因此应先向用户确认。

  1. 选择模型。 list_models 中带 studio 的条目可用于工作室,studio 描述其视频模式、时长、参考素材限制、尾帧和音频能力。
  2. 附加文件(可选)。 调用 upload_media,设置 use: "studio" 且不提供 sequenceId。返回的 upload 可作为参考图片、音频、首尾帧,上传的视频参考片段则使用 { url }。来自 list_generated_assets 且 source: "studio" 的片段须使用 { assetId },即 ID 而非网址。网址始终视为上传。真实人物上传仍须提供上述 portraitAttestation。
  3. 编写提示词(可选)。 draft_studio_prompt 根据参考素材编写提示词,会消耗额度。
  4. 生成。 调用 create_studio_assets,提供 activity(image 或 video)、模型、aspectRatio 和提示词。视频还需要 duration、mode(text、reference 或 frames),一次最多 4 个。
  5. 轮询。 对返回的每个 ID 调用 get_generated_asset,直到 status 为 completed 或 failed。
  6. 优化。 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尚未验证。

“尚未验证”表示尚无人将该客户端连接到实际部署并运行上述流程,验证后会在此记录结果。