Clipwright

Clipwright API

一个将脚本转换为口型同步 UGC 视频的 HTTP API。它专为智能体驱动而构建：每次调用都是一个 JSON 请求，每次拒绝都会说明下一步该做什么，并且不会在任何地方发布内容。本页面的每个字也对应 https://clipwright.io/docs.md, 处的一个 Markdown 文件，以及 https://clipwright.io/llms.txt. 处为智能体提供的简短契约。

身份验证

每次调用都发送到 https://api.clipwright.io，并在一个请求头中携带密钥：

Authorization: Bearer cw_your_key_here

• 密钥以 cw_ 开头，仅在签发时显示一次。我们只保存摘要，因此丢失的密钥会被替换，而不会被找回。
• 在 https://app.clipwright.io/api-keys. 的仪表盘中签发和撤销密钥。撤销将在下一次请求时生效。
• @clipwright/cli 和 @clipwright/mcp-server 从环境变量 CLIPWRIGHT_API_KEY 读取密钥；@clipwright/sdk 将其作为参数接收。
• 没有密钥或使用已撤销密钥的调用会在任何计费之前以 401 拒绝。

03

费用说明

• 从纯脚本生成 make_ugc：成品视频每秒 30 积分，向上取整到整秒。
• 带片段或插图的 make_ugc：人脸出现在屏幕上的每秒 10 积分，且我们交付的视频至少 400 积分。没有人脸的秒数不收费，未交付任何文件的运行完全不收费，即使供应商已被支付。人脸时间在整个视频中累加并向上取整一次，而不是按片段分别取整。这些字段需要在部署时进行长文本资格认证；在未开启时，它们会在任何计费前按名称被拒绝。
• 以中等质量创建 create_actor：肖像 10 积分，每个额外格式 10 积分。
• 以高质量创建 create_actor：肖像 20 积分，每个额外格式 20 积分。
• 积分以套餐购买：1000 积分 10.00 美元，一次性付款，无订阅。

花钱前先询问：任一技能的报价端点不收费。其答案的价值因技能而异。

• make_ugc：报价是根据脚本文字读取的估算值。实际收费基于成品视频中测量的结果——纯脚本计费器上的时长、人脸计费器上的人脸秒数——因此账单可能高于或低于报价。
• create_actor：报价为你要求的每个格式定价，这是你可能支付的最高金额。你只需为实际发布的肖像和变体付费；未生成的格式会在 warnings[] 中列出且不收费。

失败运行的费用也因技能而异：

• 从纯脚本生成 make_ugc：在交付工作到达供应商后失败的运行会被收费。在此之前失败的不收费，我们主动停止、丢失或拒绝的运行也不收费，即使供应商已被支付。在人脸计费器上，任何失败都不收费。
• create_actor：失败的运行完全不收费，即使供应商已被支付，因为没有演员交付给你。

04

端点

端点	消耗积分	功能
GET /health	否	API 本身的存活状态。无需密钥即可响应。
GET /v1/voices	否	你可以在 voice 或 voice_id 中指定的声音。
GET /v1/account	否	密钥对应账户的余额、欠款和冻结金额。
POST /v1/skills/make_ugc/quote	否	为此输入定价 make_ugc 调用。不收费。
GET /v1/runs/{id}	否	任何技能一次运行的状态、警告和视频 URL。
POST /v1/skills/make_ugc/run	是	启动视频运行并立即返回 run_id。轮询运行以获取结果。
GET /v1/public/skills	否	技能及其输入的目录，无需密钥。
GET /v1/actors	否	账户上保存的演员，包含 make_ugc 接受的 id。
DELETE /v1/actors/{id}	否	忘记已保存的演员。正在运行的演员会被保留。
GET /v1/actors/{id}/defaults	否	读取已保存演员对插图中人物的默认策略。
POST /v1/actors/{id}/defaults	否	设置已保存演员对插图中人物的默认策略。运行可以覆盖它。
POST /v1/skills/create_actor/quote	否	为此输入定价 create_actor 调用。不收费。
POST /v1/skills/create_actor/run	是	启动演员运行并立即返回 run_id。轮询运行以获取结果。
POST /v1/uploads	否	接收图像字节并返回 make_ugc 和 create_actor 接受的 https URL。

