视频超清放大接口文档
把视频做等比超清放大,输出长边约 1920,比例不变。异步受理,完成后查询或回调。
把一段视频做等比超清放大。输入一个视频地址,输出画质提升、比例不变的 MP4,不带平台水印。时长按源片保留。本接口是异步的:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。
上游是 SeedVR2 7B。输出长边固定约 1920:先把长边预处理到 960,再按 2 倍放出,宽高按 32 对齐。
| 源片 | 典型产物 |
|---|---|
| 横屏 | 1920×1088 |
| 竖屏 | 1152×1920 |
| 长边小于 1920 | 放大到长边约 1920 |
| 长边大于 1920 | 收到长边约 1920,再做细节增强 |
这不是 4K 接口。产物尺寸以实际文件为准。业务需要 4K 时要单独开通,不在本接口的默认行为里。
10 秒、1080p 的素材大约 2.5–3 分钟。用回调或轮询,不要在一次请求里等到完成。
| 方法与路径 | 产品编码 | 说明 |
|---|---|---|
POST /api/video_upscale | video_upscale | 提交视频超清放大任务 |
GET /api/tasks/{request_id} | — | 查询任务 |
不填回调地址也可以提交,结果用查询接口获取。
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | https://star-api.aiaibase.com |
路径接在根地址后面。例如测试环境提交:
POST https://test-star-api.aiaibase.com/api/video_upscale请求体为 JSON,Content-Type: application/json。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 由平台签发,只能放在服务端。浏览器或前端仓库里不要出现 Key,由自己的后端转发。测试 Key 向平台单独申请,不要复用线上 Key。
输入必须是服务端能直接下载的 http 或 https 地址。处理期间地址必须有效,签名地址至少留 10 分钟。支持 MP4、MOV、WebM,不支持 m3u8。建议单文件不超过 100MiB。内网地址、需要登录或 Cookie 的地址会处理失败。
放大只改分辨率,不做补帧,也不去水印。需要去水印时使用视频去水印或视频去水印快速版。
所有响应都是同一结构。业务结果看 success 和 error.code。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据。失败时不返回 |
error | object | 失败时的错误。含 code、message,参数错误时还有 details |
meta.request_id | string | 平台任务号。查询和排查都用这个值 |
meta.timestamp | string | 响应时间 |
{
"success": false,
"error": {
"code": 4107,
"message": "video_url 视频链接不合法",
"details": [{ "field": "video_url", "message": "视频链接不合法" }]
},
"meta": { "request_id": "…", "timestamp": "…" }
}调用方请求号:
- 字段为
client_request_id。建议每次提交都带。 - 这是调用方自己的单号,和响应里的
meta.request_id不是同一个值。 - 同一密钥下,相同调用方请求号且请求体完全一致时,返回首次任务,不会重复建单。
- 同一密钥下,调用方请求号相同但请求体不同,返回 HTTP 409,业务码
4003。换一个请求号,或把请求体改回第一次。 - 不带
client_request_id时,每次提交都会新建一单。重跑同一条素材要换一个新的请求号,否则会拿到上一次的结果。
受理成功只表示任务已收下,成片还没生成,此时 data.status 为字符串 accepted。拿结果有两种方式,可以同时用:
- 轮询
GET /api/tasks/{request_id}。15 秒一次起步,2 分钟后放宽到 30–60 秒。 - 提交时传
notify_url(或别名callback_url、notice_url)。任务进入终态后,平台 POST 一份与查询接口相同的 JSON。对方返回 HTTP 2xx 视为成功,否则 30 秒后重试,最多 4 次。
多数场景直接挂回调,轮询作兜底。提交后把 meta.request_id 存下来。回调可能重复,按 meta.request_id 做幂等。回调地址需公网可达。
批量提交走上游队列。同一时间大量提交会排队,建议并发从 3 开始控制。
- 方法:
POST - 路径:
/api/video_upscale - 产品编码:
video_upscale
请求参数
| 字段 | 必填 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
video_url | 是 | string | — | 源视频地址,http 或 https。不支持 m3u8 |
video_format | 否 | string | video/h264-mp4 | 输出编码:video/h264-mp4、video/h265-mp4 |
is_encrypt | 否 | bool | false | 是否加密交付。见下方加密交付 |
bid | 否 | string | — | 业务编号,最多 200 字,原样回传 |
title | 否 | string | — | 任务标题,最多 200 字,原样回传 |
client_request_id | 否 | string | — | 调用方请求号。建议必带 |
notify_url | 否 | string | — | 完成回调地址 |
callback_url | 否 | string | — | notify_url 的别名 |
notice_url | 否 | string | — | notify_url 的别名 |
没有放大倍数、目标分辨率、宽高这类参数。倍率由上游固定。
约束:
video_format只接受video/h264-mp4和video/h265-mp4。image/webp会返回 HTTP 400,业务码1001。- 表外字段会返回 HTTP 400,业务码
1001。不要传max_side、scale_by、width、height。
受理返回
此时成片还没生成。保存 meta.request_id 用于查询。
| 字段 | 类型 | 说明 |
|---|---|---|
data.status | string | 固定为 accepted |
data.client_request_id | string | 调用方请求号。没传时可能不返回 |
meta.request_id | string | 平台任务号 |
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "biz-order-20261117-001"
},
"meta": {
"request_id": "2b6c1fb2-3eeb-49e8-95ed-ff53f415e007",
"timestamp": "2026-11-14T11:51:59Z"
}
}请求示例
curl -X POST 'https://test-star-api.aiaibase.com/api/video_upscale' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://cdn.example.com/source.mp4",
"video_format": "video/h264-mp4",
"client_request_id": "biz-order-20261117-001",
"notify_url": "https://your.host/hooks/upscale"
}'- 方法:
GET - 路径:
/api/tasks/{request_id} request_id:受理响应里的meta.request_id
只能查询当前密钥自己的任务。
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
-H 'Authorization: Bearer {API Key}'处理中。这里的 data.status 是字符串 accepted,不是数字:
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "biz-order-20261117-001"
},
"meta": { "request_id": "…", "timestamp": "…" }
}完成判定
完成条件是 success 为 true,data.status 为 2,且 data.error_code 为 SUCCESS。成品地址在 data.out_data,取第一个元素。
success 为 false 表示失败,看 error.code 和 error.message。失败响应里没有 data.status。
明文交付时,out_data 是成片地址数组。加密交付时,out_data 是对象数组,结构见下方加密交付。
明文成功
下面是一单 10 秒、1080p 素材的结果。产物长边约 1920,不是 4K。
{
"success": true,
"data": {
"client_request_id": "biz-order-20261117-001",
"status": 2,
"error_code": "SUCCESS",
"is_encrypt": false,
"is_watermark": false,
"out_data": ["https://images.aiaipic.win/…/video/output.mp4"],
"video_format": "video/h264-mp4",
"video_url": "https://cdn.example.com/source.mp4",
"task_type": "video_upscale"
},
"meta": { "request_id": "…", "timestamp": "…" }
}| 字段 | 说明 |
|---|---|
out_data | 成片地址数组。明文交付时每个元素是 MP4 地址 |
status | 成功为数字 2。处理中是字符串 accepted |
error_code | 成功时为 SUCCESS |
is_encrypt | 是否加密交付 |
is_watermark | 成片是否带平台水印。成功时为 false |
task_type | 固定为 video_upscale |
client_request_id | 调用方请求号 |
结果里还可能带上游透传字段,例如 task_id、workflow_name、created_at、updated_at。workflow_name 里可能出现 2160,那是工作流名字,不代表产物是 4K。这些字段不稳定。程序只依赖本文档列出的字段。成片地址拿到后尽快转存。
失败
{
"success": false,
"error": { "code": 3600, "message": "上游异常原文" },
"meta": { "request_id": "…", "timestamp": "…" }
}3600 表示上游处理失败,例如源地址不可达、解码失败、签名过期或模型报错。失败不计费。改完源或参数后,换一个新的 client_request_id 重新提交。
请求体带了 notify_url、callback_url 或 notice_url 时,任务进入终态后,平台向该地址 POST。没有回调地址时不会 POST。
| 项 | 值 |
|---|---|
| 方法 | POST |
| 请求体 | 与 GET /api/tasks/{request_id} 的响应 JSON 相同 |
Content-Type | application/json |
| 成功条件 | 回调地址返回 HTTP 2xx |
| 重试 | 非 2xx 或连接失败时,30 秒后重试,最多 4 次 |
用 meta.request_id 对应自己的业务单。成功时按 data.is_encrypt 读取 data.out_data。
is_encrypt 为 true 时,产物走加密链路,和视频去水印快速版是同一套交付。默认 false,需要可直接下载的 MP4 时不要打开。
{
"success": true,
"data": {
"status": 2,
"error_code": "SUCCESS",
"is_encrypt": true,
"out_data": [
{
"download_url": "https://p0-static.inaiai.com/encrypt/…/stream.m3u8",
"encryption_key": "https://p0-static.inaiai.com/encrypt/…/enc.key"
}
],
"video_format": "video/h264-mp4",
"task_type": "video_upscale"
},
"meta": { "request_id": "…" }
}- 加密产物是 HLS + AES-128,不是 MP4。
download_url是 m3u8 播放列表,encryption_key是 AES key。 - key 是公开 URL。支持 HLS 的播放器拿到播放列表后会自己取 key,调用方不用实现解密。
- Web 使用 hls.js,key 域名需要允许跨域。iOS / Safari 原生支持 HLS。Android 使用 ExoPlayer。
- 不能把
download_url直接放进<video src>。业务要一个可直传的 MP4 时,不要走加密交付。
| HTTP | 业务码 | 说明 |
|---|---|---|
| 400 | 1001 | 参数错误。未知字段、取值非法,或 video_format 传了 image/webp。看 error.details[].field |
| 400 | 4102 | 缺少 video_url |
| 400 | 4107 | video_url 不是合法的 http 或 https 链接。m3u8 源也会被拒绝 |
| 401 | 1102 | 缺少 Authorization |
| 401 | 5003 | API Key 无效或已停用 |
| 200 | 5204 | 未开通该产品 |
| 200 | 3600 | 上游处理失败。源不可达、解码失败或超时。不计费 |
| 200 | 9001 | 系统负载过高,稍后重试 |
| 409 | 4003 | 同一调用方请求号,请求体不同 |
| 500 | 1500 | 服务器内部错误。排查时带上 meta.request_id |
按输出视频的秒数计费,档位由产物分辨率自动确定,调用方不能自选。不足 1 秒按 1 秒,其余向上取整到整秒。失败不计费。同一调用方请求号且请求体相同的重复提交不重复计费。余额不足时拒绝受理,充值后重新提交。响应里不返回金额。
当前默认倍率下,产物长边约 1920。横屏 1080p、竖屏 1080p,以及 720p 及更低的源片,产物都在这一档附近。更高档要产物面积真正达到对应范围才会命中,默认链路不会产生。计费看产物,不看源片分辨率。
| 项 | 值 |
|---|---|
| 环境 | https://test-star-api.aiaibase.com |
| 样片 | https://test-videos.co.uk/vids/jellyfish/mp4/h264/1080/Jellyfish_1080_10s_1MB.mp4(10 秒,1080p) |
| 预期 | 约 2.5–3 分钟后 data.status 为 2,out_data 为一条 MP4,长边约 1920 |
BASE=https://test-star-api.aiaibase.com
curl -s -X POST "$BASE/api/video_upscale" \
-H "Authorization: Bearer {API Key}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://test-videos.co.uk/vids/jellyfish/mp4/h264/1080/Jellyfish_1080_10s_1MB.mp4",
"client_request_id": "demo-upscale-0001"
}'
curl -s "$BASE/api/tasks/{request_id}" \
-H "Authorization: Bearer {API Key}"success 为 true、data.status 为 2 且 data.error_code 为 SUCCESS 时,取 out_data 的第一个地址。success 为 false 时看 error.code 和 error.message。