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

# Edit image

> Create new images from input images and a prompt with a model served on the Images API

Create new images from one or more input images and a prompt that says what to keep and what to change. Send the images as files in a `multipart/form-data` body, as `client.images.edit` in the OpenAI SDK does, or as base64 data URLs in a JSON body. This endpoint follows the [OpenAI Images API](https://platform.openai.com/docs/api-reference/images/createEdit).

It serves models whose `endpoints` in the [List models API](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) contain `/v1/images/edits`. To make a variation of an image, send it here and describe the variation in the prompt. See [Edit an image](https://docs.inworld.ai/router/image-generation.md#edit-an-image) for a walkthrough, and [OpenAI Images API compatibility](https://docs.inworld.ai/router/image-generation.md#openai-images-api-compatibility) for how each field is handled.

## API reference

**Endpoint:** `POST https://api.inworld.ai/v1/images/edits`

### Authorization

- `Authorization` (string; required) — Your [authentication](https://docs.inworld.ai/api-reference/introduction.md) credentials. For Basic authentication, populate `Basic $INWORLD_API_KEY`.

### Request body

Content type: `multipart/form-data`

- `model` (string; required) — An Images API model ID: a model whose `endpoints` in the [List models API](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) contain this route.
- `prompt` (string; required) — What to keep and what to change in the input images.
- `image` (string) — An input image file: PNG, JPEG or WebP, up to 20 MiB. For several images, repeat the field, up to the model's number of input images (`meta/muse-image-1.0` takes up to 10). Send the images as `image` or as `image[]`.
- `image[]` (string) — The same as `image`, under the name some clients use for several files. Send the images as `image` or as `image[]`.
- `mask` (string) — An image that marks the area to edit, on models that take one; rejected (`400`) on others, including `meta/muse-image-1.0`.
- `n` (integer; default: 1) — How many images to return, from 1 to the model's maximum. A larger value returns `400` with the maximum in the message. `meta/muse-image-1.0` returns up to 10.
- `size` (string) — `auto` or `WIDTHxHEIGHT`, on models that take it. The model chooses the exact pixel dimensions and can treat the value as a shape: a `1024x1024` request to `meta/muse-image-1.0` returned 1600x1600 images.
- `output_format` (string) — The file format of the returned images, on models that take it, with the values each model allows. `meta/muse-image-1.0` takes `png`, `jpeg` or `webp`, and returns `webp` when it is left out.
- `quality` (string) — Image quality, on models that take it; rejected (`400`) on others, including `meta/muse-image-1.0`.
- `background` (string) — Background, such as transparent or opaque, on models that take it; rejected (`400`) on others, including `meta/muse-image-1.0`.
- `input_fidelity` (string) — How closely to keep the input images, on models that take it; rejected (`400`) on others, including `meta/muse-image-1.0`.
- `response_format` (enum<string>; default: "b64_json"; options: "b64_json") — Images are always returned as base64 in `b64_json`. `url` is rejected (`400`).
- `stream` (boolean; default: false) — Return the result as server-sent events. The API sends one completed event per image once all images are ready; it sends no partial images.
- `user` (string) — Accepted for compatibility and ignored: it is not sent to the model.
- `safety_identifier` (string) — Accepted for compatibility and ignored: it is not sent to the model.

### Response

Status: `200`. Content type: `application/json`.

- `created` (integer; required) — When the images were created, in Unix seconds.
- `data` (object[]; required) — One entry per image returned.
  - `b64_json` (string; required) — The image file, base64-encoded.
  - `revised_prompt` (string) — The prompt the model used, when it rewrote yours.
- `output_format` (string) — The file format of every image in `data`, such as `png`, `jpeg` or `webp`.
- `size` (string) — The size of the returned images when the model reports it; otherwise the size you asked for. Read the dimensions from the image file if you depend on them.
- `background` (string) — The images' background, when known.
- `quality` (string) — The images' quality, when known.
- `usage` (object) — Token counts the model reports, for information only: the Images API bills per image returned, not per token. Omitted when the model reports none.
  - `input_tokens` (integer)
  - `output_tokens` (integer)
  - `total_tokens` (integer)
  - `input_tokens_details` (object) — Present only when the model reports it.
    - `text_tokens` (integer)
    - `image_tokens` (integer)
  - `output_tokens_details` (object) — Present only when the model reports it.
    - `text_tokens` (integer)
    - `image_tokens` (integer)

### Response examples

#### 200: default_response

```json
{
  "created": 1794505773,
  "data": [
    {
      "b64_json": "UklGRq7DBABXRUJQ..."
    }
  ],
  "output_format": "webp",
  "size": "1920x1280",
  "background": "opaque",
  "usage": {
    "input_tokens": 9919,
    "output_tokens": 829,
    "total_tokens": 10748
  }
}
```

#### 400: default_response

```json
{
  "error": {
    "message": "images[0].image_url must be a base64 data URL",
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "images[0].image_url"
  }
}
```

#### 404: default_response

```json
{
  "error": {
    "message": "the model does not exist or is not an image generation model",
    "type": "not_found_error",
    "code": "model_not_found",
    "param": "model"
  }
}
```

#### 502: default_response

```json
{
  "error": {
    "message": "the model returned no image",
    "type": "upstream_error",
    "code": "no_image_returned"
  }
}
```

### Code examples

#### cURL

```bash
curl -sS https://api.inworld.ai/v1/images/edits \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -F model=meta/muse-image-1.0 \
  -F "prompt=Keep the teapot and composition. Change the background to a pale blue studio backdrop." \
  -F "image=@image-1.png" \
  -F output_format=png \
  -o response.json
jq -r '.data[0].b64_json' response.json | base64 --decode > edited-1.png
```

#### Python

```python
import base64
import os
from pathlib import Path

from openai import OpenAI

api_key = os.environ["INWORLD_API_KEY"]
client = OpenAI(
    base_url="https://api.inworld.ai/v1",
    api_key=api_key,
    default_headers={"Authorization": f"Basic {api_key}"},
)

result = client.images.edit(
    model="meta/muse-image-1.0",
    image=Path("image-1.png"),
    prompt="Keep the teapot and composition. Change the background to a pale blue studio backdrop.",
    output_format="png",
)

for index, image in enumerate(result.data or [], start=1):
    if not image.b64_json:
        raise RuntimeError("The response carried no image data")
    path = Path(f"edited-{index}.png")
    path.write_bytes(base64.b64decode(image.b64_json))
    print(f"Saved {path}")
```

#### JavaScript

```javascript
const options = {method: 'POST', headers: {"Authorization":"<api_key>"}};

fetch('https://api.inworld.ai/v1/images/edits', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

#### Node

```javascript
import { createReadStream } from 'node:fs';
import { writeFile } from 'node:fs/promises';
import OpenAI from 'openai';

const apiKey = process.env.INWORLD_API_KEY;
if (!apiKey) throw new Error('Set INWORLD_API_KEY first');

const client = new OpenAI({
  baseURL: 'https://api.inworld.ai/v1',
  apiKey,
  defaultHeaders: { Authorization: `Basic ${apiKey}` },
});

const result = await client.images.edit({
  model: 'meta/muse-image-1.0',
  image: createReadStream('image-1.png'),
  prompt: 'Keep the teapot and composition. Change the background to a pale blue studio backdrop.',
  output_format: 'png',
});

for (const [index, image] of (result.data ?? []).entries()) {
  if (!image.b64_json) throw new Error('The response carried no image data');
  const path = `edited-${index + 1}.png`;
  await writeFile(path, Buffer.from(image.b64_json, 'base64'));
  console.log(`Saved ${path}`);
}
```