博客

教程

如何通过 HiAPI API 使用 topaz-upscale/video:curl 与 Python 示例

2026年11月17日
封面图:数张半透明玻璃薄片以克制角度交叠,在浅色背景上折射出冷蓝色平行色带,画面无文字。
本页内容

topaz-upscale/video 的功能与适用场景

topaz-upscale/video 是 HiAPI 上的视频增强端点。你向它发送源视频和指令,它会返回增强后的视频:更高分辨率、重建的精细细节,并可选地通过帧插值实现更平滑的运动。当素材已经存在、问题在于质量而非内容生成时,就应该使用这个端点。

适用场景

与该端点自然匹配的典型任务:

  • 档案与老旧素材——旧录像、压缩屏幕录制或继承的媒体,需要在现代分辨率下显得拿得出手。
  • 渲染管线——为速度而先以低分辨率渲染的已完成序列,随后增强用于交付。
  • 运动清理——低帧率源需要插值帧以避免播放时卡顿。
  • 交付变体——一个母版,多个输出层级,按层级分别应用增强。

何时选择它而非替代方案

决策通常归结为三个问题:

  1. 问题在于分辨率和细节,还是在于内容?如果你需要凭空发明新像素(从未拍摄过的场景),那这是错误的工具。增强假定底层有真实的源帧。
  2. 你的管线能容忍异步工作吗?视频任务不是瞬时的。如果你的用户体验要求亚秒级响应,这个端点应放在后台任务中,而非请求处理器中。
  3. 你需要帧插值和放大吗?如果运动平滑度很重要,你希望在一次处理中同时获得两种能力,而不是串联多个独立工具。topaz-upscale/video 两者都覆盖。

如果你的源是单张静态图像,请改用图像放大器。如果源本身没问题但编码很差,先修复编码——增强无法恢复重度压缩已经销毁的细节,而且你会为计算付费却得不到质量提升。

首次调用前准备请求

大多数首次调用的失败源于缺失环节,而非糟糕的提示词。在编写任何代码之前,先把这些准备好。

账户与凭证

你需要一个有权访问 topaz-upscale/video 的 HiAPI API 密钥。将密钥保存在环境变量中而非源代码里——下面每个示例都从环境读取 HIAPI_API_KEY。

export HIAPI_API_KEY="your-key-here"

可访问的源媒体

模型必须能够获取你的输入。两种可靠模式:

  • 公开或签名 URL——服务无需交互式认证即可下载的 URL。如果你的存储需要签名链接,请生成一个有效期充裕的链接,并记得在重试时重新生成,否则长任务会在中途失败。
  • 先上传——通过平台的上传机制推送文件并引用返回的标识符。对于大文件和私有网络后面的任何内容,这是更安全的选择。

值得检查的源特征

在花费一次调用之前,确认:

  • 时长。长视频意味着长任务。如果你在测试,从源中间截取 5–10 秒的片段——中间通常比开头帧更具代表性。
  • 编解码器与容器。罕见编解码器有时无法解码。如有疑问,重新封装为常见容器。
  • 帧率。精确记录;在推理帧插值时会用到。
  • 分辨率。记录精确的源尺寸,这样你的前后对比才诚实。

明确你的输出目标

在首次调用之前决定输出分辨率和帧率,而不是之后。对 720p 源升到 1080p 合理的增强设置,与 480p 源升到 4K 的设置不同。把目标写下来;你将在后续每个请求中复用它。

使用 curl 发起调用

请求是向 topaz-upscale/video 端点发送一个带 JSON 体的 POST。以下是一个完整可运行的示例——替换为你自己的媒体 URL。

curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale/video",
    "input": {
      "video": "https://your-bucket.example.com/clips/source_720p.mp4"
    },
    "parameters": {
      "target_resolution": "1080p",
      "target_fps": 60,
      "interpolation": "smooth",
      "detail": "balanced"
    },
    "prompt": "恢复织物和皮肤上的精细纹理,保持颗粒自然,插值到 60fps 且无重影"
  }'

解读响应

即时响应会确认任务。你会收到任务标识符和状态字段。视频工作是异步的,因此实际模式是:

# 1. 提交并捕获任务 id
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq -r '.id')

# 2. 轮询直到状态为终态
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'

