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

# 生成图片

# ominiapi OpenAI Images 原生格式接口文档

## 1. 通用信息

**Base URL**

```text theme={null}
https://www.ominiapi.com
```

**请求头**

生成图片接口使用 JSON 请求：

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

图片编辑接口使用表单文件上传：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
```

使用 `curl -F` 上传文件时，不需要手动设置 `Content-Type: multipart/form-data`，`curl` 会自动生成包含 boundary 的请求头。

**接口格式**

```http theme={null}
POST /v1/images/generations/
POST /v1/images/edits/
```

实际可用模型以 ominiapi/new-api 后台渠道配置为准。

## 2. 图片生成接口

根据文本提示词生成图片。

### 接口地址

```http theme={null}
POST /v1/images/generations/
```

### 请求 URL 示例

```text theme={null}
https://www.ominiapi.com/v1/images/generations/
```

### 请求参数

| 参数           | 类型      | 必填 | 说明                                                                                           |
| ------------ | ------- | -- | -------------------------------------------------------------------------------------------- |
| `model`      | string  | 否  | 图片生成模型。NewAPI 文档列出的模型包括 `dall-e-2`、`dall-e-3`、`gpt-image-1`，默认通常为 `dall-e-2`；实际可用模型以后台渠道配置为准 |
| `prompt`     | string  | 是  | 图片生成提示词。`gpt-image-1` 最大 32000 字符，`dall-e-2` 最大 1000 字符，`dall-e-3` 最大 4000 字符                |
| `n`          | integer | 否  | 生成图片数量，范围 `1` 到 `10`；`dall-e-3` 仅支持 `n=1`                                                    |
| `size`       | string  | 否  | 输出图片尺寸，不同模型支持的尺寸不同                                                                           |
| `background` | string  | 否  | 仅 `gpt-image-1` 支持。背景类型，可选 `transparent`、`opaque`、`auto`                                     |
| `moderation` | string  | 否  | 仅 `gpt-image-1` 支持。内容审核强度，可选 `low`、`auto`                                                    |
| `quality`    | string  | 否  | 图片质量，具体可用值取决于模型和渠道支持                                                                         |
| `stream`     | string  | 否  | 是否启用流式返回，具体行为取决于渠道支持                                                                         |
| `style`      | string  | 否  | 图片风格，具体可用值取决于模型和渠道支持                                                                         |
| `user`       | string  | 否  | 代表最终用户的唯一标识符，可用于监控和检测滥用行为                                                                    |

### size 参数

| 模型            | 可选值                                        |
| ------------- | ------------------------------------------ |
| `gpt-image-1` | `1024x1024`、`1536x1024`、`1024x1536`、`auto` |
| `dall-e-2`    | `256x256`、`512x512`、`1024x1024`            |
| `dall-e-3`    | `1024x1024`、`1792x1024`、`1024x1792`        |

### 请求体示例

```json theme={null}
{
  "model": "gpt-image-1",
  "prompt": "A cute baby sea otter wearing a beret.",
  "n": 1,
  "size": "1024x1024"
}
```

### curl 示例

```bash theme={null}
curl -X POST "https://www.ominiapi.com/v1/images/generations/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A cute baby sea otter wearing a beret.",
    "n": 1,
    "size": "1024x1024"
  }'
