# @clipwright/sdk 中文文档

规范地址：https://npmcn.com/package/%40clipwright/sdk/

版本：0\.47\.0
npm 元数据更新时间：2026-11-09T12:30:19.767Z
中文译文更新时间：2026-11-10T02:03:24.536Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40clipwright/sdk
原文对照：https://npmcn.com/package/%40clipwright/sdk/?lang=original
项目主页：https://clipwright.io/?ref=npm
源码仓库：https://github.com/seocombat/clipwright-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：125 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-07-26T18:39:07.768Z
- 最新版本发布：2026-11-09T12:30:19.558Z
- 近 30 天下载量：4938（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

Clipwright UGC 视频 API 的脚本客户端

## 安装

```sh
npm install @clipwright/sdk
```

也可以使用：`pnpm add @clipwright/sdk`、`yarn add @clipwright/sdk`、`bun add @clipwright/sdk`

## README

# @clipwright/ sdk (英语)

类型脚本客户端 [剪贴笔](https://clipwright.io/?ref=npm) UGC 和无相 aPI视频.

```ts
import { ClipwrightClient } from "@clipwright/sdk";

const client = new ClipwrightClient({ apiKey: process.env.CLIPWRIGHT_API_KEY! });

const quote = await client.quoteUgc({ script: "Hello from Clipwright." });
const run = await client.makeUgc({ script: "Hello from Clipwright." });
```

`makeUgc` 制作剪辑 **花钱**· ; `quoteUgc` 没有。 原生渲染开始 从输入和这个装置的 id,所以重审请求返回原运行,而不是支付两次. 过 `idempotencyKey` 明确,当你故意想要新的运行.

食人鱼,每个提示 一个代理 变成视频,它发出的电话 价钱,在 [`@clipwright/mcp-server` 读取](https://www.npmjs.com/package/@clipwright/mcp-server)。 。 。 .

## 工作流程计划

| 方法 | 请求和结果 |
| --- | --- |
| `listWorkflows()` | 7个公用方法以及其中哪一种可以运行. 免费. |
| `getWorkflow(methodId)` | 一种方法的指导,限制和能力快照. 免费. |
| `createWorkflowPlan({ document })` | 存储完整的账户所属文档. 自由; 开始不运行 . |
| `planReferenceRemake(request)` | 服务器汇编一个参考分析( E)`analysis_id`,或 `reference_profile` 准确的剧本变成新的 `reference-remake` 计划;其中的警告,将说出它所不创造的东西。 自由; 开始不运行 . |
| `getWorkflowPlan(planId)` | 阅读目前的修订、准备问题和警告。 免费. |
| `saveWorkflowPlan(planId, { base_version, document })` | 保存已编辑的修订版 。 免费;批准是分开的. |
| `approveWorkflowPlan(planId, { revision, content_digest })` | 明确批准该修订. 自由; 开始不运行 . |
| `quoteWorkflowPlan(planId)` | 用空的 POST 机构引用已核准的修订. 免费. |
| `runWorkflowPlan(planId, request)` | 开始一个付酬的意向 并立即归还其缴获的收据和原生跑道. |

这五种本土方法 `ugc-product-intro`, (中文(简体) ), `ugc-faq-answer`, (中文(简体) ), `faceless-explainer`, (中文(简体) ), `product-image-story` 财务报告和审定财务报表 `reference-remake`,服务器列表的位置 它们是可用的. `website-proof-demo` 财务报告和审定财务报表 `kinetic-launch` 保留 `execution_blocked`;目录可用性不允许账户. 使用文档中方法响应中的方法和能标.

筹备、保存、批准和援引决不相互调用或发射 运行。 在批准前检查选定的修订问题和警告; 在付费发射前显示引用的本地价格。 完整地说 `{ "document": ... }` 内 `create.json`,这些是单独的免费电话:

```ts
import { readFile } from "node:fs/promises";

const plan = await client.createWorkflowPlan(JSON.parse(await readFile("create.json", "utf8")));
console.log(plan);
// After inspecting the plan and choosing this exact revision:
await client.approveWorkflowPlan(plan.plan_id, {
  revision: plan.revision,
  content_digest: plan.content_digest,
});
const workflowQuote = await client.quoteWorkflowPlan(plan.plan_id);
console.log(workflowQuote);
```

在用户接受此引文后,付费的发射机体有五个字段:

```ts
const request = {
  revision: workflowQuote.revision,
  content_digest: workflowQuote.content_digest,
  semantic_input_digest: workflowQuote.semantic_input_digest,
  quote_id: workflowQuote.quote_id,
  idempotency_key: "workflow-example:1",
};
const launched = await client.runWorkflowPlan(workflowQuote.plan_id, request);
const status = await client.getRun(launched.receipt.run_id);
```

每个购买意图选择并保留一个明确的密钥. SDK也一样 键入身体和 `Idempotency-Key`; 它拒绝被更改或拒绝的密钥 HTTP 发送前头编码 。 工作流程发射未使用安装 ID 或自动尝试后缀。 如果获取、 机构读取或响应验证 发送后失败 , `ClipwrightResponseError.mayHaveTakenEffect` 真实: 保存 原始请求和收回购买的钥匙。 新钥匙可以付两次. 没有自动支付重试,引文刷新或源重签重放.

写作拒绝未知字段和文件超过256000 JSON字节. 读取接受 未来字段和enum值并在文档中保存未知字段; 年长的客户端拒绝不支持的保存, 而不是删除意图 。 保留 已接受的原始说明保持不变。 丢失的保存答案后, 重复同样的 明确基准版本并返回已保存的当前版本 ; 一个真正不同的当前文件冲突. 工作流拒绝保留每个结构性问题和警告 `failure` 财务报告和审定财务报表 `report()`类型 `workflow_invalid`, (中文(简体) ), `workflow_conflict` 或者说 `workflow_not_ready` 并且没有自动重试.

`getRun(id, { wait_seconds })` 让服务器按下读取数最多为50 秒至运行成功或失败; `signal` 取消这个. 包括可选 `workflow` 证据:不可改变的收据和 `approved_plan` (购买的文件没有 `brief.reference_profile`,其 间距为 `warnings`· ; `getWorkflowPlan` 返回完整的当前修订版),原生状态/警告, `actual_output`, (中文(简体) ), `asset_placements`, (中文(简体) ), 咨询意见比处理和鉴定问题要重要。 验证本地无相 结算可以证明文物摘要、格式和测量期限,而无需 后可选几何. 安置证明需要一个完整无缺的检查站; 没有证据是 `null` 一个问题,而一个测量的空列表是 `[]`UGC 没有字节/格式证明保留其本地视频 URL 和报告 `actual_output: null`。历史证据不会延长已过期的媒体链接. `creative_acceptance` 遗 物 `not_reviewed`;技术交付是分开的 从一个人的回顾 创造性的结果.

原始图像实例使用稳定的自有上传标识和源摘要 非重叠单词/引号锚。 生成的开口器是说明性的; 原始产品证明属于支持的 IMAGE shots. 保护区必须 幸存的原生作物、 PAN 和标题; 不支持的布局、 源方向 或拒绝安置。 见 [aPI合同](https://clipwright.io/docs)。 。 。 .

## 原生视频方法

`quoteFaceless(input)` 给一个无面相视频定价 `duration_seconds` 第30至第90条 (传送的视频从25秒跑到四分之一, 从来没有超过90,a 解释,只要它的叙述,和 绝不是比引言更昂贵的 `startFaceless(input, { attempt })` 启动并立即返回运行; 民意调查 `getRun` 直到它成功为止 输入名称 `input_mode`数字 : `{ input_mode: "script", script, duration_seconds }` 读你的文字为书面, `{ input_mode: "brief", brief, duration_seconds }` 从 a 写入描述 简介。 除非 `captions: false`两种方法 拒绝错配 `script`编号 :`brief` 在发送任何东西之前. `voice` 选择 叙事声音: 来自 `listVoices({ skill: "make_faceless" })`用英语, 俄语,西班牙语,葡萄牙语,法语或意大利语. 没有它,叙述是 读取方式 `narrator_en_wise_lady`和英语 `format: "explainer"` 视频 最快的声音。 API 拒绝一个未知的名称和一个 `make_ugc` 任何收费前的发言权; `voice_id` 在发送前被拒绝.

`listVoices({ language, gender, age, use_case, model, skill })` 返回声音 `voice`,每个过滤器可选。 这是免费的。 带样本的声音带有 `preview_url` 一小时后结束 传出一个声音 `name` 作为 `voice`· ; `language` 只是一个过滤器,因为任何声音都会说任何支持的语言. 每个声音都说出一个技能 `skill`数字 : `make_ugc` 或者说 `make_faceless`另一种技能在任何指控之前都拒绝。 无 `skill` 列表中包含 `make_ugc` 只发出声音 `make_faceless` 以 `skill: "make_faceless"`。 。 。 .

对于 `make_ugc` 列表中包含预设,语音模型的30个声音 `gemini-3.8-flash-tts` (单位:千美元)`kind: "model_voice"`)和目录. A 类 `model_voice` 声音没有自己的语言: `language: "en"` 财务报告和审定财务报表 `language: "ru"` 发现它, 其样本为英文,除非您要求 `language: "ru"`名称 声音让跑步者说话 `gemini-3.8-flash-tts` 无 `tts_model`该模式 只有自己的声音才拒绝 `captions: true` 在任何指控之前.

无 `voice` 或者说 `voice_id`,声音跟随演员的性别: `sarah` 页:1 一个女人, `george` 为了男人. `actor_id` 将目录带入性别 `image`, (中文(简体) ), 通过 `actor_gender` (单位:千美元)`"female"` 或者说 `"male"`) (中文(简体) ). 一个 `image` 无 `actor_gender` 获得 `george` 和警告. `actor_gender` 旁边 `actor_id` 或无 `image` 在任何指控之前,拒绝。 与 `tts_model: "gemini-3.8-flash-tts"` 默认为 `kore` 一个女人和 `charon` 否则.

`getRunShots(runId)` 读取完整视频的镜头: 在框架、其类型、其覆盖的词、其描述和一个签名链接中 它的源图片或剪辑。 一次没有镜头的跑来显示答案 `planned: false` 与 `editable.state` 财务报告和审定财务报表 `editable.reason`这是答案, 不是一个错误. `getRunEdit(runId)` 阅读该运行的编辑草稿 `saveRunEdit(runId, { base_version, document })` 保护它。 0版本表示 无所存. 草案读取的版本保存名称 拒绝使用 `edit_conflict` 当存储的一个不同时;错误带有 `failure.version`。没有草稿的跑步被拒绝 `run_not_editable`, (中文(简体) ), 携带 `failure.state` 财务报告和审定财务报表 `failure.reason`。 。 。 . `saveRunEdit` 发送一个请求 永不重复:一个被否认的拯救者 `edit_conflict` 何时 再说一遍,读一下草稿 和你面前的文件比较一下 把它当作冲突 三通通相随自在. 一份草稿不收费 使无所事事。 反应是容忍的:一种射击、一种行动或 后一个 API 添加到的普通字符串.

`quoteRevision(runId, request)` 修改无相视频 没什么,和 `startRevision(runId, request, { attempt })` 启动它:一个新的运行, 立刻返回,这让视频 与你改变镜头。 这个 请求是 `{ document }`,或 `{ changes: [{ shot_id, operation }] }`. 交付的修订版收取其 引用总数; 失败者不收费 。 同样的要求和尝试 发送相同的同能键,所以 重新发送返回第一次运行; `attempt: 2` 开始第二个。 在付费编辑时 在服务器上关闭,两通电话都丢出 `ClipwrightApiError` 类型 `editing_closed`,没有重审.

`quoteCandidate(runId, request)` 以白白的价钱买下一个选手, `createCandidate(runId, request)` 让它和 `listCandidates(runId)` 列出 竞选者家族的候选人 候选人是一张图片或一张剪辑 在修改中保留或丢弃 `{ shot_id, operation, take }`一个送货候选人收取一个单位的费用 是否保留或丢弃; 失败者不收费。 独能键来自运行和 请求,因此重传返回第一次运行 `take: 2` 再来一个. 在服务器上被枪决时 三通电话发出 `ClipwrightApiError` 类型 `editing_closed`。 。 。 .

`listUploads()` 列出账户上传的更新版本 先拍一张 每人带一个新签的 `url` 财务报告和审定财务报表 `usable_until`:它的创建加上365天的存储时间,减去2小时的距离. 免费.

要求数 `CLIPWRIGHT_CLIENT_ID`,或可写 `~/.clipwright/` 用于SDK 创建第一个使用。 而不是产生一个丢弃的ID, 因为每个过程的 id 会禁用重复保护而不说.

## 取消请求的截止日期(行为改变)

`fetch` 在节点没有默认超时, 因此在此发布连接前 被接受,然后沉默——一个代理在你和API之间死去——被吊死 永远. `maxWaitMs` 没有保存您: 已检查 _介于_ 身份调查,所以 控制从来没有回到它.

现在有两个期限 中止请求本身, 不只是等待:

-   `maxWaitMs` (单位:千美元) `makeUgc` 电话,默认10分钟 将整个电话, 包括飞行中的请求到期时.
-   `requestTimeoutMs` (每个客户端,默认为30 s)将每个单项请求都限定.

```ts
const client = new ClipwrightClient({
  apiKey: process.env.CLIPWRIGHT_API_KEY!,
  requestTimeoutMs: 60_000,
});
```

**您有什么变化 :** 一个曾经挂掉的电话 现在拒绝。 A 类 `makeUgc` 投票被缩短 仍然会出现同样的超时错误 给跑道起名 晚点再拿吧 `getRun`A级 **开始** 请求在飞行中中止 掷出 `ClipwrightResponseError` 与 `mayHaveTakenEffect: true` 财务报告和审定财务报表 `deliveryConfirmed: false` - 运行可能存在,可能收费,所以检查您 最近运行, 而不是用新的一能键重试 。 关于 自由路径( e)`quoteUgc`, (中文(简体) ), `listVoices`, (中文(简体) ), `getRun`(a) 拒绝 `TimeoutError` `DOMException`;重试是安全的.

提升 `requestTimeoutMs` 如果你坐在一个慢的代理后面, 它必须保持积极, 并且非正值或非无限值被大声拒绝而不是被替换 默认值.

## 更改日志

每一版中的变化和被删除的 [shitchwright.io/changelog (英语)](https://clipwright.io/changelog)。阅读其 **断开 :** 条目 升级前.

## 常见问题

### @clipwright/sdk 是什么？

Clipwright UGC 视频 API 的脚本客户端

### 如何安装 @clipwright/sdk？

在项目目录运行 npm install @clipwright/sdk，或使用 pnpm add / yarn add / bun add。

### @clipwright/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @clipwright/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @clipwright/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @clipwright/sdk 可以商用吗？

@clipwright/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @clipwright/sdk 的下载量有多少？

根据 npm 官方下载统计，@clipwright/sdk 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,938 次，日均约 165 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @clipwright/sdk 还在维护吗？

最新版本 0\.47\.0 发布于 2026/11/09（今天）；至今共发布 54 个版本，其中过去 12 个月发布了 54 个；首次发布于 2026/07/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。