任一技能的一次运行都从同一位置 GET /v1/runs/{id} 读取，并经历以下状态：queued、generating、scripting、tts、avatar、compositing、uploading、succeeded、failed。

05

技能及其输入

make_ugc。开始生成口型同步的 UGC 视频。在所选语音模型的文本限制内提供脚本；演员来自 actor_id（来自 list_actors 的已保存演员）或 image，否则使用默认演员。格式和分辨率遵循请求和源，默认为 1080x1920。字幕是选择加入的：先询问用户。渲染器尚未支持的字段在其描述中带有“NOT HONORED YET”注释——请阅读而不是猜测。

在生成前调用 quote_ugc 并显示费用。这不会等待视频：它启动运行并立即返回 run_id。然后你必须使用该 run_id 轮询 get_run，直到状态为 'succeeded'（video_url）或 'failed'。一个失败的运行，如果其付费供应商作业仍由我们持有，可以回到 'queued' 并稍后达到 'succeeded'；无论何时发生，它都会在 warnings[] 中列出。传递 attempt=2,3,… 以故意为相同输入启动新的运行（失败后重试）。

字段	必填	含义
script	可选	演员说的文字；除非 segments 提供口语文本，否则必填。Segments 和文本锚定插图需要在服务器上进行长文本资格认证。脚本限制按语音模型：eleven_v3：5000 字符；eleven_flash_v2_5：10000 字符；eleven_turbo_v2_5：10000 字符。计数包括空格、音频标签和重音标记；表情符号可能计为两个字符。没有字数限制。时长和价格在测量前为估算值。俄语重音：将重读元音写成小写单词中的大写字母（“потОм”、“зАмок”），eleven_v3 会将其作为重音标记 U+0301（“пото́м”）接收；直接输入的重音标记会被保留。单词开头的大写字母保持大写，包含第二个大写字母或内部大写辅音的单词（全大写、“ВУЗы”）保持原样。单词内的单个大写元音始终被读作重音，因此请写“Яндекс Еда”，而不是“ЯндексЕда”。告诉使用俄语写作的用户他们可以用这种方式标记重音。eleven_flash_v2_5 和 eleven_turbo_v2_5 更便宜，但会误读重音标记：大写字母会原样到达。
segments	可选	有序的演员和图像片段；需要在服务器上进行长文本资格认证、captions=false 和 1080p。图像媒体需要显式的 broll_policy=anyone。
inserts	可选	文本锚定的图像插图覆盖完整旁白，每个覆盖从其锚点起的 cover_words 个口语单词；需要在服务器上进行长文本资格认证、captions=false、1080p 和显式的 broll_policy=anyone。
person	可选	NOT HONORED YET：person 尚未被支持：此请求使用默认演员；从 list_actors 中选择 actor_id 或提供 image 以选择不同的面孔
actor_id	可选	来自 list_actors 的已保存 Clipwright 演员 ID。选择 actor_id、image 或 person；不要组合它们。没有 voice 或 voice_id 时，声音跟随演员的性别。不要与 actor_gender 组合。
image	可选	演员照片的公开 https URL（PNG、JPEG 或 WebP，最大 10 MB）。磁盘上的文件先通过 upload_image（POST /v1/uploads）——传递它返回的 URL。我们无法使用的源——私有或回环主机、http、不可达、重定向、超过 10 MB 或不是这些图像类型之一——会在任何计费前被拒绝（unusable_source）。我们不检测面孔的性别：传递 actor_gender 或 voice，否则使用默认男声并带有警告。
actor_gender	可选	image 中面孔的性别：female | male。仅与 image 一起使用：选择该性别的默认声音（female：sarah，male：george）。与 actor_id（其性别已知）且没有 image 时被拒绝。显式的 voice 或 voice_id 优先，响应会警告 actor_gender 未产生任何效果。
name	可选	NOT HONORED YET：name 尚未被支持：它不会到达渲染器
broll_policy	可选	仅存储：B-roll 的已保存策略：anyone 允许包括演员在内的人；no_actor 排除演员；no_people 排除所有人，包括手。分段媒体生成已关闭。此设置仅存储，对仅演员视频没有影响。运行覆盖优先于账户演员默认值；否则为 no_people。
captions	可选	NOT HONORED YET：请求了字幕但在此原型（阶段 B）中未渲染
caption_style	可选	NOT HONORED YET：caption_style 未被支持：字幕在此原型（阶段 B）中未渲染
look	可选	NOT HONORED YET：look 尚未被支持：它不会到达渲染器
aspect_ratio	可选	输出格式：9:16 | 1:1 | 16:9。省略表示 9:16，其他形状的源会被裁剪为 9:16 并带有警告——每当传递 image 时请显式传递它。请求与源之间超过 15% 的不匹配会在任何计费前被拒绝（aspect_conflict）。
resolution	可选	输出分辨率：720p | 1080p | 4k（短边 720 / 1080 / 2160 px）。省略表示 1080p。
voice	可选	来自 list_voices 的声音名称。精选预设：owner_ru_clone | sarah | george | eric | daria_ru_female（owner_ru_clone 是俄语克隆声音）。API 会在任何计费前拒绝 list_voices 未返回的名称。省略表示演员性别的默认声音：actor_id 的性别、带 image 的 actor_gender，或默认演员和没有 actor_gender 的 image 的 george。与 voice_id 互斥。
voice_id	可选	目录外声音的原始供应商声音 ID（16–32 个字母和数字）。惰性检查：未知 ID 会使运行失败，而不是请求失败。与 voice 互斥。
tts_model	可选	语音模型：eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5。省略表示所选预设的模型（list_voices 显示它；每个预设都使用 eleven_v3）或原始 voice_id 的 eleven_v3。eleven_v3 是表现力最强的，也是唯一能读取重音标记的（俄语单词中的大写元音，“потОм”，会变成一个；参见 script）；eleven_flash_v2_5 和 eleven_turbo_v2_5 是俄语以外语言的更便宜替代品。脚本限制按语音模型：eleven_v3：5000 字符；eleven_flash_v2_5：10000 字符；eleven_turbo_v2_5：10000 字符。计数包括空格、音频标签和重音标记；表情符号可能计为两个字符。没有字数限制。时长和价格在测量前为估算值。
disclosure_overlay	可选	接受值：true | false。
background	可选	接受值：white | blur | contain。

