开发者指南

公开 API

通过 API 创建 AI 视频作品,支持单次请求创建、状态查询、HAL 链接、?wait 长轮询及 OpenAPI 3.1 规范

FayBai 提供一组精简的公开 HTTP API,供智能体和脚本无需操作界面即可创建视频作品。API 具备自描述能力:智能体通过两个无需认证的端点即可了解全部接口,无需先阅读本页。

接口发现

  • GET /api/v1 — API 根端点:包含使用说明、创建请求的 JSON Schema,以及可用操作的 HAL _links 目录。
  • GET /api/v1/openapi.json — 完整的 OpenAPI 3.1 规范,与 API 校验所用的 Schema 同源生成。

这两个端点无需认证,工具可以在配置密钥前发现 API。此站点的 /llms.txt 列出了 API 和文档入口。

身份认证

除接口发现和设备登录的两个端点外,调用方需要发送 osk_ 密钥或 OAuth 访问令牌。获取密钥有两种方式:

  • 设备码登录(供智能体和 CLI 使用,无需复制粘贴):POST /api/v1/device/code 返回 device_code、简短的 user_code 和 verification_url。向用户展示验证码和网址(或打开 verification_url_complete),随后轮询 GET /api/v1/device/token?device_code=…&wait=60s,直到返回 200 { api_key, organization }。用户尚未决定时返回 428 authorization_pending(继续轮询;?wait 在服务端等待);未使用 ?wait 且轮询间隔短于 interval 时返回 429 slow_down;拒绝授权返回 403 access_denied;过期返回 410 expired_token(验证码有效期为 10 分钟,过期后重新开始)。两个端点均按 IP 限流。
  • 手动创建:在控制台的设置 → 开发者中创建密钥。

两种方式获得的都是普通密钥,用户可在设置 → 开发者中撤销。可通过以下任一请求头发送:

Authorization: Bearer <key>
x-api-key: <key>

密钥限定在组织范围内,只能访问所属组织的作品,限流为每秒 10 个请求;超限返回 429,并带有 Retry-After 请求头。

OAuth 2.1(使用 FayBai 登录)

能够执行授权码 + PKCE 流程的应用无需使用密钥,例如 Claude、Cursor 等托管 MCP 客户端、提供“连接 FayBai”功能的第三方应用,以及能够通过浏览器重定向的其他应用。FayBai 是 OAuth 2.1 授权服务器:

  • 发现:GET /.well-known/oauth-authorization-server(RFC 8414;也支持 /.well-known/openid-configuration)。API 的受保护资源文档位于 GET /.well-known/oauth-protected-resource/api/v1(RFC 9728),MCP 端点的对应文档位于 /.well-known/oauth-protected-resource/mcp。
  • 动态注册(RFC 7591):向 POST /api/auth/oauth2/register 提交 redirect_uris 和 client_name,无需在控制台操作。该端点按 IP 限流。超过一周未使用的 DCR 客户端(无授权同意记录,也无刷新令牌)会在后续注册请求时被删除。
  • 授权:引导用户访问 /api/auth/oauth2/authorize,携带 PKCE(S256)、所需权限范围和 resource=<origin>/api/v1(RFC 8707),使令牌签发给此 API。用户按需登录后,在授权同意页面批准;页面会展示应用名称和承担费用的组织。
  • 令牌:在 /api/auth/oauth2/token 兑换授权码。访问令牌为有效期一小时的 JWT;请求 offline_access 可获得刷新令牌。

像发送密钥一样发送访问令牌:

Authorization: Bearer <access_token>

与密钥不同,令牌受权限范围限制:

权限范围授予的权限
sequences:read所有 GET 请求
sequences:write编辑和导出(POST …/exports、风格修改)
generate所有消耗额度的操作(POST /sequences、增强)
credits:read查询额度余额(预留给 MCP 端点)

令牌缺少路由所需权限时返回 403,并通过 WWW-Authenticate: Bearer error="insufficient_scope", scope="…" 说明重新授权所需范围;无效或过期令牌返回 401 和 error="invalid_token"。两者均携带指向 RFC 9728 文档的 resource_metadata="…",MCP 客户端据此进入授权流程。

用户可以在设置 → 开发者 → 已授权应用中查看和撤销授权。撤销后刷新令牌立即失效;已签发的访问令牌在一小时内到期。

MCP(POST /mcp)

Claude、Cursor 等托管 MCP 客户端,以及支持 Streamable HTTP 的 CLI,使用 POST /mcp。每个请求相互独立(MCP 2026-07-28;无会话存储,无 SSE 传输)。

  • OAuth:/mcp 的 401 响应携带 WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp",因此 claude mcp add --transport http openstory https://<host>/mcp 可以找到授权服务器。令牌的受众必须绑定到 <origin>/mcp(授权时使用 resource=<origin>/mcp)。
  • API 密钥:使用 Authorization: Bearer osk_… 可在不经 OAuth 的情况下列出工具(Claude Code 使用 --header)。密钥限流为每秒 10 个请求;OAuth JWT 按用户限流。
  • 来源:浏览器客户端必须发送允许的 Origin(应用域名、已知托管 MCP 客户端或回环地址)。允许不带 Origin 的请求(curl、CLI);不允许的 Origin 返回 403。

