# HappyHorse Oversea 视频生成 API 对接文档

## 概述

HappyHorse Oversea 视频生成接口，支持文生视频、图生视频、参考生视频、视频编辑等多种模式。

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

---

## 认证方式

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

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

---

## 支持的使用场景

### 场景1：文生视频（t2v）

纯文本描述生成视频。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/happyhorse-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只金毛犬在阳光明媚的草地上奔跑，镜头跟随拍摄",
    "genType": "t2v",
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 5
  }'
```

### 场景2：图生视频（i2v）

传入首帧图片，基于图片内容生成视频。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/happyhorse-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "女孩抱着狐狸，温柔地看向镜头，头发被风吹动",
    "genType": "i2v",
    "imageUrls": ["https://example.com/fox_girl.png"],
    "resolution": "1080P",
    "duration": 5
  }'
```

### 场景3：参考生视频（r2v）

传入多张参考图片（1-9张），模型参考图片内容生成视频。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/happyhorse-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "戴着眼镜穿蓝色T恤的男生和柯基小狗在草坪上玩耍",
    "genType": "r2v",
    "imageUrls": [
      "https://example.com/boy.png",
      "https://example.com/dog.png",
      "https://example.com/grass.png"
    ],
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 5
  }'
```

### 场景4：视频编辑（v2v）

对已有视频进行编辑，支持主体替换、局部重绘等。

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/happyhorse-oversea" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "将视频中的房子外墙刷成蓝色，天气改为雪天",
    "genType": "v2v",
    "videoUrl": "https://example.com/house_video.mp4",
    "imageUrls": ["https://example.com/snow_scene.jpg"],
    "audioSetting": "auto"
  }'
```

---

## 查询任务状态

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

---

## 接口详情

### 1. 创建 HappyHorse Oversea 任务

**POST** `/api/v2/open/aigc/happyhorse-oversea`

创建一个 HappyHorse Oversea 视频生成任务。

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 提示词 |
| genType | string | 否 | 生成类型：`t2v`(默认) / `i2v` / `r2v` / `v2v`，不传则自动推断 |
| imageUrls | string[] | 否 | 参考图片URL列表（i2v仅1张；r2v 1-9张；v2v 0-5张） |
| base64File | string | 否 | Base64编码的图片（会转换为imageUrl） |
| base64FileList | string[] | 否 | Base64编码的多张图片 |
| videoUrl | string | 条件必填 | 输入视频URL（v2v时必填，MP4/MOV，3-60秒，最大100MB） |
| resolution | string | 否 | 分辨率：`1080P`(默认) / `720P` |
| ratio | string | 否 | 宽高比：`16:9`(默认) / `9:16` / `1:1` / `4:3` / `3:4`（v2v不支持） |
| duration | int | 否 | 视频时长（秒），3-15，默认5（v2v不支持，跟随输入视频） |
| seed | int | 否 | 随机种子，用于复现结果 |
| watermark | bool | 否 | 是否带水印，默认 `false` |
| audioSetting | string | 否 | 声音控制（仅v2v）：`auto`(默认) / `origin`(保留原声) |
| nsfwChecker | bool | 否 | 内容过滤开关，设为 `false` 时禁用内容过滤，默认 `false` |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

#### genType 自动推断规则

如果不传 `genType`，系统将根据输入自动判断：
- 有 `videoUrl` → `v2v`
- 有 `base64File` 或仅1张图 → `i2v`
- 有多张图片 → `r2v`
- 仅有文本 → `t2v`

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID，用于查询任务状态 |
| data.status | string | 任务状态，创建时固定为 `processing` |
| data.createdAt | string | 创建时间 |

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 15:00:00"
  }
}
```

---

### 2. 查询任务状态

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

查询单个任务的执行状态。

#### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskId | string | 是 | 任务 ID |

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| 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_20260508150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:00:05"
  }
}
```

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/08/output.mp4"
    ],
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:03:30"
  }
}
```

**失败**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508150000_abc12345",
    "status": "failed",
    "errorMsg": "视频生成失败，请重试",
    "createdAt": "2026-05-08 15:00:00",
    "updatedAt": "2026-05-08 15:02:00"
  }
}
```

---

### 3. 批量查询任务状态

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

批量查询多个任务的执行状态（最多 100 个）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskIds | string[] | 是 | 任务 ID 列表，最多 100 个 |

#### 请求示例

```json
{
  "taskIds": ["task_20260508150000_abc12345", "task_20260508150200_def67890"]
}
```

---

## 回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。

### 回调请求

**Headers**
```
Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}
```

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260508150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-08T15:03:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

---

## 参数取值范围

### 分辨率 (resolution)

| 值 | 说明 |
|----|------|
| `720P` | 标清 |
| `1080P` | 高清（默认） |

### 宽高比 (ratio)

| 值 | 说明 |
|----|------|
| `16:9` | 横屏（默认） |
| `9:16` | 竖屏 |
| `1:1` | 方形 |
| `4:3` | 标准横屏 |
| `3:4` | 标准竖屏 |

### 时长 (duration)

- 范围：3 ~ 15 秒
- 默认：5 秒

### 生成类型 (genType)

| 值 | 说明 | 图片要求 |
|----|------|---------|
| `t2v` | 文生视频 | 无需图片 |
| `i2v` | 图生视频 | 必须1张图片（首帧） |
| `r2v` | 参考生视频 | 必须1-9张参考图 |
| `v2v` | 视频编辑 | 必须提供videoUrl，可选0-5张参考图 |

---

## 错误码

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

---

## 最佳实践

### 1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

### 2. 处理时间参考

- 文生视频(t2v)：通常 1 ~ 3 分钟
- 图生视频(i2v)：通常 1 ~ 3 分钟
- 参考生视频(r2v)：通常 1 ~ 3 分钟
- 视频编辑(v2v)：通常 2 ~ 5 分钟
- 分辨率越高、时长越长，处理时间越长

### 3. Prompt 建议

- 用简洁准确的自然语言描述画面内容和运动
- 可以指定镜头运动（推进、拉远、环绕等）
- 建议包含：主体描述 + 动作 + 场景/背景
- 当生成结果不符合预期时，尝试将抽象描述换成具象描述