create_actor。从描述虚构成年人的文字为此账户创建个人演员：一个 9:16 肖像，恰好一张脸，加上从中编辑的其他请求格式。立即返回 run_id；轮询 get_run 直到 'succeeded'（created_actor.actor_id，然后将其作为 actor_id 传递给 make_ugc）或 'failed'。每个发布的图像按报价显示的价格收费；被拒绝的描述和不可用的肖像不收费。当生成被关闭时，调用会以 actor_generation_disabled 失败。

字段	必填	含义
description	必填	描述虚构成年人的文字：外貌、衣着、场景。提及真实人物或与其相似会被拒绝，且不会产生任何费用（actor_prompt_refused）。
gender	必填	female | male。确定演员的性别以及使用该演员的视频的默认声音。
approximate_age	必填	大致年龄（岁），18 至 90：演员均为成年人。
name	必填	在 list_actors 中显示的名称。
aspect_ratios	可选	要创建的格式：9:16 | 1:1 | 16:9，始终包含 9:16。省略表示全部三种。未通过身份检查的格式不收费，并会在警告中列出。
quality	可选	图像质量：medium | high。省略表示 medium。每张图片的价格取决于此；报价会在任何收费前显示。

输出格式遵循请求和来源。支持的格式为 9:16、1:1、16:9，分辨率为 720p、1080p、4k；未指定时默认为 9:16 的 1080p。

06

开始一次运行

付费调用除密钥外还带有一个标头：Idempotency-Key。POST /v1/skills/make_ugc/run 和 POST /v1/skills/create_actor/run 需要此标头，缺少该标头的调用会在任何收费前以 400 idempotency_key_required 被拒绝。

• 您选择密钥，它是区分重试与第二次订单的唯一依据。任何唯一字符串均可；只要您可能重新发送调用，就请保留它。
• 相同密钥配合相同请求体会返回已开始的运行，且第二次不会收费。这正是普通重试安全的原因。
• 相同密钥配合不同请求体会以 409 idempotency_key_reused 被拒绝。新请求请使用新密钥，而不是在已使用的密钥下修改请求。
• 要对相同输入有意开始新运行（失败后的重试），请发送新密钥。您已付费的运行保持不变。
• @clipwright/sdk 和 @clipwright/mcp-server 会根据客户端和输入为您构建密钥，并将 attempt=2、3…… 转换为新密钥。在纯 HTTP 下，密钥由您自行选择。

