Grok Imagine 2.0 图片生成 API 文档

概述

Grok Imagine 2.0 图片生成接口，通过统一的创建接口 + extra_body.operation 字段区分 4 种方法（method）：

方法	operation	说明
文生图	`text-to-image`	纯文本描述生成图片
图生图	`image-edit`	基于 1~5 张参考图 + 提示词进行编辑/重绘
分割图	`segment-map`	对图片进行区域分割，返回每个区域的掩码图 + 名称 + 索引
分割编辑	`segment-edit`	基于前序任务的分割结果，对指定区域进行编辑

所有方法均为异步任务：创建接口返回 taskId，通过查询接口轮询获取结果。

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

认证方式

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

Authorization: Bearer {YOUR_AUTH_TOKEN}

快速开始

cURL 示例

创建任务（文生图）

curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-2-0",
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "size": "16:9",
    "extra_body": { "operation": "text-to-image" }
  }'

创建任务（图生图，带参考图）

curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-2-0",
    "prompt": "Transform the image into watercolor style",
    "image": ["https://example.com/reference.jpg"],
    "size": "auto",
    "extra_body": { "operation": "image-edit" }
  }'

查询任务状态

curl -X GET "https://api.apiverse.ai/v1/images/generations/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"

接口列表

1. 创建 Grok Imagine 2.0 任务

POST /v1/images/generations

创建一个 Grok Imagine 2.0 图片生成任务。通过 extra_body.operation 指定方法。

Content-Type: application/json

公共请求参数

参数	类型	必填	说明
model	string	是	固定填 `grok-imagine-2-0`
prompt	string	是	提示词。所有方法均必填（`segment-map` 逻辑上不使用，但需传占位文本）
extra_body	object	是	方法参数容器，见下方 `extra_body` 字段说明
size	string	否	宽高比，仅 `text-to-image` / `image-edit` 生效
image	string[]	条件	参考图 URL 列表。`image-edit` 必填（1~5 张）；`segment-map` 可用单张作为分割源（与 `source_task_id` 二选一）
callback_url	string	否	任务完成后的回调通知 URL
task_nickname	string	否	任务昵称，查询/下载时便于识别

`extra_body` 字段

参数	类型	必填	说明
operation	string	是	方法：`text-to-image` / `image-edit` / `segment-map` / `segment-edit`
source_task_id	string	条件	前序任务的 `taskId`；`segment-edit` 必填，`segment-map` 与 `image` 二选一
mask_indexs	int[]	否	掩码索引数组，仅 `segment-edit` 可选。取值 = `segment-map` 返回的 `index + 1`（详见下方说明）

各方法参数明细

① 文生图 text-to-image

参数	必填	说明
prompt	是	图片描述提示词
size	否	宽高比，默认 `1:1`，可选 `1:1` / `2:3` / `3:2` / `16:9` / `9:16`

{
  "model": "grok-imagine-2-0",
  "prompt": "A futuristic city at night, neon lights, cyberpunk",
  "size": "16:9",
  "extra_body": { "operation": "text-to-image" }
}

② 图生图 image-edit

参数	必填	说明
prompt	是	描述希望对参考图进行的变换
image	是	参考图 URL 列表，1~5 张（超过 5 张只取前 5 张）
size	否	宽高比，可选值同上，额外支持 `auto`（保持参考图比例）

{
  "model": "grok-imagine-2-0",
  "prompt": "Transform this image into watercolor style",
  "image": [
    "https://example.com/ref1.jpg",
    "https://example.com/ref2.jpg"
  ],
  "size": "auto",
  "extra_body": { "operation": "image-edit" }
}

③ 分割图 segment-map

对一张图片进行区域分割，返回每个区域的掩码图 + 区域名称 + 区域索引（index），供 segment-edit 定位编辑目标。

分割源二选一：

参数	必填	说明
prompt	是	框架要求非空，传占位文本即可（如 `"segment"`）
extra_body.source_task_id	二选一	前序任务的 `taskId`（须为当前账号下已成功的 Grok Imagine 2.0 任务）
image	二选一	直接传单张图片 URL 作为分割源（数组只取第一张）。与 `source_task_id` 至少提供其一

用前序任务作为分割源：

{
  "model": "grok-imagine-2-0",
  "prompt": "segment",
  "extra_body": {
    "operation": "segment-map",
    "source_task_id": "task_20260810103000_abc12345"
  }
}

直接传参考图作为分割源：

{
  "model": "grok-imagine-2-0",
  "prompt": "segment",
  "image": ["https://example.com/photo.jpg"],
  "extra_body": { "operation": "segment-map" }
}

