如何使用 Grok Imagine API 进行文生视频：curl、Python 与一个可运行的请求

Grok Imagine 是 xAI 的视频生成模型，HiAPI 通过与其他所有生成模型相同的统一异步端点开放其文生视频变体：POST /v1/tasks。你发送一个提示词（外加可选的时长、模式、宽高比和分辨率），立即获得一个 taskId，并在任务完成后获取一个 .mp4 URL。

本指南是通往可运行请求的最短路径：确切的输入模式（已对照线上 API 验证，包括你猜错字段名时会遇到的 400 错误）、可直接复制粘贴的 curl 流程、一个小型的带轮询的 Python 客户端，以及你在生产环境中会使用的回调模式。

你要构建什么，以及你需要什么

目标：通过 grok-imagine/text-to-video，完全基于 HTTP，将文本提示词转换为 6–30 秒的视频片段。

你只需要一样东西：一个 HiAPI API 密钥。在 HiAPI 仪表盘中创建一个——单个密钥可通用于所有模型，因此如果你已经在 HiAPI 上调用过图像模型，同一个密钥在这里同样有效。请求使用标准的 bearer 请求头进行认证：

Authorization: Bearer sk-<your-key>

输入模式（在编写任何代码之前）

任务 API 会按模型严格校验 input——未知字段会以 400 被拒绝，而不是被静默忽略。以下是 grok-imagine/text-to-video 的完整模式：

字段	类型	必填	取值	默认值
prompt	string	是	最多 5000 个字符，英文效果最佳	—
duration	integer	否	6–30（秒）	6
mode	enum	否	fun、normal	normal
aspect_ratio	enum	否	2:3、3:2、1:1、16:9、9:16	2:3
resolution	enum	否	480p、720p	480p

有三点值得事先了解：

• mode 是“运动模式”开关。 normal 是平衡的；fun 会产生更具创意、更夸张的运动。如果你在其他地方看到 Grok Imagine 的模式以其他名称描述，API 参数就是 mode——发送类似 motion_mode 的内容会让你得到 400 additional properties 'motion_mode' not allowed。
• duration 会线性影响成本。 Grok Imagine 按输出秒数计费，因此 30 秒片段成本是 6 秒片段的 5 倍。当前的每秒费率见 HiAPI 定价页面。
• 默认宽高比是 2:3（竖屏）。 如果你想要宽屏，请显式传入 16:9——这一点会让从默认横向的模型迁移过来的用户措手不及。

超出范围的取值会快速失败并给出描述性消息，例如 duration: 31 返回：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

最小可运行示例：curl

两次调用：创建任务，然后轮询它。

1. 创建任务：

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

注意模型 id 就是裸字符串 grok-imagine/text-to-video——没有提供商前缀，也没有版本后缀。

2. 轮询直到终态：

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

.mp4 URL 是临时的——expireAt 是一个大约一周后的 Unix 时间戳。任务成功后立即下载字节并自行持久化；不要从任何面向用户的地方热链接 temp.hiapi.ai URL。（如果你曾遇到失效的输出链接，原因就在这里——参见 hiapi 输出 URL 已过期：请在过期前下载。）

Python：一个小型轮询客户端

同一流程的可复用脚本——创建、带截止时间轮询、下载：

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

6 秒片段通常远在上方 15 分钟截止时间内完成；更长的时长会按比例耗时更长，因此对 30 秒任务请保留这个宽松的超时时间。

生产环境注意事项

用回调替代轮询。 对于脚本之外的任何场景，在创建时传入顶层 callback 对象，HiAPI 会将终态任务状态 POST 到你的端点——无需照看轮询循环：

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when 只接受 "final"（当任务达到 success 或 fail 时你会收到一次 POST，而不是增量进度）。经验法则：轮询适合 CLI、批处理作业和任何短生命周期场景；回调适合 Web 后端，否则你会让工作进程容量被多分钟的渲染占住。如果你的回调端点似乎没有收到任何内容，请排查 为什么你的 hiapi 任务回调没有触发。

幂等性。 任务创建不是幂等的——重试超时的创建请求可能产生两个计费任务。拿到 taskId 的那一刻就记录它，并在出现模糊失败（创建时网络超时）时，在重新提交前检查你的任务历史。由于 duration 按秒计费，重复的 30 秒任务是代价高昂的那种重复。

错误处理。 你实际会看到的两类错误：

• 模式 400 错误（error_code: "INVALID_REQUEST"）——字段名错误、时长超出范围、枚举值无效。这些是确定性的；修正请求，不要重试。
• 认证失败——无效密钥或无权访问此模型的密钥会返回 401，并带有 "code": "permission_denied" 和消息 "This API key cannot use the selected model." 在仪表盘中检查密钥，并确认该模型已对其启用。
• 任务级失败——创建成功，但任务随后以 status: "fail" 进入终态，并带有一个 error 对象（内容策略、上游容量）。这些值得以退避方式重试一次。如果任务似乎卡在 handling，参见 诊断挂起或超时的 /v1/tasks 作业。

下一步

• Grok Imagine 文生视频模型页面——演练场和当前定价
• 模型输入参考——此模型的规范模式
• 创建任务和获取任务详情——完整的异步 API 信封
• 快速开始——端到端完成第一次 HiAPI 调用，以及认证了解密钥处理

常见问题

什么是 Grok Imagine API，我如何访问它？ Grok Imagine 是 xAI 的视频生成模型。通过 HiAPI，你使用单个 HiAPI 密钥在统一的 POST /v1/tasks 端点上以 grok-imagine/text-to-video 调用它——无需单独的 xAI 账户或 SDK。

Grok Imagine 视频可以有多长？ duration 接受 6 到 30 秒的整数（默认 6）。超出该范围的值会在创建时以 400 被拒绝，计费按输出秒数计算。

fun 和 normal 模式有什么区别？ normal（默认）提供平衡、真实的运动；fun 更偏向创意和夸张。这是 API 暴露的唯一运动风格开关——按请求选择，而不是按账户。

grok-imagine/text-to-video 支持 1080p 吗？ 目前不支持——resolution 接受 480p（默认）或 720p。如果你需要更高的输出分辨率，请在下游放大，或在模型页面比较其他视频模型。

我可以使用 Grok Imagine 为现有图像添加动画吗？ 此模型不行——它只支持文本。同一任务端点上有一个单独的 grok-imagine/image-to-video 模型，接受图像输入；异步生命周期（创建 → 轮询/回调 → 下载）完全相同。

Grok Imagine API 有免费层吗？ 生成会按视频秒数从你的 HiAPI 余额中计费——没有无密钥的免费端点。当前费率见定价页面；关于这个领域“免费”现实上是什么样，这篇免费文生视频 API 对比涵盖了各种选项。