# 视频超分增强 API 对接文档

## 概述

视频超分增强接口接收一条已有的视频地址，把画面增强到指定分辨率档位（`720p` / `1080p` / `2k` / `4k`），异步返回增强后的视频链接。

适用场景：低分辨率素材提清、AIGC 生成视频二次提清、老片修复交付前的分辨率补齐。

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

---

## 认证方式

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

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

---

## 调用流程

```
创建超分任务(videoUrl + quality)
        │
        └── taskId → 轮询任务状态 / 等待回调 → 返回增强后的视频链接
```

- 任务为**异步**：创建接口立即返回 `taskId`，`status` 固定为 `processing`。
- 结果通过「轮询查询接口」或「回调通知」获取，二者可任选其一。
- 任务成功后 `result[0]` 为增强后的视频地址。

---

## 创建超分任务

**POST** `/api/v2/open/aigc/super-resolution`

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| videoUrl | string | 是 | 待增强的源视频 URL，需公网可访问 |
| quality | string | 是 | 目标分辨率档位：`720p` / `1080p` / `2k` / `4k` |
| duration | int | 否 | 源视频时长（秒），用于计费。**强烈建议如实传入**，不传按 1 分钟计费 |
| taskNickname | string | 否 | 任务昵称，便于在控制台/任务列表中识别 |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

> **`quality` 说明**：大小写不敏感，各档位同时兼容以下写法，会归一化到标准档位：
>
> | 标准档位 | 兼容写法 |
> |---------|---------|
> | `720p` | `720`、`hd` |
> | `1080p` | `1080`、`fhd` |
> | `2k` | `2560`、`1440` |
> | `4k` | `2160` |
>
> 取值不在上表内时接口直接返回参数错误。
>
> **`duration` 说明**：计费按输出时长分钟数向上取整（不足 1 分钟按 1 分钟）。该值只在创建时用于计费冻结，**任务完成后不会按实际视频时长二次调整**，所以传得不准会导致费用与预期不符。

### 请求示例

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/super-resolution" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/source_480p.mp4",
    "quality": "1080p",
    "duration": 8,
    "taskNickname": "宣传片提清",
    "callbackUrl": "https://your-domain.com/callback/sr"
  }'
```

### 响应参数

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

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903160000_abc12345",
    "status": "processing",
    "createdAt": "2026-09-03 16:00:00"
  }
}
```

---

## 查询任务状态

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

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

### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| data.taskId | string | 任务 ID |
| data.status | string | 任务状态：`processing` / `success` / `failed` |
| data.result | array | 成功时返回增强后的视频链接，`result[0]` 为增强结果 |
| data.errorMsg | string | 失败原因，仅 `failed` 时返回 |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 最后更新时间 |

### 响应示例

**处理中**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903160000_abc12345",
    "status": "processing",
    "createdAt": "2026-09-03 16:00:00",
    "updatedAt": "2026-09-03 16:00:05"
  }
}
```

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903160000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/09/03/output_1080p.mp4"
    ],
    "createdAt": "2026-09-03 16:00:00",
    "updatedAt": "2026-09-03 16:02:40"
  }
}
```

**失败**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903160000_abc12345",
    "status": "failed",
    "errorMsg": "超分任务执行失败",
    "createdAt": "2026-09-03 16:00:00",
    "updatedAt": "2026-09-03 16:01:30"
  }
}
```

---

## 回调通知

若创建任务时提供了 `callbackUrl`，任务完成（成功或失败）时会向该 URL 发送 POST 回调。

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

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260903160000_abc12345",
  "status": "success",
  "result": [
    "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/09/03/output_1080p.mp4"
  ],
  "errorMsg": "",
  "timestamp": "2026-09-03T16:02:40+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

> 回调接收端需返回 2xx 状态码，且响应时间不超过 10 秒，否则视为投递失败。回调只作为通知手段，业务上建议同时保留低频轮询兜底。

---

## 计费说明

- 按 **档位 × 输出时长（分钟）** 计费，时长向上取整，**不足 1 分钟按 1 分钟计费**。
- 档位越高单价越高（`4k` > `2k` > `1080p` > `720p`），具体单价请参考价格表或联系商务。
- 创建任务时按 `duration` 预冻结费用：任务**成功后扣费**，任务**失败自动全额解冻**。
- `duration` 不传时按 1 分钟冻结并结算，请如实传入源视频时长以免费用与预期不符。

---

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误（如 `videoUrl` 为空、`quality` 取值不合法） |
| 10005 | API Key 无效或缺失 |
| 10006 | 余额不足 |
| 30003 | 任务不存在 |
| 90003 | 服务器内部错误 |

---

## 最佳实践

1. **源视频可公网访问**：`videoUrl` 需为无鉴权、可直接下载的地址，否则任务会因下载失败而失败（失败自动解冻，不扣费）。
2. **如实传 `duration`**：这是唯一影响费用的时长口径，建议在提交前读取视频元信息拿到真实秒数。
3. **档位按交付需求选**：轻量提清选 `720p`，常规高清交付选 `1080p`；大屏/影视级交付再考虑 `2k` / `4k`，耗时与费用同步上升。
4. **轮询间隔**：
   - 前 30 秒：每 3 秒查询一次
   - 30 秒 ~ 2 分钟：每 5 秒查询一次
   - 2 分钟后：每 10 秒查询一次
5. **优先用回调**：配置 `callbackUrl` 可显著减少轮询开销，同时保留低频轮询作为兜底。