AI Video APIAI Video API

Grok Imagine

Grok Imagine 是 xAI 的视频生成模型,支持文生视频和图生视频,可选 fun、normal、spicy 运动风格。

模型

模型名称模式
grok-imagine-text-to-video文生视频
grok-imagine-image-to-video图生视频,支持单图或多图参考

定价

按秒 × 分辨率计费:

分辨率积分/秒
480p2.4
720p4.5

6 秒 480p 视频约 15 积分;10 秒 720p 视频约 45 积分。

创建任务

POST https://api.aivideoapi.ai/v1/videos/generations

请求体

字段类型必填说明
modelstring是见上方模型列表
inputobject是生成参数
callback_urlstring否接收任务完成/失败通知的 URL

通用字段

字段类型必填说明
promptstring视情况文本提示词,最长 5000 字符。文生视频必填;图生视频可选
aspect_ratiostring否2:3、3:2、1:1、16:9、9:16,默认 2:3。图生视频仅在多图输入时生效,单图模式跟随源图宽高比
modestring否生成模式,影响运动风格和强度,见下方说明。默认 normal
durationinteger否6-30 秒,默认 6
resolutionstring否480p 或 720p,默认 480p
nsfw_checkerboolean否默认 true,设为 false 可关闭内容过滤

mode 取值

取值说明
fun更具创意和趣味性的演绎
normal平衡风格,运动质量良好
spicy更动感、更强烈的运动效果(不支持外部图片输入)

注意:spicy 仅适用于文生视频;图生视频(传入 image_urls)只能使用 fun 或 normal。

文生视频 Input

仅使用通用字段,prompt 必填。

图生视频 Input

字段类型必填说明
image_urlsstring[]是1-7 张公网 HTTP(S) 图片 URL。JPEG/PNG/WEBP,每张最大 10MB。可在 prompt 中用 @image1、@image2 等引用

示例

文生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-text-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "一条超现实走廊里,几扇门依次打开,门内是不同的微型客厅。",
      "aspect_ratio": "2:3",
      "duration": 6,
      "resolution": "480p"
    }
  }'

图生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "image_urls": ["https://example.com/portrait.png"],
      "prompt": "她缓缓转头微笑,镜头慢慢推近。",
      "duration": 6,
      "resolution": "720p"
    }
  }'

图生视频(多图 + @image 引用)

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/coffee.jpg"
      ],
      "prompt": "@image1 坐在办公桌前;有人把 @image2 放到她面前,她拿起来。",
      "aspect_ratio": "16:9",
      "duration": 6
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态流转: pending -> processing -> completed 或 failed。

处理中

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "processing",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "progress": null
}

完成(文生视频)

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "completed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "completed_at": 1779624200,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/21328ece-4fe3-4b4b-8a60-516080938e78.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/text-to-video",
      "costTime": 41,
      "completeTime": 1779624193000
    }
  }
}

完成(图生视频)

{
  "id": "45168da4-8b09-4208-bc7d-dc872c1a7602",
  "status": "completed",
  "model": "grok-imagine-image-to-video",
  "created_at": 1779624320,
  "completed_at": 1779624386,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/0c36f21f-f270-49d5-a3f4-dc0c05b4cb86.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/image-to-video",
      "costTime": 52,
      "completeTime": 1779624376000
    }
  }
}

视频 URL 有效期为 24 小时,请在生成完成后及时下载。

失败

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

任务失败时,预扣积分会自动退还。

回调 (Callback)

创建任务时传入 callback_url,系统会在任务完成或失败时自动向你的 URL 发送 POST 请求。

任务完成时回调

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "completed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "completed_at": 1779624200,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/21328ece-4fe3-4b4b-8a60-516080938e78.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/text-to-video",
      "costTime": 41,
      "completeTime": 1779624193000
    }
  }
}

任务失败时回调

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码错误码类型说明
400invalid_requestinvalid_request_error缺少必填参数或参数无效
401invalid_api_keyauthentication_errorAPI Key 无效、已禁用或已删除
402insufficient_creditsbilling_error积分余额不足，请充值
403ip_not_allowedpermission_error请求 IP 不在 Key 的白名单中
404model_not_foundinvalid_request_error模型不存在或已停用
404task_not_foundinvalid_request_error任务 ID 不存在
429rate_limit_exceededrate_limit_error请求过于频繁，请降低频率
429spend_limit_exceededbilling_error达到 Key 的消费限额（每小时/每天/总量）
500internal_errorapi_error服务器内部错误
503upstream_errorupstream_error上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

  • Key 不以 sk- 开头
  • Key 已被禁用或删除
  • 用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

  • 输入内容包含敏感或违规信息
  • 上游服务暂时不可用
  • 请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。