API 参考

每个端点及其请求和响应的形态。所有路由都相对于 https://sketchie.ai/api。

约定

每个 /v1/* 端点都需要 Authorization: Bearer sk_... 请求头。错误以带有 error 标志和 message 的 JSON 形式返回：

错误响应

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

生成端点的速率限制为每分钟 20 个请求。所有其他端点共享每分钟 200 的限制。

创建讲解视频

POST https://sketchie.ai/api/v1/explainer

启动一次生成并返回 202 Accepted 及一条排队记录。轮询获取讲解视频直到它为 ready。

请求体

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

字段	类型	备注
`input`	string	要讲解的内容。一个简短的提示词或完整的文档文本。除非存在 `source` 或 `sceneGraph`，否则必填。别名：`prompt`。
`length`	string or number	目标时长，格式为 `"M:SS"`（`"0:30"`、`"1:00"`）或秒。30 的正整数倍，最多 360。省略以自动确定时长。别名：`lengthSeconds`（数字）。
`voice`	string	可选。语音引用。默认为标准旁白（Nora）。参见语音。
`language`	string	可选。受支持的语言代码（默认 `en`）。参见语言。
`aspect`	string	可选。`16:9`（默认）、`9:16` 或 `1:1`。
`source`	string	可选。要转成讲解视频的文档、文章或文字记录。存在时，`input` 变为可选的指导。
`preset`	string	可选的绘制风格：`marker`（默认）、`chalkboard`、`pencil`、`blueprint`、`crayon`、`clean`。
`fillMode`	string	可选的揭示填充技法：`A`、`B`、`C`（默认）或 `D`。
`sceneGraph`	object	可选。一个预先编写的 scene graph。工作进程会跳过图生成并直接渲染它，但此端点仍会创建一个新的讲解视频，并消耗调用方正常的免费额度或付费套餐配额。要编辑现有讲解视频，请使用编辑讲解视频。

返回讲解视频记录：id、status、prompt、lengthSeconds、voice、language、aspect、videoUrl（就绪前为 null）以及 sceneGraph（生成前为 null）。对于没有 source 的空 input、格式错误的 length，或无效的 aspect、preset、fillMode 或 language，会返回 400。

获取讲解视频

GET https://sketchie.ai/api/v1/explainer/:id

返回完整记录：当前 status、就绪后的 videoUrl、可编辑的 sceneGraph、版本历史（versions）以及头版本的场景 chunks。不存在的 id 返回 404。

列出讲解视频

GET https://sketchie.ai/api/v1/explainer?limit=50

按最新优先列出调用密钥的讲解视频。限定于密钥所有者。limit 限定在 1 到 100（默认 50）。返回轻量摘要（无 scene graph 或版本）。完整记录请使用获取讲解视频。

编辑讲解视频

POST https://sketchie.ai/api/v1/explainer/:id/edit

可编辑性的楔子。把平实语言的指令变成有针对性的重新渲染。只有受影响的场景会重新渲染，产生一个新版本。返回 202 及排队的版本。轮询获取讲解视频直到头版本为 ready。这会追加到现有视频，因此不会消耗另一个免费视频创建名额。每个视频的首次重新渲染是免费的。之后的重新渲染使用付费套餐分钟，免费账户会被要求开始一个套餐。讲解视频必须已经是 ready（否则 409）。

请求体

{ "instruction": "Make the title scene shorter and warmer" }

还原到某个版本

POST https://sketchie.ai/api/v1/explainer/:id/revert

把头重新指向较早的就绪版本，并把其图和视频镜像到记录上。目标必须是带有视频的 ready 版本（否则 409）。

请求体

{ "versionId": "..." }

实时状态流

GET https://sketchie.ai/api/v1/explainer/events

一个 Server-Sent Events 流（text/event-stream）。打开一个连接，你任何讲解视频上的每次状态转换都会作为 event: status 帧到达，因此你可以在工作进程完成的那一刻更新"视频就绪"状态，而不必轮询。该流限定于你密钥的所有者。

语音

GET https://sketchie.ai/api/v1/voices

旁白语音目录。可选的 ?language=<code> 会筛选到以该语言为母语的语音。返回 voices（每个都有一个友好的 name、作为 voice 传入的 id、language、isDefault 以及可播放的 preview_url）以及全局 default。参见语音。

语言

GET https://sketchie.ai/api/v1/languages

受支持的旁白语言，格式为 { code, label, native }。每个 code 在创建时都是有效的 language。参见语言。

账户状态

GET https://sketchie.ai/api/v1/account/state

返回 videosGenerated（终身）、账户 image 和 isAdmin。需要认证。

账单状态

GET https://sketchie.ai/api/v1/billing/status

需要认证，对免费和付费账户都返回 200。免费账户返回 plan: "free" 以及 videoAllowance、videosUsed 和 videosRemaining。付费账户还返回 planLabel、billingInterval、trialStatus、quotaMinutes、minutesUsedThisPeriod、minutesRemaining 和 bonusMinutes。

运行时配置与健康

GET https://sketchie.ai/api/config

公开。返回 { "authEnforced": true }。存活检查位于 GET /health。