说明：该方法成功后，除 result[]（掩码图 URL 列表）外，还在 grokOutput.segments[] 中返回每个区域的 maskUrl / name / index。index 从 0 开始；将某个 index 传给 segment-edit 时需 +1（详见方法 ④）。

④ 分割编辑 segment-edit

基于前序 segment-map 任务的分割结果，对指定区域进行编辑。

参数	必填	说明
prompt	是	描述对目标区域的编辑内容
extra_body.source_task_id	是	前序 `segment-map` 任务的 `taskId`
extra_body.mask_indexs	否	要编辑的区域索引数组；不传则按默认处理

索引换算（重要）：mask_indexs 的取值 = segment-map 返回的 grokOutput.segments[].index 加 1。
segment-map 的 index 从 0 开始，而 mask_indexs 从 1 开始。
例：要编辑 segment-map 中 index=0 的区域，mask_indexs 传 [1]；编辑 index=2 的区域传 [3]。

{
  "model": "grok-imagine-2-0",
  "prompt": "Change the sky to a starry night",
  "extra_body": {
    "operation": "segment-edit",
    "source_task_id": "task_20260810103000_abc12345",
    "mask_indexs": [1, 3]
  }
}

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID，用于查询任务状态
data.status	string	任务状态，创建时固定为 `processing`
data.createdAt	string	创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-10 10:30:00"
  }
}

2. 查询任务状态

GET /v1/images/generations/{taskId}

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

路径参数

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

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID
data.status	string	任务状态：`processing` / `success` / `failed`
data.result	string[]	生成的图片 URL 列表（成功时返回；`segment-map` 返回掩码图 URL 列表）
data.grokOutput	object	仅 `segment-map` 成功时返回，见下方 `grokOutput` 说明
data.errorCode	string	错误码（失败时返回）
data.errorMsg	string	错误信息（失败时返回）
data.progress	int	进度，0-100
data.pointConsume	string	实际消费点数（decimal 字符串）
data.taskNickname	string	任务昵称（创建时传入则返回）
data.createdAt	string	创建时间（字符串）
data.updatedAt	string	更新时间（字符串）

`grokOutput` 字段（仅 `segment-map` 成功时返回）

参数	类型	说明
grokOutput.segments	object[]	分割区域列表
grokOutput.segments[].maskUrl	string	该区域掩码图 URL
grokOutput.segments[].name	string	该区域名称
grokOutput.segments[].index	int	该区域索引，从 0 开始；用于 `segment-edit` 时需 +1

响应示例

成功

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

成功（segment-map，带分割区域元数据）

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260810103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/08/10/mask_000.png",
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/08/10/mask_001.png"
    ],
    "grokOutput": {
      "segments": [
        { "maskUrl": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/08/10/mask_000.png", "name": "sky", "index": 0 },
        { "maskUrl": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/08/10/mask_001.png", "name": "person", "index": 1 }
      ]
    },
    "createdAt": "2026-08-10 10:30:00",
    "updatedAt": "2026-08-10 10:31:30"
  }
}

编辑上例中 index=0（sky）区域时，segment-edit 的 mask_indexs 传 [1]。

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

回调通知

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

Headers

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

Body（任务详情包裹在 data 字段中，结构与「查询任务状态」接口的 data 一致）：

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

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
30003	异步任务不存在，请检查 taskId
90003	服务器内部错误

最佳实践

方法选择

从零生成 → text-to-image
已有参考图做重绘/风格化 → image-edit
想对某张已生成图做局部编辑 → 先 segment-map 拿到 grokOutput.segments（含 index），再 segment-edit 传 mask_indexs（= 目标 index + 1）编辑目标区域

轮询策略

前 30 秒：每 3 秒查询一次
30 秒 ~ 2 分钟：每 5 秒查询一次
2 分钟后：每 10 秒查询一次

处理时间参考

文生图 / 图生图：通常 10 ~ 60 秒
分割图 / 分割编辑：通常 10 ~ 60 秒

Prompt 编写建议

使用清晰、具体的描述，可指定艺术风格（如 oil painting, watercolor, digital art 等）
图生图与分割编辑时，prompt 应描述希望进行的变换
支持多语言，英文效果通常更好

Grok Imagine 2.0 图片生成

概述

认证方式

快速开始

cURL 示例

接口列表

1. 创建 Grok Imagine 2.0 任务

公共请求参数

extra_body 字段

各方法参数明细

响应参数

响应示例

2. 查询任务状态

路径参数

响应参数

grokOutput 字段（仅 segment-map 成功时返回）

响应示例

回调通知

错误码

最佳实践

方法选择

轮询策略

处理时间参考

Prompt 编写建议

`extra_body` 字段

`grokOutput` 字段（仅 `segment-map` 成功时返回）