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

# 图像生成与编辑（按张计费）

> 通过 OpenAI 兼容接口使用 gpt-image-2 按张计费 SKU 生成和编辑图片

本文适用于已开通 `gpt-image-2` 按张计费 SKU 的文生图、改图和异步图片任务请求。接口路径、认证方式和 OpenAI Images API 保持兼容，但按张计费 SKU 只承诺本文列出的稳定参数。

如果你的账号使用 token 计费通道，或需要 `medium` / `high`、`b64_json`、JPEG/WebP、`1024x1024` 等官方兼容能力，请参考 [图像生成与编辑（Token 计费）](/openai/images-token-billing)。

<Note>
  同一个请求模型仍然是 `gpt-image-2`。实际按张还是按 token 结算，取决于账号在控制台开通的模型价格和计费 SKU。
</Note>

## 计费模式

| 模式       | 适用场景               | 计费依据                         |
| -------- | ------------------ | ---------------------------- |
| 按张计费     | 稳定低成本文生图、改图和异步图片任务 | 成功返回并可解码的图片张数 x 对应分辨率 SKU 单价 |
| Token 计费 | 官方完整兼容能力、复杂参数、改图   | 平台记录或上游返回的 token 用量          |

按张计费下，`usage.*` 可能被记录用于排查，但不作为客户账单的稳定计费依据。

## 快速开始

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte white ceramic mug",
    "size": "1024x1536",
    "response_format": "url",
    "quality": "low",
    "output_format": "png",
    "n": 1
  }'
```

Python SDK:

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://models.phanedge.cloud/v1", api_key="$TOKEN")

result = client.images.generate(
    model="gpt-image-2",
    prompt="A clean studio product photo of a matte white ceramic mug",
    size="1024x1536",
    response_format="url",
    quality="low",
    output_format="png",
    n=1,
)
print(result.data[0].url)
```

## 文生图请求参数

`POST /v1/images/generations` 和 `POST /v1/images/generations/async` 只承诺以下参数和值：

| 参数                | 类型      | 必填 | 稳定值            | 说明                             |
| ----------------- | ------- | -- | -------------- | ------------------------------ |
| `model`           | string  | 是  | `gpt-image-2`  | 固定模型名                          |
| `prompt`          | string  | 是  | 非空文本           | 图片描述                           |
| `size`            | string  | 是  | 见下方分辨率 SKU     | 决定 1K / 2K / 4K 计费档            |
| `response_format` | string  | 否  | `url`          | 建议显式传入；按张计费稳定响应只承诺 URL         |
| `quality`         | string  | 否  | `low` / `auto` | 省略时按 `low` 处理；`auto` 按稳定低成本档处理 |
| `output_format`   | string  | 否  | `png`          | 建议显式传入；按张计费稳定输出只承诺 PNG         |
| `n`               | integer | 否  | `1`            | 仅支持单张生成                        |

<Warning>
  按张计费 SKU 不承诺官方 Images API 的完整参数全集。未列出的参数或未列出的取值不属于按张计费渠道验收标准；接入按张计费基础池的新渠道必须在网关或渠道适配层返回稳定参数错误，不能依赖上游静默接受。
</Warning>

## 改图请求参数

`POST /v1/images/edits` 和 `POST /v1/images/edits/async` 使用 `multipart/form-data`。按张计费 SKU 只承诺以下参数和值：

| 参数                | 类型             | 必填 | 稳定值             | 说明                               |
| ----------------- | -------------- | -- | --------------- | -------------------------------- |
| `model`           | string         | 是  | `gpt-image-2`   | 固定模型名                            |
| `image`           | file 或 file\[] | 是  | 1 至 10 张 PNG 图片 | 基础 edit 使用 1 张图；多参考图最多 10 张      |
| `mask`            | file           | 否  | PNG mask        | 支持 1 张输入图 + 1 张 mask 的 mask edit |
| `prompt`          | string         | 是  | 非空文本            | 编辑描述                             |
| `size`            | string         | 是  | 见下方分辨率 SKU      | 决定 1K / 2K / 4K 计费档              |
| `response_format` | string         | 否  | `url`           | 建议显式传入；按张计费稳定响应只承诺 URL           |
| `quality`         | string         | 否  | `low` / `auto`  | 省略时按 `low` 处理                    |
| `output_format`   | string         | 否  | `png`           | 建议显式传入；按张计费稳定输出只承诺 PNG           |
| `n`               | integer        | 否  | `1`             | 仅支持单张结果                          |

能力范围：

| 能力        | 标准                               |
| --------- | -------------------------------- |
| 基础 edit   | 1 张参考图 + `prompt`                |
| mask edit | 1 张参考图 + 1 张 PNG mask + `prompt` |
| 多参考图 edit | 最多 10 张参考图 + `prompt`            |

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "prompt=将图片转换为干净的电商主图" \
  -F "size=1024x1536" \
  -F "response_format=url" \
  -F "quality=low" \
  -F "output_format=png" \
  -F "n=1"