首个工具为 whoami(返回当前调用用户和 organization 组织信息)。客户端可先用它确认连接,再调用创作工具。

创建作品

POST /api/v1/sequences 将剧本转换为视频作品。生成过程在后台异步执行:调用会立即返回 202,其中包含新建作品的 ID 和用于轮询状态的网址。

将 FAYBAI_ORIGIN 设为签发此 API 密钥的 FayBai 站点源地址。填写协议、主机和可选端口,去掉末尾的斜杠。将 FAYBAI_API_KEY 设为该站点签发的密钥。

curl -X POST "${FAYBAI_ORIGIN:?Set FAYBAI_ORIGIN to your FayBai site origin}/api/v1/sequences" \
  -H "Authorization: Bearer ${FAYBAI_API_KEY:?Set FAYBAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "A lighthouse keeper befriends a stranded whale.",
    "title": "Sea Tale",
    "style": "Cinematic Noir",
    "targetSeconds": 30,
    "motion": true,
    "music": true,
    "characters": ["Old Tom the keeper", { "name": "The whale", "isHuman": false }],
    "locations": ["Stormy lighthouse"]
  }'

请求体便于使用:可以通过 ID 或名称引用风格、角色和地点,也可以传入内联对象创建新资源。未指定 style(或设为 "auto")时使用“匹配剧本”,即从剧本派生风格。enhance(auto | always | off)控制剧本扩写;motion 和 music 控制视频与配乐开关,stopAt(script … music)则指定生成终点并覆盖这两个开关。三者均未指定时,与应用中新建作品一样,在 dialogue 阶段停止。startFrames(默认 false)为每个镜头渲染静帧并据此生成动画;关闭时直接根据参考图生成视频,不生成静帧。draftMotion(默认 true)在 Seedance 2.5 上先生成低分辨率预览版,满意后再生成高质量版本;其他视频模型直接生成成片。未指定 videoModels 时,组织能够使用 Seedance 2.5 就使用它,否则使用 Seedance 2.0。有台词的角色会在部署环境支持音色设计时获得生成的音色。不存在 voices 字段。完整请求结构请查看 GET /api/v1 或 OpenAPI 规范。

响应(202):

{
  "sequences": [
    {
      "id": "seq_…",
      "status": "draft",
      "workflowRunId": "…",
      "statusUrl": "/api/v1/sequences/seq_…",
      "_links": {
        "self": { "href": "…", "method": "GET" },
        "poll": { "href": "…", "method": "GET", "templated": true }
      }
    }
  ],
  "enhancedScript": "…",
  "_links": { "self": { "…": "…" } }
}

轮询状态

GET /api/v1/sequences/{id} 返回从数据库派生的状态文档,包括整体状态、生成所用的 style 和 models、画幅比例、各帧的图片/视频状态与网址、音乐、海报,以及完成/失败数量。由于信息来自数据库,即使稍后重新连接也能获取准确状态。

style 为 { id, name }(只有风格记录无法解析的少见情况下,名称才为 null),models 为 { analysis, image, video, music },值均为原始模型 ID。控制台筛选和搜索作品时使用的也是这些值。

最终状态为 completed 时,仍可能存在 counts.videosFailed > 0;单帧失败不会使整次运行失败,因此需要检查数量来确认完整流程是否成功。

列出你的作品

GET /api/v1/sequences 按时间从新到旧返回组织的作品。每项是状态文档的简要信息,包含 status、aspectRatio、style、models、poster、music 和完成/失败 counts,不包含逐帧数组;可通过 self 链接访问完整状态文档。

curl "${FAYBAI_ORIGIN:?Set FAYBAI_ORIGIN to your FayBai site origin}/api/v1/sequences?limit=20" \
  -H "x-api-key: ${FAYBAI_API_KEY:?Set FAYBAI_API_KEY}"

使用 ?limit(默认 20,最多 100)和响应 _links.next 返回的不透明 ?cursor 分页。访问该链接获取下一页;没有该链接表示已到末尾。已归档作品不在列表中。

使用 ?wait 长轮询

智能体通常没有休眠工具,因此所有可轮询端点均支持 ?wait=<duration>(60s、30、2m、1500ms;上限为 90 秒)。服务端保持请求,作品发生变化或进入最终状态时立即返回:

curl "${FAYBAI_ORIGIN:?Set FAYBAI_ORIGIN to your FayBai site origin}/api/v1/sequences/seq_…?wait=60s" \
  -H "x-api-key: ${FAYBAI_API_KEY:?Set FAYBAI_API_KEY}"

响应携带 X-Wait-Changed(是否有进展)和 X-Wait-Done(是否结束)响应头。对于 POST,?wait 还会嵌入每个新作品的首个进度快照,并为每部作品提供 waitChanged/waitDone 标志。格式错误的 wait 会返回 400,不会静默降为非阻塞请求。

约定

  • HAL 链接。每个响应都有 _links 映射,列出该资源可用的操作,并注明各自的 method。请沿链接操作。
  • 错误始终为 JSON:{ "error": { "code", "message", "details"? } },并带有对应 HTTP 状态码,不会返回 HTML 页面或重定向。