教程

如何使用 grok-imagine-1.5-lite 文生视频 API（curl + Python）

2026年11月3日

如果你想用一句话生成一段带声音的短视频，grok-imagine-1.5-lite/text-to-video 是 hiapi 上能到 1080P 的最便宜选择。它接收一条提示词，返回一段 1–15 秒、音频已混入的 MP4，并且运行在与平台上其他所有模型相同的统一任务 API 上。本页给出可直接粘贴运行的请求、精确的 schema（对照实时端点验证过，不是从规范抄的）、真实响应的样子，以及我在测试时踩到的坑。

以下内容均在 2026-10-21 对照实时 API 核验过。价格为我实测所得；若价格有变，以定价页为准。

1. 你将构建什么，以及需要准备什么

目标：发送一条文本提示词，拿回一段可下载、带音频的 MP4 片段。

你只需要一样东西：一个 hiapi API key。在控制台创建一个并保存在服务端——它形如 sk-...，放在 Authorization: Bearer 请求头里。没有免 key 的路径；下面每个请求都必须经过认证。

该模型是异步的。你不会在 POST 响应里直接拿到视频。你先创建一个任务，拿到 taskId，然后轮询（或使用回调）直到任务完成并给出输出 URL。

2. 最小可运行示例

两步：创建任务，然后轮询结果。

创建任务（curl）

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "黎明时分，一只红狐踏过新雪，呼出的气息化作白雾，柔和的晨光，轻柔的环境风声。电影感，自然色彩。无文字。",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

注意结构：model 在顶层，其他所有内容嵌套在 input 下。如果平铺发送字段（不加 input 包装），API 会以 invalid input: must be a JSON object 拒绝整个请求体——这是最常见的错误。

创建成功会立即返回一个任务 id：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB" }, "message": "success" }

轮询结果（Python）

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("黎明时分，一只红狐踏过新雪，轻柔的环境风声。电影感。"))

Schema（实时验证）

字段放在 input 内。该 schema 是封闭的——任何它不认识的 key 都会返回 400，所以不要发送 seed、negative_prompt 或 motion_mode（这里都不存在；所有镜头和运动方向都通过提示词措辞表达）。

字段	类型	是否必填	可接受值
`prompt`	string	是	自由文本
`duration`	integer	是	1–15（整秒；`5.5` 会被拒绝）
`resolution`	string	—	`480p`、`720p`、`1080p`
`aspect_ratio`	string	—	`16:9`、`4:3`、`3:2`、`1:1`、`2:3`、`3:4`、`9:16`

该模型没有 auto 宽高比（它的图生视频同级模型有一个；这个文生视频端点没有）。请显式指定比例，否则你会得到模型默认的比例。

下面是一个已完成任务的真实返回：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

这是该模型生成的一段片段（hiapi 为 grok-imagine-1.5-lite/text-to-video 提供的参考输出，由其文档示例提示词生成——"日出时分，一只玻璃热气球飘过梯田"）：

3. 投入生产

用回调代替轮询。轮询对脚本来说没问题；对服务器来说，加上 callback，这样就不必一直保持请求打开。当任务进入终态时，平台会把任务详情 POST 到你的 URL：

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

在该任务类型上，when 只接受 "final"。在你的 handler 里按 taskId 去重——回调可能重试，所以要把 handler 当作幂等的。

输出 URL 会过期。注意 storage: "temp" 和 expireAt unix 时间戳——临时输出存放在 temp.hiapi.ai 上约 7 天，之后返回 404。不要保存热链接。任务成功的那一刻就下载字节，或者调用存储转存端点在 TTL 到期前把产物移到永久存储。

费用按输出秒数计。计费只由 duration 和你请求的分辨率决定。测试时：480P $0.029/s，720P $0.043/s，1080P $0.20/s。所以 5 秒 720P 片段约 $0.215，5 秒 1080P 片段约 $1.00，1 秒 480P 片段约 $0.029。1080P 费率大约是 720P 的 5 倍——只有确实需要该分辨率时才用。最新数字见定价页。

错误处理。被拒绝的请求会以 HTTP 400 返回，并带有可记录、可据以处理的精确消息。校验发生在创建任何任务之前，所以这里的 400 不产生费用。我实际触发的真实响应：

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

任务被接受但之后失败，会以 data.status: "fail" 并在详情端点附带 data.error 对象的形式出现——而不是 HTTP 错误——所以要检查 status，不要依赖轮询的 HTTP 状态码。

4. 我实际观察到的

我跑了一次真实生成来确认端到端流程（不只是 schema）：duration: 1、resolution: "480p"、aspect_ratio: "16:9"。

它确实可用且会计费——POST 返回了 taskId，任务以真实输出 URL 完成。服务端渲染 1 秒片段实际耗时约 51 秒；即使很小的片段也不是即时的，所以把轮询截止时间设得宽裕些（我设 300 秒）。
任务会经过中间状态。status 字段依次经过 handling → archiving → success。只有 success 和 fail 是终态；不要把 archiving 当作已完成。
480P 在 16:9 下渲染为 848×480 H.264。对下载文件运行 ffprobe：一个 H.264 视频流（848×480），外加一个内嵌的 MJPEG 缩略图流。这个 495 KB 文件是有效的 MP4。
音频总是内置的。即使我的提示词只提到“轻柔的环境风声”，输出仍带有 AAC 音轨——模型会合成匹配的音频并混入同一个 MP4。没有单独的音频 URL，也没有禁用它的开关；如果你需要无声片段，自己剥离音轨（ffmpeg -an）。

范围说明：我验证了 API 契约、上述三类错误，以及一次 480P 渲染。我没有对 720P/1080P 输出质量或长（15 秒）时长做基准测试，所以我不对这些做质量断言——只说明 schema 接受它们并按秒计费。

5. Lite 与标准 Grok Imagine 视频 API 的对比

构建前先选对端点：

grok-imagine-1.5-lite/text-to-video（本页）：480P/720P/1080P，1–15 秒（因此可以生成 1 或 2 秒片段），价格 $0.029–$0.20/s。它是 hiapi 托管的唯一 1.5 代文生视频端点，也是唯一能达到 1080P 的 Grok t2v 档位。
grok-imagine/text-to-video（较旧的标准档，见本指南）：每秒更便宜（$0.0114–$0.0214/s），并提供 Motion Modes，但最高只到 720p，且要求 6–30 秒时长——无法生成不足 6 秒的片段。