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

# Edit Image

> Edit or extend an existing image from a text prompt using image editing models. Accepts multipart/form-data (for file uploads) or application/json (with image references as base64 data URLs or file IDs).

Edit or extend an existing image from a text prompt using OpenAI compatible image editing models through Requesty's routing.

## Base URL

```
https://router.requesty.ai/v1/images/edits
```

## Authentication

Include your Requesty API key in the request headers:

```bash theme={"dark"}
Authorization: Bearer YOUR_REQUESTY_API_KEY
```

## Example Request

The endpoint accepts both `multipart/form-data` (the OpenAI SDK default for file uploads) and `application/json` (with image references as base64 data URLs or file IDs).

### multipart/form-data

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -F "model=azure/openai/gpt-image-1" \
  -F "prompt=Make the sky a dramatic sunset" \
  -F "image[]=@./photo.png" \
  -F "size=1024x1024" \
  -F "quality=auto"
```

### application/json

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -d '{
    "model": "azure/openai/gpt-image-1",
    "prompt": "Make the sky a dramatic sunset",
    "images": [
      { "image_url": "data:image/png;base64,iVBORw0KGgo..." }
    ],
    "size": "1024x1024",
    "quality": "auto"
  }'
```

## Supported Models

* `azure/openai/gpt-image-1` OpenAI's GPT Image 1 model via Azure
* `azure/openai/gpt-image-1.5` OpenAI's GPT Image 1.5 model via Azure

## Masked Edits

Provide a `mask` image to restrict edits to a specific region. Transparent pixels in the mask are the area that will be regenerated.

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -F "model=azure/openai/gpt-image-1" \
  -F "prompt=Replace the background with a forest" \
  -F "image[]=@./portrait.png" \
  -F "mask=@./mask.png" \
  -F "size=1024x1024"
```

## Transparent Backgrounds

Use the `background` parameter together with `output_format=png` (or `webp`) to produce edits with transparent backgrounds:

```bash theme={"dark"}
curl https://router.requesty.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -F "model=azure/openai/gpt-image-1" \
  -F "prompt=Isolate the product on a transparent background" \
  -F "image[]=@./product.png" \
  -F "background=transparent" \
  -F "output_format=png"
```

## Error Handling

The API returns standard HTTP status codes:

* `200` Success
* `400` Bad Request (invalid parameters)
* `401` Unauthorized (invalid API key)
* `413` Payload Too Large (uploaded images exceed the size limit)
* `429` Rate Limited
* `500` Internal Server Error

<Info>
  This endpoint is fully compatible with the OpenAI Images API. You can use the OpenAI SDK's `client.images.edit()` method directly.
</Info>

<Tip>
  To generate a new image from scratch rather than edit an existing one, use the [Create Image endpoint](/api-reference/endpoint/images-generations-create). See the [Image Generation feature guide](/features/image-generation) for a full comparison.
</Tip>


## OpenAPI

````yaml POST /v1/images/edits
openapi: 3.0.3
info:
  title: Requesty API
  description: Requesty API for AI model routing and key management
  version: 1.0.0
servers:
  - url: https://api-v2.requesty.ai
    description: Management API endpoint
  - url: https://router.requesty.ai
    description: Inference router endpoint
security:
  - BearerAuth: []
paths:
  /v1/images/edits:
    servers:
      - url: https://router.requesty.ai
        description: Inference router endpoint
    post:
      summary: Edit image
      description: >-
        Edit or extend an existing image from a text prompt using image editing
        models. Accepts multipart/form-data (for file uploads) or
        application/json (with image references as base64 data URLs or file
        IDs).
      operationId: createImageEdit
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageEditMultipartRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/ImageEditRequest'
      responses:
        '200':
          description: Image edit response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '400':
          description: Bad request - malformed payload or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or empty Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required - organization balance exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - invalid token or model not in access list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - provider/model not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
        '429':
          description: Rate limit exceeded. Retry after the Retry-After header value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad gateway - upstream provider returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ImageEditMultipartRequest:
      type: object
      required:
        - prompt
        - model
        - image[]
      properties:
        model:
          type: string
          description: The model to use for image editing
          example: azure/openai/gpt-image-1
        prompt:
          type: string
          description: A text description of the desired edit
        image[]:
          type: array
          description: >-
            One or more image files to edit. Repeat the image[] field to upload
            multiple images (up to 16 for GPT image models).
          items:
            type: string
            format: binary
        size:
          type: string
          description: Output size. Defaults to auto.
          enum:
            - auto
            - 1024x1024
            - 1536x1024
            - 1024x1536
        quality:
          type: string
          description: Image quality. Defaults to auto.
          enum:
            - auto
            - high
            - medium
            - low
        mask:
          type: string
          format: binary
          description: >-
            Optional mask image file. Transparent pixels mark the area that will
            be regenerated.
    ImageEditRequest:
      type: object
      required:
        - prompt
        - model
        - images
      properties:
        model:
          type: string
          description: The model to use for image editing
          example: azure/openai/gpt-image-1
        prompt:
          type: string
          description: A text description of the desired edit
          example: Make the sky a dramatic sunset
        images:
          type: array
          description: >-
            The list of input image references to edit. Up to 16 images for GPT
            image models.
          items:
            $ref: '#/components/schemas/ImageReference'
        size:
          type: string
          description: The size of the edited images. Defaults to auto.
          enum:
            - auto
            - 1024x1024
            - 1536x1024
            - 1024x1536
          default: auto
          example: 1024x1024
        quality:
          type: string
          description: The quality of the edited image. Defaults to auto.
          enum:
            - auto
            - high
            - medium
            - low
          default: auto
        mask:
          $ref: '#/components/schemas/ImageReference'
          description: >-
            Optional mask image. Transparent pixels in the mask mark the area
            that will be regenerated.
    ImageGenerationResponse:
      type: object
      required:
        - created
        - data
      properties:
        created:
          type: integer
          description: The Unix timestamp of when the image was created
          example: 1719000000
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageData'
          description: The list of generated images
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - origin
            - message
          properties:
            origin:
              type: string
              enum:
                - router
                - provider
              description: >-
                Whether the error originated from Requesty's router or an
                upstream provider.
            message:
              type: string
              description: Human-readable error description.
    ImageReference:
      type: object
      description: >-
        A reference to an input image by uploaded file ID or by URL. Provide
        exactly one of file_id or image_url. image_url accepts a public URL or a
        base64 data URL (for example data:image/png;base64,iVBORw0KGgo...).
      properties:
        file_id:
          type: string
          description: The File API ID of an uploaded image to use as input
        image_url:
          type: string
          description: A public URL or a base64 encoded data URL for the input image
    ImageData:
      type: object
      properties:
        url:
          type: string
          description: The URL of the generated image (when response_format is url)
        b64_json:
          type: string
          description: >-
            The base64-encoded JSON of the generated image (when response_format
            is b64_json)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````