Grok Imagine Image to Video API

POST Base URL: https://api.hiapi.ai /v1/tasks

复制页面

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称	grok-imagine/image-to-video
类型	视频生成（图生视频）
接口	POST /v1/tasks
价格	见 HiAPI 定价

Grok Imagine 图生视频，把一张或多张参考图动起来生成电影级短视频，可搭配可选提示词描述运动，支持画幅、运动模式（fun/normal/spicy）、480p/720p/1080p 与 6-30 秒时长，通过 HiAPI 统一 API Key 调用。

生产建议

生产环境建议

• 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
• GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
• callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

让产品图动起来

传入产品图或海报作为参考图，生成有镜头运动的广告短视频。

image_urlsprompt

人像动态短视频

用人像照片生成自然的动态短视频，适合社媒和创意演示。

image_urlsduration

静态场景加运镜

给风景/场景静态图加入镜头推进等运动；mode 可选 fun、normal、spicy。

image_urlsmode

多图参考

最多传 7 张参考图，在提示词中用 @image1 等引用具体图片。

image_urls

请求参数

</> 生成示例代码

model string 必填

固定填 grok-imagine/image-to-video。

示例 grok-imagine/image-to-video

input object 必填

业务参数对象；Grok Imagine Image to Video 的模型专属配置都放在这里。

image_urls string[] 必填

参考图片 URL 或 asset:// 素材 ID，1-7 张。支持 JPEG/PNG/WEBP，单张 ≤10MB。不支持 SVG。在 prompt 中用 @image1 等引用具体图片。resolution 为 1080p 时只能传 1 张。

prompt string 可选

描述期望视频运动的文本提示词（可选，英文效果最佳），最长 5000 字符。

aspect_ratio enum 可选

输出视频画幅比例。仅多图参考模式生效；单图输入时该参数无效，输出跟随输入图片比例。

默认 2:3 可选值: 2:33:21:116:99:16

mode enum 可选

生成模式，影响运动风格与强度。fun 更有创意、normal 均衡、spicy 动感更强。使用外部图片（image_urls）时上游可能按 normal 处理。

默认 normal 可选值: funnormalspicy

duration integer 可选

视频时长 6-30 秒（整数）。费用按秒计算；16-30 秒以及多图且超过 10 秒的视频会分段生成后拼接，可能有接缝。

默认 6

resolution enum 可选

输出视频分辨率档位。720p 画质更高，480p 生成更快、更省；1080p 画质最高，仅支持单张输入图片。实际像素跟随输入图片比例。

默认 480p 可选值: 480p720p1080p

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 http(s) 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

基础图生视频

传一张参考图 + 运动提示词，最低成本验证。

请求体⧉

{
  "model": "grok-imagine/image-to-video",
  "input": {
    "image_urls": [
      "https://example.com/reference.jpg"
    ],
    "prompt": "camera slowly pushes forward, gentle motion",
    "duration": 6,
    "resolution": "480p"
  }
}

高清图生视频

1080p 输出，画质最高；该档位只支持单张输入图片。

请求体⧉

{
  "model": "grok-imagine/image-to-video",
  "input": {
    "image_urls": [
      "https://example.com/reference.jpg"
    ],
    "prompt": "the subject slowly turns and smiles, hair gently moving",
    "mode": "normal",
    "duration": 8,
    "resolution": "1080p"
  }
}

多图参考图生视频

传多张参考图，此时 aspect_ratio 生效，按所选画幅输出。

请求体⧉

{
  "model": "grok-imagine/image-to-video",
  "input": {
    "image_urls": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.jpg"
    ],
    "prompt": "@image1 keeps the face, @image2 sets the background, the camera slowly orbits, soft studio light",
    "mode": "normal",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

获取结果

1. 提交成功后立即返回 taskId（不等待生成完成）。
2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
3. status=success 后，从返回的 output[].url 下载生成的视频。
4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

Grok Imagine 图生视频是什么？

Grok Imagine 图生视频是 HiAPI 提供的 AI 视频生成 API，把参考图动起来生成电影级短视频，通过 POST /v1/tasks、model 填 grok-imagine/image-to-video 调用。

可以传几张参考图？

image_urls 支持 1-7 张，支持 JPEG/PNG/WEBP，单张不超过 10MB，不支持 SVG。可在提示词中用 @image1 等引用具体图片。resolution 为 1080p 时只能传 1 张。

传了 aspect_ratio 为什么输出比例没变？

aspect_ratio 仅多图参考模式生效。单图输入时该参数无效，输出始终跟随输入图片的比例；需要指定画幅时请传 2 张以上参考图。

1080p 是固定 1920×1080 吗？

不是。1080p 是清晰度档位，实际像素跟随输入图片比例，例如 4:3 的输入图在 1080p 档输出约 1664×1248。

prompt 是必填的吗？

图生视频的 prompt 是可选的，用来描述期望的运动方向和节奏；只传参考图也能生成。

长视频会分段生成吗？

16-30 秒的视频，以及多图且超过 10 秒的视频，会分段生成后拼接，可能出现接缝；对连续性要求高时建议控制在 15 秒内（多图时控制在 10 秒内）。

下一步

• 获取 API Key
• 查看 Grok Imagine Image to Video 价格
• 对比 AI 视频 API
• 在线试用 Playground