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

# Edit Images

> Edit existing images using Google Gemini 2.5 Flash Image with text instructions.
All requests and responses are processed through SMLTP for security and compliance.

This endpoint is specifically designed for **image-to-image editing** where:
- An image file is **required** (unlike `/images/generations` where it's optional)
- A text prompt describes how to edit or transform the image
- The edited image is returned with the same quality and format options

All prompts and responses are automatically processed through SMLTP for audit logging and compliance.


# Edit Images

Edit existing images using Google Gemini 2.5 Flash Image with text instructions.

## Endpoint

```
POST /images/edits
```

## Description

Edit existing images using Google Gemini 2.5 Flash Image with text instructions. This endpoint is specifically designed for **image-to-image editing** where:

* An image file is **required** (unlike `/images/generations` where it's optional)
* A text prompt describes how to edit or transform the image
* The edited image is returned with the same quality and format options

All prompts and responses are automatically processed through SMLTP for audit logging and compliance.

## Authentication

Required: API Key

```bash theme={null}
Authorization: Bearer sk-your-api-key-here
```

## Request Body

This endpoint accepts `multipart/form-data` format.

### Parameters

| Parameter         | Type   | Required | Description                                                                                  |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `prompt`          | string | Yes      | Text instructions describing how to edit or transform the uploaded image (1-4000 characters) |
| `image`           | binary | Yes      | Image file to edit (JPEG, PNG, WEBP, or GIF, max 10MB)                                       |
| `smltp_policy`    | string | No       | SMLTP security policy (default: "internal")                                                  |
| `response_format` | string | No       | Response format: "url" or "b64\_json" (default: "url")                                       |

## Request Examples

### cURL

```bash theme={null}
curl -X POST "https://{customer.name}.hiperai.ai/api/external/images/edits" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "prompt=Add dramatic sunset colors to the sky and enhance the overall atmosphere" \
  -F "image=@/path/to/image.jpg" \
  -F "smltp_policy=internal" \
  -F "response_format=url"
```

### JavaScript/Node.js

```javascript theme={null}
const formData = new FormData();
formData.append('prompt', 'Add dramatic sunset colors to the sky and enhance the overall atmosphere');
formData.append('image', fileInput.files[0]);
formData.append('smltp_policy', 'internal');
formData.append('response_format', 'url');

const response = await fetch('https://{customer.name}.hiperai.ai/api/external/images/edits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here'
  },
  body: formData
});

const data = await response.json();
console.log('Edited image URL:', data.data[0].url);
```

### Python

```python theme={null}
import requests

url = "https://{customer.name}.hiperai.ai/api/external/images/edits"
headers = {
    "Authorization": "Bearer sk-your-api-key-here"
}

with open('image.jpg', 'rb') as f:
    files = {'image': f}
    data = {
        'prompt': 'Add dramatic sunset colors to the sky and enhance the overall atmosphere',
        'smltp_policy': 'internal',
        'response_format': 'url'
    }
    response = requests.post(url, headers=headers, files=files, data=data)
    result = response.json()
    print('Edited image URL:', result['data'][0]['url'])
```

## Response

### Success Response (200)

```json theme={null}
{
  "success": true,
  "id": "f55bb4aa-ad9a-4b5a-9c94-511bf6fce806",
  "object": "image.edit",
  "created": 1705312200,
  "data": [
    {
      "url": "http://localhost:5173/uploads/secureai_image_api_edit_68c5c6d2d57c85b102eb05e2_f55bb4aa_0.png",
      "revised_prompt": "Add dramatic sunset colors to the sky and enhance the overall atmosphere"
    }
  ],
  "metadata": {
    "model": "google/gemini-2.5-flash-image-preview",
    "provider": "Google",
    "total_images": 1,
    "is_image_to_image": true,
    "text_response": null,
    "smltp_trace_id": "trx-6caec994-73af-4f2c-9e13-572d53262f2a",
    "smltp_bundle_id": "jti-26464307-d455-4a3d-9ca4-8ec144cb601c",
    "smltp_policy": "internal"
  }
}
```

### Response Fields

| Field      | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| `success`  | boolean | Always true for successful requests          |
| `id`       | string  | Unique request identifier                    |
| `object`   | string  | Object type: "image.edit"                    |
| `created`  | integer | Unix timestamp of when image was edited      |
| `data`     | array   | Array of edited images                       |
| `metadata` | object  | Additional metadata including SMLTP tracking |

### Image Object

| Field            | Type   | Description                                                      |
| ---------------- | ------ | ---------------------------------------------------------------- |
| `url`            | string | URL to access the edited image (when response\_format is "url")  |
| `b64_json`       | string | Base64-encoded image data (when response\_format is "b64\_json") |
| `revised_prompt` | string | The prompt actually used for editing (may differ from input)     |

### Metadata Object

| Field               | Type         | Description                                         |
| ------------------- | ------------ | --------------------------------------------------- |
| `model`             | string       | Model used: "google/gemini-2.5-flash-image-preview" |
| `provider`          | string       | Provider: "Google"                                  |
| `total_images`      | integer      | Total number of images (always 1 for edits)         |
| `is_image_to_image` | boolean      | Always true for this endpoint                       |
| `text_response`     | string\|null | Optional text response from the model               |
| `smltp_trace_id`    | string       | SMLTP trace ID for audit tracking                   |
| `smltp_bundle_id`   | string       | SMLTP bundle ID for audit tracking                  |
| `smltp_policy`      | string       | SMLTP policy that was applied                       |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": "Missing image",
  "message": "An image file is required for image-to-image editing",
  "request_id": "f55bb4aa-ad9a-4b5a-9c94-511bf6fce806"
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": "Access denied",
  "message": "SMLTP policy not allowed"
}
```

### 413 Payload Too Large

```json theme={null}
{
  "success": false,
  "error": "File too large",
  "message": "Maximum image size is 10MB",
  "request_id": "f55bb4aa-ad9a-4b5a-9c94-511bf6fce806"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": "Internal server error",
  "message": "Image editing failed"
}
```

### 503 Service Unavailable

```json theme={null}
{
  "success": false,
  "error": "Service unavailable",
  "message": "Image generation service is not configured",
  "request_id": "f55bb4aa-ad9a-4b5a-9c94-511bf6fce806"
}
```

## Notes

* Supported image formats: JPEG, PNG, WEBP, GIF
* Maximum file size: 10MB per image
* The image file is **required** for this endpoint (unlike `/images/generations`)
* The prompt describes how to edit or transform the uploaded image
* All requests are processed through SMLTP for security and compliance
* Use `response_format: "b64_json"` to receive base64-encoded image data instead of URLs


## OpenAPI

````yaml POST /images/edits
openapi: 3.0.3
info:
  title: SecureAI External API
  description: >
    SecureAI External API provides AI chat completion and image generation
    capabilities with knowledge base retrieval, 

    security policies, and comprehensive usage tracking. This API is designed
    for external developers 

    and integrations using API key authentication.


    ## Key Features

    - **RAG (Retrieval-Augmented Generation)**: Automatically search knowledge
    bases for relevant context

    - **Multi-Model Support**: OpenAI, Anthropic, Google, Meta, and other AI
    models

    - **Model Redundancy & Failover**: Caller-defined failover chains (primary +
    fallbacks) with per-attempt timeouts

    - **OpenAI-Compatible Endpoint**: Point any OpenAI SDK at `/api/external/v1`
    — no code changes

    - **Image Generation**: Generate and edit images using Google Gemini 2.5
    Flash Image

    - **Speech-to-Speech (S2S)**: Real-time voice conversations using OpenAI
    Realtime API with WebRTC

    - **Security Policies**: SMLTP policy enforcement, per-call Prompt Shield,
    and signed compliance receipts

    - **Usage Tracking**: Comprehensive usage monitoring, self-service quota,
    and rate limiting

    - **Knowledge Base Integration**: Access to personal and shared knowledge
    bases

    - **User Management**: Complete user, group, and role management
    capabilities

    - **Audit Logging**: Comprehensive activity and security audit logs


    ## Authentication

    All endpoints (except health check) require API key authentication using
    Bearer token:

    ```

    Authorization: Bearer sk-your-api-key-here

    ```


    ## Billing and Usage

    By default, API requests are billed to the user account that owns the API
    key. You can specify 

    a different user to bill by including the `user_id` parameter in your
    request. This allows for:

    - Multi-tenant applications with per-user billing

    - Flexible completion limit management

    - Per-user "Usage by Model" settings


    ## Rate Limits

    - Default: 60 requests per minute, 1000 requests per hour

    - Daily limits: 100 requests (configurable)

    - Monthly limits: 10,000 requests (configurable)


    ## Base URL

    ```

    https://secureai.hiperai.ai/api/external

    ```
  version: 1.1.0
  contact:
    name: SecureAI Support
    email: support@secureai.hiperai.ai
  license:
    name: Proprietary
    url: https://secureai.hiperai.ai/terms
servers:
  - url: https://secureai.hiperai.ai/api/external
    description: Production server
  - url: http://localhost:3010/api/external
    description: Development server
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: System health and status endpoints
  - name: Discovery
    description: Endpoints to discover available models, indexes, and policies
  - name: Chat
    description: AI chat completion endpoints
  - name: User Management
    description: Endpoints for managing user accounts and roles
  - name: Index Management
    description: Endpoints for managing knowledge base indexes
  - name: Group Management
    description: Endpoints for managing user groups
  - name: SMLTP Security
    description: Endpoints for managing SMLTP security policies and audit logs
  - name: Role Management
    description: Endpoints for managing user roles
  - name: Activity Logs
    description: Endpoints for retrieving activity logs
externalDocs:
  description: SecureAI Documentation
  url: https://secureai.hiperai.ai/docs
paths:
  /images/edits:
    post:
      tags:
        - Images
      summary: Image-to-Image Editing
      description: >
        Edit existing images using Google Gemini 2.5 Flash Image with text
        instructions.

        All requests and responses are processed through SMLTP for security and
        compliance.


        This endpoint is specifically designed for **image-to-image editing**
        where:

        - An image file is **required** (unlike `/images/generations` where it's
        optional)

        - A text prompt describes how to edit or transform the image

        - The edited image is returned with the same quality and format options


        All prompts and responses are automatically processed through SMLTP for
        audit logging and compliance.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - prompt
                - image
              properties:
                prompt:
                  type: string
                  description: >-
                    Text instructions describing how to edit or transform the
                    uploaded image
                  example: >-
                    Add dramatic sunset colors to the sky and enhance the
                    overall atmosphere
                  minLength: 1
                  maxLength: 4000
                image:
                  type: string
                  format: binary
                  description: >-
                    Image file to edit (required, JPEG, PNG, WEBP, or GIF, max
                    10MB)
                smltp_policy:
                  type: string
                  description: >-
                    SMLTP security policy to apply (e.g., 'internal', 'public',
                    'confidential', 'hipaa', 'gdpr')
                  default: internal
                  example: internal
                response_format:
                  type: string
                  description: The format of the response images
                  enum:
                    - url
                    - b64_json
                  default: url
                  example: url
      responses:
        '200':
          description: Image edited successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  id:
                    type: string
                    description: Unique request identifier
                    example: f55bb4aa-ad9a-4b5a-9c94-511bf6fce806
                  object:
                    type: string
                    example: image.edit
                  created:
                    type: integer
                    description: Unix timestamp of when the image was edited
                    example: 1705312200
                  data:
                    type: array
                    description: Array of edited images
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: >-
                            URL to access the edited image (when response_format
                            is 'url')
                          example: >-
                            http://localhost:5173/uploads/secureai_image_api_edit_68c5c6d2d57c85b102eb05e2_f55bb4aa_0.png
                        b64_json:
                          type: string
                          description: >-
                            Base64-encoded image data (when response_format is
                            'b64_json')
                          example: iVBORw0KGgoAAAANSUhEUgAA...
                        revised_prompt:
                          type: string
                          description: >-
                            The prompt that was actually used for editing (may
                            differ from input)
                          example: >-
                            Add dramatic sunset colors to the sky and enhance
                            the overall atmosphere
                  metadata:
                    type: object
                    properties:
                      model:
                        type: string
                        example: google/gemini-2.5-flash-image-preview
                      provider:
                        type: string
                        example: Google
                      total_images:
                        type: integer
                        example: 1
                      is_image_to_image:
                        type: boolean
                        description: Always true for this endpoint
                        example: true
                      text_response:
                        type: string
                        nullable: true
                        description: Optional text response from the model
                        example: null
                      smltp_trace_id:
                        type: string
                        description: SMLTP trace ID for audit tracking
                        example: trx-6caec994-73af-4f2c-9e13-572d53262f2a
                      smltp_bundle_id:
                        type: string
                        description: SMLTP bundle ID for audit tracking
                        example: jti-26464307-d455-4a3d-9ca4-8ec144cb601c
                      smltp_policy:
                        type: string
                        description: SMLTP policy that was applied
                        example: internal
              example:
                success: true
                id: f55bb4aa-ad9a-4b5a-9c94-511bf6fce806
                object: image.edit
                created: 1705312200
                data:
                  - url: >-
                      http://localhost:5173/uploads/secureai_image_api_edit_68c5c6d2d57c85b102eb05e2_f55bb4aa_0.png
                    revised_prompt: >-
                      Add dramatic sunset colors to the sky and enhance the
                      overall atmosphere
                metadata:
                  model: google/gemini-2.5-flash-image-preview
                  provider: Google
                  total_images: 1
                  is_image_to_image: true
                  text_response: null
                  smltp_trace_id: trx-6caec994-73af-4f2c-9e13-572d53262f2a
                  smltp_bundle_id: jti-26464307-d455-4a3d-9ca4-8ec144cb601c
                  smltp_policy: internal
        '400':
          description: >-
            Invalid request parameters (missing prompt, missing image, invalid
            image format, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: Missing image
                message: An image file is required for image-to-image editing
                request_id: f55bb4aa-ad9a-4b5a-9c94-511bf6fce806
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied (SMLTP policy not allowed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Image file too large (maximum 10MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: File too large
                message: Maximum image size is 10MB
                request_id: f55bb4aa-ad9a-4b5a-9c94-511bf6fce806
        '500':
          description: Internal server error or image editing failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Image generation service unavailable (Gemini service not configured)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: Service unavailable
                message: Image generation service is not configured
                request_id: f55bb4aa-ad9a-4b5a-9c94-511bf6fce806
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid API key
        message:
          type: string
          example: The provided API key is invalid or has been revoked
        request_id:
          type: string
          example: req-abc123
          description: Request ID for tracking (if available)
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication using Bearer token format.
        Example: `Authorization: Bearer sk-your-api-key-here`

````