Grok Imagine 图片/视频生成

查看 Markdown 原文

概述

Grok Imagine 图片/视频生成接口，支持文生图、图生图、文生视频、图生视频四种模式。

Base URL: https://api.apiverse.ai

认证方式

所有接口均需要在请求头中携带 Token 进行认证：

Authorization: Bearer {YOUR_AUTH_TOKEN}

快速开始

cURL 示例

创建 Grok 任务（文生图）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "aspectRatio": "16:9",
    "enablePro": true
  }'

创建 Grok 任务（图生图）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform the image into watercolor style",
    "genType": "i2i",
    "imageUrls": ["https://example.com/reference.jpg"]
  }'

创建 Grok 任务（文生视频）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A couple dancing in a bed",
    "genType": "t2v",
    "mode": "normal",
    "duration": 6,
    "resolution": "480p"
  }'

创建 Grok 任务（图生视频）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Make the person in the image dance",
    "genType": "i2v",
    "imageUrls": ["https://example.com/reference.jpg"],
    "mode": "fun",
    "duration": 6
  }'

查询任务状态

curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"

查询账户余额

curl -X GET "https://api.apiverse.ai/api/v2/open/balance" \
  -H "Authorization: Bearer your_auth_token_here"

接口列表

1. 创建 Grok Imagine 任务

POST /api/v2/open/aigc/grok

创建一个 Grok Imagine 图片或视频生成任务。

Content-Type: application/json

请求参数

参数类型必填说明
promptstring是图片/视频描述提示词
genTypestring否生成类型：t2i(文生图,默认) / i2i(图生图) / t2v(文生视频) / i2v(图生视频)
imageUrlsstring[]条件参考图片 URL 列表，图生图/图生视频时必填
base64Filestring否Base64 编码的图片数据，支持 jpg/png/gif/webp，最大 10MB
base64FileListstring[]否Base64 编码的多张图片数据，每张支持 jpg/png/gif/webp，单张最大 10MB
aspectRatiostring否宽高比：2:3 / 3:2 / 1:1 / 16:9 / 9:16，默认 1:1
enableProboolean否质量模式（仅文生图有效），true=高质量，false=速度优先
modestring否运动风格（仅视频有效）：fun / normal(默认) / spicy
durationinteger否视频时长（仅视频有效）：6/10/15/20/30秒，默认6秒
resolutionstring否视频分辨率（仅视频有效）：480p(默认) / 720p
callbackUrlstring否任务完成后的回调通知 URL
说明：
- base64File、imageUrls、base64FileList 可同时使用，图片处理顺序为：base64File（单张，放最前面）→ imageUrls（URL列表）→ base64FileList（多张base64，追加到末尾）
- 图生图/图生视频时必须提供参考图片
- 视频参数（mode/duration/resolution）仅在 t2v 和 i2v 模式下生效
- 创建任务时会预扣费，余额不足将返回错误

请求示例

文生图：

{
  "prompt": "A beautiful sunset over the ocean, oil painting style",
  "aspectRatio": "16:9",
  "enablePro": true
}

图生图：

{
  "prompt": "Transform this image into watercolor style",
  "genType": "i2i",
  "imageUrls": ["https://example.com/reference.jpg"]
}

文生视频：

{
  "prompt": "A couple dancing in a romantic setting",
  "genType": "t2v",
  "aspectRatio": "16:9",
  "mode": "normal",
  "duration": 10,
  "resolution": "720p"
}

图生视频：

{
  "prompt": "Make the person wave their hand",
  "genType": "i2v",
  "imageUrls": ["https://example.com/reference.jpg"],
  "mode": "fun",
  "duration": 6,
  "resolution": "480p"
}

响应参数

参数类型说明
codeint状态码，0 表示成功
msgstring状态信息
data.taskIdstring任务 ID，用于查询任务状态
data.statusstring任务状态，创建时固定为 processing
data.createdAtstring创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260422103000_abc12345",
    "status": "processing",
    "createdAt": "2026-04-22 10:30:00"
  }
}

