视频生成 API

GetToken 视频 API 提供 Grok 文生视频和图生视频能力。视频采用异步任务方式生成：先创建任务，再查询状态，最后通过内容接口获取视频文件。

所有请求都使用 service_type=video_api 的专用 API Key。视频 Key 与普通文本 Key、生图 Key 分开管理，不能混用。

前提条件

已登录 GetToken 控制台。
已在控制台「视频 API」页面创建视频专用 API Key。
已了解 base_url 与线路选择（见 Codex 配置：原理与线路）。

以下示例使用：

base_url: https://api.gettoken.dev

接口地址

方法	路径	用途
POST	`/v1/videos/generations`	创建视频生成任务
GET	`/v1/videos/{task_id}`	查询任务状态
GET	`/v1/videos/{task_id}/content`	获取视频文件内容

当前正式协议只包含视频生成、状态查询和内容下载。视频编辑和视频延长不在本指南的支持范围内。

模型与输入方式

模型	文生视频	图生视频	参考图
`grok-imagine-video`	支持	支持	可选
`grok-imagine-video-1.5-preview`	不支持	支持	必填

图生视频仍然属于视频生成能力，不代表独立的图片生成接口。

创建参数

字段	必填	说明
`model`	是	使用上表中的正式模型 ID
`prompt`	是	描述希望生成的视频内容
`seconds`	是	1–15 秒，建议使用字符串，例如 `"8"`
`size`	是	使用下表中的明确宽高
`image_url`	图生视频必填	顶层字段，填写公网 HTTPS URL 或 Data URL

支持尺寸

`size`	方向与清晰度
`1280x720`	横屏 720p
`720x1280`	竖屏 720p
`1792x1024`	横屏 1080p
`1024x1792`	竖屏 1080p

当前正式尺寸不包含 480p。

参考图支持 JPEG、PNG 和 WebP。单图最大 60 MiB，整个请求体最大 96 MiB。使用公网 URL 时，地址必须能通过 HTTPS 直接访问。

创建文生视频

curl --fail https://api.gettoken.dev/v1/videos/generations \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A quiet city street after rain",
    "seconds": "8",
    "size": "1280x720"
  }'

创建图生视频

curl --fail https://api.gettoken.dev/v1/videos/generations \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "prompt": "让画面中的主体向前移动，镜头缓慢推进",
    "seconds": "8",
    "size": "1280x720",
    "image_url": "https://example.com/reference.webp"
  }'

创建成功后，请优先保存响应顶层的 id，并将它作为后续接口的 task_id。兼容响应中也可能出现 request_id 或 task_id。

查询任务状态

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  https://api.gettoken.dev/v1/videos/TASK_ID

正式状态包括：

状态	处理方式
`pending`	任务仍在生成，继续轮询
`done`	任务完成，调用内容接口下载
`expired`	停止轮询，读取响应中的错误信息

建议每 5–10 秒查询一次，客户端总等待时间可设置为 5 分钟。

任务完成时，状态响应可能类似：

{
  "id": "TASK_ID",
  "status": "done",
  "video": {
    "url": "/v1/videos/TASK_ID/content",
    "duration": 8
  }
}

这里的 video.url 是受鉴权的内容接口路径，不是已经包含在 JSON 中的视频文件。客户端仍需发起一次独立的 HTTP 请求，并携带 API Key 获取视频字节。

通过内容接口下载视频

状态接口返回的是任务信息，不是视频文件。任务完成后，必须继续请求 /v1/videos/{task_id}/content 才能获得视频内容。

使用创建任务时的同一把视频 API Key 下载：

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  https://api.gettoken.dev/v1/videos/TASK_ID/content \
  --output grok-video.mp4

不要直接依赖状态响应中的上游签名地址。GetToken 的内容接口会在服务端获取官方视频，并以 video/mp4 字节流返回给客户端。这样可以统一鉴权，也能避免客户端必须直接访问上游视频域名。

内容接口支持 HTTP Range。播放器、断点续传或分段下载可以传递 Range：

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Range: bytes=0-" \
  https://api.gettoken.dev/v1/videos/TASK_ID/content \
  --output grok-video.mp4

响应可能包含：

Content-Type: video/mp4
Accept-Ranges: bytes
Content-Length
Content-Range（分段请求时）

状态查询和内容下载不会重复计费。内容接口仍受任务归属和 API Key 权限校验保护，不能省略 Authorization，也不能换用其他 Key。

费用与保留时间

视频按实际生成时长计费，具体单价以控制台「视频 API」页面的实时报价为准。提交前可以按模型、清晰度和时长预估费用，最终费用以实际使用记录为准。

GetToken 视频结果保留 24 小时。任务进入 done 后请尽快通过内容接口保存到自己的存储中。

注意事项

创建结果不明确时，不要自动跨账号重复提交，以免产生重复任务和重复计费。
grok-imagine-video-1.5-preview 必须提供 image_url。
状态查询和内容下载必须使用创建任务时的同一把视频 API Key。
取消、批量生成和多参考图当前不开放。

本页内容