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

# 编辑图像

> 基于参考图和文本提示编辑图像，支持遮罩区域与多参考图输入

## 多参考图

通过 `images` 字段可传入 1–16 张额外参考图（URL、base64 或 File ID），
配合主图 `image` 实现多图参考生成。

## 请求格式

支持两种请求格式：

* **`multipart/form-data`**：以文件方式上传图像
* **`application/json`**：以 base64 data URL（如 `data:image/jpeg;base64,...`）传入图像

## 遮罩说明

* `mask` 和 `input_image_mask` 参数会被接受但当前不生效，
  编辑始终作用于整图。如需局部编辑，建议在客户端自行合成。

## 输出尺寸

建议显式传入 `size` 参数以获得可控的输出尺寸。
不传 `size` 时，输出尺寸可能受输入图像影响而不稳定。

## `gpt-image-2` 特有参数

| 参数               | 说明               |
| ---------------- | ---------------- |
| `images`（多参考图）   | 支持 1–16 张参考图     |
| `input_fidelity` | 自动高保真，API 忽略手动设置 |


## OpenAPI

````yaml /openapi/images.zh.yaml post /v1/images/edits
openapi: 3.1.0
info:
  title: InfinityBlue API — 图像（Images）
  version: 1.0.0
  summary: 图像生成与编辑接口
  description: >
    InfinityBlue 图像接口支持 OpenAI 原生格式与 NanoBanana（Gemini 原生）格式，

    涵盖文生图、图像编辑以及多参考图融合生成等场景。


    ## 认证


    所有请求都需要在请求头中携带 API Key：


    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    在 [控制台](https://api.getinfinityblue.com/console) 创建和管理你的 API Key。


    ## 接口格式约定


    | 路径前缀 | 兼容格式 |

    | --- | --- |

    | `/v1/images/*` | OpenAI Images API |

    | `/v1/chat/completions` | OpenAI Chat Completions（NanoBanana OpenAI 格式） |

    | `/v1beta/models/{model}:generateContent` | Google Gemini 原生（NanoBanana
    原生格式） |
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: 图像（Images）
    description: |
      OpenAI 兼容的图像生成与编辑接口，支持 `gpt-image-2` 等模型。
  - name: NanoBanana
    description: |
      NanoBanana 图像生成接口，支持原生 Gemini 格式与 OpenAI 聊天格式，
      可用于文生图、多参考图融合及风格统一等场景。
paths:
  /v1/images/edits:
    post:
      tags:
        - 图像（Images）
      summary: 编辑图像
      description: >
        根据原始图像和文本提示创建编辑或扩展后的图像。

        支持 `gpt-image-2` 模型，可传入多张参考图实现风格统一或素材融合。


        请求体支持 `multipart/form-data`（上传文件）和 `application/json`（base64 data
        URL）两种格式。
      operationId: createImageEdit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageEditJsonRequest'
            examples:
              basic_edit:
                summary: 单参考图编辑
                value:
                  model: gpt-image-2
                  prompt: 把主图中的笔头替换成参考图中的圆头软质刷头，其余不变
                  image: data:image/jpeg;base64,<主图base64数据>
                  images:
                    - data:image/jpeg;base64,<参考图base64数据>
                  size: 1024x1024
              multi_reference:
                summary: 多参考图风格融合
                value:
                  model: gpt-image-2
                  prompt: 参考这些图片的风格，重新设计主图的配色方案
                  image: data:image/jpeg;base64,<主图base64数据>
                  images:
                    - data:image/jpeg;base64,<参考图1>
                    - data:image/jpeg;base64,<参考图2>
                  size: 1536x1024
                  output_format: png
              jpeg_output:
                summary: JPEG 格式输出
                value:
                  model: gpt-image-2
                  prompt: 将主图中的产品背景替换为纯白摄影棚效果
                  image: data:image/jpeg;base64,<主图base64数据>
                  size: 2048x2048
                  output_format: jpeg
                  output_compression: 85
                  response_format: url
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageEditRequest'
      responses:
        '200':
          description: 成功生成编辑图像
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API Key 无效或缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ImageEditJsonRequest:
      type: object
      required:
        - model
        - prompt
        - image
      description: |
        图像编辑请求体（JSON 格式）。图片以 base64 data URL（如 `data:image/jpeg;base64,...`）
        或图片 URL 传入。
      properties:
        model:
          type: string
          description: |
            使用的图像模型，传入 `gpt-image-2`。
            快照版本（如 `gpt-image-2-2026-04-21`）暂不可用。
          examples:
            - gpt-image-2
        prompt:
          type: string
          description: 所需图像编辑的文本描述，最大长度为 1000 个字符。
          examples:
            - 把主图中的笔头替换成参考图中的圆头软质刷头，其余不变
        image:
          type: string
          description: |
            主图像，支持 base64 data URL（如 `data:image/jpeg;base64,...`）或图片 URL。
        images:
          type: array
          description: |
            额外参考图像列表（1–16 张），支持 base64 data URL 或图片 URL。
            配合主图 `image` 实现多图参考编辑。
          items:
            type: string
        'n':
          type: integer
          minimum: 1
          default: 1
          description: |
            本站暂不支持 `n` 参数，默认 `n=1`，每次请求输出 1 张图片。
            如需多张图片，请循环调用接口。
        size:
          type: string
          description: |
            输出图像的尺寸。参数规则与生成接口一致，默认为 `auto`。
            建议显式传入以获得可控的输出尺寸。
          examples:
            - 1024x1024
            - 1536x1024
        response_format:
          type: string
          default: b64_json
          description: |
            返回图像的格式。默认为 `b64_json`，返回 Base64 编码的图像数据；
            设为 `url` 时返回图像的临时访问 URL。
          enum:
            - b64_json
            - url
        output_format:
          type: string
          description: |
            输出图像的格式。默认为 `png`，可选 `png`、`jpeg`、`webp`。
          enum:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            输出图像的压缩质量（0–100），仅在 `output_format` 为 `jpeg` 或 `webp` 时生效。
        background:
          type: string
          description: |
            生成图像的背景设置。默认为 `auto`，可选 `opaque`（不透明）或 `auto`。
            `gpt-image-2` 不支持 `transparent`（透明背景），传入该值会返回 400 错误。
          enum:
            - opaque
            - auto
        quality:
          type: string
          description: |
            本站暂不支持 `quality` 分档，统一使用 `auto` 级别输出。
            参数会被接受但各级别间无实际差异。
          enum:
            - low
            - medium
            - high
            - auto
        mask:
          type: string
          description: |
            遮罩图像，base64 data URL 格式。
            本站当前不支持遮罩编辑，参数会被接受但不生效，编辑始终作用于整图。
        input_image_mask:
          type: string
          description: |
            `gpt-image-2` 专用遮罩字段，base64 data URL 格式。
            本站当前不支持遮罩编辑，参数会被接受但不生效，编辑始终作用于整图。
        input_fidelity:
          type: string
          description: |
            输入保真度设置。对于 `gpt-image-2`，强制高保真，
            API 会自动忽略此参数的手动设置。
        user:
          type: string
          description: 代表终端用户的唯一标识符，可用于监控和滥用检测。
    ImageEditRequest:
      type: object
      required:
        - image
        - prompt
      description: 图像编辑请求体（`multipart/form-data`）。
      properties:
        image:
          type: string
          format: binary
          description: |
            要编辑的主图像文件。对于 `gpt-image-2`，可作为参考图之一使用；
            如未提供遮罩，建议通过 `input_image_mask` 指定编辑区域。
        images:
          type: array
          description: |
            额外参考图像列表，支持 1–16 张。接受 URL、base64 或 File ID。
            可在此字段提供多张参考图；其余参数规则与图像生成接口一致。
          items:
            type: string
        mask:
          type: string
          format: binary
          description: |
            遮罩图像文件，其完全透明区域（alpha=0）指定编辑位置。
            本站当前不支持遮罩编辑，参数会被接受但不生效，编辑始终作用于整图。
        input_image_mask:
          type: string
          format: binary
          description: |
            `gpt-image-2` 专用遮罩字段。
            本站当前不支持遮罩编辑，参数会被接受但不生效，编辑始终作用于整图。
        prompt:
          type: string
          description: 所需图像的文本描述，最大长度为 1000 个字符。
          examples:
            - 把图中的猫换成一只柴犬，保持背景不变
        'n':
          type: integer
          minimum: 1
          default: 1
          description: |
            本站暂不支持 `n` 参数，默认 `n=1`，每次请求输出 1 张图片。
            如需多张图片，请循环调用接口。
        size:
          type: string
          description: |
            生成图像的尺寸。对于 `gpt-image-2`，参数规则与生成接口一致，
            默认为 `auto`，支持灵活尺寸及常用预设（如 `1024x1024`、`1536x1024`）。
          examples:
            - 1024x1024
        response_format:
          type: string
          description: 返回图像的格式，必须是 `url` 或 `b64_json`。
          enum:
            - url
            - b64_json
        input_fidelity:
          type: string
          description: |
            输入保真度设置。对于 `gpt-image-2`，强制高保真，
            API 会自动忽略此参数的手动设置。
        model:
          type: string
          description: |
            使用的图像模型，传入 `gpt-image-2`。
            快照版本（如 `gpt-image-2-2026-04-21`）暂不可用。
          examples:
            - gpt-image-2
        quality:
          type: string
          description: |
            本站暂不支持 `quality` 分档，统一使用 `auto` 级别输出。
            参数会被接受但各级别间无实际差异。
          enum:
            - low
            - medium
            - high
            - auto
        output_format:
          type: string
          description: |
            输出图像的格式。默认为 `png`，可选 `png`、`jpeg`、`webp`。
          enum:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            输出图像的压缩质量（0–100），仅在 `output_format` 为 `jpeg` 或 `webp` 时生效。
        background:
          type: string
          description: |
            生成图像的背景设置。默认为 `auto`，可选 `opaque`（不透明）或 `auto`。
            `gpt-image-2` 不支持 `transparent`（透明背景），传入该值会返回 400 错误。
          enum:
            - opaque
            - auto
        user:
          type: string
          description: 代表终端用户的唯一标识符，可用于监控和滥用检测。
    ImageGenerationResponse:
      type: object
      description: 图像生成响应体。
      properties:
        created:
          type: integer
          description: 创建时间的 Unix 时间戳（秒）。
          examples:
            - 1713833628
        data:
          type: array
          description: 生成的图像列表。
          items:
            type: object
            properties:
              b64_json:
                type: string
                description: Base64 编码的图像数据（当 `response_format=b64_json` 时返回）。
              url:
                type: string
                description: 图像的临时访问 URL（当 `response_format=url` 时返回）。
        usage:
          $ref: '#/components/schemas/ImageUsage'
    ErrorResponse:
      type: object
      description: 标准错误响应。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 错误信息。
              examples:
                - 无效的尺寸。支持的尺寸为 1024x1024、1536x1024、1024x1536。
            type:
              type: string
              description: 错误类型。
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: 相关参数。
              examples:
                - size
            code:
              type:
                - string
                - 'null'
              description: 错误代码。
              examples:
                - invalid_size
    ImageUsage:
      type: object
      description: 本次请求的 token 用量统计。
      properties:
        total_tokens:
          type: integer
          description: 总消耗 token 数。
        input_tokens:
          type: integer
          description: 输入消耗的 token 数。
        output_tokens:
          type: integer
          description: 输出消耗的 token 数（含图像生成 token）。
        input_tokens_details:
          type: object
          description: 输入 token 明细。
          properties:
            text_tokens:
              type: integer
              description: 文本 token 数。
            image_tokens:
              type: integer
              description: 图像 token 数。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        使用 Bearer Token 认证，格式：`Authorization: Bearer sk-xxxxxx`。
        在 [控制台](https://api.getinfinityblue.com/console) 获取 API Key。

````