博客

使用指南

通过 HiAPI API 使用 topaz-upscale/video:短视频画质提升工作流

帧插值、增强设置,以及一个可用的竖屏视频 HiAPI 请求

2026年11月20日
抽象封面艺术,深松绿背景上绘有鼠尾草绿与雾绿色切面的大型对分棱柱,平面几何编辑风格。
本页内容

为什么短视频需要自己的画质提升方案

竖屏短视频——也就是在手机屏幕上停留十五到六十秒的那类片段——出问题的方式与长视频不同。横屏纪录片可以借助运动模糊和背景细节掩盖画面的绵软。而竖屏片段会被观众全神贯注地观看,画面被裁切到狭窄的取景框,还常常被托管平台重新压缩。源视频中的任何弱点都会被放大,而不是被宽容。

这就改变了画质提升要解决的问题。面对长视频素材,你或许只需提升一个母版的画质就完事了。而面对短视频,你通常要处理的源文件已经为移动端编码过一次(甚至两次),随后又被交付给一个会再次编码的平台。目标不只是一个更高的分辨率数字,而是一个能在下一轮压缩中存活下来的文件:边缘干净、运动稳定、整帧细节一致。

因此,请把这当作一条流水线,而不是一次调用:

  1. 规范化源文件——裁剪到精确的剪辑点,锁定宽高比,并在提升画质之前确定帧率。
  2. 提升画质并增强,使用 topaz-upscale/video,审慎设置帧插值和增强。
  3. 验证输出与源文件是否一致,然后再发布,因为画质提升在锐化画面的同时,也很容易把纹理抹平。

每个步骤都有自己的失败模式。裁剪错误的片段会浪费运行时间。粗心的插值会制造出不自然的运动。跳过验证会把瑕疵直接送到观众面前。本指南的其余部分将按顺序逐一讲解每个决策,然后展示一个可用的 HiAPI 请求,供你适配自己的素材使用。

竖屏片段在保持宽高比的同时,切面密度——以及分辨率——随之增长。

topaz-upscale/video 在 HiAPI 上的功能

topaz-upscale/video 是 HiAPI 模型目录中的视频画质提升端点。你向它发送视频素材以及设置,它返回一个已提升画质的视频。这就是全部约定——其余都是配置。

请这样把它定位到你的处理链中:

  • 输入:API 能够获取的视频,通常是你的源文件 URL。你已在此步骤之前完成宽高比规范化和剪辑;模型只提升你给它的内容。
  • 处理:服务按照你指定的画质提升和增强设置运行你的片段,包括在你启用时的帧插值。
  • 输出:任务结果中引用的已提升画质的视频素材,你下载后交给发布步骤。

面向开发者的几点实用说明:

  • 这是一个任务,而不是同步响应。视频处理耗时与时长和设置成正比,因此 API 在首次响应时返回的是一个任务(供你轮询或等待),而不是成片文件。
  • 运行时间随片段长度增长。更长的片段或更重的设置会消耗更多处理时间。短视频在这方面是优势——迭代成本低。
  • 参数以在线文档为准。topaz-upscale/video 的确切参数名、可接受取值和默认值由 HiAPI 当前模型文档定义。不要因为桌面工具或其他厂商使用了相似的名称,就假定某个参数存在。构建前请查看模型页面。

该模型在你的流水线中恰好处于一个位置:规范化之后,验证与发布之前。保持这个边界清晰,工作流的其余部分就依然简单。

该模型作为链中的单个处理阶段:一个输入视频进,一个已提升画质的输出视频出。

为短视频节奏规划帧插值

帧插值会合成中间帧,以提高有效帧率——例如把 24 或 30 fps 的源文件变成更流畅的 60 fps 输出。在短视频上,人们很容易到处启用它,因为流畅的运动看起来更高级。但这种直觉通常是错误的。

插值何时有帮助

  • 快速运镜或甩镜。竖屏片段常用快速运动,在低帧率下会抖动。插值可以平滑扫过的运动。
  • 慢动作或变速序列。如果你以低帧率拍摄再放慢,插值可以填补间隙并减少卡顿。
  • 源帧率已接近目标帧率。从 30 fps 提升到 60 fps 是一种适度、可预测的提升。

何时只增加成本而没有可见收益

  • 静态口播镜头。如果画面几乎不变,插值帧与周围帧几乎相同。你白白付出了运行时间。
  • 已是高帧率的源。把 60 fps 插值到 120 fps 可能无论如何都熬不过平台重新编码。
  • 严重运动模糊或质量极低的源。插值会猜测它看不清的运动,而这些猜测会在边缘附近表现为扭曲或重影。

一个审慎的默认设置

对大多数短视频工作,开始时把插值关闭,按源帧率提升画质,然后检查结果。如果运动抖动,就在能解决问题的最低目标帧率下启用插值。一次只改一个变量,这样你才能知道是什么带来了改善——或者瑕疵。

还要记住,插值会与运行时间相互影响。每个插值帧都是额外的工作。在十五秒的片段上差异很小;在成百上千的批次中则会累积。在把某个设置应用到整个队列之前,先在一个有代表性的片段上测量。

不靠猜测选择增强设置

增强设置控制模型锐化、降噪和恢复细节的力度。不存在通用的“最佳”配置,因为合适的量取决于你的源画质以及片段将在哪里发布。

从源出发,而不是从目标出发

在触碰任何设置之前,先对输入问两个问题:

  1. 源有多干净?清晰的相机原始素材可以承受轻度增强。被重度重新压缩或低码率的源需要更多克制,因为增强会把压缩伪影和真实细节一起放大。
  2. 平台会对它做什么?每个主流短视频平台都会重新编码上传内容。在你的显示器上看起来不错的激进锐化,在第二次编码后可能变成振铃和光晕。

