视频超分增强 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 分钟）。该值只在创建时用于计费冻结，任务完成后不会按实际视频时长二次调整，所以传得不准会导致费用与预期不符。

请求示例

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	创建时间

响应示例

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

查询任务状态

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

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	最后更新时间

响应示例

处理中

{
  "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"
  }
}

成功

{
  "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"
  }
}

失败

{
  "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

{
  "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	服务器内部错误

最佳实践

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