跳到正文
HopBase 文档
登录控制台

Grok Imagine 视频 API

用 Grok Imagine 生成视频：型号、参数、任务轮询、返回结果与报错。

grok-imagine-video-1.5 从文本生成视频，可加参考图：提交任务后轮询任务 ID，完成后下载成片。

项目值
Base URLhttps://api.hop-base.com/v1
提交任务POST /v1/video/generate
查询任务GET /v1/video/tasks/{task_id}
密钥分组「Grok 视频」

Grok Imagine 生图走同步的 OpenAI Images 接口，参数与视频不通用，见 Grok Imagine 生图。

可用型号

模型 ID分辨率时长（秒）官方价
grok-imagine-video-1.5480p / 720p / 1080p1–15$0.08起/ 秒

grok-imagine-video-1.5 是文生视频加可选参考图：没有首尾帧，不接受参考视频与参考音频。

生图与对话由Grok 全系分组提供，视频由Grok 视频分组提供，这是两个分组：密钥包含 Grok 视频分组才能调视频模型，一把密钥可以同时包含两个分组。请用实际要使用的密钥调 GET /v1/models 确认。

各分辨率档与参考图的官方价见模型卡：grok-imagine-video-1.5。视频请求的全部字段见 API 参考提交视频任务。

请求参数

参数必填取值默认值
model必填grok-imagine-video-1.5—
prompt / content二选一文本—
resolution必填480p / 720p / 1080p—
duration可选整数 1–15（秒）5
aspect_ratio可选1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:316:9
reference_images可选{ "url": "https://..." } 数组—
  • model 精确匹配。
  • content 是只含 text 元素的数组，文本不能为空，不接受图片、视频、音频元素。
  • resolution 按该档位每秒计费；带 reference_images 时仅 480p / 720p。
  • duration 与 aspect_ratio 的默认值由服务端填，按成片 duration_seconds 计费。
  • 画幅请用 aspect_ratio，传 ratio 会被拒绝。
  • reference_images 是顶层数组，仅公网可直达的 HTTP(S)，不接受 Data URL / asset://；每张参考图另计一笔。

ratio、frames、seed、camera_fixed、draft、draft_task、service_tier、generate_audio、watermark、return_last_frame 会被拒绝。其他未列字段（如顶层 image）网关不校验，也不会当作参考图。

返回结果

视频沿用 Seedance 的 task 包装，不要按可灵的顶层 id 读取。

提交响应

提交成功返回 200，任务 ID 在 task.id（形如 vt…）：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "pending",
    "outputs": []
  }
}

任务查询字段

用 task.id 轮询 GET /v1/video/tasks/{task_id}。

字段说明
task.idHopBase 任务 ID，vt…
task.statuspending / processing / completed / failed
task.outputs视频地址，字符串数组
task.duration_seconds成片秒数，按它计费
task.error.message失败原因
usage.cost / usage.cost_usd / usage.currency任务结束后的实际扣费，见视频总览；cost_usd 为从余额扣除的美元金额，cost 为同一笔的人民币金额

终态只有 completed 与 failed，其他值都按进行中处理。

进行中

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "processing",
    "outputs": [],
    "error": null
  }
}

成功

完成后返回 duration_seconds 与 outputs 里的视频地址：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "completed",
    "duration_seconds": 5,
    "outputs": [
      "https://api.hop-base.com/example-signed-video.mp4"
    ],
    "error": null
  },
  "usage": { "cost": 1.02, "cost_usd": 0.15, "currency": "CNY" }
}

失败

执行失败时 HTTP 仍为 200，检查 task.status 和 task.error.message：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

最小示例

# 1. 提交
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "一只橘猫奔跑穿过阳光下的草地，镜头跟随",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

# 2. 用返回的 task.id 轮询
curl https://api.hop-base.com/v1/video/tasks/vt你的任务ID \
  -H "Authorization: Bearer sk-your-key"

注意事项

  • outputs 自任务完成起 24 小时有效，再次查询不会续期，过期访问返回 410。请及时下载保存。
  • 提示词触发内容审核时任务会 failed，error.message 含 content-moderated。
  • 带 reference_images 时分辨率只能选 480p / 720p。
  • 参考图只接受公网 HTTP(S) 地址，最大张数尚未验证。
  • 视频与生图、对话不在同一分组，要调视频请给密钥加上 Grok 视频分组。

常见报错 → 改法

提交阶段的报错为 400，只有 error.message，没有 code。

报错开头改法
... requires resolution传 resolution
... does not support resolution 4k改用列出的分辨率
... duration must be an integer in 1-15传 1–15 的整数
... does not support ratio改用 aspect_ratio
aspect_ratio must be one of ...从列出的比例中选
... does not support parameter generate_audio删掉该字段
... only supports text segments in content参考图放进 reference_images
reference_images[0] must be a {"url": "..."} object每项写成 {"url": …}
reference_images[0].url must be a publicly reachable http(s) address改用公网 HTTP(S) 地址
... reference-to-video supports up to 720p去掉参考图，或选 480p / 720p
任务失败，error.message 含 content-moderated改写提示词

报错原文：

grok-imagine-video-1.5 requires resolution: 480p / 720p / 1080p
model grok-imagine-video-1.5 does not support resolution 4k
grok-imagine-video-1.5 duration must be an integer in 1-15, got 20
grok-imagine-video-1.5 uses aspect_ratio for the frame ratio and does not support ratio
aspect_ratio must be one of 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3, got 21:9
grok-imagine-video-1.5 does not support parameter generate_audio
grok-imagine-video-1.5 only supports text segments in content; use reference_images for reference images
reference_images[0] must be a {"url": "..."} object
reference_images[0].url must be a publicly reachable http(s) address
grok-imagine-video-1.5 reference-to-video supports up to 720p; remove the reference images or choose 480p/720p
priority must be within 0-9, got 12
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

计费

按成片秒数计费，单价随 resolution 档位不同；每张参考图另计一笔。失败的任务不计费。

任务结束后，查询响应根对象的 usage 还会带 cost_usd（本任务从余额实际扣除的美元金额，未扣费的失败为 0）、cost（同一笔的人民币金额）与 currency（恒为 CNY）。提交前的余额判断（不足返回 402）等所有视频任务通用的规则见视频总览。

官方牌价见价格页。你的实际单价以登录后的模型广场为准，每次请求的实际扣费见控制台「使用记录」。

下一步

  • Grok Imagine 生图：生成与编辑图片
  • 视频总览：各视频系列对比与共用的任务流程
  • Grok：Grok 对话与推理模型，含长上下文加价、推理 Token 计费与服务端工具收费
  • 错误码与重试：各错误码的含义以及是否该重试

本页目录

可用型号请求参数返回结果提交响应任务查询字段进行中成功失败最小示例注意事项常见报错 → 改法计费下一步