> ## 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 查询生成结果 

<RequestExample>
  ```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));
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

## 认证

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用 Bearer Token 进行认证。

  获取 API Key：

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

  使用时在请求头中添加：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  视频生成模型名称，固定为 `pixverse-v6`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频内容描述，最长 5000 字符。所有模式下均为必填。
</ParamField>

<ParamField body="resolution" type="string" default="540p">
  视频分辨率档位，直接影响计费。

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

  <Warning>
    传入其它分辨率会返回参数错误。
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  视频时长，单位为秒，取值范围为 `1-15`。

  <Warning>
    首尾帧过渡模式仅支持 `5` 或 `8` 秒。
  </Warning>
</ParamField>

<ParamField body="size" type="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`：电影宽屏
</ParamField>

<ParamField body="seed" type="integer" default="0">
  随机种子，取值范围为 `0-2147483647`。相同 prompt 和 seed 可用于复现相近结果。
</ParamField>

<ParamField body="negative_prompt" type="string">
  负面提示词，用于排除不想要的画面内容，最长 2048 字符。
</ParamField>

<ParamField body="audio" type="boolean" default="false">
  是否生成音轨。

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

<ParamField body="watermark" type="boolean" default="false">
  是否在视频右下角添加水印。

  * `true`：添加水印
  * `false`：不添加水印（默认）
</ParamField>

<ParamField body="motion_mode" type="string">
  运动模式。

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

  <Warning>
    `fast` 仅适用于旧版本模型，传给 `pixverse-v6` 会被上游拒绝。
  </Warning>
</ParamField>

<ParamField body="generate_multi_clip_switch" type="boolean" default="false">
  是否生成多片段连续视频，仅文生视频和图生视频支持。

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

<ParamField body="image_urls" type="array<url>">
  图生视频输入图片 URL 数组，仅取第一张。

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

<ParamField body="first_frame_image" type="url">
  首尾帧过渡模式的首帧图片 URL，必须与 `last_frame_image` 成对传入。
</ParamField>

<ParamField body="last_frame_image" type="url">
  首尾帧过渡模式的尾帧图片 URL，必须与 `first_frame_image` 成对传入。
</ParamField>

<ParamField body="img_references" type="array<url>">
  多参考图融合模式的参考图片 URL 数组，支持 1-7 张图片。

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

<ParamField body="extend_from_task_id" type="string">
  视频续写来源任务 ID。传入该字段会触发视频续写模式。

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

## 生成模式

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

| 生成模式   | 触发条件                                         | 说明                    |
| ------ | -------------------------------------------- | --------------------- |
| 文生视频   | 不传任何图片或续写字段                                  | 根据 `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。
</Warning>

## 参数规则

| 限制项       | 说明                                                  |
| --------- | --------------------------------------------------- |
| 视频时长      | `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` 任务 |

## 响应

<ResponseField name="code" type="integer">
  响应状态码，成功时为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  返回任务数组。

  <Expandable title="数组元素">
    <ResponseField name="status" type="string">
      任务初始状态，提交成功时为 `submitted`。
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务唯一标识符，用于查询任务状态和结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

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

```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
}
```