一个实用的决策框架

  • 高质量原始素材、适度提升:使用保守的增强。让放大器完成工作,把锐化保持在最低程度,以便纹理能在平台压缩后存活。
  • 绵软或已压缩的源:先依靠降噪,再做适度锐化。对噪声源过度锐化会产生脆硬的边缘,比原来的绵软更难看。
  • 文字、人脸和产品细节:短视频片段通常依赖清晰可读的字幕和清晰的人脸。请专门验证这些区域——对风景有帮助的增强可能把精细文字抹糊。
  • 运动密集的片段:把保守增强与你对插值的决策搭配起来。重度锐化加插值是闪烁伪影最常见的来源。

确认实际可用的选项

确切的增强参数、其可接受范围以及任何预设,都由 HiAPI 针对 topaz-upscale/video 的在线模型文档定义。参数名和默认值可能变化,且不一定与你用过的其他工具一致。阅读模型页面,在请求中显式设置值,避免依赖记忆中的默认值。拿不准时,在同一段短片段上运行两种设置并比较——这比在整批上猜测更便宜。

一个可用的 topaz-upscale/video HiAPI 请求

编写请求之前,先设置两个环境变量,让你的密钥永远不会进入源代码管理:

export HIAPI_API_KEY="your_api_key_here"
export SOURCE_VIDEO="https://your-bucket.example.com/clips/cut_vertical.mp4"

现在提交一个任务。下面的结构就是模式:让请求指向该模型,传入源视频 URL,并显式包含你的画质提升和插值设置。查阅 HiAPI 模型文档中 topaz-upscale/video 的确切参数名和可接受取值,然后调整请求体以匹配。

curl -X POST "https://api.hiapi.ai/v1/models/topaz-upscale/video/jobs" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "video_url": "'"$SOURCE_VIDEO"'"
    },
    "settings": {
      "upscale": {
        "target_resolution": "1080p"
      },
      "frame_interpolation": {
        "enabled": false
      },
      "enhancement": {
        "strength": "conservative"
      }
    }
  }'

预期什么以及如何应对:

  • 响应包含任务标识符和状态。保存任务 ID——你需要它来获取结果。
  • 轮询或等待。短片段很快完成,但始终要编写你的客户端来处理待处理状态,而不是假定首次读取就已完成。
  • 获取输出素材,从已完成的任务中下载到你自己的存储,然后再加入发布队列。
  • 重新提交,而不是修补。如果你想测试启用插值,就发送一个改了标志的新任务。每个任务只保留一个变量,比较才诚实。

第一个请求也是你最快的验证:在围绕它构建任何自动化之前,先用你自己的片段、真实的宽高比和时长运行它。

请求生命周期:任务进入队列,被轮询,最终解析为输出素材。

验证结果并把画质提升融入流水线

已提升画质的文件并不自动就是更好的文件。验证是把模型调用变成可靠工作流的步骤。

要检查什么

  • 边缘和精细细节。放大文字、人脸和硬边缘。寻找源文件没有的光晕、振铃或抹糊的纹理。
  • 运动一致性。以正常速度观看快速运动片段。插值伪影会在单帧上表现为扭曲或重影——暂停并逐帧检查。
  • 色彩和曝光。确认输出在色调或亮度上没有偏移;增强可能微妙地改变对比度。
  • 音频和时长。确保片段长度相同,音轨完整到毫秒。重新编码后发生漂移的音轨会破坏字幕同步。
  • 平台压缩之后。私下上传一份测试副本,检查重新编码后的版本,因为那才是观众实际看到的。

在流水线中放在哪里

一条干净的短视频流水线如下:

  1. 编辑并导出最终剪辑,使用原生分辨率和稳定的帧率。
  2. 上传源文件到 API 可访问的存储。
  3. 提交画质提升任务,使用显式设置,并把任务 ID 与片段一起记录。
  4. 下载并验证输出,使用上述检查。
  5. 发布——直接发布或进入一个跨平台排期发布的队列。

两条运营说明。保留原始源文件;绝不要用已提升画质的版本覆盖它,因为你会想用不同设置重新运行。并且为每个片段记录设置,这样当某个输出看起来不对时,你能准确追溯到是哪个配置产生的它。这种可追溯性让你能够随时间调整设置,而不是每一批都重新猜测。

成本、限制以及规模化之前要确认的事项

在把生产流量路由到 topaz-upscale/video 之前,请从 HiAPI 当前的模型文档中确认运营细节,而不是根据其他工具做假设。

  • 计费依据。了解该模型如何计费——例如按输出时长还是按分辨率档位——并查看实时价格面板获取当前数字。价格可能变动,这是你绝不该从记忆或论坛帖子中硬编码的一项。
  • 时长和文件大小限制。输入有最大时长和大小限制;短视频通常轻松落在限制内,但包含更长源的批量任务可能不会。提交前确认上限。
  • 吞吐量和并发。你能并行运行多少任务,以及是否存在速率限制,决定了队列的形态。设计你的客户端,在收到速率限制响应时退避并重试。
  • 超时行为。视频任务可能比典型 HTTP 请求耗时更长。确认推荐的轮询间隔和任务保留窗口。
  • 参数稳定性。把模型的设置视为一份在线约定的一部分。集成时阅读文档,当行为出乎意料时重新检查。

一个好的扩展模式:验证一个有代表性的片段,测量其实际运行时间和成本,然后保守地外推并加入缓冲。把价格和限制放在配置中,而不是代码中,这样更新只需改配置而无需部署。

先从 topaz-upscale/video 上的一个片段开始,验证它,然后扩展——这是通向一条可信赖的短视频画质提升流水线的最快路径。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档