读取结果时,三个字段很重要:

  • status——从排队到运行再到终态。将任何无法识别的状态视为“继续等待”,而非成功。
  • output——成功时存在,包含增强视频的 URL 或标识符。
  • error——失败时存在。按字面阅读消息;它通常会指出有问题的字段。

如果你在迭代提示词,将请求体放入文件(request.json)并使用 -d @request.json。这能保持 shell 历史干净,并让你对同一请求的不同版本进行 diff。

从 Python 调用同一端点

Python 版本是同一 HTTP 契约的薄包装。使用 requests,将密钥保存在环境中,并将提交与轮询循环包装在函数中,这样调用方无需知道它是异步的。

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

def enhance_video(
    video_url: str,
    prompt: str,
    target_resolution: str = "1080p",
    target_fps: int = 60,
    poll_interval: float = 5.0,
    timeout: float = 1800.0,
) -> str:
    payload = {
        "model": "topaz-upscale/video",
        "input": {"video": video_url},
        "parameters": {
            "target_resolution": target_resolution,
            "target_fps": target_fps,
            "interpolation": "smooth",
            "detail": "balanced",
        },
        "prompt": prompt,
    }

    resp = requests.post(f"{BASE}/video/enhance",
                         headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["output"]["video"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "增强失败"))
        time.sleep(poll_interval)

    raise TimeoutError(f"任务 {job_id} 未在预期时间内完成")

在真实管线中使用它的注意事项

  • 轮询采用指数退避。固定五秒间隔对 shell 脚本没问题;生产环境中应退避并设置间隔上限。长视频可能需要一段时间,更频繁地轮询不会让它们更快完成。
  • 幂等性。如果提交调用超时,你可能不知道任务是否已启动。将请求体与任务 id 一起记录,以便核对重复项,而不是盲目重新提交。
  • 持久化任务 id。收到后立即写入数据库。如果进程在轮询中途死亡,你可以按 id 恢复,而不用为第二次增强付费。

帧插值的提示词配方

帧插值是提示词最容易出错的地方——要么太模糊无法引导任何东西,要么过于规定性,导致模型追求矛盾的目标。提示词与结构化参数并存;让措辞关于意图和运动特征,让参数承载数值目标。

模式:描述运动,而非数学

较差:

interpolate

较好:

插值到平滑的 60fps。保持原始运动节奏——不改变速度。平移和摄像机运动应线性且稳定;避免帧边缘的扭曲。

你已经在 parameters 中告诉 API 目标帧率。提示词应描述这段素材的平滑运动看起来是什么样。

模式:点名要避免的伪影

将 24p 平滑到 60fps。避免快速移动的手部出现重影,避免栏杆和头发等细物体周围的拖影。静态背景必须保持完全静止。

点名具体失败模式远比“高质量”有效。模型可以对照具体指令检查自己的输出。

模式:将运动与纹理分开

此轮仅关注运动平滑度。保持现有细节和颗粒不变——纹理恢复另行处理。

当你串联两个处理阶段时很有用,这样每个提示词只有一个职责。

模式:处理混合运动素材

固定机位但主体运动的采访片段,明确点出摄像机静止会有良好效果:

插值到 60fps。摄像机固定——背景必须完全不动或闪烁。只有说话者的头部和手部应显示平滑运动。

克制写长篇大论的冲动。三句话覆盖目标运动、要避免的伪影以及必须保持静止的内容,几乎能覆盖所有情况。

细节重建的提示词配方

细节重建是任务中发明合理精细结构的那一半。失败模式是幻觉纹理:皮肤看起来像塑料,植被变成噪点,文字变成乱码。提示词应给发明设定上限。

模式:锚定源

重建与源帧一致的细节。不要发明原始像素未暗示的纹理。在细节确实丢失的地方,优先选择柔和可信的结果,而非锐化后的噪点。

这一条指令就能防止大多数过度锐化的病理。

模式:点名画面中的材质

恢复织物纹理、发丝和皮肤毛孔的精细细节。保持肤色自然、毛孔不规则——避免平滑、喷绘般的外观。金属表面应保留现有高光,不产生新的高光。

针对材质的指令给模型提供了可操作的约束,无需一整段泛泛而谈。

模式:保护文字和图形

此片段包含屏幕字幕和徽标。文字必须保持清晰可读且无扭曲。不要重绘或改变任何图形元素的风格。

