> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gregapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 图像生成（OpenAI 风格）

使用 OpenAI 兼容接口（`/v1/images/generations` 和 `/v1/images/edits`）调用 Gemini 图像生成模型，提供文生图和参考图编辑两个同步接口。兼容 OpenAI SDK，迁移成本低。

## 支持的模型

| 模型 | 最大分辨率 |
| - | - |
| `gemini-2.5-flash-image` | 1K（仅 1K） |
| `gemini-3-pro-image-preview` | 1K / 2K / 4K |
| `gemini-3.1-flash-image` | 512 / 1K / 2K / 4K |

## 认证方式

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

## 文生图 `/v1/images/generations`

**方法**：`POST`

**Base URL**：`https://api.gregapi.com/v1/images/generations`

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 取值 | 说明 |
| - | - | - | - | - | - |
| `model` | string | 是 | - | 模型名 | `gemini-2.5-flash-image`、`gemini-3-pro-image-preview`、`gemini-3.1-flash-image` |
| `prompt` | string | 是 | - | - | 图像描述文本 |
| `n` | integer | 否 | 1 | 仅支持 1 | 生成数量 |
| `size` | string | 否 | 自动推断 | `512` / `1K` / `2K` / `4K` 或 `widthxheight` | 分辨率；档位格式（推荐）或数字格式（历史兼容） |
| `aspect_ratio` | string | 否 | 自动推断 | 宽高比 | 显式指定宽高比 |
| `response_format` | string | 否 | `b64_json` | `b64_json` / `url` | 输出格式：base64 或 URL |

宽高比枚举：

```
1:1  2:3  3:2  3:4  4:3  4:5  5:4  9:16  16:9  21:9
```

`gemini-3.1-flash-image` 额外支持 `1:4`、`4:1`、`1:8`、`8:1`、`9:21`。

### 请求示例

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-3-pro-image-preview",
  "prompt": "A futuristic cityscape at sunset with flying cars",
  "size": "2K",
  "aspect_ratio": "16:9",
  "response_format": "b64_json"
}'
```

### 响应结构（`response_format=b64_json`）

```json theme={null}
{
  "created": 1700000000,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>",
      "revised_prompt": "优化后的提示词（如有）"
    }
  ]
}
```

### 响应结构（`response_format=url`）

```json theme={null}
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://example.com/xxx.png"
    }
  ]
}
```

### 封控但已计费的错误响应

```json theme={null}
{
  "error": {
    "message": "no image generated (request id: 20260608235925678097275ZgRxuG4y)",
    "type": "one_hub_error",
    "code": "no_image_generated"
  },
  "usage": {
    "input_tokens": 353,
    "output_tokens": 0,
    "total_tokens": 353,
    "output_tokens_details": null,
    "input_tokens_details": {
      "text_tokens": 95,
      "image_tokens": 258
    }
  }
}
```

仅当本次失败已产生可计费 prompt/input tokens 时才会返回 `usage`；参数校验失败、额度不足、网络失败或上游未返回 usage 的普通失败不会返回 `usage`。

## 参考图编辑 `/v1/images/edits`

**方法**：`POST`（multipart/form-data）

**Base URL**：`https://api.gregapi.com/v1/images/edits`

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| - | - | - | - | - |
| `model` | string | 是 | - | 模型名称 |
| `prompt` | string | 是 | - | 编辑指令 |
| `image` | file | 否 | - | 基准图（主图），与 `image_urls[]` 二选一 |
| `image[]` | file\[] | 否 | - | 参考图，最多 14 张 |
| `image_urls[]` | string\[] | 否 | - | 图片 URL 列表，第一个作为基准图，其余作为参考图；可与 `image`/`image[]` 混用 |
| `size` | string | 否 | 自动推断 | 输出分辨率，`512` / `1K` / `2K` / `4K` 或 `widthxheight` |
| `aspect_ratio` | string | 否 | 自动推断 | 显式指定宽高比 |
| `response_format` | string | 否 | `b64_json` | `b64_json` 或 `url` |
| `mask` | file | 否 | - | 蒙版图（局部编辑时使用） |

### 说明

* `image_urls[]` 第一个 URL 作为基准图，其余作为参考图；总计最多 14 张。
* 仅支持公网 HTTP/HTTPS 图片 URL，不支持 localhost 和内网 IP。
* 未指定 `size` 时自动从基准图推断（仅对 `gemini-3-pro-image-preview` 生效）。
* 显式传入 `aspect_ratio` 时优先使用指定宽高比。

### 改图示例

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=将这张图片转换为油画风格" \
  -F "response_format=url" \
  -F "image=@/path/to/base.png"
```

## 错误码

| HTTP 状态码 | 说明 | 解决方案 |
| - | - | - |
| 400 | 参数错误 | 检查 prompt、size 格式 |
| 413 | 图片过大 | 压缩参考图至 10MB 以内 |
| 429 | 超出限额 | 检查配额或等待重试 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.