> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pixverse v6 视频生成

>  - Pixverse v6 统一视频生成模型
- 支持文生视频、图生视频、首尾帧过渡、多参考图融合和视频续写
- 支持 360p/540p/720p/1080p 分辨率，1-15 秒视频时长
- 异步任务接口，提交后通过任务 ID 查询生成结果 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "pixverse-v6",
    "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
    "size": "16:9",
    "resolution": "540p",
    "duration": 5
  }'
```

```python Python theme={null}
import requests

url = "https://api.apimart.ai/v1/videos/generations"

payload = {
    "model": "pixverse-v6",
    "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
    "size": "16:9",
    "resolution": "540p",
    "duration": 5
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/videos/generations";

const payload = {
  model: "pixverse-v6",
  prompt: "A cinematic shot of a corgi running through a sunflower field at golden hour",
  size: "16:9",
  resolution: "540p",
  duration: 5
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Error:", error));
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01JWXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "invalid duration 20, allowed range: 1-15 seconds"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}
```

```json 403 theme={null}
{
  "error": {
    "code": 403,
    "message": "insufficient quota: balance=0, required=0.25",
    "type": "quota_not_enough"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 进行认证。

获取 API Key：

访问 [API Key 管理页面](https://apimart.ai/keys) 获取您的 API Key。

使用时在请求头中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## 请求参数

**model** `string` *required*

视频生成模型名称，固定为 `pixverse-v6`。

**nsfw\_check** `boolean` (default: false)

是否在提交视频任务前执行内容审核。

* `true`：使用 `omni-moderation-latest` 审核提示词和输入图片
* `false` 或不传：不发起审核请求，不增加审核成本与延迟（默认）

**prompt** `string` *required*

视频内容描述，最长 5000 字符。所有模式下均为必填。

**resolution** `string` (default: 540p)

视频分辨率档位，直接影响计费。

* `360p`：标清
* `540p`：标准（默认）
* `720p`：高清
* `1080p`：超高清

> [!WARNING]
>
> 传入其它分辨率会返回参数错误。

**duration** `integer` (default: 5)

视频时长，单位为秒，取值范围为 `1-15`。

> [!WARNING]
>
> 首尾帧过渡模式仅支持 `5` 或 `8` 秒。

**size** `string` (default: 16:9)

视频宽高比，仅在文生视频和多参考图融合模式生效。

* `16:9`：横向宽屏（默认）
* `4:3`：横向 4:3
* `1:1`：正方形
* `3:4`：纵向 3:4
* `9:16`：纵向竖屏
* `2:3`：纵向 2:3
* `3:2`：横向 3:2
* `21:9`：电影宽屏

**seed** `integer` (default: 0)

随机种子，取值范围为 `0-2147483647`。相同 prompt 和 seed 可用于复现相近结果。

**negative\_prompt** `string`

负面提示词，用于排除不想要的画面内容，最长 2048 字符。

**audio** `boolean` (default: false)

是否生成音轨。

* `true`：生成音轨（会提高计费单价）
* `false`：不生成音轨（默认）

**watermark** `boolean` (default: false)

是否在视频右下角添加水印。

* `true`：添加水印
* `false`：不添加水印（默认）

**motion\_mode** `string`

运动模式。

* `normal`：标准模式（`pixverse-v6` 仅支持此值）

> [!WARNING]
>
> `fast` 仅适用于旧版本模型，传给 `pixverse-v6` 会被上游拒绝。

**generate\_multi\_clip\_switch** `boolean` (default: false)

是否生成多片段连续视频，仅文生视频和图生视频支持。

* `true`：生成多片段连续视频
* `false`：单片段视频（默认）

**image\_urls** `array\<url\>`

图生视频输入图片 URL 数组，仅取第一张。

图片必须是公网可访问的 HTTP/HTTPS URL。

**first\_frame\_image** `url`

首尾帧过渡模式的首帧图片 URL，必须与 `last_frame_image` 成对传入。

**last\_frame\_image** `url`

首尾帧过渡模式的尾帧图片 URL，必须与 `first_frame_image` 成对传入。

**img\_references** `array\<url\>`

多参考图融合模式的参考图片 URL 数组，支持 1-7 张图片。

传入该字段会触发多参考图融合模式。

**extend\_from\_task\_id** `string`

视频续写来源任务 ID。传入该字段会触发视频续写模式。

来源任务必须属于当前用户，模型必须为 `pixverse-v6`，并且状态必须为 `completed`。

## 生成模式

适配器会根据请求字段自动分发到对应生成模式。按优先级匹配，先满足者命中。

| 生成模式 | 触发条件 | 说明 |
| - | - | - |
| 文生视频 | 不传任何图片或续写字段 | 根据 `prompt` 生成视频 |
| 图生视频 | 传 `image_urls` 单张 | 使用第一张图片作为输入图 |
| 首尾帧过渡 | 同时传 `first_frame_image` 和 `last_frame_image` | 生成两帧之间的平滑过渡 |
| 多参考图融合 | 传 `img_references` 数组 | 融合 1-7 张参考图生成视频 |
| 视频续写 | 传 `extend_from_task_id` | 从已完成的 Pixverse 任务继续生成 |

> [!WARNING]
>
> 所有图片入口只接受公网 HTTP/HTTPS URL，不支持 base64 或 Data URI。若只有本地图片，请先上传到对象存储后再传 URL。

## 参数规则

| 限制项 | 说明 |
| - | - |
| 视频时长 | `1 ≤ duration ≤ 15` 秒；首尾帧过渡模式仅支持 `5` 或 `8` 秒 |
| 分辨率 | 仅支持 `360p`、`540p`、`720p`、`1080p` |
| 宽高比 | `size` 仅在文生视频和多参考图融合模式生效 |
| Prompt 长度 | `prompt` 最长 5000 字符，`negative_prompt` 最长 2048 字符 |
| 图生视频 | `image_urls` 仅取第一张图片 |
| 首尾帧过渡 | `first_frame_image` 和 `last_frame_image` 必须成对出现 |
| 运动模式 | `pixverse-v6` 仅支持 `normal` |
| 多参考图融合 | `img_references` 支持 1-7 张图片 |
| 视频续写 | `extend_from_task_id` 必须指向当前用户已完成的 `pixverse-v6` 任务 |

## 响应

**code** `integer`

响应状态码，成功时为 `200`。

**data** `array`

返回任务数组。

**数组元素**

**status** `string`

任务初始状态，提交成功时为 `submitted`。

**task\_id** `string`

任务唯一标识符，用于查询任务状态和结果。

## 查询任务结果

视频生成为异步任务。提交后会返回 `task_id`，使用 [获取任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 接口查询生成进度和结果。

```bash cURL theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01JWXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

建议每 5 秒轮询一次，直到任务状态变为 `completed` 或 `failed`。

### 成功结果示例

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "completed",
    "progress": 100,
    "cost": 0.2,
    "credits_cost": 2,
    "created": 1779958948,
    "completed": 1779958999,
    "estimated_time": 100,
    "actual_time": 51,
    "result": {
      "videos": [
        {
          "url": ["https://upload.apimart.ai/f/video/xxxx.mp4"],
          "expires_at": 1780045399
        }
      ]
    }
  }
}
```

视频 URL 路径为 `data.result.videos[0].url[0]`。`url` 字段本身是数组，视频链接通常 24 小时后过期，请及时下载或转存。

### 失败结果示例

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "created": 1779958948,
    "completed": 1779958960,
    "error": {
      "code": "task_failed",
      "message": "pixverse error 400063: moderation failed",
      "type": "task_failed"
    }
  }
}
```

失败时 `cost` 通常为 `0`，错误原因请读取 `data.error.message`。

## 使用场景

### 场景 1：文生视频

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A neon-lit alley in Tokyo at night, light rain, anamorphic lens flare",
  "size": "21:9",
  "resolution": "720p",
  "duration": 8,
  "seed": 42,
  "audio": true
}
```

### 场景 2：图生视频

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "Camera slowly zooms in, gentle wind moves the leaves",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "resolution": "540p",
  "duration": 5
}
```

### 场景 3：首尾帧过渡

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "transform smoothly from a puppy to a cat",
  "first_frame_image": "https://example.com/puppy.jpg",
  "last_frame_image": "https://example.com/cat.jpg",
  "resolution": "540p",
  "duration": 5,
  "motion_mode": "normal"
}
```

### 场景 4：多参考图融合

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A girl wearing the outfit from image 2, holding the cat from image 3",
  "img_references": [
    "https://example.com/character.jpg",
    "https://example.com/outfit.jpg",
    "https://example.com/cat.jpg"
  ],
  "size": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

### 场景 5：视频续写

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "the character now walks into a forest",
  "extend_from_task_id": "task_01JWXXXXXXXXXXXX",
  "resolution": "540p",
  "duration": 5
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.