```

## 分辨率 SKU

文生图、基础改图、mask 改图和多参考图改图使用同一组按张计费稳定尺寸。

| SKU | `size`      | 实际尺寸        | 比例   |
| --- | ----------- | ----------- | ---- |
| 1K  | `1024x1536` | `1024x1536` | 2:3  |
| 1K  | `1536x1024` | `1536x1024` | 3:2  |
| 2K  | `2048x2048` | `2048x2048` | 1:1  |
| 2K  | `2048x1152` | `2048x1152` | 16:9 |
| 2K  | `1152x2048` | `1152x2048` | 9:16 |
| 2K  | `2048x1536` | `2048x1536` | 4:3  |
| 2K  | `1536x2048` | `1536x2048` | 3:4  |
| 2K  | `2048x1024` | `2048x1024` | 2:1  |
| 2K  | `1024x2048` | `1024x2048` | 1:2  |
| 2K  | `2048x1280` | `2048x1280` | 8:5  |
| 2K  | `1280x2048` | `1280x2048` | 5:8  |
| 4K  | `1280x3840` | `1280x3840` | 1:3  |
| 4K  | `3840x1280` | `3840x1280` | 3:1  |
| 4K  | `3840x2160` | `3840x2160` | 16:9 |
| 4K  | `2160x3840` | `2160x3840` | 9:16 |

SKU 说明：

* 1K、2K、4K 是平台的计费 SKU 分类，不等同于严格的总像素、短边分辨率或标准 UHD 定义。
* `1280x3840` 因长边达到 3840 像素，归入 4K SKU。
* `size=auto` 不是按张计费稳定能力。
* `1024x1024` 不在按张计费稳定尺寸列表内；如需方图，请使用 token 计费通道或联系平台确认账号能力。

## 响应体

成功响应至少包含 `data[].url`：

```json theme={null}
{
  "created": 1762789802,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}
```

| 字段           | 说明                          |
| ------------ | --------------------------- |
| `created`    | 创建时间戳                       |
| `data[].url` | 图片 URL，可能是远程 URL 或 data URL |
| `usage`      | 可选诊断字段，不作为按张计费账单依据          |

按张计费稳定响应要求：

* `data[].url` 必须存在。
* 图片必须可以完整下载或解码。
* 实际 MIME 为 `image/png`。
* 固定尺寸必须与请求的 `size` 精确一致。
* 默认或显式 `n=1` 时只返回一张图片。

## 异步图片任务

按张计费 SKU 也可使用平台托管的异步任务接口。异步接口先创建 `image_<ULID>` 任务，再由后台 worker 执行同步图片请求，最后通过轮询接口返回托管图片 URL。

文生图创建任务：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations/async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte white ceramic mug",
    "size": "1024x1536",
    "response_format": "url",
    "quality": "low",
    "output_format": "png",
    "n": 1
  }'
```

文生图轮询结果：

```bash theme={null}
curl -X GET "https://models.phanedge.cloud/v1/images/generations/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

改图创建任务：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/edits/async" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "prompt=将图片转换为干净的电商主图" \
  -F "size=1024x1536" \
  -F "response_format=url" \
  -F "quality=low" \
  -F "output_format=png" \
  -F "n=1"
```

改图轮询结果：

