教程
muse-video-1.0 图生视频 API 教程:curl 与 Python Requests
本页内容
muse-video-1.0 图生视频端点要求什么
muse-video-1.0/image-to-video 端点将单张静态图像转换为一段短视频。在写下第一行代码之前,先理解请求的结构,能帮助你一次就组装出正确的请求载荷。
从高层来看,一次调用涉及四个方面:
- 模型路由 —— 你通过 HiAPI 统一 API 以
muse-video-1.0/image-to-video来指定模型。 - 输入图像 —— 作为动画起点的静态帧。这是必需的创意输入。
- 生成选项 —— 音频行为和时长档位,它们塑造的是输出特性而非源素材。
- 异步执行 —— 生成不会内联返回成品视频。你先提交任务,然后轮询获取结果。
最后一点是开发者最常忽略的。由于渲染需要时间,该端点基于任务机制:初始调用会确认你的请求并返回一个句柄,随后你再通过状态查询跟进,直到视频就绪。请从一开始就围绕这个两阶段流程设计客户端,而不是事后才补上轮询。
请求体本身是 JSON。字段采用分组结构:图像位于独立的 input 块中,音频和时长则与它并列,作为生成设置。保持这个心智模型 —— 输入、选项与任务生命周期三者分离 —— 本教程的其余部分就会很直接。
身份认证
每个请求都使用你的 HiAPI API 密钥进行身份认证,以 bearer 凭据的形式放在 Authorization 请求头中。请将密钥视为机密:从环境变量加载,而不是硬编码在你可能分享的脚本里。
export HIAPI_API_KEY="your_api_key_here"
导出密钥后,你已具备理解该请求所需的全部条件。接下来的章节将逐步构建请求载荷。
准备并上传你的首帧图像
首帧图像是整个任务的创意锚点。你提供的内容会成为第零帧,模型从那里向前动画。把它做对能避免浪费生成次数。
源帧的实用建议
- 使用清晰、高质量的静态图。 作为单帧图像读起来顺畅的内容,能为模型提供最佳的起点。
- 选择与目标输出匹配的宽高比。 宽幅横图和竖版长图会导致差异极大的构图,因此在实际上传前就应确定方向。
- 避免严重运动模糊或主体不明确。 视觉上已经稳定的静态图能生成更可预测的动画。
- 确保文件在请求时可访问。 无论你传的是 URL 还是编码后的载荷,都要确保任务提交那一刻该引用可达。
图像如何进入请求
图像在 JSON 请求体的 input 块中提供。一个最小的图像输入如下所示:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
如果你的源图像存放在本地,请将其托管在请求可访问的位置,或以端点接受的编码形式传入。关键规则是:input.image 中的值在任务创建时必须解析为真实的图像内容 —— 损坏或过期的链接会在提交时失败,而不是在轮询时失败,这实际上是一个有用的早期信号。
生成前先验证
快速健全性检查很有价值:在浏览器中打开图像 URL,确认能加载,然后确认尺寸适合你的预期输出。这里花两秒检查,能避免之后令人困惑的调试过程。
首帧准备就绪且可访问后,就可以继续处理生成选项了。
设置音频参数与时长档位
除图像之外,muse-video-1.0/image-to-video 还提供两类选项,用于改变输出的特性:音频行为和时长。
音频参数
音频以请求体中的一个字段表示,与你的 input 并列。调用前先确定意图:
- 静音输出 —— 如果你计划后期添加自己的配乐,或需要干净的视频轨,则保持音频关闭。
- 启用音频 —— 如果片段应自带声音,则打开音频。请在请求载荷中明确检查该选项,而不是假设默认值。
由于音频处理是请求本身的属性,而非后处理步骤,在扩大规模之前值得先敲定。如果你的流水线混合了静音和带音频的片段,请在你自己的客户端代码中把该选择建模为显式参数,以免意外发生。
时长档位
该端点允许你为片段选择时长档位。请把时长当作有意的创意与成本决策:
- 较短档位 适合快速预览、社交片段和分镜测试,你希望在许多源图像上快速获得反馈。
- 较长档位 给动画更多发展空间,更适合主视觉镜头或需要呼吸感的序列。
时长按输出秒数计费,因此你选择的档位直接影响消耗。仅仅为了快速视觉检查而渲染长片段没有任何好处 —— 迭代首帧时先用短档位,然后将胜出的设置提升到更长档位。
一起组装这些选项
在 JSON 中,音频和时长设置与 input 块并列:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
请使用端点文档中给出的确切档位标识符,而不是猜测值。下一节会将其变为可运行的请求。
一个可用的 curl 请求
请求载荷组装好后,以下是初始提交的 curl 命令。它会创建任务;不会返回成品视频。
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
关于该命令的几点说明:
- URL 按名称指定模型。 你不需要为每个模型单独准备客户端;路径已经标识了
muse-video-1.0/image-to-video。 - 请求头携带你的密钥。
$HIAPI_API_KEY从你之前导出的环境变量展开,因此密钥永远不会出现在脚本本身中。 - 请求体就是你刚构建的载荷。 图像 URL、音频标志和时长档位一起传递。
响应是一个任务确认:它包含你刚创建的任务的标识符。复制该标识符 —— 轮询步骤中会用到。如果你只是在探索,可以用 JSON 格式化工具处理响应,以便更容易找到 job ID。
如果提交失败,错误通常是即时且具体的:JSON 请求体格式错误、缺少图像引用,或选项值无法识别。这种快速反馈循环正是值得在接入轮询之前单独测试提交的原因。
同样的请求用 Python 实现
大多数集成最终会落在 Python 上,因此这里给出使用标准库的等效提交 —— 无需第三方 SDK。
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
该脚本逐字段地对应 curl 调用。几个值得养成的习惯:
- 将请求载荷保存在字典中。 将其构建为 Python 字典意味着你可以把相同的结构喂给任何 HTTP 库 ——
urllib、requests或异步客户端 —— 而无需重写逻辑。 - 从环境读取密钥。
os.environ让凭据远离源代码控制。 - 立即将响应解析为 JSON。 将 job ID 提取到命名变量中,让轮询步骤读起来更清晰。
如果你更喜欢 requests 库,唯一的变化是更换传输层:构造相同的 payload 字典并用你的请求头集合发送,然后对响应调用 .json()。端点、请求头和请求体保持完全一致。
任务提交并捕获其标识符后,剩下的工作就是以正确的方式等待结果。
轮询异步任务并获取视频
视频生成不是即时的,因此该端点是异步的。提交后,你轮询任务状态以了解渲染何时完成,然后获取输出。
轮询循环
健壮的循环做三件事:在检查之间等待,设置上限以免无限运行,并区分“仍在处理”、“已完成”和“失败”。
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
生产环境的设计要点
- 使用合理的间隔。 五秒是合理的起点;不要猛击状态端点。
- 始终限制尝试次数。
max_attempts上限将无限等待转变为可以记录和告警的清晰错误。 - 显式处理失败状态。 失败的任务带有诊断信息 —— 将其暴露出来,而不是静默重试相同输入。
- 持久化 job ID。 如果你的进程重启,可以恢复轮询,而不必付费重新生成。
获取输出
任务成功时,状态响应会包含成品视频的输出引用。请及时将其下载到你自己的存储中,而不是依赖长期有效的链接。一旦你在本地或存储桶中持有该文件,从流水线的角度看生成就完成了。
这就是整个生命周期:提交、轮询、获取。在代码中将两个阶段分开,每个阶段都会保持简单。
常见陷阱与调试技巧
使用 muse-video-1.0/image-to-video 时的大多数集成问题都可以归为少数几类。以下是出问题时应检查的内容。
图像输入问题
- 图像引用不可达。 如果 URL 需要认证或已过期,任务会在提交时失败。在请求期间将帧托管在公开可读的位置。
- 宽高比不匹配。 将竖版静态图强行用于横版输出会导致尴尬的裁剪或黑边。设置源方向以匹配目标。
- 内容错误。 很容易指向缩略图或占位图而不是真正的帧。验证 URL 打开的是预期图像。
参数错误
- 猜测时长值。 使用端点文档中确切给出的档位标识符。无法识别的值是常见的拒绝原因。
- 忘记音频标志。 如果你省略音频设置却期望有声音,可能会得到静音片段。对于是否需要音频要显式说明。
- 混淆顶层字段和 input 字段。 图像属于
input内部;音频和时长是input的兄弟节点,而不是其子节点。嵌套错误会产生令人困惑的验证消息。
轮询错误
- 将提交视为完成。 第一次响应只是确认,不是视频。始终跟进状态检查。
- 无限制轮询。 无上限的循环会在任务停滞时挂起你的 worker。添加上限和超时错误。
- 忽略失败。 以失败状态结束的任务永远不会产生视频;捕获它并检查诊断信息,而不是继续等待。
- 在错误输入上长时间等待。 当渲染持续失败时,停止重新生成。先修复源帧或参数,然后重新提交。
一个有效的调试顺序
- 确认图像 URL 在浏览器中能加载。
- 仅使用图像提交一个最小载荷,以隔离参数问题。
- 验证 job ID 是否干净地返回。
- 先手动轮询,观察状态转换。
- 只有在这之后,才自动化循环,并围绕瞬时网络错误添加重试。
按顺序处理这些步骤能快速将问题缩小到某一层 —— 图像、选项或生命周期 —— 并保持集成推进。理解了请求结构、选项和轮询流程后,你就准备好针对该端点进行构建了。