Skip to main content
本文将介绍 Grok Videos Generation API 的对接说明,它可以通过输入文本提示词、输入图片以及可选的参考图片来生成 Grok Imagine(xAI)视频。

申请流程

要使用 Grok Videos Generation API,首先到 Ace Data Cloud 控制台 获取您的 API Token,留作备用。 如果你尚未登录或注册,会自动跳转到登录页面邀请你注册和登录,完成后会自动返回当前页面。 一个 API Token 即可调用平台所有服务,无需为每个服务单独申请。 首次申请会赠送免费额度,可免费体验;额度不足时可在 控制台 充值通用余额。
📘 完整文档:Grok Videos Generation API →

模型说明

本 API 通过模型名的后缀选择上游端点::reverse 走快速/标准端点(更便宜),:official 走官方端点(画质更高,按输出秒数计费)。共支持四个模型:
  • grok-imagine-video-1.5-fast:reverse(默认):支持文生视频(仅传 prompt)和图生视频(传 image_url),时长 6–30 秒,按时长分档计费,最便宜。
  • grok-imagine-video:reverse:支持文生与图生视频,时长 1–15 秒,按输出秒数计费。
  • grok-imagine-video:official:官方端点,支持文生与图生视频,时长 1–15 秒,按输出秒数计费,画质更高。
  • grok-imagine-video-1.5:official:官方端点,仅支持图生视频,必须传入 image_url,时长 1–15 秒,支持最高 1080p,按输出秒数计费。

基本使用

首先了解下基本的使用方式,输入提示词 prompt、模型 model 等参数,便可生成对应的视频。 可以看到这里我们设置了 Request Headers,包括:
  • accept:想要接收怎样格式的响应结果,这里填写为 application/json,即 JSON 格式。
  • authorization:调用 API 的密钥,申请之后可以直接下拉选择。
另外设置了 Request Body,包括:
  • prompt:描述想要生成视频内容的文本提示词。做文生视频时必填;传入 image_url 时可选。
  • model:生成视频的模型,可选 grok-imagine-video-1.5-fast:reverse(默认)、grok-imagine-video:reverse、grok-imagine-video:official 或 grok-imagine-video-1.5:official。
  • image_url:图生视频的输入图片链接。当 model 为 grok-imagine-video-1.5:official 时必填。
  • reference_image_urls:可选的参考图片链接数组,用于引导视频的风格或内容。
  • aspect_ratio:生成视频的宽高比,可选 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3。
  • resolution:输出分辨率,可选 480p(默认)、720p 或 1080p。
  • duration:生成视频的时长(秒)。grok-imagine-video-1.5-fast:reverse 取值范围 6–30,其余模型取值范围 1–15,默认 6。推荐使用 6 秒或 10 秒,这两个标准时长相对稳定。
  • callback_url:异步回调地址,设置后 API 会立即返回 task_id,任务完成时将结果 POST 到该地址。
  • async:可选,设为 true 时接口立即返回 task_id,无需提供 callback_url,随后通过对应的任务查询接口轮询获取结果。
点击「Try」按钮即可进行测试,得到的结果类似如下:
返回结果一共有多个字段,介绍如下:
  • success:本次视频生成请求是否成功。
  • task_id:本次视频生成任务的 ID。
  • trace_id:本次请求的跟踪 ID,用于排查问题。
  • data:生成的视频结果列表。
    • id:生成视频的唯一标识。
    • video_url:生成视频的链接地址。
    • state:视频生成任务的状态,可选 pending / succeeded / failed。
我们只需要根据结果中 data 的 video_url 链接地址获取生成的视频即可。 对应的 CURL 代码如下:
对应的 Python 代码如下:

图生视频

如果想基于一张输入图片生成视频,可以传入 image_url。使用 grok-imagine-video-1.5:official 时必须提供该字段:

参考图引导

如果想用一张或多张参考图引导生成视频的风格或内容,可以在 reference_image_urls 中传入图片链接数组:

异步回调

视频生成需要一定的处理时间。如果不希望保持长连接等待,可以传入 callback_url,此时 API 会立即返回 task_id,任务完成后会将最终结果 POST 到该地址:
立即返回的结果如下:

查询任务结果

如果使用了异步回调或希望主动查询任务状态,可以通过 Grok Tasks API(POST https://api.acedata.cloud/grok/tasks)根据 task_id 查询任务的最新状态与结果。

计费说明

本服务的计费方式由 model 决定:
  • grok-imagine-video-1.5-fast:reverse:按时长分档计费,与分辨率无关——6–10 秒、11–20 秒、21–30 秒分别对应不同档位价格。
  • grok-imagine-video:reverse:按「输出秒数」计费,总价 = 单价 × duration。
  • grok-imagine-video:official 与 grok-imagine-video-1.5:official:官方端点,按「输出秒数」计费,分辨率越高单价越高;官方模型即使内容审核失败也会计费。
具体单价以定价页为准。失败的请求不计费,也不占用免费额度。

错误处理

当请求出现问题时,API 会返回对应的错误码与说明,常见的如下:
  • 400:请求参数有误,例如文生视频缺少 prompt,或 grok-imagine-video-1.5:official 缺少 image_url,或 duration 超出范围(grok-imagine-video-1.5-fast:reverse 为 6–30,其余模型为 1–15)。
  • 401:鉴权失败,token 无效或与 API 不匹配。
  • 403:余额不足,或提示词命中内容审核被拒绝。
  • 429:请求过于频繁,请稍后重试。
  • 500:视频生成失败或服务异常。