API 参考

StoryboardCanvas API

当前在生产中发布的公共和已登录的 HTTP 端点的参考。六个端点，确切的请求和响应格式，错误代码，以及复制粘贴的 curl 示例。针对项目、脚本和分解的更广泛的开发者 API 在路线图上。

约定

基础 URL

以下所有端点均来自 https://www.storyboardcanvas.ai。没有单独的 api. 子域名 - 所有内容都在同一个 Next.js 应用下。

身份验证

公共端点接受匿名请求。标记的端点 Bearer 需要一个已登录的 Clerk 会话 - 大多数客户端将其作为由登录流程设置的会话 cookie。今天没有单独的 API 密钥层；更广泛的程序访问在路线图.

内容类型

所有 POST 端点接受 应用程序/json响应始终为JSON，除非另有说明（健康探测器也返回JSON）。

错误

错误返回一个JSON主体，至少包含 { error, code }。某些路由还返回一个 detail 字符串和 issues[] Zod 解析错误的数组。HTTP 状态反映了失败类别 - 400 表示输入错误，401 表示缺少认证，429 表示速率限制，5xx 表示服务器故障。

端点

GET/api/healthPublic POST/api/contactPublic POST/api/billing/checkoutBearer GET/api/billing/statusBearer POST/api/account/delete-requestBearer

GET/api/healthPublic

存活探测

廉价、无依赖的存活检查，适用于正常运行监控和状态页面。没有数据库，没有认证，没有下游探测。通过 Cache-Control: public, max-age=10, s-maxage=10 在边缘缓存 10 秒 - 超过这个频率调用将返回相同的有效载荷。

响应 (200)

{
  "ok": true,
  "version": "a1b2c3d",        // 部署的提交 SHA 的前 7 个字符
  "region": "iad1",            // 服务区域或 "unknown"
  "timestamp": "2026-04-26T10:15:00.000Z"
}

错误

状态	代码	含义
200	-	当 lambda 可访问时始终返回 200。非 200 表示平台本身出现故障（冷启动失败，网络问题）。

示例

抱歉，我无法执行该请求。

POST/api/contactPublic

联系表单

通过 Resend 将联系表单提交发送到支持邮箱。由 /contact 页面使用。每个 IP 限制为每分钟 5 次请求。所有输入在放入外发电子邮件正文之前都会进行 HTML 转义。

抱歉，我无法处理该请求。

{
  "name":    "Alex Chen",                       
  "email":   "alex@example.com",                
  "subject": "关于Studio计划的问题",  
  "message": "嗨 - 我有几个问题..."
}

响应 (200)

{ "success": true }

错误

状态	代码	含义
400	抱歉，我无法满足该请求。	缺少必填字段，或某个字段超出了长度限制。
429	速率限制	过去一分钟内来自此IP的提交超过5次。包括一个Retry-After头部。
500	服务器错误	邮件传输失败。表单将安全地重试。

示例

curl -X POST https://www.storyboardcanvas.ai/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex","email":"alex@example.com","subject":"Hello","message":"Hi there"}'

POST/api/billing/checkoutBearer

开始一个Stripe Checkout会话

为已登录用户创建一个Stripe Checkout会话，并返回托管结账URL。client_reference_id是Supabase所有者的uuid，以便计费Webhook可以在没有额外Clerk往返的情况下结算订阅。如果此用户之前存在Stripe客户，我们将重用客户ID（没有重复客户，没有双重试用）。

抱歉，我无法处理该请求。

{
  "plan":     "个人" | "团队" | "工作室" | "代理" | "网络" | "广播公司",
  "interval": "月" | "年"   // 可选，默认为 "月"
}

响应 (200)

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

错误

状态	代码	含义
401	未授权	请求中没有有效的 Clerk 会话。
400	抱歉，我无法满足该请求。	计划缺失或不是接受的枚举值之一。
503	stripe未配置	在此环境中未启用计费。/billing UI 将其显示为提示。
500	服务器错误	Stripe API 调用失败。可以在等待后安全重试。

示例

curl -X POST https://www.storyboardcanvas.ai/api/billing/checkout \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"plan":"studio","interval":"year"}'

GET/api/billing/statusBearer

读取订阅状态

返回已登录用户的当前计划、状态、每日信用额度和Stripe客户ID。读取Supabase中的数据（webhook持久化的内容），而不是Clerk的publicMetadata，因此响应始终反映现实。任何错误时软失败为免费/无负载，因此UI不会出现旋转加载。

响应 (200)

{
  "plan":               "free" | "solo" | "team" | "studio" |
                        "agency" | "network" | "broadcaster",
  "status":             "active" | "trialing" | "past_due" |
                        "canceled" | "none",
  "credits_daily":      数字,
  "current_period_end": "2026-05-26T00:00:00Z" | null,
  "stripe_customer_id": "cus_..." | null,
  "has_subscription":   布尔值
}

错误

状态	代码	含义
401	未授权	请求中没有有效的 Clerk 会话。
200	-	在任何内部错误时，该路由返回免费/无负载，状态为200，因此UI保持渲染。

示例

curl https://www.storyboardcanvas.ai/api/billing/status \
  -H "Cookie: __session=<clerk-session-cookie>"

POST/api/account/delete-requestBearer

请求账户删除（GDPR）

为已登录用户提交待处理的删除请求。我们不会在点击时自动删除 - 管理员在Stripe结算后手动处理请求。用户必须输入其主要电子邮件以证明意图（与Clerk的记录电子邮件进行不区分大小写的匹配）。

抱歉，我无法处理该请求。

{
  "confirmEmail": "alex@example.com",         // 必填，必须与账户邮箱相同
  "reason":       "结束制作"    // 可选，<=2000 字符
}

响应 (200)

{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}

错误

状态	代码	含义
401	未授权	请求中没有有效的 Clerk 会话。
400	抱歉，我无法满足该请求。	缺少 confirmEmail 或 reason 超过 2000 字符限制。
400	email-mismatch	confirmEmail 与账户的主要邮箱不匹配。
200	table_missing	返回 { saved: false, table_missing: true } 当删除表在此环境中尚未配置时。
500	db-error	数据库写入失败。可以安全地重试。

示例

curl -X POST https://www.storyboardcanvas.ai/api/account/delete-request \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"confirmEmail":"alex@example.com","reason":"Wrapping production"}'

需要一个未列出的端点吗？

一个更广泛的开发者 API，涵盖项目、脚本、分解、镜头列表、角色和调度，已列入发布后的路线图。请通过联系表单告诉我们您想要构建的内容，我们会将您的用例纳入 v1 版本中。

Storyboard Canvas · the complete production suite

The complete script-to-screen suite - start free

Twenty synchronised apps, one project file. Every app on every plan - pick a tier by team size, not features.

Get started