```

### 透明背景请求体示例

`background` 仅支持 `gpt-image-1`。如果设置为 `transparent`，输出格式需要支持透明度，例如 `png` 或 `webp`。

```json theme={null}
{
  "model": "gpt-image-1",
  "prompt": "A clean product icon of a glass bottle on transparent background.",
  "size": "1024x1024",
  "background": "transparent"
}
```

### 响应示例

返回图片可能是 base64，也可能是图片 URL。

```json theme={null}
{
  "created": 0,
  "data": [
    {
      "b64_json": "BASE64_IMAGE_DATA",
      "url": "https://example.com/generated-image.png"
    }
  ],
  "usage": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    }
  }
}
```

### 保存 base64 图片示例

```bash theme={null}
curl -X POST "https://www.ominiapi.com/v1/images/generations/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A cute baby sea otter wearing a beret.",
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png
```

## 3. 图片编辑接口

根据原始图片、可选遮罩和文本提示词创建编辑图片或扩展图片。

### 接口地址

```http theme={null}
POST /v1/images/edits/
```

### 请求 URL 示例

```text theme={null}
https://www.ominiapi.com/v1/images/edits/
```

### 请求参数

| 参数                | 类型     | 必填 | 说明                                                                      |
| ----------------- | ------ | -- | ----------------------------------------------------------------------- |
| `image`           | file   | 是  | 要编辑的图片。必须是有效 PNG 文件，小于 `4MB`，并且是方形图片。如果未提供 `mask`，图片必须具有透明度，透明区域将作为编辑遮罩 |
| `mask`            | file   | 否  | 遮罩图片。完全透明区域表示 `image` 中需要编辑的位置。必须是有效 PNG 文件，小于 `4MB`，尺寸与原始 `image` 相同   |
| `prompt`          | string | 是  | 图片编辑提示词，最大 1000 字符                                                      |
| `n`               | string | 否  | 生成图片数量，范围 `1` 到 `10`                                                    |
| `size`            | string | 否  | 输出图片尺寸，可选 `256x256`、`512x512`、`1024x1024`                               |
| `response_format` | string | 否  | 返回格式，可选 `url`、`b64_json`                                                |
| `user`            | string | 否  | 代表最终用户的唯一标识符，可用于监控和检测滥用行为                                               |
| `model`           | string | 否  | 图片编辑模型，实际可用模型以后台渠道配置为准                                                  |

### 图片要求

| 项目         | 要求                        |
| ---------- | ------------------------- |
| `image` 格式 | PNG                       |
| `image` 大小 | 小于 `4MB`                  |
| `image` 比例 | 方形                        |
| 无 `mask` 时 | `image` 必须带透明度，透明区域作为编辑遮罩 |
| `mask` 格式  | PNG                       |
| `mask` 大小  | 小于 `4MB`                  |
| `mask` 尺寸  | 必须与原始 `image` 相同          |

### 表单参数示例

```text theme={null}
image=@image.png
prompt=A cute baby sea otter wearing a beret.
n=1
size=1024x1024
response_format=b64_json
```

### curl 示例

```bash theme={null}
curl -X POST "https://www.ominiapi.com/v1/images/edits/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@image.png" \
  -F "prompt=A cute baby sea otter wearing a beret." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"
```

### mask 编辑 curl 示例

```bash theme={null}
curl -X POST "https://www.ominiapi.com/v1/images/edits/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@image.png" \
  -F "mask=@mask.png" \
  -F "prompt=Replace the transparent area with a sunny beach background." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"
```

### 响应示例

NewAPI 当前页面的编辑图像响应示例为空对象：

```json theme={null}
{}
```

实际部署中，响应内容可能取决于所接入的上游模型和 NewAPI 配置。如果使用 OpenAI 兼容的图片响应，一般会返回包含 `created` 和 `data` 的结构，其中 `data` 内可能包含 `url` 或 `b64_json`。

**OpenAI 兼容响应示例**

```json theme={null}
{
  "created": 0,
  "data": [
    {
      "b64_json": "BASE64_IMAGE_DATA"
    }
  ]
}
```

## 4. 常见问题

| 问题                 | 检查项                                                |
| ------------------ | -------------------------------------------------- |
| `401 Unauthorized` | 检查 `Authorization: Bearer YOUR_API_KEY` 是否正确       |
| `400 Bad Request`  | 检查必填参数、图片格式、图片大小、尺寸枚举是否符合要求                        |
| 图片编辑失败             | 确认 `image` 是 PNG、小于 4MB、方形；如果没有 `mask`，确认图片包含透明度   |
| mask 不生效           | 确认 `mask` 是 PNG、小于 4MB、尺寸与原图一致，且透明区域为要编辑的位置        |
| 返回中没有 `b64_json`   | 编辑接口可尝试传入 `response_format=b64_json`；生成接口需检查渠道返回格式 |