Hailuo 2.3 API 指南：文生视频、图生视频与 Fast 版本

TL;DR

• Hailuo 2.3 是 MiniMax 的视频模型。在 HiAPI 上它有三个端点：hailuo-2.3/text-to-video、hailuo-2.3/image-to-video，以及更便宜的 hailuo-2.3-fast/image-to-video。
• 它按条计费，而不是按秒：6 秒视频 $0.40，10 秒视频 $0.80。Fast 图生视频为 $0.27 和 $0.46。
• 输入参数很少：prompt、duration（字符串 "6" 或 "10"）、prompt_optimizer，图生视频再加一个 image_url。没有分辨率、宽高比或 seed 参数。打开文生视频模型页即可试用；新账号赠送 200 免费额度。

该用哪个端点

	文生视频	图生视频	Fast 图生视频
模型 ID	hailuo-2.3/text-to-video	hailuo-2.3/image-to-video	hailuo-2.3-fast/image-to-video
必填参数	prompt	prompt + image_url	prompt + image_url
6 秒视频	$0.40	$0.40	$0.27
10 秒视频	$0.80	$0.80	$0.46
图像输入	无	一张首帧	一张首帧

HiAPI 实时价格，核查于 2026 年 10 月 20 日。失败的任务不收费。

探索一个场景时从文本开始；当首帧必须精确时（比如已有的产品或角色）从图像开始。图生视频场景下，Fast 便宜三分之一且输入相同，所以可以先用 Fast 打草稿，当某个镜头需要更多运动细节时再切换到标准模型。

文生视频：真实输出

这是模型页上的示例，时长 6 秒：

a kung fu master practicing forms in heavy rain, water droplets scattering in slow motion, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

用此提示词生成 →

hailuo-2.3/text-to-video，6 秒，1366×768，无音频，$0.40。

六秒里，这位大师依次完成数个站姿和手臂击打动作，身后的雨一直在下。镜头保持稳定。尽管请求里没有宽高比字段，输出仍是横屏；文生视频无法指定竖屏。

图生视频：真实输出

图生视频会保留你的画面并让它动起来。下面两个示例都使用 16:9 的首帧，返回结果为 1364×768。

首帧：

steam bursts from the locomotive as it slowly starts moving, wheels turning, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

用此提示词生成 →

hailuo-2.3/image-to-video，6 秒，1364×768，无音频，$0.40。

车站、车厢和日落都保持与画面中一致。机车向前牵引，蒸汽在站台低处弥漫开来。

同样的思路换成 Fast，场景更安静：

boats rocking gently, seagulls gliding through the morning mist, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

用此提示词生成 →

hailuo-2.3-fast/image-to-video，6 秒，1364×768，无音频，$0.27。

运动幅度很小：船只轻轻摇晃，雾气缓缓漂移，接近结尾时出现一只海鸥。像这样安静、氛围化的镜头，Fast 就足够了。

图生视频的提示词要写接下来发生什么。模型已经看到了画面，所以“一辆黑色机车停在车站”不会增加任何信息；“它开始移动时蒸汽喷涌而出”才是告诉它该做什么。

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3/text-to-video",
    "input": {
      "prompt": "A glass of iced tea tips over in slow motion, tea splashing across a wooden table, ice cubes tumbling, macro shot",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

你会得到一个 taskId。轮询 GET https://api.hiapi.ai/v1/tasks/{taskId}，直到 data.status 为 success，然后下载 data.output[0].url。视频需要几分钟，而不是几秒。

图生视频则更换模型并添加一张图片：

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": {
    "prompt": "The cat stretches, hops off the windowsill and walks toward the camera",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "duration": "6"
  }
}

Python：提交、轮询、下载

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)  # a 400 lists every invalid field at once
    task_id = r["data"]["taskId"]  # save this; if your script dies, poll it again instead of resubmitting
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate("hailuo-2.3/image-to-video",
               prompt="Steam bursts from the locomotive as it slowly starts moving, wheels turning",
               image_url="https://your-cdn.example.com/train.jpg",
               duration="10")  # a string, not 10

with open("hailuo.mp4", "wb") as f:
    f.write(requests.get(url, timeout=120).content)

输出链接在任务完成后约 7 天过期，所以要保存文件，而不是只存链接。

参数

字段	必填	取值	说明
prompt	是	文本	描述运动和镜头运动
image_url	仅图生视频	一个公网 URL	单个字符串，不是数组。jpeg、png 或 webp
duration	否	"6"（默认）或 "10"	必须是字符串
prompt_optimizer	否	true（默认）/ false	在生成前扩写短提示词

运动和镜头运动都写在提示词里。没有 motion_strength、camera_movement、resolution、aspect_ratio 或 seed 字段。

你会遇到的错误

这些错误在提交时以 HTTP 400 返回，因此不会创建任务，也不会产生计费：

• duration: got number, want string：你传了 6。请传 "6"。
• duration: value must be one of '6', '10'：只有两种时长。
• image_url: missing required field "image_url"：图生视频需要一张首帧。字段名是单数的 image_url。
• additional properties 'resolution' not allowed（或 aspect_ratio、image_urls、seed）：删掉该字段。

如果任务最终以 fail 结束，请读取 data.error。图生视频场景下，常见原因是服务端无法抓取图片 URL，例如私有存储桶或已过期的签名链接。

常见问题

Hailuo 2.3 每秒多少钱？

它不是按秒计费的。你按条付费：标准模型 6 秒 $0.40、10 秒 $0.80；Fast 为 $0.27 和 $0.46。折算下来，标准模型 6 秒视频约每秒 $0.067，Fast 约每秒 $0.045。

我能生成竖屏视频吗？

文生视频不行，它没有宽高比字段，返回横屏。图生视频同样没有宽高比字段；文档没有说明竖屏首帧是否会产生竖屏视频，所以在基于此开发之前，先用 $0.27 测一条 6 秒的 Fast 视频。

我应该关闭 prompt_optimizer 吗？

短提示词保持开启。当你精心写好了措辞、希望模型严格照写执行时，再关闭它。

有声音吗？

上面三个示例视频都没有音轨，也没有可以开启声音的字段。

Fast 更差吗？

它输入相同，价格便宜三分之一。在上面船只的例子里，运动柔和且干净。对于包含大量快速动作的镜头，先在两个模型上各生成一条 6 秒草稿做对比，再渲染 10 秒版本。

更多视频模型横向对比：HiAPI 上最便宜的图像与视频 API。想不用代码就试用 Hailuo，打开图生视频模型页。