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

# 图片同步生成（按张计费）

> 使用 /v3/images/generations 和 /v3/images/edits 进行同步按张计费的图片生成与编辑。

V3 图片接口支持图片生成和图片编辑两个功能。请求后直接返回结果图 URL 和用量统计，无需轮询任务状态。

<Info>
  * `/v3/images/generations` — 图片生成，JSON 请求体
  * `/v3/images/edits` — 图片编辑，`multipart/form-data` 文件上传
</Info>

## 图片生成

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v3/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张极简风格的云端工作站海报，蓝白配色，科技感",
    "n": 1,
    "size": "1024x1024"
  }'
```

### 请求字段

| 字段                   | 类型      | 必填 | 说明                                           |
| -------------------- | ------- | -- | -------------------------------------------- |
| `model`              | string  | 是  | 模型调用 ID，需支持 `images_generations_v3` endpoint |
| `prompt`             | string  | 是  | 图片生成提示词                                      |
| `n`                  | integer | 否  | 一次返回图片数，默认 1，范围 1–10                         |
| `size`               | string  | 否  | 图片尺寸，默认 `1024x1024`，支持规格见下表                  |
| `background`         | string  | 否  | 背景模式：`transparent`、`opaque`、`auto`           |
| `moderation`         | string  | 否  | 内容安全策略，默认以模型配置为准                             |
| `output_format`      | string  | 否  | 输出格式：`png`、`jpeg`、`webp`，默认 `png`            |
| `output_compression` | integer | 否  | JPEG/WebP 压缩质量（0–100），仅对 `jpeg` 和 `webp` 生效  |

## 图片编辑

编辑接口使用 `multipart/form-data`，`image` 和 `mask` 只支持文件上传，不支持 URL 或 base64 字符串。

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v3/images/edits" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=将背景改为蓝天白云，保持主体不变" \
  -F "image=@/path/to/input.png" \
  -F "size=1024x1024"
```

带遮罩的精准编辑：

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v3/images/edits" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把遮罩区域换成草地" \
  -F "image=@/path/to/input.png" \
  -F "mask=@/path/to/mask.png" \
  -F "size=1024x1024"
```

### 请求字段

| 字段              | 类型      | 必填 | 说明                                     |
| --------------- | ------- | -- | -------------------------------------- |
| `model`         | string  | 是  | 模型调用 ID，需支持 `images_edits_v3` endpoint |
| `prompt`        | string  | 是  | 图片编辑提示词                                |
| `image`         | file    | 是  | 待编辑原图，仅支持文件上传，可传一张或多张                  |
| `mask`          | file    | 否  | 遮罩文件，仅支持文件上传                           |
| `n`             | integer | 否  | 一次返回图片数，默认 1，范围 1–10                   |
| `size`          | string  | 否  | 输出图片尺寸，默认 `1024x1024`                  |
| `background`    | string  | 否  | 背景模式：`transparent`、`opaque`、`auto`     |
| `output_format` | string  | 否  | 输出格式：`png`、`jpeg`、`webp`，默认 `png`      |

## 支持的尺寸

| 尺寸          | 比例      |
| ----------- | ------- |
| `1024x1024` | 1:1（默认） |
| `1024x1536` | 2:3（竖版） |
| `1536x1024` | 3:2（横版） |
| `2048x2048` | 1:1 高清  |
| `2048x1152` | 16:9    |
| `1152x2048` | 9:16    |
| `3840x2160` | 4K 横版   |
| `2160x3840` | 4K 竖版   |
| `2048x1360` | 3:2 高清  |
| `1360x2048` | 2:3 高清  |
| `2048x1536` | 4:3     |
| `1536x2048` | 3:4     |
| `2048x880`  | 超宽横版    |
| `880x2048`  | 超高竖版    |
| `688x2048`  | 极窄竖版    |
| `2048x688`  | 极宽横版    |
| `2048x1024` | 2:1     |
| `auto`      | 由模型自动决定 |

## 响应结构

两个接口的响应结构相同：

```json theme={null}
{
  "created": 1779860032,
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "data": [
    {
      "url": "https://cdn.wengaocloud.com/images/ai/example.png",
      "revised_prompt": "一张极简风格的云端工作站海报，蓝白配色，强调科技感与简约美学"
    }
  ],
  "usage": {
    "total_tokens": 800,
    "input_tokens": 300,
    "output_tokens": 500,
    "input_tokens_details": {
      "text_tokens": 100,
      "image_tokens": 200
    }
  }
}
```

### 响应字段说明

| 字段                           | 说明                                                                   |
| ---------------------------- | -------------------------------------------------------------------- |
| `created`                    | 响应创建时间戳（Unix 秒）                                                      |
| `background`                 | 生成图像的背景类型                                                            |
| `output_format`              | 输出图片格式                                                               |
| `quality`                    | 实际使用的图像质量等级。                                                         |
| `size`                       | 实际返回的图像尺寸                                                            |
| `data[]`                     | 图像结果列表                                                               |
| `data[].url`                 | 生成图像的访问 URL                                                          |
| `data[].revised_prompt`      | 实际用于生成的提示词（平台可能对原始提示词进行优化）                                           |
| `usage`                      | 图像生成的资源使用统计                                                          |
| `usage.total_tokens`         | 本次请求消耗的 Token 总数                                                     |
| `usage.input_tokens`         | 输入侧消耗的 Token 数                                                       |
| `usage.output_tokens`        | 输出侧消耗的 Token 数                                                       |
| `usage.input_tokens_details` | 输入 Token 明细，包含 `text_tokens`（文本 Token 数）和 `image_tokens`（图像 Token 数） |

## 计费说明

* 按返回 `data[]` 里的实际图片数计费，最多不超过请求的 `n`。
* 生成前会检查模型可见性、余额和价格配置；余额不足直接返回 `402`。
* 同步接口直接扣费，无冻结/解冻流程。

<Tip>
  如果需要长耗时或后台排队处理图片，请使用 [图片异步生成](/guides/async-images) 接口。
</Tip>