07

当调用失败时

每次拒绝都会携带一个包含 code 和 message 的错误对象。如何处理取决于拒绝的类型，而非文本内容：

拒绝类型	HTTP	是否重复相同调用？	处理方法
rate_limited	429	是，等待后	背压，而非错误：响应会在 Retry-After 和请求体中指明等待秒数。
server_error	500、502、503	是，等待后	失败发生在服务器端。不要使用新的幂等密钥启动第二次运行：相同调用即为重试。
insufficient_credits	402	否，会得到相同结果	停止并告知对方余额和价格；两者均在请求体中。重复调用无法改变任何一项。
debt_outstanding	402	否，会得到相同结果	停止。购买积分会在任何金额到达余额前清除欠款，从而解除阻止。
not_admitted	403	否，会得到相同结果	停止。账户没有测试版访问权限；重试或购买都无法改变这一点。请联系运营人员。
client_error	400、401、404、409、413、415	否，会得到相同结果	停止。请求本身被拒绝：阅读消息、修正调用，然后重新发送。

这些是 API 在 error.code 中可能返回的所有代码。您未见过的新代码仍遵循上表中的对应行，因为该行由状态码决定：

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

限制

• 每 60 秒 60 次付费请求和 300 次免费请求。窗口按账户而非密钥计算，因此额外密钥不会带来额外吞吐量。
• 每个账户同时运行 3 个渲染；其余排队，不会被拒绝。
• 速率限制导致的拒绝会在 Retry-After 和请求体中指明等待秒数。以两者中较大者为准。
• 每个片段最多 49 个插入，且演员在其中的出现次数最多 6 次。两者均根据您发送的词索引计算，因此要求更多内容的输入会在任何付费前被拒绝。
• cover_words 表示一个插入覆盖的口语词数，从其锚点的第一个词开始计算。插入在第一个未覆盖的词处结束，因此两个覆盖范围相接的插入是相邻的，它们之间不会留下演员镜头。
• 您未覆盖的词占比决定了片段中显示面孔的部分，且不会随语音速度变化。词长确实会变化：在 560 词的脚本中，要求 19% 的覆盖率在 997 次模拟运行中的 1000 次里得到 16 到 22 的结果，并在五万次运行中保持在 15 到 24 以内。这些数字是在此配置的声音和该长度下测量的；较短的脚本分布更分散，不同的声音会改变这些数值。
• 两个单次词选择会改变价格，而不仅仅是外观。锚定在第 0 词的插入拥有第一个词之前的静默；锚定在第 1 词会留下演员的额外出现，而每次出现都是独立的付费任务。覆盖到最后一个词的插入会将片段带到结尾，并以相同方式移除结尾的出现。
• 报价会将占比报告为 estimatedFaceWordShare。请读取该字段；不要将 estimatedFaceSeconds 除以 estimatedTotalDurationSec。这两个字段回答不同的问题——前者是我们在语速范围慢端持有的储备，后者是片段预期运行时长——它们的比值不是任何内容的占比。

09

此 API 永远不会做的事

• 发布任何内容。我们返回文件和签名链接；其去向由您决定。
• 取消已开始的运行。没有对应端点：一旦供应商已收到工作，在我们这边停止它不会撤销费用。
• 接受这些字段：character、broll_url、webhook_url。它们会在任何收费前按名称被拒绝，而不是被接受后静默忽略。
• 在未说明的情况下更改您要求的格式或分辨率。不匹配要么在警告中修正，要么在付费调用前被拒绝。
• 回拨给您。没有 webhook：请使用 GET /v1/runs/{id} 读取运行状态。
• 再次显示密钥，或从备份中恢复密钥。

10

其他值得了解的内容

• 警告而非沉默。任何我们无法满足的内容都会以 warnings[] 的形式在相同运行中返回，并注明名称。参数不会在没有说明的情况下消失。
• 一个 MCP 服务器。@clipwright/mcp-server 以工具形式暴露相同契约，其 tools/list 是本页面的机器可读形式。