# @blitzreels/sdk 中文文档

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

版本：0\.2\.25
npm 元数据更新时间：2026-10-29T23:55:03.727Z
中文译文更新时间：2026-11-08T07:01:33.225Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：824 kB，239 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-05-06T07:42:54.154Z
- 最新版本发布：2026-10-29T23:55:03.545Z
- 近 30 天下载量：57182（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

TypeScript SDK供AI代理和开发者在BlitzReels内部编辑视频.

## 安装

```sh
npm install @blitzreels/sdk
```

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

## README

# @ blitzreels/ sdk (英语)

为 BlitzReels 公共 API 输入了 TypeScript 客户端 .

使用 `client.clipBatches.getForAsset({ assetId })` 恢复最新趋势 包含尚未创建剪辑的批次. 反应是 `{ batch: null }` 当工作空间没有批次的该资产.

官方网站(简体中文) [https://blitzreels.com/ 互联网档案馆的存檔,存档日期2013-12-21](https://blitzreels.com/)

SDK是 BlitzReels CLI 和外部使用的共享 API 层 类型脚本集成. 它有意不进口Next.js/仅进口服务器.

## 安装

```bash
npm install @blitzreels/sdk
```

## 使用量

```ts
import { BlitzReelsClient } from "@blitzreels/sdk";

const client = new BlitzReelsClient({
  apiKey: process.env.BLITZREELS_API_KEY ?? "",
  baseUrl: "https://blitzreels.com/api/v1",
});

const auth = await client.auth.validate();
const projects = await client.projects.list({
  limit: 20,
  cursor: undefined,
  offset: undefined,
  search: undefined,
  status: "active",
});
```

API 密钥授权一个工作空间 。 使用已安装的 TypeScript 声明进行精确的方法输入 . 通过 [能力](https://blitzreels.com/api/capabilities.json), (中文(简体) ), 读取 [生成的 API 合同](https://blitzreels.com/api/docs.md)。 。 。 . SDK拥有运输;消费者加入应用同意/认证和UI映射.

上传的视频出版接受工作空间媒体资产,而不存在 Blitz Reels项目. MP4, MOV, 和 WebM 输入被对照每个选中 在预定目标之前提供. 媒体资产必须具备期限和尺寸. 待决元数据返回可重试 `conflict` 与 `error_details.reason: media_asset_processing` 财务报告和审定财务报表 `error_details.media_asset_id`在复制媒体或创建出版来源/文章之前. 票价 `client.media.get({ assetId })`,然后用同样的ID重试调度. 没有元数据处理失败或完成的资产返回不可重试 `validation_error`。 。 。 .

TikTok直接员额需要明确 `privacyLevel`; TikTok 草稿没有. 使用 `containsSyntheticMedia` 每个请求一次, 如此 BlitzReels 映射声明 到每个供应商的原地.

API 请求失败, 可重试 `timeout` 默认在30秒后出错 . 设定 `requestTimeoutMs` 在客户端配置中,当集成需要不同的截止日期时.

## 排定的网络员额

此来源增加了 X 文本帖和 LinkedIn/ Threads 文本或导出媒体帖. 可用性取决于部署的服务器配置和连接账户的权限. X在验证免费API访问之前仍然被禁用;这些方法无法允许付费API通话. 链接 在目标个人简介中,不是组织网页.

```ts
const receipt = await client.publishing.scheduleNetworkPost({
  platform: "linkedin",
  connectionId,
  projectId: null,
  exportId: null,
  caption: "Testing scheduled publishing from BlitzReels.",
  scheduledFor,
  timezone: "Europe/Paris",
  idempotencyKey,
});

const status = await client.publishing.getPost({ postId: receipt.post_id });
```

都通过 `projectId` 财务报告和审定财务报表 `exportId` 用于完成媒体导出,或两者兼而有之 `null` 用于文本. 使用 `listConnections()` 在预定日期之前解决预定目的地. 超时后再取出相同的一能键并请求机体来取回原收发. 预定的收据是排队验收;检查每个目标的状况和提供者的ID以便公布. 不确定的出版物需要在提交新职位之前先检查提供者.

## 本地 API

```ts
const client = new BlitzReelsClient({
  apiKey: process.env.BLITZREELS_API_KEY ?? "",
  baseUrl: "http://localhost:3100/api/v1",
});
```

本地/ 开发 API 密钥使用 `br_test_...`; 生产密钥使用 `br_live_...`。 。 。 .

## 来源、释放和许可证

Npm包可公开安装,但其犬形来源为私有和专有. 发布的行为取决于已安装的软件包版本. 大型上传使用多段传输; `BLITZREELS_REQUEST_TIMEOUT_MS` 控制 SDK API 请求 .

行政事业单位回收和其他内部经营资源不出口或者列入公共文物.

见 `LICENSE` 包条款.

### 生成分辨率

`generation.images` 财务报告和审定财务报表 `generation.videos` 接受 `resolution` 并转发给REST. 放弃或通过无效 使用模型默认. `generation.options({ kind: "image" })` 财务报告和审定财务报表 `generation.options({ kind: "video" })` 返回每个模型 `parameters.resolution` (单位:千美元)`supported`, (中文(简体) ), `values`, (中文(简体) ), `default`, (中文(简体) ), `reason`) (中文(简体) ). 不支持的显式设置失败验证; 它们永远不会被默默地丢弃 . 图像选项包括 `credit_cost_by_resolution`没有单独的质量等级, 报告 `parameters.quality`图像任务结果包括所要求的分辨率, 可计量的宽度/高,以及使用的入计量.

生成投入与REST和MCP共享模型认知验证. `generation.videos()` 接受 `endFrameAssetId`, (中文(简体) ), `referenceVideoAssetIds`,以及 `referenceAudioAssetIds`。 。 。 . 不需要只参考种子模型 `sourceAssetId`;提供源成为第一个参考. `endFrameAssetId` 需要源首帧,不能与引用数组相混合. 发现每个模型的计数、持续时间限制、音频行为、种子/负瞬间支持以及提供者 与 `generation.options({ kind: "video" })`。不支持的明确设置被拒绝. `generateAudio: null` (或省略)使用模型行为. `enhancePrompt: true` 使用共享的 BlitzReels 大脑 带有模型语法,边框参考预览,帧角色,和音频意图. `catalog.voices()` 读取内置 `/voices` 目录和返回 `{ voices: [...] }`。 。 。 . `voices.list/get/clone/archive` 在下面管理被克隆的声音 `/workspace/voices`; 列表返回 `{ items: [...] }`。 。 。 .

语音ID被验证对 `generation.options({ kind: "voiceover" }).voices`,包括提供者和预览 URL.

为源视频编辑, `generation.planBrief({ prompt, model, durationSeconds, aspectRatio })` 返回一个 `execution` 合同。 过 `model: null` 用于基于意图的选择. `generation.videos` 接受 `transformation` 字符对源角色绑定 `keepOriginalAudio`。 。 。 . 原声道开关与 `generateAudio`;来源决定了编辑持续时间. 见 [源视频编辑](https://npmcn.com/package/docs/video-transformation-api.md) 用于工作流程和当前核查边界.

### 无脸投入和迅速改进

`generation.faceless` 接受 `inputMode: "topic" | "script"` 财务报告和审定财务报表 `improvePrompt: boolean`。 。 。 . 在制定可审查的生产计划之前,将题目写入叙述中. 对于编剧剧本, `improvePrompt: false` 保留准确的描述. Oconduct 值保留脚本输入,但对现有客户端的改进已禁用 .

## 变异恢复

`client.contentReview.submit({ projectId, expectedProjectRevision, caption, reason, language, idempotencyKey })` 在工作空间审查队列中添加一个非空保存的视频或旋转木马. 它回来了 `draftId`,提交 项目修订、初步审查版本和 `mutationReceipt`没有进行渲染、收费或公布. 重复相同的输入和密钥,以在网络,MCP和SDK客户端中为同一个工作空间用户回收收据. 修改了投入,进行了僵化的修订并重复了项目提交;现有审查决定仍然得到保存.

`client.mutations.lookup({ operation, idempotencyKey })` 读取当前 API 密钥和工作空间的收据. 使用 `project.create` 或者说 `generation.image.create` 在提交前保存密钥. 结果是 `{ receipt: null }` 当读取时找不到记录时; 尚未解决的请求仍然可以接受. 已完成的收据显示资源标识,不显示提示,租赁令牌或内部出错. 其地位是指提交情况,而不是背景工作完成情况.

`media.finalizeUpload` 接受可选选项 `idempotencyKey`。 。 。 . 重用相同的定稿输入来回收丢失的响应,而不读取已删除的重复对象 . 失败的尝试可以重试同样的密钥;进行中的尝试只能在5分后恢复.

## 统一出版

`client.publishing.createPost({ post, idempotencyKey })` 使用共享 `PublishingPostInput` 合同. 打电话 `validatePost(post)` 现场飞行前和 `capabilities()` 用于支持的格式和平台限制. 这个 [CLI 生命周期指南](https://npmcn.com/package/%40blitzreels/cli/README.md#unified-post-lifecycle) 包含相同的 JSON 输入和默认值.

```ts
const post = {
  source: { type: "media_asset" as const, media_asset_id: assetId },
  caption: "My caption",
  mode: "now" as const,
  targets: [
    { platform: "instagram" as const, connection_id: instagramId, share_to_story: true },
    { platform: "facebook" as const, connection_id: facebookId, video_format: "reel" as const },
  ],
};
const validation = await client.publishing.validatePost(post);
if (!validation.valid) throw new Error(JSON.stringify(validation.issues));
const receipt = await client.publishing.createPost({ post, idempotencyKey: "launch-post-1" });
const current = await client.publishing.getPost({ postId: receipt.post_id });
```

成功的创建确认接受;读取目标收据确认出版. `getPublishingPostSchema()` 财务报告和审定财务报表 `publishingPostInputSchema` 曝光合同没有认证. `listPosts({ status, limit, offset })` 绑定; 默认值为 20和 0, 最大页面大小为 100. `cancelTarget`, (中文(简体) ), `retryTarget` 财务报告和审定财务报表 `rescheduleTarget` 需求 `targetId`, (中文(简体) ), `expectedRevision` 财务报告和审定财务报表 `idempotencyKey`。 。 。 . 额外调整时间表 `scheduledFor`。在丢失的响应后重新使用相同输入的密钥.

创建草稿与 `post.mode: draft` 没有时间表. `updateDraft({ postId, expectedRevision, post, idempotencyKey })` 替换未排定的草稿. `scheduleDraft({ postId, expectedRevision, mode: "now", idempotencyKey })` 验证并推广同样的身份证. 以后出版,使用 `mode: "schedule"` 与 `scheduledFor`。 。 。 . `deleteDraft({ postId, expectedRevision, idempotencyKey })` 软删除只包含不定期的草稿.

REST 用途 `POST /publishing/posts`, (中文(简体) ), `POST /publishing/posts/validate`, (中文(简体) ), `GET /publishing/posts`, (中文(简体) ), `GET /publishing/posts/{postId}`,以及 `GET /publishing/capabilities`。 。 。 . 编辑草稿使用 `PATCH /publishing/posts/{postId}/draft`; 推广用途 `POST /publishing/posts/{postId}/schedule`。 。 。 . 删除用途草案 `DELETE /publishing/posts/{postId}/draft?expected_revision=...`。 。 。 . 目标行动使用情况 `POST /publishing/targets/{targetId}/{cancel|retry|reschedule}`。 。 。 . 所有新出版的书写需要 `Idempotency-Key`。使用REST的修订字段 `expected_revision`。 。 。 .

Meta原生Reel-to-Story共享在收件中仍然是明确的人工跟踪. `share_to_story` 从不默默地上传单独的"故事". 独立的故事,重复的队列,第一次评论, 提供音频/协作器和发布网络呼声者不属于这一发布的一部分. 部署匹配的 API 和 `0194_publishing_drafts` 在使用这些新软件包方法之前迁移.

## 网络研究(当地来源)

`client.knowledge.research` 曝光情况 `list`, (中文(简体) ), `quote`, (中文(简体) ), `start`, (中文(简体) ), `get`, (中文(简体) ), `cancel` 财务报告和审定财务报表 `resume`。 。 。 . 使用 `list({ status: "all", limit: 10, offset: 0 })` 以找到保存的工作空间工作,包括另一个代理开始的工作. 页数上限为20个摘要; `status: "active"` 选择已排队/正在运行的任务. 服务器的推出需要配置研究定价和经过验证的运行时间. 明确传出 `prompt`, (中文(简体) ), `productUrl` (或无), `seriesId` (或无), `language`, (中文(简体) ), `maxSources` 财务报告和审定财务报表 `maxCredits` 改为 `quote`。 。 。 . 从不变的请求开始加上返回的请求 `quoteId` 和召唤者 `idempotencyKey`。 。 。 . 中断后重复启动输入/ 键以恢复已接受的工作 . 读取 `{ jobId }` 检查信用、诊断、记录和保存的简短参考. `delivery.dispatched` 报告队列确认,而不是完成. 取消未来工作;恢复工作可以按原费率使用所接受的剩余预算.

### 创造性支出

`client.creativeSource.usage({ before: null, limit: 25 })` 读取工作空间支出上限和工作收据. 使用 `nextCursor` 作为 `before` 下页. `coveredOperations` 列出受保护的工作家庭; 目前的食谱、研究、截图和孤立的源构建. 未知的提供商成本保留其预订. `costBasis` 将报告的费用与分配的上限区分开来. Repipe引文保留了现有的信用估计;工作空间/全球货币接纳在一开始就得到解剖检查.

### 保存的食谱版本

`client.recipes.listVersions({ projectId, offset: 0, limit: 20 })` 列出不可移动的模板版本, 包括当前项目修订和最新保存的版本. `client.recipes.inspectVersion` 接受 `projectId`, (中文(简体) ), `version`, (中文(简体) ), `section`, (中文(简体) ), `sourceRevisionId`, (中文(简体) ), `path`, (中文(简体) ), `offset` 财务报告和审定财务报表 `limit`。 。 。 . 节是 `overview`, (中文(简体) ), `variables`, (中文(简体) ), `artifacts`, (中文(简体) ), `dependencies`, (中文(简体) ), `assets` 财务报告和审定财务报表 `source`。 。 。 . 用于源区域外的源选择 。 源头检查需要保存源头修订ID; 2; 一个无效路径列表文件,一个路径读取一个精确保存的文件,包括软件包清单和锁文件. 每个收藏默认为20行并最多100个许可. 文本预览在 4,096 个字符后报告截图 . 这些读取了保留快照和当前模板权限 。 公共模板的能见度不授予 跨工作空间版本访问。 通过公共工作终点进行保存/复制是单独的未完成的工作.

食谱写作使用 `client.recipes.quote({ request, limits })`,然后是 `client.recipes.start({ request, limits, quoteId, maxCredits, idempotencyKey })`。 。 。 . 请求是 `{ kind: "capture", value: { projectId, expectedProjectRevision, expectedVersion } }` 或者说 `{ kind: "copy", value: { templateProjectId, version, projectId, expectedProjectRevision } }`。 。 。 . 复制一个已存在的空项目的目标; 可选源/ 已取消的映射选择额外的目标项目 . 限制绑定的传输字节,存储字节,操作和存储请求;其最大值在共享的图中. 票价 `client.recipes.get({ jobId })`· ; `cancel({ jobId })` 在不删除已完成产出的情况下停止新工作. 重试相同的起始输入/键来恢复录入和排队交付. SDK发送 `Idempotency-Key` 当作头相. 开始返回录取收据和当前工作,而不是完成的渲染。 需要定价配置.

可通过 `source quote --spec-file FILE --json` 财务报告和审定财务报表 `client.creativeSource.quote({ projectId, revision, compositionId, frame, output })`。 。 。 . 传回 `id` 作为建筑物 `quoteId` 拒绝更改价格或设置. 无效的引号接受当前配置的边框;所有边框都以相同的工作空间/全球美元上限构建保留地.

## 出口估计数

```typescript
const quote = await client.exports.quote({
  projectId,
  expectedRevision: null,
  resolution: "1080p",
  renderMode: "auto",
  frameRate: null,
});
```

此处为返回资格、估计入计量和未开始工作的最多工作空间的美元预留. 无法获得的费率有无效数额和理由。 允许重新检查当前限制; 引号保留什么 .

音频引文只读,与生成和被保存的音频恢复共用相同的预算保障:

```ts
const audioQuote = await client.generation.quoteAudio({
  kind: "music", characters: null, seconds: 30, preview: true, recovery: false, narrationTake: false,
});
```

`maximumUsd` 包括限定范围的工人复试、供应商请求、转移和初步保留. 未知的费率返回一个无效的上限和拒绝理由。 回收引用使用 `recovery: true` 并且排除了新的供应商购买. 再次检查当前限制 。 现有未知的调度员保留了他们的预留位置,再也没有自动发送其他工作.

图像、视频和单独的即时引用使用相同的只读预算界面:

```ts
const visualQuote = await client.generation.quote({
  kind: "video", model: "kling-2.1", seconds: 5, resolution: null,
  sourceImageModel: "fal-ai/nano-banana-2", enhancePrompt: true,
});
```

`sourceImageModel` 包括一个图像到视频生成的起始图像; 对现有源无效使用 . `enhancePrompt` 包括一个增强。 合并上限使用最早的政策到期和当前信贷/预算限额. 用于独立的增强用途 `kind: "prompt"` 带有无效模型、秒、分辨率和源图像模型. 返回的限制描述了所配置的信封;实际生成仍然验证其全部输入并重新检查录入. 无报价准备金、购买供应商工作或锁定价格。 无法获得的综合价格返回一个无效的上限.

设定 `narrationTake: true` 直接描述和语音预览. 字符封适用于已准备好的语音,包括指令;最终生成检查已准备好的实际文本. 回收引用保留处理/IO而不购买替换语. 现有的音频工作说明使用其父母津贴.

读取帧成本 `projects.quotePreview({ projectId, expectedRevision: null, frameCount: 3, targetWidth: 768, mode: "analyze" })`。 。 。 . 接受快照和旋转木马预览选项 `idempotencyKey`;成功的再试再利用保留了输出并刷新了 URL. 改变的重试输入冲突,不确定的工作在更换之前需要调节.

## 常见问题

### @blitzreels/sdk 是什么？

TypeScript SDK供AI代理和开发者在BlitzReels内部编辑视频\.

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

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

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

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

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

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

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

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

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

@blitzreels/sdk 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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