SuperToken

Appearance

SuperToken 文档

xAI 视频生成 ​

通过 SuperToken，你可以调用 xAI Grok Imagine 视频能力。接口采用异步任务模式：先提交生成任务，再查询任务状态，任务完成后获取视频地址。

接口地址 ​

text
https://api.supertoken.cc/v1

认证方式 ​

在请求头中添加 API 密钥：

http
Authorization: Bearer YOUR_API_KEY

模型说明 ​

xAI 官方视频 API 中，grok-imagine-video 和 grok-imagine-video-1.5-preview 的能力范围不同。SuperToken 提供按时长和分辨率区分的模型名，便于调度和计费。

SuperToken 模型名官方底层模型支持模式推荐参数
grok-imagine-video-15s-480pgrok-imagine-video纯文生视频、图生视频、参考图视频纯文生/图生视频 duration 最高 15 秒；参考图视频最高 10 秒；resolution 为 480p
grok-imagine-video-15s-720pgrok-imagine-video纯文生视频、图生视频、参考图视频纯文生/图生视频 duration 最高 15 秒；参考图视频最高 10 秒；resolution 为 720p
grok-imagine-video-1.5-preview-15s-480pgrok-imagine-video-1.5-preview图生视频duration 最高 15 秒，resolution 为 480p
grok-imagine-video-1.5-preview-15s-720pgrok-imagine-video-1.5-preview图生视频duration 最高 15 秒，resolution 为 720p

TIP

如果请求中显式传入 resolution，建议与所选规格模型名保持一致。

WARNING

grok-imagine-video-1.5-preview 需要一张起始图片。不要向 1.5 Preview 规格模型传 reference_images，也不要把它用于纯文生视频。纯文生视频和参考图视频请使用 grok-imagine-video-15s-480p 或 grok-imagine-video-15s-720p。

创建视频任务 ​

请求地址 ​

text
POST /v1/videos/generations

纯文生视频示例 ​

只传 prompt，由模型根据文字生成视频。这个模式适合从零生成完整场景。

图生视频示例 ​

上传或提供一张图片作为起始画面，模型会根据图片内容和提示词生成一段视频。这个模式适合让静态图片产生镜头运动、环境变化或主体动作。

参考图视频示例 ​

传入 prompt 和一张或多张参考图，让模型把参考图中的人物、物体、服装或风格融入生成视频。这个模式仍然由文本提示词驱动，但会额外参考多张图片；参考图不会强制成为第一帧，更适合做角色一致性、商品展示和风格参考。参考图视频目前请将 duration 控制在 10 秒以内。

请求参数 ​

参数类型必填说明
modelstring是SuperToken 模型名，如 grok-imagine-video-15s-720p
promptstring纯文生视频和参考图视频必填，图生视频可选视频提示词；图生视频未传时模型会仅根据输入图片生成视频
durationinteger否视频时长，范围 1-15 秒，默认 8 秒；使用 reference_images 参考图视频时最高 10 秒
secondsinteger/string否OpenAI 兼容别名，等价于 duration，同样受参考图视频 10 秒限制
aspect_ratiostring否支持 1:1、16:9、9:16、4:3、3:4、3:2、2:3，默认 16:9
resolutionstring否支持 480p、720p；建议与模型规格保持一致
imageobject图生视频必填图生视频输入，支持 { "url": "..." } 或 { "file_id": "..." }。url 可传公开图片地址或 base64 data URL
image_urlstring否兼容字段，等价于 image.url
reference_imagesarray参考图视频必填参考图列表，可传多张。每项支持 { "url": "..." } 或 { "file_id": "..." }，url 可传公开图片地址或 base64 data URL；多图参考生成视频目前最高 10 秒
output.upload_urlstring否将生成视频上传到指定签名 URL
userstring否终端用户标识

WARNING

一个请求只能使用一种生成模式：纯文生视频只传 prompt；图生视频传 prompt + image；参考图视频传 prompt + reference_images。image 和 reference_images 不要同时传。使用 reference_images 时，duration 不要超过 10 秒。

TIP

