博客

教程

muse-video-1.0 图生视频 API 教程:curl 与 Python Requests

2026年11月13日
muse-video-1.0 教程封面图:深青绿色背景上的青蓝色多面矿物横截面扁平插画。
本页内容

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。添加上限和超时错误。
  • 忽略失败。 以失败状态结束的任务永远不会产生视频;捕获它并检查诊断信息,而不是继续等待。
  • 在错误输入上长时间等待。 当渲染持续失败时,停止重新生成。先修复源帧或参数,然后重新提交。

一个有效的调试顺序

  1. 确认图像 URL 在浏览器中能加载。
  2. 仅使用图像提交一个最小载荷,以隔离参数问题。
  3. 验证 job ID 是否干净地返回。
  4. 先手动轮询,观察状态转换。
  5. 只有在这之后,才自动化循环,并围绕瞬时网络错误添加重试。

按顺序处理这些步骤能快速将问题缩小到某一层 —— 图像、选项或生命周期 —— 并保持集成推进。理解了请求结构、选项和轮询流程后,你就准备好针对该端点进行构建了。

立即开始构建持久 AI 产物

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

阅读 API 文档