# Grok 图像生成
> 文生图与参考图编辑
> 参考图最多 5 张，一次最多 10 张
> 支持多图占位符精确指定</
`POST /v1/images/generations`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求结构
请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 `content` 数组包装。
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | `prompt` |
| 单图编辑 | `prompt` + `image`（1 张） |
| 多图参考 | `prompt` + `image`（多张） |
多图时占位符 `<IMAGE_0>`、`<IMAGE_1>` 按数组位置对应。`grok-imagine-image` 支持到 `<IMAGE_4>`，`grok-imagine-image-quality` 支持到 `<IMAGE_2>`。
两套模型字段不同：1.5 系列用 `size` 控制画幅，官方模型用 `aspect_ratio` 加 `resolution`，不要混用。
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含图片本身。拿结果用 `task_id` 轮询[获取任务状态](../tasks/status.html)，图片地址在 `result.images[0].url`，该地址会过期，请及时转存。
- `model` (string / 必填) — 取值见下方模型列表。 `grok-imagine-1.5-ext` 是 `grok-imagine-1.5-apimart` 的等价别名。
- `prompt` (string / 必填) — 画面描述，中英文均可。官方模型上限 8000 字符。
- `size` (string / 可选) — 1.5 系列使用，宽高比取值 `1:1`（默认）、`16:9`、`9:16`、`3:2`、`2:3`。只能写比例，不能写像素。
- `aspect_ratio` (string / 可选) — 官方模型使用，默认 `auto`。 取值 `1:1`、`3:4`、`4:3`、`9:16`、`16:9`、`2:3`、`3:2`、`9:19.5`、`19.5:9`、`9:20`、`20:9`、`1:2`、`2:1`、`auto`。
- `resolution` (string / 可选) — 官方模型使用，取值 `1k`（默认）、`2k`。不要传像素值。
- `n` (integer / 可选) — 生成张数，取值 1 到 10，默认 `1`。必须传数字。
- `image` (string | string[] / 可选) — 参考图，1.5 系列最多 5 张，官方版 `grok-imagine-image` 最多 5 张、`-quality` 最多 3 张。 必须是公网可达的绝对地址。不用时整段省略，不要传空数组。
- `nsfw_check` (boolean / 可选) — 为 `true` 时先做内容审查，默认 `false`。
## 两套响应结构
1.5 系列的提交返回 HTTP 200，任务 ID 在 `data[].task_id`：
```json
{ "code": 200, "data": [{ "status": "submitted", "task_id": "task_01K..." }] }
```
官方模型返回 HTTP 202，任务 ID 在 `data.id`：
```json
{
  "code": 202,
  "request_id": "req_xxx",
  "data": {
    "id": "task_01K...",
    "object": "generation.task",
    "type": "image",
    "status": "pending",
    "progress": 0,
    "poll_url": "/v1/tasks/task_01K..."
  }
}
```
两者都用同一个任务状态接口轮询。
## 响应
提交成功返回受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
完成态返回：
```json
{
  "code": 200,
  "data": {
    "id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        { "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
      ]
    },
    "created": 1763088289,
    "completed": 1763088302
  }
}
```
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 payment_required |
| 429 | 触发限流 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `grok-imagine-1.5-apimart` | 默认型号，支持文生图与编辑，一次最多 10 张 |
| `grok-imagine-1.5-ext` | 上者的等价别名 |
| `grok-imagine-image` | 官方通道，1k / 2k，参考图 0 到 5 张 |
| `grok-imagine-image-quality` | 官方通道高画质，参考图 0 到 3 张 |
`quality` 字段在官方模型上不支持，不要传。
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://api.oairoute.com/api/pricing`。
## 使用示例
**文生图{Text to image}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-imagine-1.5-apimart",
  "prompt": "赛博朋克街角，雨后霓虹倒影",
  "size": "16:9",
  "n": 1
}'
```
**文生图{Text to image}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "grok-imagine-1.5-apimart",
  "prompt": "赛博朋克街角，雨后霓虹倒影",
  "size": "16:9",
  "n": 1
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生图{Text to image}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "grok-imagine-1.5-apimart",
  "prompt": "赛博朋克街角，雨后霓虹倒影",
  "size": "16:9",
  "n": 1
}),
});
console.log(await res.json());
```
**200 文生图{Text to image}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**单图编辑{Image edit}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-imagine-1.5-apimart",
  "prompt": "把背景换成深夜街道，保持人物不变",
  "image": [
    "https://example.com/person.png"
  ]
}'
```
**单图编辑{Image edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "grok-imagine-1.5-apimart",
  "prompt": "把背景换成深夜街道，保持人物不变",
  "image": [
    "https://example.com/person.png"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**单图编辑{Image edit}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "grok-imagine-1.5-apimart",
  "prompt": "把背景换成深夜街道，保持人物不变",
  "image": [
    "https://example.com/person.png"
  ]
}),
});
console.log(await res.json());
```
**200 单图编辑{Image edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**多图参考{Multi reference}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-imagine-1.5-apimart",
  "prompt": "<IMAGE_0> 中的人物穿着 <IMAGE_1> 的外套",
  "image": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}'
```
**多图参考{Multi reference}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "grok-imagine-1.5-apimart",
  "prompt": "<IMAGE_0> 中的人物穿着 <IMAGE_1> 的外套",
  "image": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多图参考{Multi reference}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "grok-imagine-1.5-apimart",
  "prompt": "<IMAGE_0> 中的人物穿着 <IMAGE_1> 的外套",
  "image": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}),
});
console.log(await res.json());
```
**200 多图参考{Multi reference}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**批量出图{Batch}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-imagine-1.5-apimart",
  "prompt": "极简线条风格的季节图标",
  "size": "1:1",
  "n": 10
}'
```
**批量出图{Batch}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "grok-imagine-1.5-apimart",
  "prompt": "极简线条风格的季节图标",
  "size": "1:1",
  "n": 10
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**批量出图{Batch}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "grok-imagine-1.5-apimart",
  "prompt": "极简线条风格的季节图标",
  "size": "1:1",
  "n": 10
}),
});
console.log(await res.json());
```
**200 批量出图{Batch}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```