reference_images 是 grok-imagine-video 的参考图视频参数。grok-imagine-video-1.5-preview-* 规格模型只支持图生视频，请使用 image.url、image.file_id 或兼容字段 image_url。

创建响应 ​

json
{
  "request_id": "task_xxxxx",
  "id": "task_xxxxx"
}

request_id 和 id 都是 SuperToken 返回的任务 ID。调用成功后，可以用这个任务 ID 请求 /v1/videos/{task_id} 查询任务状态，也可以在 SuperToken 站点控制台的任务日志里查看接近实时的任务进度、任务状态和结果入口。

任务日志中的 xAI 视频任务

查询任务状态 ​

请求地址 ​

text
GET /v1/videos/{task_id}

请求示例 ​

输入任务 ID 查询异步任务的当前状态、进度和完成后的视频地址。创建接口返回的 id 可用于这里查询。

响应示例 ​

json
{
  "id": "task_xxxxx",
  "object": "video",
  "model": "grok-imagine-video-15s-720p",
  "status": "completed",
  "progress": 100,
  "created_at": 1780646461,
  "completed_at": 1780646520,
  "metadata": {
    "url": "https://example.com/video.mp4"
  }
}

状态说明 ​

status说明
queued排队中
in_progress生成中
completed已完成
failed失败

获取视频地址 ​

任务完成后，查询响应中的 metadata.url 会返回视频地址。控制台任务日志的结果列也会提供视频预览或打开入口。

其他 xAI 视频模式 ​

xAI 官方的 grok-imagine-video 还支持视频编辑和视频扩展模式，对应字段包括 video、/v1/videos/edits 和 /v1/videos/extensions。当前本文重点说明 /v1/videos/generations 的纯文生视频、图生视频和参考图视频。编辑和扩展如开放独立规格，请以模型广场和后续文档为准。

任务日志 ​

调用视频生成接口后，SuperToken 会在任务日志中创建异步任务记录。任务状态会接近实时更新，完成后可以在结果列预览或打开视频。

任务日志中的 xAI 视频任务

任务日志中的任务 ID 与 API 返回的 id 一致。排查问题时，可以用这个任务 ID 对照接口返回、平台记录和生成结果。

Python 完整示例 ​

python
import os
import time
import requests

API_KEY = os.environ.get("SUPERTOKEN_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://api.supertoken.cc/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "grok-imagine-video-15s-480p",
    "prompt": "Make the water crash down and slowly pan out the camera",
    "image": {
        "url": "https://docs.x.ai/assets/api-examples/video/waterfall-still.png",
    },
    "duration": 15,
    "resolution": "480p",
}

create_resp = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=120,
)
create_resp.raise_for_status()

task_id = create_resp.json()["id"]
print("任务 ID:", task_id)

while True:
    status_resp = requests.get(
        f"{BASE_URL}/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    )
    status_resp.raise_for_status()
    task = status_resp.json()

    print("状态:", task["status"], "进度:", task.get("progress"))

    if task["status"] == "completed":
        print("视频地址:", task.get("metadata", {}).get("url"))
        break

    if task["status"] == "failed":
        raise RuntimeError(task.get("error") or task)

    time.sleep(5)

注意事项 ​

  • 视频接口是异步任务，不会在创建接口里直接返回视频文件。
  • 请求体使用 application/json，不要使用 multipart 表单。
  • grok-imagine-video-15s-* 支持纯文生视频、图生视频和参考图视频。
  • grok-imagine-video-1.5-preview-15s-* 只支持图生视频，需要传入一张图片。
  • 公开图片 URL、base64 data URL 和 file_id 都可以用于 image 或 reference_images。
  • 多图参考生成视频目前最高 10 秒；纯文生视频和普通图生视频仍可按模型规格使用 15 秒。
  • 不要向 1.5 Preview 规格模型传 reference_images。
  • 生成耗时通常比文本和图片更长，建议轮询间隔设置为 5 秒以上。
  • 完成后读取 metadata.url 获取视频地址。
  • 视频 URL 可能有有效期，长期保存请及时自行转存。

下一步 ​

SuperToken - 让全球顶级 AI 模型触手可达

Copyright © 2026-present SuperToken