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

# Create image edit

> Use POST /v1/images/edits in RunBridge AI to edit images with multipart uploads, masks, GPT image models, and encoded image output controls.

Use this route to edit GPT images with multipart uploads on RunBridge AI.

## Use this route when

* You already have a source image and want a prompt-driven edit
* You may need a mask for targeted changes
* You can handle multipart file upload instead of a plain JSON request

## Safe first request

* Start with one PNG or JPG file
* Skip the mask until the base edit flow works
* Use `model: "gpt-image-2"` for GPT image edit requests on this route
* Use one short instruction that asks for one visible change
* Read the edited result from `data[0].b64_json`
* Set `output_format: "jpeg"` when you want a JPEG payload
* Expect longer latency than plain image generation

## Model behavior

* GPT image edit models on this route return inline base64 image data
* `output_format` controls the encoded image type inside `b64_json`


## OpenAPI

````yaml api/openapi/image/openai/post-image-editing.openapi.json POST /v1/images/edits
openapi: 3.1.0
info:
  title: Image Editing API
  version: 1.0.0
  description: >-
    Edit GPT images through the RunBridge AI image edits route. GPT image edit
    models return Base64 image data in `data[].b64_json`; `output_format`
    controls the encoded image type.
servers:
  - url: https://api.runbridge.ai
security:
  - bearerAuth: []
