# @api\.video/video-uploader 中文文档

规范地址：https://npmcn.com/package/%40api.video/video-uploader/

版本：1\.1\.6
npm 元数据更新时间：2025-05-22T12:50:44.688Z
中文译文更新时间：2026-11-06T09:56:37.730Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40api.video/video-uploader
原文对照：https://npmcn.com/package/%40api.video/video-uploader/?lang=original
项目主页：https://github.com/apivideo/api.video-typescript-uploader#readme
源码仓库：https://github.com/apivideo/api.video-typescript-uploader

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

- 包体积（解压后）：152 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-06-30T15:44:02.466Z
- 最新版本发布：2023-10-31T14:16:41.171Z
- 近 30 天下载量：6752（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

api.video 视频上传器

## 安装

```sh
npm install @api.video/video-uploader
```

也可以使用：`pnpm add @api.video/video-uploader`、`yarn add @api.video/video-uploader`、`bun add @api.video/video-uploader`

## README

[![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video)   [![badge](https://img.shields.io/github/stars/apivideo/api.video-typescript-uploader?style=social)](https://github.com/apivideo/api.video-typescript-uploader)   [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video/) ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)

# api.video 排字视频上传器

![npm](https://img.shields.io/npm/v/@api.video/video-uploader) ![ts](https://badgen.net/badge/-/TypeScript/blue?icon=typescript&label)

[视频](https://api.video/) 是产品制造者的视频基础设施。 闪电快视频 API 用于在您的应用程序中集成,缩放,并管理点播后低空直播功能.

# 目录

-   [目录](https://npmcn.com/package/%40api.video/video-uploader/#readme-table-of-contents)
-   [项目说明](https://npmcn.com/package/%40api.video/video-uploader/#readme-project-description)
-   [开始](https://npmcn.com/package/%40api.video/video-uploader/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40api.video/video-uploader/#readme-installation)
        -   [安装方法 1: 需要js](https://npmcn.com/package/%40api.video/video-uploader/#readme-installation-method-1-requirejs)
        -   [安装方法 # 2 : 打字符](https://npmcn.com/package/%40api.video/video-uploader/#readme-installation-method-2-typescript)
        -   [在 Javascript 计划中简单包含](https://npmcn.com/package/%40api.video/video-uploader/#readme-simple-include-in-a-javascript-project)
-   [文档 - 标准上传](https://npmcn.com/package/%40api.video/video-uploader/#readme-documentation---standard-upload)
    -   [即兴](https://npmcn.com/package/%40api.video/video-uploader/#readme-instanciation)
        -   [选项](https://npmcn.com/package/%40api.video/video-uploader/#readme-options)
            -   [使用授权的上传符( 建议):](https://npmcn.com/package/%40api.video/video-uploader/#readme-using-a-delegated-upload-token-recommended)
            -   [使用访问符( 损坏 ) :](https://npmcn.com/package/%40api.video/video-uploader/#readme-using-an-access-token-discouraged)
            -   [使用 API 密钥( N)**强烈的** 沮丧:](https://npmcn.com/package/%40api.video/video-uploader/#readme-using-an-api-key-strongly-discouraged)
            -   [共同选项](https://npmcn.com/package/%40api.video/video-uploader/#readme-common-options)
        -   [示例](https://npmcn.com/package/%40api.video/video-uploader/#readme-example)
    -   [方法](https://npmcn.com/package/%40api.video/video-uploader/#readme-methods)
        -   [`upload()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-upload)
        -   [`onProgress()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-onprogress)
        -   [`cancel()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-cancel)
        -   [`onPlayable()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-onplayable)
-   [文档 - 渐进上传](https://npmcn.com/package/%40api.video/video-uploader/#readme-documentation---progressive-upload)
    -   [即兴](https://npmcn.com/package/%40api.video/video-uploader/#readme-instanciation-1)
        -   [选项](https://npmcn.com/package/%40api.video/video-uploader/#readme-options-1)
            -   [使用授权的上传符( 建议):](https://npmcn.com/package/%40api.video/video-uploader/#readme-using-a-delegated-upload-token-recommended-1)
            -   [使用访问符( 损坏 ) :](https://npmcn.com/package/%40api.video/video-uploader/#readme-using-an-access-token-discouraged-1)
            -   [共同选项](https://npmcn.com/package/%40api.video/video-uploader/#readme-common-options-1)
        -   [示例](https://npmcn.com/package/%40api.video/video-uploader/#readme-example-1)
    -   [方法](https://npmcn.com/package/%40api.video/video-uploader/#readme-methods-1)
        -   [`uploadPart(file: Blob)`](https://npmcn.com/package/%40api.video/video-uploader/#readme-uploadpartfile-blob)
        -   [`uploadLastPart(file: Blob)`](https://npmcn.com/package/%40api.video/video-uploader/#readme-uploadlastpartfile-blob)
        -   [`onProgress()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-onprogress-1)
        -   [`cancel()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-cancel-1)
        -   [`onPlayable()`](https://npmcn.com/package/%40api.video/video-uploader/#readme-onplayable-1)
-   [静态包装器](https://npmcn.com/package/%40api.video/video-uploader/#readme-static-wrapper)

# 项目说明

Typescript 库将视频上传到 api.video ,使用前端授权上传符(或常用访问符).

它允许您以两种方式上传视频:

-   标准上传: 一去一去发送整个视频文件
-   渐进上传: 按块发送视频文件, 不需要知道视频文件的最终大小

# 开始

## 安装

### 安装方法 1: 需要js

如果您使用需要js, 您可以将库添加为您的项目依赖性

```sh
$ npm install --save @api.video/video-uploader
```

然后可以在脚本中使用库 :

```javascript
// standard upload:
var { VideoUploader } = require('@api.video/video-uploader');

var uploader = new VideoUploader({
    // ... (see bellow)
}); 

// progressive upload:
var { ProgressiveUploader } = require('@api.video/video-uploader');

var uploader = new ProgressiveUploader({
    // ... (see bellow)
}); 
```

### 安装方法 # 2 : 打字符

如果您使用 Typescript, 您可以将库添加为您的项目依赖性

```sh
$ npm install --save @api.video/video-uploader
```

然后可以在脚本中使用库 :

```typescript
// standard upload:
import { VideoUploader } from '@api.video/video-uploader'

const uploader = new VideoUploader({
    // ... (see bellow)
});

// progressive upload:
import { ProgressiveUploader } from '@api.video/video-uploader'

const uploader = new ProgressiveUploader({
    // ... (see bellow)
});
```

### 在 Javascript 计划中简单包含

将库包含在您的 HTML 文件里 :

```html
<head>
    ...
    <script src="https://unpkg.com/@api.video/video-uploader" defer></script>
</head>
```

然后,一旦 `window.onload` 事件已被三进制, 使用 `new VideoUploader()`数字 :

```html
...
<form>
    <input type="file" id="input" onchange="uploadFile(this.files)">
</form>
<script type="text/javascript">
    function uploadFile(files) {
        new VideoUploader({
            file: files[0],
            uploadToken: "YOUR_DELEGATED_TOKEN"
        }).upload();
    }
</script>
```

# 文档 - 标准上传

## 即兴

### 选项

上传库使用一个 `options` 对象。 要提供选项取决于您要认证到 API 的方式: 要么使用授权的上传符( recommanded) , 要么使用通常的访问符.

#### 使用授权的上传符( 建议):

在从客户端上传时,使用授权上传符进行认证是最佳选项. 更多关于授权上传信条 [授权上传](https://api.video/blog/tutorials/delegated-uploads)。 。 。 .

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 上传脚本 | **对** | 字符串 | 您的上传标志 |
| 视频 | 没有 | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

#### 使用访问符( 损坏 ) :

**3⁄4 ̄ ̧漯B**: 注意暴露您的访问符客户端会导致巨大的安全问题. 只有你知道自己在做什么,才使用这种方法:).

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 访问脚本 | **对** | 字符串 | 您的访问符 |
| 刷新脚本 | **没有** | 字符串 | 您的刷新令牌( 请不要说, 如果您不提供刷新令牌, 您的上传可能因访问令牌寿命为 60 分钟而失败 ) |
| 视频 | **对** | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

#### 使用 API 密钥( N)**强烈的** 沮丧:

**3⁄4 ̄ ̧漯B**: 注意暴露您的API关键客户端会导致巨大的安全问题. 只有你知道自己在做什么,才使用这种方法:).

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| API 密钥 | **对** | 字符串 | 您的 api.video API 键 |
| 视频 | **对** | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

#### 共同选项

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 文件 | **对** | 文件 | 您要上传的文件 |
| 视频Name | 没有 | 字符串 | 视频名称(覆盖正常上传的原始文件名,覆盖渐进上传的默认“文件”名称) |
| 块大小 | 没有 | 编号 | 每个上传块的字节数( 默认: 50MB, min: 5MB, 最大: 128MB) |
| 爱比荷斯 | 没有 | 字符串 | api.video 主机(默认:ws.api.video) |
| 重试 | 没有 | 编号 | aPI 调用失败时重试的次数( 默认: 5) |
| 重试策略 | 没有 | (重复:号码,错误:视频UploadError) QQ 号码QQ 无效 | 函数返回要等待的 ms 数,然后重试失败的上传。 返回无效以停止重试 |
| 最大视频期限 | 没有 | 编号 | 文件允许的最大持续时间( 秒) |

### 示例

```javascript
    const uploader = new VideoUploader({
        file: files[0],
        uploadToken: "YOUR_DELEGATED_TOKEN",
        chunkSize: 1024*1024*10, // 10MB
        retries: 10,
    });
```

## 方法

### `upload()`

上传方法开始上传 。 它不需要参数。 它返回文件上传后解决的保证 。 如果API呼叫失败超过指定的重试次数,则承诺被拒绝. 如果成功,承诺就包含 `video` aPI返回的对象. 失败时, 承诺会嵌入由 API 返回的状态代码和错误消息 .

**示例**

```javascript
    // ... uploader instanciation

    uploader.upload()
        .then((video) => console.log(video))
        .catch((error) => console.log(error.status, error.message));
```

### `onProgress()`

进程( ) 方法允许您定义一个上传进程倾听器 。 它需要有一个参数的召回函数:关于进步事件. 关于进步的事件包含以下属性:

-   上传Bytes( 数字): 此上传的字节总数
-   总数Bytes( 数目): 文件的总大小
-   块( 数目): 上传块数
-   块字节( 个数): 块的大小
-   当前Chunk (数字): 正在上传的块索引
-   当前ChunkUploaded Bytes (数字): 当前块上传的字节数

### `cancel()`

取消()方法取消上传. 它不需要参数.

**示例**

```javascript
    // ... uploader instanciation
    
    uploader.onProgress((event) => {
        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
        console.log(`total size of the file: ${event.totalBytes}.`);
        console.log(`number of upload chunks: ${event.chunksCount} .`);
        console.log(`size of a chunk: ${event.chunksBytes}.`);
        console.log(`index of the chunk being uploaded: ${event.currentChunk}.`);
        console.log(`number of bytes uploaded for the current chunk: ${event.currentChunkUploadedBytes}.`);
    });
```

### `onPlayable()`

使用可播放()方法可以定义视频播放时会调用的收听器 。 它需要有一个参数的回调函数: `video` aPI返回的对象.

**示例**

```html
    <div id="player-container"></div>

    <script>
        // ... uploader instanciation
    
        uploader.onPlayable((video) => {
            // the video is playable, we can display the player
            document.getElementById('player-container').innerHTML = v.assets.iframe;
        });
    </script>
```

# 文档 - 渐进上传

## 即兴

### 选项

渐进上传对象使用一个 `options` 对象。 要提供选项取决于您要认证到 API 的方式: 要么使用授权的上传符( recommanded) , 要么使用通常的访问符.

#### 使用授权的上传符( 建议):

在从客户端上传时,使用授权上传符进行认证是最佳选项. 更多关于授权上传信条 [授权上传](https://api.video/blog/tutorials/delegated-uploads)。 。 。 .

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 上传脚本 | **对** | 字符串 | 您的上传标志 |
| 视频 | 没有 | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

#### 使用访问符( 损坏 ) :

**3⁄4 ̄ ̧漯B**: 注意暴露您的访问符客户端会导致巨大的安全问题. 只有你知道自己在做什么,才使用这种方法:).

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 访问脚本 | **对** | 字符串 | 您的访问符 |
| 视频 | **对** | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

#### 共同选项

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 爱比荷斯 | 没有 | 字符串 | api.video 主机(默认:ws.api.video) |
| 重试 | 没有 | 编号 | aPI 调用失败时重试的次数( 默认: 5) |
| 重试策略 | 没有 | (重复:号码,错误:视频UploadError) QQ 号码QQ 无效 | 函数返回要等待的 ms 数,然后重试失败的上传。 返回无效以停止重试 |
| 防止Empty 组件 | 没有 | 布尔 | 如果选中的话, 上传将成功, 即使一个空 Blob 被传递到上传 LastPart () 。 这在某些情况下可能会改变一些性能( 默认: 假) |
| 合并上载前的小部件 | 没有 | 布尔 | 如果错误, 小于 5MB 的部分在上传前不会合并, 导致错误( 默认: 真) |

### 示例

```javascript
    const uploader = new ProgressiveUploader({
        uploadToken: "YOUR_DELEGATED_TOKEN",
        retries: 10,
    });
```

## 方法

### `uploadPart(file: Blob)`

上传方法开始上传 。 它不需要参数。 它返回文件上传后解决的保证 。 如果API呼叫失败超过指定的重试次数,则承诺被拒绝. 如果成功,承诺就包含 `video` aPI返回的对象. 失败时, 承诺会嵌入由 API 返回的状态代码和错误消息 .

**示例**

```javascript
    // ... uploader instanciation

    uploader.uploadPart(blob)
        .catch((error) => console.log(error.status, error.message));
```

### `uploadLastPart(file: Blob)`

上传方法开始上传 。 它不需要参数。 它返回文件上传后解决的保证 。 如果API呼叫失败超过指定的重试次数,则承诺被拒绝. 如果成功,承诺就包含 `video` aPI返回的对象. 失败时, 承诺会嵌入由 API 返回的状态代码和错误消息 .

**示例**

```javascript
    // ... uploader instanciation

    uploader.uploadLastPart(blob)
        .then((video) => console.log(video))
        .catch((error) => console.log(error.status, error.message));
```

### `onProgress()`

进程( ) 方法允许您定义一个上传进程倾听器 。 它需要有一个参数的召回函数:关于进步事件. 关于进步的事件包含以下属性:

-   上传Bytes( 数字): 此上传的字节总数
-   总数Bytes( 数目): 文件的总大小
-   部分( 数目): 上传部分的索引

**示例**

```javascript
    // ... uploader instanciation
    
    uploader.onProgress((event) => {
        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
        console.log(`total size of the file: ${event.totalBytes}.`);
        console.log(`current part: ${event.part}.`);
    });
```

### `cancel()`

取消()方法取消上传. 它不需要参数.

### `onPlayable()`

使用可播放()方法可以定义视频播放时会调用的收听器 。 它需要有一个参数的回调函数: `video` aPI返回的对象.

**示例**

```html
    <div id="player-container"></div>

    <script>
        // ... uploader instanciation
    
        uploader.onPlayable((video) => {
            // the video is playable, we can display the player
            document.getElementById('player-container').innerHTML = v.assets.iframe;
        });
    </script>
```

# 静态包装器

对于管理对象实例不切实际的情况,考虑使用 [上传器StaticWrapper](https://npmcn.com/package/%40api.video/video-uploader/doc/UploaderStaticWrapper.md) 类,它为所有功能提供静态方法等同.

## 常见问题

### @api\.video/video-uploader 是什么？

api\.video 视频上传器

### 如何安装 @api\.video/video-uploader？

在项目目录运行 npm install @api\.video/video-uploader，或使用 pnpm add / yarn add / bun add。

### @api\.video/video-uploader 支持 TypeScript 吗？

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

### @api\.video/video-uploader 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @api\.video/video-uploader 可以商用吗？

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

### @api\.video/video-uploader 的下载量有多少？

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

### @api\.video/video-uploader 还在维护吗？

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