# PixVerse 视频生成 API 对接文档

## 概述

PixVerse Open API 当前提供 `V6` 和 `C1` 两个模型版本，支持文生视频(`t2v`)和图生视频(`i2v`)。

**Base URL**: `https://api.apiverse.ai`

---

## 认证方式

所有接口均需要在请求头中携带 Token 进行认证：

```http
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

## 接口列表

| 模型 | 创建任务接口 |
|------|--------------|
| PixVerse V6 | `POST /api/v2/open/aigc/pix-verse-v6` |
| PixVerse C1 | `POST /api/v2/open/aigc/pix-verse-c1` |
| 查询任务 | `GET /api/v2/open/aigc/{taskId}` |
| 批量查询 | `POST /api/v2/open/aigc/batch` |

---

## 创建任务

**Content-Type**: `application/json`

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 提示词，最多 1500 字符 |
| genType | string | 否 | 生成类型：`t2v`(默认) / `i2v` |
| imageUrls | string[] | 条件 | 参考图片 URL；`i2v` 必须 1 张 |
| base64File | string | 否 | Base64 编码图片，会追加到 `imageUrls` 前面 |
| base64FileList | string[] | 否 | Base64 编码图片列表，会追加到 `imageUrls` 后面 |
| resolution | string | 否 | 分辨率：`720P` / `1080P`(默认) |
| aspectRatio | string | 否 | 宽高比：`16:9`(默认) / `9:16` / `1:1` / `4:3` / `3:4` |
| duration | int | 否 | 视频时长，默认 5 秒，支持 5 或 8 秒 |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

### 快速开始

**PixVerse V6 文生视频**

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/pix-verse-v6" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "霓虹街道中一位角色向前奔跑，镜头缓慢推进，电影感光影",
    "genType": "t2v",
    "resolution": "1080P",
    "aspectRatio": "16:9",
    "duration": 5
  }'
```

**PixVerse C1 图生视频**

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/pix-verse-c1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "让参考图中的角色做出挥剑动作，镜头轻微环绕，电影感运镜",
    "genType": "i2v",
    "imageUrls": [
      "https://example.com/reference.jpg"
    ],
    "resolution": "1080P",
    "aspectRatio": "16:9",
    "duration": 8
  }'
```

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260518103000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-18 10:30:00"
  }
}
```

---

## 查询任务状态

**GET** `/api/v2/open/aigc/{taskId}`

```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_20260518103000_abc12345" \
  -H "Authorization: Bearer your_auth_token_here"
```

### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID |
| data.status | string | `processing` / `success` / `failed` |
| data.result | string[] | 生成的视频 URL 列表，成功时返回 |
| data.errorMsg | string | 错误信息，失败时返回 |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 更新时间 |

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260518103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/18/output_001.mp4"
    ],
    "createdAt": "2026-05-18 10:30:00",
    "updatedAt": "2026-05-18 10:32:30"
  }
}
```

---

## 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

```json
{
  "taskIds": [
    "task_20260518103000_abc12345",
    "task_20260518103200_def67890"
  ]
}
```

---

## 回调通知

创建任务时传入 `callbackUrl` 后，任务完成会发送 POST 回调：

```json
{
  "event": "task.completed",
  "taskId": "task_20260518103000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-18T10:32:30+08:00"
}
```

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 30003 | 任务不存在 |
| 90003 | 服务器内部错误 |