# Grok Imagine 1.5 图片生成 API 对接文档

## 概述

Grok Imagine 1.5 图片生成接口，支持文生图（text-to-image）和图片编辑（image-editing）两种模式。**是否提供参考图会自动决定生成模式**：不传参考图为文生图，传入 1 张参考图为图片编辑。

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

---

## 认证方式

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

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

## 快速开始

### cURL 示例

**创建任务（文生图）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok-imagine-1.5" \
  -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"
  }'
```

**创建任务（图片编辑，带参考图）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/grok-imagine-1.5" \
  -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"]
  }'
```

**查询任务状态**
```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"
```

---

## 接口列表

### 1. 创建 Grok Imagine 1.5 任务

**POST** `/api/v2/open/aigc/grok-imagine-1.5`

创建一个 Grok Imagine 1.5 图片生成任务。**不传 `imageUrls`/`base64File` 时为文生图；传入参考图时自动切换为图片编辑。**

**Content-Type**: `application/json`

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 图片描述提示词，最多 2,000 字符 |
| genType | string | 否 | 生成类型：`t2i`(文生图,默认) / `i2i`(图片编辑)。也可不传，系统按是否带参考图自动判定 |
| imageUrls | string[] | 条件 | 参考图 URL 列表，图片编辑时必填，**最多 1 张**（多传只取第一张） |
| base64File | string | 否 | Base64 编码的参考图，支持 jpg/png/gif/webp，最大 10MB |
| aspectRatio | string | 否 | 宽高比，默认 `1:1`，支持：`1:1` / `16:9` / `9:16` / `3:2` / `2:3` |
| n | int | 否 | 生成数量，范围 1-10，默认 1。**按生成数量计费** |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

> **说明**：
> - `base64File` 与 `imageUrls` 二选一提供参考图即可；若同时提供，`base64File` 优先。
> - 图片编辑仅支持 1 张参考图。

#### 请求示例

**文生图：**
```json
{
  "prompt": "A beautiful sunset over the ocean, oil painting style",
  "aspectRatio": "16:9",
  "n": 2
}
```

**图片编辑：**
```json
{
  "prompt": "Transform this image into watercolor style",
  "genType": "i2i",
  "imageUrls": ["https://example.com/reference.jpg"]
}
```

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| 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** `/api/v2/open/aigc/{taskId}`

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

#### 路径参数

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

#### 响应参数

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

#### 响应示例

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

**失败**
```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"
  }
}
```

---

### 3. 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

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

#### 请求参数

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

#### 请求示例

```json
{
  "taskIds": ["task_20260810103000_abc12345", "task_20260810103200_def67890"]
}
```

---

## 回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 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 | 异步任务不存在，请检查 task_id |
| 90003 | 服务器内部错误 |

---

## 最佳实践

### 轮询策略

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

### 处理时间参考

- 文生图：通常 10 ~ 60 秒
- 图片编辑：通常 10 ~ 60 秒

### Prompt 编写建议

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