# 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 示例

**创建任务（文生图）**
```bash
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" }
  }'
```

**创建任务（图生图，带参考图）**
```bash
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" }
  }'
```

**查询任务状态**
```bash
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` |

```json
{
  "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`（保持参考图比例） |

```json
{
  "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` 至少提供其一 |

用前序任务作为分割源：

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

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

```json
{
  "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]`。

```json
{
  "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 | 创建时间 |

#### 响应示例

**成功**
```json
{
  "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 |

#### 响应示例

**成功**
```json
{
  "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`，带分割区域元数据）**
```json
{
  "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]`。
```json
{
  "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` 一致）：

```json
{
  "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 应描述希望进行的变换
- 支持多语言，英文效果通常更好