Upscale Video

Upscale Video（产品 upscale_video）把视频放大到 1080p、2k 或 4k，保留音轨。有 bytedance、topaz 两种放大服务，参数和计费方式不同。一个任务出 1 段视频，按源视频计价。

创建任务

用所有模型共用的创建任务接口，model 传 "upscale-video"。接口通常不到 1 秒返回，几秒内在后台读取源视频、冻结费用；任务结束后获取结果。

请求头

请求体

用 bytedance 放大到 1080p、24 帧：

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b4d2f7a-6e1c-4c8b-a3f5-8d0e6b2a9c47" \
  -d '{
    "model": "upscale-video",
    "video_url": "https://example.com/clip.mp4",
    "provider": "bytedance",
    "resolution": "1080p",
    "fps": 24,
    "preset": "common"
  }'

用 topaz 放大到 4k（不传 fps、preset），请求体是：

{
  "model": "upscale-video",
  "video_url": "https://example.com/clip.mp4",
  "provider": "topaz",
  "resolution": "4k"
}

响应：200 OK。data 是刚创建的任务，只有下面这几个字段，各字段的含义见创建任务的返回。保存 data.id，用它获取结果。创建后几秒内才冻结费用，任务可能在这时失败（例如源视频读不了），以查询或回调的结果为准。

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jbm6e8g1j4k7n0s3v6y9c2d5",
    "model": "upscale-video",
    "status": "queued",
    "error": null,
    "created_at": "2026-11-03T08:30:00Z"
  }
}

获取结果

实测从创建到结束的耗时：10 秒的视频放大到 1080p，topaz 约 2 分钟，bytedance 约 2.5 分钟；长视频会久得多，生成服务忙时也会更慢。任务结束（成功或失败）后用下面任一方式拿结果：

• 回调（生产环境推荐）：创建时传了 webhook_url，任务结束时会把完整的任务推送一次，见回调。
• 轮询：用 data.id 调用 GET /v1/tasks/{task_id}，间隔 15 秒以上，直到 status 为 succeeded 或 failed；多个任务用列出任务的 ids 一次查询。

上面 bytedance 的请求成功后（省略了其他字段）：

{
  "status": "succeeded",
  "input": {
    "video_url": "https://example.com/clip.mp4",
    "provider": "bytedance",
    "resolution": "1080p",
    "fps": 24,
    "preset": "common"
  },
  "num_outputs": 1,
  "outputs": [
    {
      "index": 0,
      "type": "video",
      "url": "https://cdn.nanoapi.ai/h/tk_01jbm6e8g1j4k7n0s3v6y9c2d5_1_1793694600.mp4",
      "preview_url": "https://cdn.nanoapi.ai/h/tk_01jbm6e8g1j4k7n0s3v6y9c2d5_1_1793694600_compressed.mp4"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "…", // 按源视频算出的价格，见价格
    "charged": "…", // 一样，偶尔略少
    "refunded": "0.00",
    "billed_seconds": null
  }
}

失败时冻结的钱全额退回，原因在 data.error.type，见错误。完整的字段见任务对象。

素材

视频以公开的 http(s) 链接放在 video_url 里提交。不提供上传接口，请自行托管文件。链接最长 4096 字符，必须能直接下载，不能指向 localhost 或内网、回环、保留地址。

任务结束前链接要保持可访问，有有效期的链接也不能提前过期。

实测过的时长

180 秒以内的也不保证都能成功。下面是实测成功过的范围，超出的可能失败，冻结的钱全额退回（invalid_media、video_too_long、invalid_request 或 generation_failed）：

价格

bytedance：费用 = 每秒单价（按分辨率和 fps）× 源视频时长
topaz：    费用 = 每次的固定费用 + ceil(源视频帧数 × 每帧单价 ÷ 取整步长) × 取整步长

正在读取当前价格…

• bytedance：源视频画面（视频轨）的时长，不取整。fps 为 60 时每秒单价翻倍；preset 不影响价格。
• topaz：源视频的帧数，平台读取视频后才知道。按帧计算的部分向上取整到 price_step（GET /v1/products 里 topaz 那几行的字段）的整数倍。请用整数微美元（金额 × 1,000,000）计算，不要用浮点数：浮点除法可能比整数多出一点点（JavaScript 里 0.07 / 0.01 是 7.000000000000001），向上取整时就多算一档。
• 创建后几秒内读取源视频、算出价格再冻结。成功后扣冻结的金额，偶尔略少（少数视频在生成时会被重新处理，例如手机剪辑留下的隐藏帧、重新编码），不会更多；失败全额退回。冻结和扣费的通用规则见计费。
• billing.billed_seconds 一直是 null。

例：10 秒的视频用 bytedance 放大到 1080p、24 帧（上面第一个请求），费用是 10 × 1080p、24 帧的每秒单价。10 秒、24 帧（240 帧）的视频用 topaz 放大到 4k，费用是 4k 每次的固定费用 + 240 × 4k 的每帧单价，按帧计算的部分向上取整到 price_step 的整数倍。

想在提交前显示价格：自己读出视频的时长（topaz 的帧数按时长 × 帧率估算），用 GET /v1/products 返回的当前单价计算：upscale_video 产品的 prices 按 provider、resolution、fps 每种一行；topaz 那几行的 billing_unit 是 frame，每次的固定费用在 base_price，取整步长在 price_step。价格会调整，不要写死。算出来的是预估，实际费用以查询任务返回的 billing.frozen 为准（创建后几秒内冻结）。

错误

这个模型特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误，全部失败原因见失败原因。

创建请求出错：请求返回 HTTP 错误，任务不会创建。param 是对应的参数名。

创建接口的其他错误（401、402、429 等）见创建任务 → 错误。

任务失败：创建请求成功（200），任务之后变成 failed。这种情况没有 HTTP 状态码，原因在任务的 error.type，通过查询任务或回调拿到。

所有失败的任务都已全额退回冻结金额，billing.charged 为 "0.00"。程序判断请用 error.type：括号里的 message 用于展示，措辞可能调整，见每种原因的 message。