> ## 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.

# Create image

> Generate images from a text prompt with a model served on the Images API

Generate images from a text prompt. The response carries every image as base64 in `data[].b64_json`. This endpoint follows the [OpenAI Images API](https://platform.openai.com/docs/api-reference/images/create) and works with `client.images.generate` in the OpenAI SDK.

It serves the image models whose `endpoints` in the [List models API](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) contain `/v1/images/generations`. Other image models, including some that output only images, generate images through [chat completions](https://docs.inworld.ai/api-reference/routerAPI/chat-completions.md) instead. Each model takes its own options, and the API rejects an option the model does not take with `400`. See [Generate and edit images with the Images API](https://docs.inworld.ai/router/image-generation.md#generate-and-edit-images-with-the-images-api) for options, errors and billing, 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/generations`

### 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: `application/json`

- `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 generate. It has no length limit of its own: the request body is limited to 512 KiB, and the model can reject a longer prompt than it accepts.
- `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`.
- `moderation` (string) — Moderation level, 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.

#### Request example

```json
{
  "model": "meta/muse-image-1.0",
  "prompt": "A ceramic teapot on a wooden table by a window, soft morning light, product photograph",
  "output_format": "png"
}
```

### 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": "meta/muse-image-1.0 does not take quality",
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "quality"
  }
}
```

#### 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/generations \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/muse-image-1.0",
    "prompt": "A ceramic teapot on a wooden table by a window, soft morning light, product photograph",
    "output_format": "png"
  }' \
  -o response.json
jq -r '.data[0].b64_json' response.json | base64 --decode > image-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.generate(
    model="meta/muse-image-1.0",
    prompt="A ceramic teapot on a wooden table by a window, soft morning light, product photograph",
    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"image-{index}.png")
    path.write_bytes(base64.b64decode(image.b64_json))
    print(f"Saved {path}")
```

#### JavaScript

```javascript
const options = {method: 'POST', headers: {"Authorization":"<api_key>","Content-Type":"application/json"}, body: JSON.stringify({
  "model": "meta/muse-image-1.0",
  "prompt": "A ceramic teapot on a wooden table by a window, soft morning light, product photograph",
  "output_format": "png"
})};

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

#### Node

```javascript
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.generate({
  model: 'meta/muse-image-1.0',
  prompt: 'A ceramic teapot on a wooden table by a window, soft morning light, product photograph',
  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 = `image-${index + 1}.png`;
  await writeFile(path, Buffer.from(image.b64_json, 'base64'));
  console.log(`Saved ${path}`);
}
```