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

# Image Editing

> Edit images using text prompts

## Endpoint

```
POST /api/ai/images/edit
```

Edit an existing image using a text prompt. The request blocks until the edited image is ready.

## Request Parameters

| Parameter          | Type         | Required | Default      | Description                                                                                                                     |
| ------------------ | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string       | **yes**  | --           | Image editing model (e.g. `qwen-image-edit`, `nano-banana-2-edit`, `xai-grok-imagine-image-edit`)                               |
| `prompt`           | string       | **yes**  | --           | Description of the edit to apply.                                                                                               |
| `input_image`      | string/array | **yes**  | --           | URL(s) of the image to edit. Some models accept an array; see [per-model reference](/inference-api/reference/model-references). |
| `response_format`  | string       | no       | `"url"`      | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded image bytes inline.                                           |
| `target_namespace` | string       | no       | current user | Namespace to save results and bill to. Can be an organization name.                                                             |

## Examples

### Basic edit

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://hub.oxen.ai/api/ai/images/edit",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "qwen-image-edit",
          "prompt": "Make the background blue",
          "input_image": "https://example.com/my-photo.jpg",
      },
  )

  data = response.json()
  print("Image URL:", data["images"][0]["url"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://hub.oxen.ai/api/ai/images/edit \
    -H "Authorization: Bearer $OXEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen-image-edit",
      "prompt": "Make the background blue",
      "input_image": "https://example.com/my-photo.jpg"
    }'
  ```
</CodeGroup>

### Multi-image input

Some models accept an array of URLs in `input_image`. Consult the per-model reference for how each model uses them:

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://hub.oxen.ai/api/ai/images/edit",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2-edit",
          "prompt": "Combine these references into a single scene",
          "input_image": [
              "https://example.com/reference-a.png",
              "https://example.com/reference-b.png",
          ],
      },
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://hub.oxen.ai/api/ai/images/edit \
    -H "Authorization: Bearer $OXEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-edit",
      "prompt": "Combine these references into a single scene",
      "input_image": [
        "https://example.com/reference-a.png",
        "https://example.com/reference-b.png"
      ]
    }'
  ```
</CodeGroup>

Whether a model accepts a single image or an array of images is part of its schema. See each model's [API reference](/inference-api/reference/model-references) for the exact type.

### Response

Same format as `/ai/images/generate`:

```json theme={null}
{
  "model": "qwen-image-edit",
  "created": 1775090400,
  "images": [
    {
      "url": "https://hub.oxen.ai/api/repos/.../files/.../image.png?..."
    }
  ]
}
```

## Errors

| Condition                | Error                                            |
| ------------------------ | ------------------------------------------------ |
| Image URL not accessible | `"... 403 Client Error: Forbidden for url: ..."` |
| Model not found          | `"Model not found: <name>"`                      |

The `input_image` URL must be publicly downloadable. URLs that require authentication or block automated access will fail. Data URIs (`data:image/...;base64,...`) work as an alternative but aren't recommended for production.