视频超清放大接口文档

把视频做等比超清放大,输出长边约 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_upscalevideo_upscale提交视频超清放大任务
GET /api/tasks/{request_id}—查询任务

不填回调地址也可以提交,结果用查询接口获取。

环境根地址
测试https://test-star-api.aiaibase.com
正式https://star-api.aiaibase.com

路径接在根地址后面。例如测试环境提交:

text
POST https://test-star-api.aiaibase.com/api/video_upscale

请求体为 JSON,Content-Type: application/json。认证只使用请求头:

text
Authorization: Bearer {API Key}

{API Key} 由平台签发,只能放在服务端。浏览器或前端仓库里不要出现 Key,由自己的后端转发。测试 Key 向平台单独申请,不要复用线上 Key。

输入必须是服务端能直接下载的 http 或 https 地址。处理期间地址必须有效,签名地址至少留 10 分钟。支持 MP4、MOV、WebM,不支持 m3u8。建议单文件不超过 100MiB。内网地址、需要登录或 Cookie 的地址会处理失败。

放大只改分辨率,不做补帧,也不去水印。需要去水印时使用视频去水印或视频去水印快速版。

所有响应都是同一结构。业务结果看 success 和 error.code。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据。失败时不返回
errorobject失败时的错误。含 code、message,参数错误时还有 details
meta.request_idstring平台任务号。查询和排查都用这个值
meta.timestampstring响应时间
json
{
  "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否stringvideo/h264-mp4输出编码:video/h264-mp4、video/h265-mp4
is_encrypt否boolfalse是否加密交付。见下方加密交付
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.statusstring固定为 accepted
data.client_request_idstring调用方请求号。没传时可能不返回
meta.request_idstring平台任务号
json
{
  "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"
  }
}

请求示例

bash
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

只能查询当前密钥自己的任务。

bash
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
  -H 'Authorization: Bearer {API Key}'

处理中。这里的 data.status 是字符串 accepted,不是数字:

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

json
{
  "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。这些字段不稳定。程序只依赖本文档列出的字段。成片地址拿到后尽快转存。

失败

json
{
  "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-Typeapplication/json
成功条件回调地址返回 HTTP 2xx
重试非 2xx 或连接失败时,30 秒后重试,最多 4 次

用 meta.request_id 对应自己的业务单。成功时按 data.is_encrypt 读取 data.out_data。

is_encrypt 为 true 时,产物走加密链路,和视频去水印快速版是同一套交付。默认 false,需要可直接下载的 MP4 时不要打开。

json
{
  "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业务码说明
4001001参数错误。未知字段、取值非法,或 video_format 传了 image/webp。看 error.details[].field
4004102缺少 video_url
4004107video_url 不是合法的 http 或 https 链接。m3u8 源也会被拒绝
4011102缺少 Authorization
4015003API Key 无效或已停用
2005204未开通该产品
2003600上游处理失败。源不可达、解码失败或超时。不计费
2009001系统负载过高,稍后重试
4094003同一调用方请求号,请求体不同
5001500服务器内部错误。排查时带上 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
bash
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。