文字是风险最高的细节——乱码字幕比稍微模糊的字幕更糟。如果可读性至关重要,在对比阶段验证,而不是信任提示词。

模式:有意调节锐化

施加克制的细节恢复量。目标是 1080p 下自然观感的素材,而非锐化后的静帧。轻微柔和可以接受;振铃和光晕不可接受。

组合两者

当你在一次处理中同时插值和重建时,写一个覆盖两者的提示词,但每个分句只涉及一个关注点:

重建精细纹理——织物、头发、皮肤——与源一致,避免塑料般平滑。插值到 60fps,运动稳定,手部无重影,背景完全静止。

对比前后输出

在单帧上看起来很惊艳的增强视频,在运动中可能崩溃。建立固定的对比流程,每次更改参数或提示词时都运行它;否则你就是在猜测,而且会付出昂贵的猜测代价。

构建标准测试片段集

选择三个短片段(每个 5–10 秒),永不更改:

  1. 简单——光线良好、慢动作、干净的源。应该看起来近乎完美;如果不是,说明某处配置有误。
  2. 困难——快速运动、精细细节或混合运动类型。插值伪影会在这里出现。
  3. 对抗性——屏幕文字、细结构或重度先前压缩。幻觉会在这里显现。

对每个提示词或参数更改都针对三者运行。一个对简单片段有帮助但损害对抗性片段的更改不是改进。

按此顺序对比

  • 100% 缩放并排对比。不要用适应窗口,伪影会隐藏。检查相同的裁剪区域:面部、文字区域和高运动区域。
  • 逐帧拖动。逐帧步进快速运动部分,寻找重影、扭曲和闪烁。
  • 实时速度播放。许多伪影在逐帧拖动时消失而在运动中显现,反之亦然。两者都要看。
  • 文字可读性检查。对照源阅读增强版本中的每个字幕。这是你可用的最快客观通过/失败检查。

质量与成本并重

计费跟随端点所做的工作——输出时长和分辨率是驱动因素;查看网站的定价面板了解当前费率。实际后果:较长片段带来边际质量提升,通常不如较短片段带来明显提升的交易更划算。对每个候选配置,记录你产生的输出时长和分辨率,并问可见的改进是否值得该花费。保留优胜者,丢弃其余,并在将端点接入自动化管线之前,冻结一个配置并记录它——提示词、参数和测试结果——以便未来更改可以对照测量。

排查常见请求问题

与 topaz-upscale/video 的大多数集成摩擦可归入少数几类。按此顺序逐一处理。

认证与访问

401 意味着密钥缺失、格式错误或未发送——检查环境变量是否实际在运行命令的 shell 中设置,而不仅仅在编辑器中。403 通常意味着密钥有效但账户缺少对此模型的访问权限。确认模型名称拼写完全为 topaz-upscale/video。

服务无法获取你的视频

这是最常见的失败。症状:任务早期因下载或输入错误而失败。原因:

  • URL 是私有的或需要交互式登录。
  • 签名 URL 在任务到达下载步骤前过期——在长队列中尤其可能。
  • 主机阻止自动请求或速度慢到超时。

修复:通过平台上传文件并引用返回的标识符,或在提交时生成有效期充裕的签名 URL。

解码失败

如果错误提到媒体而非请求,将源重新封装为常见容器并重试。先在本地测试文件——如果你自己的播放器都吃力,服务也会。

任务一直运行或超时

长源需要很长时间,有些请求耗时不成比例地长。重新提交前,按 id 检查任务状态——你可能看到的是排队任务,而非失败任务。盲目重新提交可能使花费翻倍。如果从脚本轮询,确保你自己的客户端超时长于预期任务时长,否则你会放弃仍在正常运行的任务。

输出看起来比源更差

请求成功但结果过度锐化、塑料感或重影。这是提示词问题,不是 API 问题:回到细节重建和插值配方,添加明确上限——“与源一致”、“无重影”、“背景必须保持静止”。然后重新运行你的标准对比集。

间歇性、不可复现的失败

每次调用时同时记录完整请求体和任务 id。没有两者,你无法判断失败来自不同的载荷还是临时服务问题。有了十几次记录的失败,模式通常几分钟内就会浮现。

立即开始构建持久 AI 产物

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

阅读 API 文档