```bash theme={null}
curl -X GET "https://models.phanedge.cloud/v1/images/edits/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

| 接口      | 方法   | 路径                             | 成功要求                                |
| ------- | ---- | ------------------------------ | ----------------------------------- |
| 文生图异步提交 | POST | `/v1/images/generations/async` | 返回 `task_id`                        |
| 文生图异步查询 | GET  | `/v1/images/generations/{id}`  | 最终 `status=completed`，返回 1 张 URL 图片 |
| 改图异步提交  | POST | `/v1/images/edits/async`       | 返回 `task_id`                        |
| 改图异步查询  | GET  | `/v1/images/edits/{id}`        | 最终 `status=completed`，返回 1 张 URL 图片 |

| 状态            | 说明                                   |
| ------------- | ------------------------------------ |
| `pending`     | 排队中                                  |
| `in_progress` | 后台执行中                                |
| `completed`   | 已完成，读取 `data[].url`                  |
| `failed`      | 失败，读取 `error.code` / `error.message` |

异步任务完成后按成功图片张数结算。完成态响应中的 `usage` 如存在，仅用于排查和对账辅助。

<Note>
  异步图片任务要求平台已配置公开可访问的对象存储。未配置时，创建任务会返回 `storage_not_configured`。
</Note>

## 不支持参数

以下参数或取值不属于按张计费稳定承诺：

| 参数或值                                        | 说明                        |
| ------------------------------------------- | ------------------------- |
| `size=auto`                                 | 不是按张计费稳定能力                |
| 非分辨率 SKU 表内的 `size`                         | 不属于当前统一尺寸标准               |
| edit 请求中非分辨率 SKU 表内的 `size`                 | 不属于当前统一 edit 尺寸标准         |
| `quality=medium` / `quality=high`           | 不属于按张计费稳定档位，可能脱离按张 SKU 口径 |
| `output_format=jpeg` / `output_format=webp` | 当前只承诺 PNG，其他格式可能脱离按张稳定输出  |
| `output_compression`                        | 依赖 JPEG / WebP 输出，当前不开放   |
| `n>1`                                       | 请拆成多次 `n=1` 请求            |
| `background`                                | 不作为按张计费稳定参数               |
| `moderation`                                | 不作为按张计费稳定参数               |
| `user`                                      | 不作为按张计费稳定参数               |
| `input_fidelity`                            | 不作为按张计费稳定参数               |
| `stream=true`                               | 不返回可用图片流事件                |
| `partial_images`                            | 不返回可解码的局部图片事件             |
| `response_format=b64_json`                  | 按张计费稳定响应只承诺 URL           |

## 常见错误

按张计费渠道验收中，标准外参数应按 HTTP 400 参数错误处理。实际 `error.code` 可能取决于平台校验或渠道适配，常见错误如下：

| 错误码                                   | 说明                             |
| ------------------------------------- | ------------------------------ |
| `invalid_request_error`               | 参数不属于按张计费稳定能力，例如尺寸、质量档、输出格式不支持 |
| `n_not_supported`                     | `n>1`，需改为 `n=1` 或拆分请求          |
| `image_url_not_available`             | 请求 URL 输出但平台未配置对象存储            |
| `content_policy_violation`            | 内容审核未通过                        |
| `suspected_black_image_from_upstream` | 返回疑似纯黑图，已拦截                    |

## OpenAPI 参考

本文顶部的交互式 API 参考展示文生图入口；同一个按张计费 OpenAPI schema 也包含改图和异步任务接口。需要完整 OpenAI 兼容 schema 时，请查看 [Token 计费文档](/openai/images-token-billing)。


## OpenAPI

````yaml openapi/openai-gpt-image-2-per-image.json POST /v1/images/generations
openapi: 3.0.0
info:
  title: gpt-image-2 Per-Image API
  description: gpt-image-2 按张计费图像生成、编辑与异步任务稳定参数
  version: 1.2.0
servers:
  - url: https://models.phanedge.cloud
    description: PhanEdge 生产环境
security:
  - BearerAuth: []
paths:
  /v1/images/generations:
    post:
      tags:
        - gpt-image-2
      summary: 文生图（按张计费）
      description: 使用 gpt-image-2 按张计费 SKU 从文本生成图片
      operationId: createGptImage2PerImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationRequest'
            examples:
              basic:
                summary: 按张计费文生图
                value:
                  model: gpt-image-2
                  prompt: A clean studio product photo of a matte white ceramic mug
                  size: 1024x1536
                  response_format: url
                  quality: low
                  output_format: png
                  'n': 1
      responses:
        '200':
          description: 图像生成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              example:
                created: 1762789802
                data:
                  - url: https://example.com/generated-image.png
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    GenerationRequest:
      type: object
      required:
        - prompt
        - model
        - size
      description: gpt-image-2 按张计费文生图请求体
      properties:
        model:
          type: string
          enum:
            - gpt-image-2
          description: 固定模型名
        prompt:
          type: string
          minLength: 1
          description: 图片描述文本
        size:
          $ref: '#/components/schemas/StableSize'
        response_format:
          type: string
          enum:
            - url
          description: 建议显式传入；按张计费稳定响应只承诺 URL
        quality:
          type: string
          enum:
            - low
            - auto
          default: low
          description: 按张计费稳定质量档
        output_format:
          type: string
          enum:
            - png
          description: 建议显式传入；按张计费稳定输出只承诺 PNG
        'n':
          type: integer
          minimum: 1
          maximum: 1
          default: 1
          description: 按张计费稳定模式仅支持单张生成
      additionalProperties: false
    ImageResponse:
      type: object
      description: 按张计费稳定响应
      properties:
        created:
          type: integer
          description: 创建时间戳
        data:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/ImageResponseData'
        usage:
          $ref: '#/components/schemas/Usage'
          description: 可选诊断字段，不作为按张计费账单依据
      required:
        - data
    StableSize:
      type: string
      enum:
        - 1024x1536
        - 1536x1024
        - 2048x2048
        - 2048x1152
        - 1152x2048
        - 2048x1536
        - 1536x2048
        - 2048x1024
        - 1024x2048
        - 2048x1280
        - 1280x2048
        - 1280x3840
        - 3840x1280
        - 3840x2160
        - 2160x3840
      description: 按张计费稳定分辨率 SKU
    ImageResponseData:
      type: object
      properties:
        url:
          type: string
          description: 图片 URL
      required:
        - url
    Usage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              enum:
                - unsupported_parameter
                - invalid_request_error
                - n_not_supported
                - image_url_not_available
                - storage_not_configured
                - content_policy_violation
                - suspected_black_image_from_upstream
                - task_not_found
            param:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: 参数不属于按张计费稳定能力，通常返回参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <your-api-key>'

````