> ## 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.

# Create image edit

> Edit images using a reference image and text prompt, with support for masks and multiple references

## Multiple reference images

Pass 1–16 additional reference images via the `images` field
(URL, base64, or File ID) alongside the primary `image` to enable
multi-reference generation.

## Request formats

Two request formats are supported:

* **`multipart/form-data`**: Upload images as files
* **`application/json`**: Pass images as base64 data URLs (e.g. `data:image/jpeg;base64,...`)

## Mask fields

* The `mask` and `input_image_mask` parameters are accepted but
  currently have no effect — edits are always applied to the entire
  image. For partial editing, consider compositing on the client side.

## Output size

It is recommended to explicitly pass the `size` parameter for
predictable output dimensions. Without `size`, the output dimensions
may vary depending on the input images.

## `gpt-image-2` parameters

| Parameter                  | Notes                                               |
| -------------------------- | --------------------------------------------------- |
| `images` (multi-reference) | Supports 1–16 reference images                      |
| `input_fidelity`           | Auto high-fidelity; the API ignores manual settings |


## OpenAPI

````yaml /openapi/images.en.yaml post /v1/images/edits
openapi: 3.1.0
info:
  title: InfinityBlue API — Images
  version: 1.0.0
  summary: Image generation and editing endpoints
  description: >
    InfinityBlue image endpoints support both the OpenAI native format and the

    NanoBanana (Gemini native) format, covering text-to-image generation,

    image editing, and multi-reference image fusion.


    ## Authentication


    Every request must include your API key in the header:


    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    Create and manage your API keys in the
    [console](https://api.getinfinityblue.com/console).


    ## Endpoint format conventions


    | Path prefix | Compatible format |

    | --- | --- |

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

    | `/v1/chat/completions` | OpenAI Chat Completions (NanoBanana OpenAI
    format) |

    | `/v1beta/models/{model}:generateContent` | Google Gemini native
    (NanoBanana native format) |
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Images
    description: |
      OpenAI-compatible image generation and editing endpoints supporting
      models such as `gpt-image-2`.
  - name: NanoBanana
    description: |
      NanoBanana image generation endpoints available in both Gemini native
      format and OpenAI chat format, supporting text-to-image, multi-reference
      fusion, and style-unification workflows.
paths:
  /v1/images/edits:
    post:
      tags:
        - Images
      summary: Create image edit
      description: |
        Create an edited or extended image from an original image and a text
        prompt. Supports the `gpt-image-2` model with multiple reference images
        for style unification or asset fusion.

        The request body supports both `multipart/form-data` (file upload) and
        `application/json` (base64 data URL) formats.
      operationId: createImageEdit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageEditJsonRequest'
            examples:
              basic_edit:
                summary: Single-reference edit
                value:
                  model: gpt-image-2
                  prompt: >-
                    Replace the pen tip in the main image with the round soft
                    brush tip from the reference image, keep everything else
                    unchanged
                  image: data:image/jpeg;base64,<main_image_base64>
                  images:
                    - data:image/jpeg;base64,<reference_image_base64>
                  size: 1024x1024
              multi_reference:
                summary: Multi-reference style fusion
                value:
                  model: gpt-image-2
                  prompt: >-
                    Redesign the color scheme of the main image based on the
                    styles in these reference images
                  image: data:image/jpeg;base64,<main_image_base64>
                  images:
                    - data:image/jpeg;base64,<reference_1_base64>
                    - data:image/jpeg;base64,<reference_2_base64>
                  size: 1536x1024
                  output_format: png
              jpeg_output:
                summary: JPEG output with URL response
                value:
                  model: gpt-image-2
                  prompt: >-
                    Replace the product background in the main image with a
                    clean white studio backdrop
                  image: data:image/jpeg;base64,<main_image_base64>
                  size: 2048x2048
                  output_format: jpeg
                  output_compression: 85
                  response_format: url
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageEditRequest'
      responses:
        '200':
          description: Edited image generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ImageEditJsonRequest:
      type: object
      required:
        - model
        - prompt
        - image
      description: |
        Image edit request body (JSON format). Images are passed as base64
        data URLs (e.g. `data:image/jpeg;base64,...`) or image URLs.
      properties:
        model:
          type: string
          description: >
            The image model to use. Pass `gpt-image-2`.

            Snapshot versions (e.g. `gpt-image-2-2026-04-21`) are currently
            unavailable.
          examples:
            - gpt-image-2
        prompt:
          type: string
          description: A text description of the desired edit. Maximum 1,000 characters.
          examples:
            - >-
              Replace the pen tip in the main image with the round soft brush
              tip from the reference image, keep everything else unchanged
        image:
          type: string
          description: |
            The primary image. Accepts a base64 data URL
            (e.g. `data:image/jpeg;base64,...`) or an image URL.
        images:
          type: array
          description: >
            Additional reference images (1–16 items). Accepts base64 data URLs

            or image URLs. Use alongside the primary `image` for multi-reference
            editing.
          items:
            type: string
        'n':
          type: integer
          minimum: 1
          default: 1
          description: |
            The `n` parameter is not currently supported. Defaults to `n=1`,
            returning one image per request. To generate multiple images,
            call the endpoint in a loop.
        size:
          type: string
          description: |
            Size of the output image. Follows the same rules as the generation
            endpoint; defaults to `auto`. It is recommended to pass this
            explicitly for predictable output dimensions.
          examples:
            - 1024x1024
            - 1536x1024
        response_format:
          type: string
          default: b64_json
          description: |
            Format in which the generated image is returned. Defaults to
            `b64_json` (Base64-encoded data); set to `url` for a temporary
            access URL.
          enum:
            - b64_json
            - url
        output_format:
          type: string
          description: |
            Output format of the generated image. Defaults to `png`;
            options: `png`, `jpeg`, `webp`.
          enum:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Output compression quality (0–100). Applies only when
            `output_format` is `jpeg` or `webp`.
        background:
          type: string
          description: |
            Background setting for the generated image. Defaults to `auto`;
            supports `opaque` or `auto`. `gpt-image-2` does not support
            `transparent` — passing it returns a 400 error.
          enum:
            - opaque
            - auto
        quality:
          type: string
          description: |
            Quality tiers are not currently supported; all requests use the
            `auto` level. The parameter is accepted but has no observable
            difference between levels.
          enum:
            - low
            - medium
            - high
            - auto
        mask:
          type: string
          description: |
            Mask image as a base64 data URL. Masking is not currently
            supported — the parameter is accepted but has no effect; edits
            are applied to the entire image.
        input_image_mask:
          type: string
          description: |
            `gpt-image-2`-specific mask field as a base64 data URL. Masking
            is not currently supported — the parameter is accepted but has
            no effect; edits are applied to the entire image.
        input_fidelity:
          type: string
          description: |
            Input fidelity setting. For `gpt-image-2`, high fidelity is
            enforced automatically; the API ignores this parameter.
        user:
          type: string
          description: A unique identifier for your end user, useful for abuse monitoring.
    ImageEditRequest:
      type: object
      required:
        - image
        - prompt
      description: Image edit request body (`multipart/form-data`).
      properties:
        image:
          type: string
          format: binary
          description: |
            The primary image file to edit. For `gpt-image-2`, it may serve as
            one of the reference inputs. If no mask is provided, use
            `input_image_mask` to indicate the edit area.
        images:
          type: array
          description: |
            Additional reference images, 1–16 items. Accepts URLs, base64
            strings, or File IDs. Use this field to supply multiple reference
            images; other parameter rules follow the generation endpoint.
          items:
            type: string
        mask:
          type: string
          format: binary
          description: |
            Mask image file where fully transparent areas (alpha=0) indicate
            the regions to edit. Masking is not currently supported — the
            parameter is accepted but has no effect; edits are applied to
            the entire image.
        input_image_mask:
          type: string
          format: binary
          description: |
            `gpt-image-2`-specific mask field. Masking is not currently
            supported — the parameter is accepted but has no effect; edits
            are applied to the entire image.
        prompt:
          type: string
          description: A text description of the desired edit. Maximum 1,000 characters.
          examples:
            - >-
              Replace the cat in the image with a Shiba Inu, keeping the
              background unchanged
        'n':
          type: integer
          minimum: 1
          default: 1
          description: |
            The `n` parameter is not currently supported. Defaults to `n=1`,
            returning one image per request. To generate multiple images,
            call the endpoint in a loop.
        size:
          type: string
          description: |
            Size of the generated image. For `gpt-image-2`, follows the same
            rules as the generation endpoint: defaults to `auto` with flexible
            dimensions and common presets such as `1024x1024` and `1536x1024`.
          examples:
            - 1024x1024
        response_format:
          type: string
          description: >-
            Format in which the generated image is returned. Must be `url` or
            `b64_json`.
          enum:
            - url
            - b64_json
        input_fidelity:
          type: string
          description: |
            Input fidelity setting. For `gpt-image-2`, high fidelity is
            enforced automatically; the API ignores this parameter.
        model:
          type: string
          description: >
            The image model to use. Pass `gpt-image-2`.

            Snapshot versions (e.g. `gpt-image-2-2026-04-21`) are currently
            unavailable.
          examples:
            - gpt-image-2
        quality:
          type: string
          description: |
            Quality tiers are not currently supported; all requests use the
            `auto` level. The parameter is accepted but has no observable
            difference between levels.
          enum:
            - low
            - medium
            - high
            - auto
        output_format:
          type: string
          description: |
            Output format of the generated image. Defaults to `png`;
            options: `png`, `jpeg`, `webp`.
          enum:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Output compression quality (0–100). Applies only when
            `output_format` is `jpeg` or `webp`.
        background:
          type: string
          description: |
            Background setting for the generated image. Defaults to `auto`;
            supports `opaque` or `auto`. `gpt-image-2` does not support
            `transparent` — passing it returns a 400 error.
          enum:
            - opaque
            - auto
        user:
          type: string
          description: A unique identifier for your end user, useful for abuse monitoring.
    ImageGenerationResponse:
      type: object
      description: Image generation response body.
      properties:
        created:
          type: integer
          description: Unix timestamp (seconds) of creation.
          examples:
            - 1713833628
        data:
          type: array
          description: List of generated images.
          items:
            type: object
            properties:
              b64_json:
                type: string
                description: >-
                  Base64-encoded image data (returned when
                  `response_format=b64_json`).
              url:
                type: string
                description: >-
                  Temporary URL to access the image (returned when
                  `response_format=url`).
        usage:
          $ref: '#/components/schemas/ImageUsage'
    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message.
              examples:
                - >-
                  Invalid size. Supported sizes are 1024x1024, 1536x1024,
                  1024x1536.
            type:
              type: string
              description: Error type.
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: The parameter related to the error.
              examples:
                - size
            code:
              type:
                - string
                - 'null'
              description: Error code.
              examples:
                - invalid_size
    ImageUsage:
      type: object
      description: Token usage statistics for the request.
      properties:
        total_tokens:
          type: integer
          description: Total tokens consumed.
        input_tokens:
          type: integer
          description: Tokens consumed by the input.
        output_tokens:
          type: integer
          description: Tokens consumed by the output (including image generation tokens).
        input_tokens_details:
          type: object
          description: Breakdown of input token usage.
          properties:
            text_tokens:
              type: integer
              description: Text tokens consumed.
            image_tokens:
              type: integer
              description: Image tokens consumed.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Bearer token authentication, format: `Authorization: Bearer sk-xxxxxx`.

        Get your API key in the
        [console](https://api.getinfinityblue.com/console).

````