# POST /ai/edit-image

**Resource:** [AI](./ai.md)  
**Scopes:** `ai:use`  
**Write operation:** yes

Edit an existing image using AI reference guidance. Provide 1-3 reference image URLs (the subject to preserve) and a text prompt describing the new surroundings, style, or lighting. Uses the NanoBanana model (google:4@1, identity-preserving). Returns a CDN image URL, seed, and dimensions. Costs credits. The result is automatically saved to company files. IMPORTANT: Only 11 specific dimension pairs are accepted -- same constraints as generate-image. Reference URLs must be public http(s) URLs.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `prompt` | body | string | yes | Text description of the desired output (2-3000 chars). Describe the new setting, style, or lighting around the preserved subject. |
| `reference_image_url` | body | string | no | Single reference image URL (public http(s) URL). Use this OR reference_image_urls -- not both. |
| `reference_image_urls` | body | string[] | no | Array of 1-3 reference image URLs (public http(s) URLs). Use this OR reference_image_url -- not both. |
| `width` | body | number | no | Output width in pixels. Must be part of a valid pair. Default 1024. Valid pairs: 1024x1024, 1248x832, 832x1248, 1184x864, 864x1184, 896x1152, 1152x896, 768x1344, 1344x768, 1536x672, 672x1536. |
| `height` | body | number | no | Output height in pixels. Must be part of a valid pair with width. Default 1024. |
| `seed` | body | number | no | Random seed for reproducible results. Omit for random. |
| `output_format` | body | string | no | Output image format. Values: "PNG" (default, lossless), "WEBP", "JPEG". PNG is recommended when planning to run optimize_image afterwards (PNG -> WebP variants). WEBP/JPEG are smaller for direct use. |

## Response example

```json
{
  "data": {
    "image_url": "https://im.runware.ai/image/ii/...",
    "cdn_url": "https://cdn.trustpager.com/files/company-id/images/edited-image.webp",
    "image_id": "uuid",
    "seed": 1234567890,
    "width": 1024,
    "height": 1024,
    "prompt": "professional studio background, clean white backdrop, soft lighting",
    "reference_image_urls": [
      "https://example.com/subject.jpg"
    ]
  },
  "meta": {
    "credits_remaining": 9200
  }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`