余额不足

{
  "code": 40001,
  "msg": "余额不足，当前余额: 0.0100 USD，需要: 0.0750 USD",
  "data": null
}

2. 查询任务状态

GET /api/v2/open/aigc/{taskId}

查询单个任务的执行状态。

路径参数

参数类型必填说明
taskIdstring是任务 ID

响应参数

参数类型说明
codeint状态码，0 表示成功
msgstring状态信息
data.taskIdstring任务 ID
data.statusstring任务状态：processing / success / failed
data.resultstring[]生成的图片/视频 URL 列表（成功时返回）
data.errorMsgstring错误信息（失败时返回）
data.createdAtstring创建时间
data.updatedAtstring更新时间

响应示例

处理中

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260422103000_abc12345",
    "status": "processing",
    "createdAt": "2026-04-22 10:30:00",
    "updatedAt": "2026-04-22 10:30:05"
  }
}

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260422103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/04/22/output_001.png"
    ],
    "createdAt": "2026-04-22 10:30:00",
    "updatedAt": "2026-04-22 10:31:30"
  }
}

失败

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260422103000_abc12345",
    "status": "failed",
    "errorMsg": "生成失败：内容不符合规范",
    "createdAt": "2026-04-22 10:30:00",
    "updatedAt": "2026-04-22 10:30:45"
  }
}

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

批量查询多个任务的执行状态（最多 100 个）。

请求参数

参数类型必填说明
taskIdsstring[]是任务 ID 列表，最多 100 个

请求示例

{
  "taskIds": ["task_20260422103000_abc12345", "task_20260422103200_def67890"]
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "tasks": [
      {
        "taskId": "task_20260422103000_abc12345",
        "status": "success",
        "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
        "createdAt": "2026-04-22 10:30:00",
        "updatedAt": "2026-04-22 10:31:30"
      },
      {
        "taskId": "task_20260422103200_def67890",
        "status": "processing",
        "createdAt": "2026-04-22 10:32:00",
        "updatedAt": "2026-04-22 10:32:05"
      }
    ]
  }
}

4. 查询账户余额

GET /api/v2/open/balance

查询当前用户的账户余额。

响应参数

参数类型说明
codeint状态码，0 表示成功
msgstring状态信息
data.userIdstring用户 ID
data.balancestring可用余额（USD）
data.frozenBalancestring冻结余额（USD）
data.currencystring货币类型

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "userId": "user@example.com",
    "balance": "19.9250",
    "frozenBalance": "0.0750",
    "currency": "USD"
  }
}

回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 callbackUrl，系统会向该 URL 发送 POST 请求。

回调请求

Headers

Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}

Body

{
  "event": "task.completed",
  "taskId": "task_20260422103000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
  "errorMsg": "",
  "timestamp": "2026-04-22T10:31:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}

回调响应

接收方应返回 HTTP 2xx 状态码表示成功接收：

{
  "code": 0,
  "msg": "ok"
}

运动风格说明（mode 参数）

值说明
fun有趣风格，动作幅度较大，适合卡通/搞笑场景
normal正常风格（默认），自然流畅的运动
spicy强烈风格，更具戏剧性的动作效果

错误码

code说明
0成功
10002参数缺失或格式错误
10005API Key 无效或缺失
30003任务不存在
40001余额不足
90003服务器内部错误

最佳实践

1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

2. 使用回调

对于生产环境，建议使用回调通知而非轮询，可以：
- 减少 API 调用次数
- 更快获得结果通知
- 降低服务器压力

3. 处理时间参考

  • 文生图：通常 10 ~ 30 秒
  • 图生图：通常 10 ~ 30 秒
  • 文生视频：通常 1 ~ 3 分钟（根据时长）
  • 图生视频：通常 1 ~ 3 分钟（根据时长）

4. 余额管理

  • 创建任务前建议先查询余额，避免因余额不足导致任务失败
  • 任务成功后会从冻结余额中扣费
  • 任务失败后冻结金额会自动退还到可用余额