paths:
  /v1/images/edits:
    post:
      summary: Edit images
      description: >-
        Upload one or more source images, optionally include a mask, and request
        an edited result with a text instruction.
      operationId: image_editing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
                - prompt
              properties:
                image:
                  type: string
                  format: binary
                  description: >-
                    Source image file. Start with one PNG or JPG input for the
                    simplest flow.
                prompt:
                  type: string
                  description: Edit instruction describing the change you want.
                  example: Add a small red bow tie on the cat
                model:
                  type: string
                  description: >-
                    The GPT image editing model ID. Find model IDs on the
                    [Models page](/overview/models).
                  default: gpt-image-2
                mask:
                  type: string
                  format: binary
                  description: >-
                    Optional PNG mask. Transparent areas mark the regions to
                    edit. The mask dimensions must match the source image
                    exactly.
                'n':
                  type: string
                  description: Number of edited images to return.
                  default: '1'
                quality:
                  type: string
                  enum:
                    - high
                    - medium
                    - low
                  description: Quality setting for models that support it.
                  example: low
                output_format:
                  type: string
                  description: >-
                    Encoded image type for GPT image edit results returned in
                    `data[].b64_json`. For example, use `jpeg` for a JPEG
                    payload.
                size:
                  type: string
                  description: Requested output size when supported by the selected model.
              default:
                model: gpt-image-2
                prompt: Add a small red bow tie on the cat
                quality: low
      responses:
        '200':
          description: Edited image result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - created
                  - data
                  - usage
                properties:
                  created:
                    type: integer
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                      completion_tokens:
                        type: integer
                      total_tokens:
                        type: integer
                      prompt_tokens_details:
                        type: object
                        properties:
                          cached_tokens_details:
                            type: object
                            properties: {}
                      completion_tokens_details:
                        type: object
                        properties: {}
                      input_tokens:
                        type: integer
                      output_tokens:
                        type: integer
                      input_tokens_details:
                        type: object
                        properties:
                          image_tokens:
                            type: integer
                          text_tokens:
                            type: integer
                          cached_tokens_details:
                            type: object
                            properties: {}
                      claude_cache_creation_5_m_tokens:
                        type: integer
                      claude_cache_creation_1_h_tokens:
                        type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        b64_json:
                          type: string
                          description: >-
                            Base64-encoded image payload. Decode this value to
                            get the edited image bytes.
                        url:
                          type: string
                          description: >-
                            Temporary image URL when the selected model supports
                            URL output.
                        revised_prompt:
                          type: string
                          description: Revised prompt returned with the image result.
                  background:
                    type: string
                    description: Background mode returned by models that expose it.
                  output_format:
                    type: string
                    description: Encoded image type returned by GPT image models.
                  quality:
                    type: string
                    description: Quality level returned by models that expose it.
                  size:
                    type: string
                    description: Output size returned by models that expose it.
                example:
                  created: 1776836647
                  usage:
                    prompt_tokens: 0
                    completion_tokens: 0
                    total_tokens: 981
                    prompt_tokens_details:
                      cached_tokens_details: {}
                    completion_tokens_details: {}
                    input_tokens: 785
                    output_tokens: 196
                    input_tokens_details:
                      image_tokens: 768
                      text_tokens: 17
                      cached_tokens_details: {}
                    claude_cache_creation_5_m_tokens: 0
                    claude_cache_creation_1_h_tokens: 0
                  data:
                    - b64_json: <base64-image-data>
              example:
                created: 1781075000
                background: opaque
                output_format: png
                quality: low
                size: 1024x1024
                usage:
                  input_tokens: 784
                  input_tokens_details:
                    image_tokens: 768
                    text_tokens: 16
                  output_tokens: 196
                  output_tokens_details:
                    image_tokens: 196
                    text_tokens: 0
                  total_tokens: 980
                data:
                  - b64_json: iVBORw0KGgoAAAANSUhEUgAA...
      x-codeSamples:
        - lang: Shell
          label: Default
          source: |
            curl https://api.runbridge.ai/v1/images/edits \
              -H "Authorization: Bearer $RUNBRIDGE_API_KEY" \
              -F image=@cat.jpg \
              -F prompt="Add a small red bow tie on the cat" \
              -F model=gpt-image-2 \
              -F quality=low
        - lang: Shell
          label: With mask
          source: |
            curl https://api.runbridge.ai/v1/images/edits \
              -H "Authorization: Bearer $RUNBRIDGE_API_KEY" \
              -F image=@cat.jpg \
              -F mask=@mask.png \
              -F prompt="Replace the masked area with a red bow tie" \
              -F model=gpt-image-2 \
              -F quality=low
        - lang: Python
          label: Default
          source: |
            import base64
            import os
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.runbridge.ai/v1",
                api_key=os.environ["RUNBRIDGE_API_KEY"],
            )

            with open("cat.jpg", "rb") as image_file:
                result = client.images.edit(
                    model="gpt-image-2",
                    image=image_file,
                    prompt="Add a small red bow tie on the cat",
                    quality="low",
                )

            image_bytes = base64.b64decode(result.data[0].b64_json)
            with open("edited.png", "wb") as f:
                f.write(image_bytes)
        - lang: Python
          label: With mask
          source: >
            import base64

            import os

            from openai import OpenAI


            client = OpenAI(
                base_url="https://api.runbridge.ai/v1",
                api_key=os.environ["RUNBRIDGE_API_KEY"],
            )


            # The mask is a PNG whose transparent areas mark the regions to
            edit.

            # Its dimensions must match the source image exactly.

            with open("cat.jpg", "rb") as image_file, open("mask.png", "rb") as
            mask_file:
                result = client.images.edit(
                    model="gpt-image-2",
                    image=image_file,
                    mask=mask_file,
                    prompt="Replace the masked area with a red bow tie",
                    quality="low",
                )

            image_bytes = base64.b64decode(result.data[0].b64_json)

            with open("edited.png", "wb") as f:
                f.write(image_bytes)
        - lang: JavaScript
          label: Default
          source: >
            import fs from "node:fs";

            import OpenAI, { toFile } from "openai";


            const client = new OpenAI({
                baseURL: "https://api.runbridge.ai/v1",
                apiKey: process.env.RUNBRIDGE_API_KEY,
            });


            const result = await client.images.edit({
                model: "gpt-image-2",
                image: await toFile(fs.createReadStream("cat.jpg"), "cat.jpg", { type: "image/jpeg" }),
                prompt: "Add a small red bow tie on the cat",
                quality: "low",
            });


            fs.writeFileSync("edited.png", Buffer.from(result.data[0].b64_json,
            "base64"));
        - lang: JavaScript
          label: With mask
          source: >
            import fs from "node:fs";

            import OpenAI, { toFile } from "openai";


            const client = new OpenAI({
                baseURL: "https://api.runbridge.ai/v1",
                apiKey: process.env.RUNBRIDGE_API_KEY,
            });


            // The mask is a PNG whose transparent areas mark the regions to
            edit.

            // Its dimensions must match the source image exactly.

            const result = await client.images.edit({
                model: "gpt-image-2",
                image: await toFile(fs.createReadStream("cat.jpg"), "cat.jpg", { type: "image/jpeg" }),
                mask: await toFile(fs.createReadStream("mask.png"), "mask.png", { type: "image/png" }),
                prompt: "Replace the masked area with a red bow tie",
                quality: "low",
            });


            fs.writeFileSync("edited.png", Buffer.from(result.data[0].b64_json,
            "base64"));
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your RunBridge AI key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.