教程
如何通过 HiAPI API 使用 topaz-upscale/video:curl 与 Python 示例
本页内容
topaz-upscale/video 的功能与适用场景
topaz-upscale/video 是 HiAPI 上的视频增强端点。你向它发送源视频和指令,它会返回增强后的视频:更高分辨率、重建的精细细节,并可选地通过帧插值实现更平滑的运动。当素材已经存在、问题在于质量而非内容生成时,就应该使用这个端点。
适用场景
与该端点自然匹配的典型任务:
- 档案与老旧素材——旧录像、压缩屏幕录制或继承的媒体,需要在现代分辨率下显得拿得出手。
- 渲染管线——为速度而先以低分辨率渲染的已完成序列,随后增强用于交付。
- 运动清理——低帧率源需要插值帧以避免播放时卡顿。
- 交付变体——一个母版,多个输出层级,按层级分别应用增强。
何时选择它而非替代方案
决策通常归结为三个问题:
- 问题在于分辨率和细节,还是在于内容?如果你需要凭空发明新像素(从未拍摄过的场景),那这是错误的工具。增强假定底层有真实的源帧。
- 你的管线能容忍异步工作吗?视频任务不是瞬时的。如果你的用户体验要求亚秒级响应,这个端点应放在后台任务中,而非请求处理器中。
- 你需要帧插值和放大吗?如果运动平滑度很重要,你希望在一次处理中同时获得两种能力,而不是串联多个独立工具。
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 秒),永不更改:
- 简单——光线良好、慢动作、干净的源。应该看起来近乎完美;如果不是,说明某处配置有误。
- 困难——快速运动、精细细节或混合运动类型。插值伪影会在这里出现。
- 对抗性——屏幕文字、细结构或重度先前压缩。幻觉会在这里显现。
对每个提示词或参数更改都针对三者运行。一个对简单片段有帮助但损害对抗性片段的更改不是改进。
按此顺序对比
- 100% 缩放并排对比。不要用适应窗口,伪影会隐藏。检查相同的裁剪区域:面部、文字区域和高运动区域。
- 逐帧拖动。逐帧步进快速运动部分,寻找重影、扭曲和闪烁。
- 实时速度播放。许多伪影在逐帧拖动时消失而在运动中显现,反之亦然。两者都要看。
- 文字可读性检查。对照源阅读增强版本中的每个字幕。这是你可用的最快客观通过/失败检查。
质量与成本并重
计费跟随端点所做的工作——输出时长和分辨率是驱动因素;查看网站的定价面板了解当前费率。实际后果:较长片段带来边际质量提升,通常不如较短片段带来明显提升的交易更划算。对每个候选配置,记录你产生的输出时长和分辨率,并问可见的改进是否值得该花费。保留优胜者,丢弃其余,并在将端点接入自动化管线之前,冻结一个配置并记录它——提示词、参数和测试结果——以便未来更改可以对照测量。
排查常见请求问题
与 topaz-upscale/video 的大多数集成摩擦可归入少数几类。按此顺序逐一处理。
认证与访问
401 意味着密钥缺失、格式错误或未发送——检查环境变量是否实际在运行命令的 shell 中设置,而不仅仅在编辑器中。403 通常意味着密钥有效但账户缺少对此模型的访问权限。确认模型名称拼写完全为 topaz-upscale/video。
服务无法获取你的视频
这是最常见的失败。症状:任务早期因下载或输入错误而失败。原因:
- URL 是私有的或需要交互式登录。
- 签名 URL 在任务到达下载步骤前过期——在长队列中尤其可能。
- 主机阻止自动请求或速度慢到超时。
修复:通过平台上传文件并引用返回的标识符,或在提交时生成有效期充裕的签名 URL。
解码失败
如果错误提到媒体而非请求,将源重新封装为常见容器并重试。先在本地测试文件——如果你自己的播放器都吃力,服务也会。
任务一直运行或超时
长源需要很长时间,有些请求耗时不成比例地长。重新提交前,按 id 检查任务状态——你可能看到的是排队任务,而非失败任务。盲目重新提交可能使花费翻倍。如果从脚本轮询,确保你自己的客户端超时长于预期任务时长,否则你会放弃仍在正常运行的任务。
输出看起来比源更差
请求成功但结果过度锐化、塑料感或重影。这是提示词问题,不是 API 问题:回到细节重建和插值配方,添加明确上限——“与源一致”、“无重影”、“背景必须保持静止”。然后重新运行你的标准对比集。
间歇性、不可复现的失败
每次调用时同时记录完整请求体和任务 id。没有两者,你无法判断失败来自不同的载荷还是临时服务问题。有了十几次记录的失败,模式通常几分钟内就会浮现。