---
type: AI Model
id: muse-image
title: Muse Image API
provider: Meta
description: "Muse Image is Meta's image generation model. It creates images from a text prompt, edits an existing image from an instruction, blends several images into one scene, and holds a subject or product steady across a series using reference images."
resource: https://www.pixazo.ai/models/muse-image
docs_url: https://www.pixazo.ai/models/muse-image
latest_version: 1.0
tags:
  - text-to-image
  - image-to-image
  - image-editing
  - reference-to-image
  - meta
variants:
  - id: muse-image
    name: Muse Image
    version: 1.0
    capabilities:
      - Text to Image
      - Image to Image (Image Editing)
      - Image to Image (Multi-Image Compose)
      - Reference to Image
timestamp: 2026-08-28T18:56:12.811Z
---

# Muse Image API

> Provider: **Meta**
> Source: https://www.pixazo.ai/models/muse-image

Muse Image is Meta's image generation model. It creates images from a text prompt, edits an existing image from an instruction, blends several images into one scene, and holds a subject or product steady across a series using reference images.

## Muse Image

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/muse-image/v1/text-to-image
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Text to Image - Muse Image

Generate one or more images from a text prompt. Muse Image is Meta’s image generation model, served through the Pixazo AI Gateway.

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/muse-image/v1/text-to-image
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A single red maple leaf centred on a plain white background, studio lighting"
}
```

```
import requests

url = "https://gateway.pixazo.ai/muse-image/v1/text-to-image"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
  "prompt": "A single red maple leaf centred on a plain white background, studio lighting"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const response = await fetch("https://gateway.pixazo.ai/muse-image/v1/text-to-image", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
    "prompt": "A single red maple leaf centred on a plain white background, studio lighting"
  })
});

const data = await response.json();
console.log(data);
```

```
curl -X POST "https://gateway.pixazo.ai/muse-image/v1/text-to-image" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A single red maple leaf centred on a plain white background, studio lighting"
  }'
```

## Output

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=muse-image&operation=text-to-image)

## Webhook (Optional)

Send an `X-Webhook-URL` header with your request and the finished result is POSTed to that URL, so you do not have to poll.

```
POST https://gateway.pixazo.ai/muse-image/v1/text-to-image
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
X-Webhook-URL: https://your-server.example.com/hooks/pixelforge
```

### Webhook Payload (Success)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  }
}
```

### Webhook Payload (Failure)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

-   **Delivery** — one POST per terminal result, retried a few times on a non-2xx response.
-   **Respond quickly** — return 2xx within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Text to Image

Pricing: **$0.011 per generated image**. Requests that set `num_images > 1` are billed per image (num\_images × $0.011).

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

1–4000 characters

A detailed description of the image you want. Be specific about the subject, style, lighting and composition.

num\_images

No

integer

1

1–4

How many images to generate in one request. **Billed per image** — n images cost n × $0.011.

image\_size

No

string

auto

auto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscape

The shape of the output. This sets the **aspect ratio only** — the generator picks its own resolution and caps the long edge at roughly 1600 px, so the returned pixel dimensions will not match the numbers you supply. Omit it, or send `auto`, to let the model choose.

output\_format

No

string

webp

webp · png · jpeg · jpg

Encoding of the returned image. `webp` gives the smallest files at equivalent quality. `jpg` is accepted as a synonym for `jpeg`.

quality

No

string

high

standard · high

`high` lets the model reason for longer before drawing, which helps with complex prompts and legible text. `standard` is faster. **Both cost the same.**

**Not supported by this model.** Sending any of these returns `400` with an explanation rather than being silently ignored: `seed` (generation is non-deterministic — the same prompt returns a different image every time), `mask` / `mask_url` (there is no masked in-painting; describe the region to change in the prompt), `background` / `transparent` (output is always opaque), `stream` and `partial_images` (results arrive by polling), and `model`, `moderation`, `response_format` and `tool_enablement`.

## Minimum Request

```
{
  "prompt": "A single red maple leaf centred on a plain white background, studio lighting"
}
```

## Full Request (all options)

```
{
  "prompt": "A single red maple leaf centred on a plain white background, studio lighting",
  "num_images": 2,
  "image_size": "1024x1024",
  "output_format": "webp",
  "quality": "high"
}
```

## Response

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Text to Image.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Missing a required parameter
{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}
```

### Error via Status/Webhook

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

A request blocked by the content safety filter returns `status: "ERROR"` with a message asking you to rephrase the prompt or use a different reference image. Failed requests are **not charged**.

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  },
  "created_at": "2026-07-23T10:00:00.000Z",
  "updated_at": "2026-07-23 10:00:15",
  "completed_at": "2026-07-23 10:00:15"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated images (R2 CDN)

output.media\_type

string

MIME type of the output (image/webp)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error (e.g. bad inputs) — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image to Image (Image Editing) - Muse Image

Edit an existing image with a text instruction. The model changes only what you ask for and leaves the rest of the picture intact. Muse Image is Meta’s image generation model, served through the Pixazo AI Gateway.

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Change the background to a soft blue gradient",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
}
```

```
import requests

url = "https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
  "prompt": "Change the background to a soft blue gradient",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const response = await fetch("https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
    "prompt": "Change the background to a soft blue gradient",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  })
});

const data = await response.json();
console.log(data);
```

```
curl -X POST "https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Change the background to a soft blue gradient",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  }'
```

## Output

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=muse-image&operation=image-to-image-editing)

## Webhook (Optional)

Send an `X-Webhook-URL` header with your request and the finished result is POSTed to that URL, so you do not have to poll.

```
POST https://gateway.pixazo.ai/muse-image/v1/image-to-image/editing
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
X-Webhook-URL: https://your-server.example.com/hooks/pixelforge
```

### Webhook Payload (Success)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  }
}
```

### Webhook Payload (Failure)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

-   **Delivery** — one POST per terminal result, retried a few times on a non-2xx response.
-   **Respond quickly** — return 2xx within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Image to Image (Image Editing)

Pricing: **$0.011 per generated image**. Requests that set `num_images > 1` are billed per image (num\_images × $0.011).

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

1–4000 characters

A detailed description of the image you want. Be specific about the subject, style, lighting and composition.

image\_url

Yes

string

—

Public HTTPS URL or base64 data URI

The image to edit, as a public HTTPS URL — no size limit — or supplied inline as a `data:image/...;base64,` data URI. **Inline data URIs only** are capped at 20 MB per image and 40 MB per request; use an HTTPS URL for anything larger.

num\_images

No

integer

1

1–4

How many images to generate in one request. **Billed per image** — n images cost n × $0.011.

image\_size

No

string

auto

auto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscape

The shape of the output. This sets the **aspect ratio only** — the generator picks its own resolution and caps the long edge at roughly 1600 px, so the returned pixel dimensions will not match the numbers you supply. Omit it, or send `auto`, to let the model choose.

output\_format

No

string

webp

webp · png · jpeg · jpg

Encoding of the returned image. `webp` gives the smallest files at equivalent quality. `jpg` is accepted as a synonym for `jpeg`.

quality

No

string

high

standard · high

`high` lets the model reason for longer before drawing, which helps with complex prompts and legible text. `standard` is faster. **Both cost the same.**

**Not supported by this model.** Sending any of these returns `400` with an explanation rather than being silently ignored: `seed` (generation is non-deterministic — the same prompt returns a different image every time), `mask` / `mask_url` (there is no masked in-painting; describe the region to change in the prompt), `background` / `transparent` (output is always opaque), `stream` and `partial_images` (results arrive by polling), and `model`, `moderation`, `response_format` and `tool_enablement`.

## Minimum Request

```
{
  "prompt": "Change the background to a soft blue gradient",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
}
```

## Full Request (all options)

```
{
  "prompt": "Change the background to a soft blue gradient",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
  "num_images": 1,
  "image_size": "1024x1024",
  "output_format": "webp",
  "quality": "high"
}
```

## Response

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Image to Image (Image Editing).

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Missing a required parameter
{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}
```

### Error via Status/Webhook

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

A request blocked by the content safety filter returns `status: "ERROR"` with a message asking you to rephrase the prompt or use a different reference image. Failed requests are **not charged**.

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  },
  "created_at": "2026-07-23T10:00:00.000Z",
  "updated_at": "2026-07-23 10:00:15",
  "completed_at": "2026-07-23 10:00:15"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated images (R2 CDN)

output.media\_type

string

MIME type of the output (image/webp)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error (e.g. bad inputs) — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Multi-Image Compose)

## Base URL

```
https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image to Image (Multi-Image Compose) - Muse Image

Blend two or more images into a single scene — for example, place a product from one photograph into the setting of another. The model may rearrange the layout to make the composition work. Muse Image is Meta’s image generation model, served through the Pixazo AI Gateway.

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Place the product from the first image on the table in the second image",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
  ]
}
```

```
import requests

url = "https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
  "prompt": "Place the product from the first image on the table in the second image",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
  ]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const response = await fetch("https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
    "prompt": "Place the product from the first image on the table in the second image",
    "image_urls": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
    ]
  })
});

const data = await response.json();
console.log(data);
```

```
curl -X POST "https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Place the product from the first image on the table in the second image",
    "image_urls": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
    ]
  }'
```

## Output

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=muse-image&operation=image-to-image-compose)

## Webhook (Optional)

Send an `X-Webhook-URL` header with your request and the finished result is POSTed to that URL, so you do not have to poll.

```
POST https://gateway.pixazo.ai/muse-image/v1/image-to-image/compose
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
X-Webhook-URL: https://your-server.example.com/hooks/pixelforge
```

### Webhook Payload (Success)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  }
}
```

### Webhook Payload (Failure)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

-   **Delivery** — one POST per terminal result, retried a few times on a non-2xx response.
-   **Respond quickly** — return 2xx within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Image to Image (Multi-Image Compose)

Pricing: **$0.011 per generated image**. Requests that set `num_images > 1` are billed per image (num\_images × $0.011).

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

1–4000 characters

A detailed description of the image you want. Be specific about the subject, style, lighting and composition.

image\_urls

Yes

array of string

—

2–6 items

The images to combine, as public HTTPS URLs or base64 data URIs. At least two are required — use `image-to-image/editing` for a single image. **They must be two different images:** repeated URLs are collapsed before the minimum is checked, so `[A, A]` is rejected as one image, not accepted as two.

num\_images

No

integer

1

1–4

How many images to generate in one request. **Billed per image** — n images cost n × $0.011.

image\_size

No

string

auto

auto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscape

The shape of the output. This sets the **aspect ratio only** — the generator picks its own resolution and caps the long edge at roughly 1600 px, so the returned pixel dimensions will not match the numbers you supply. Omit it, or send `auto`, to let the model choose.

output\_format

No

string

webp

webp · png · jpeg · jpg

Encoding of the returned image. `webp` gives the smallest files at equivalent quality. `jpg` is accepted as a synonym for `jpeg`.

quality

No

string

high

standard · high

`high` lets the model reason for longer before drawing, which helps with complex prompts and legible text. `standard` is faster. **Both cost the same.**

**Not supported by this model.** Sending any of these returns `400` with an explanation rather than being silently ignored: `seed` (generation is non-deterministic — the same prompt returns a different image every time), `mask` / `mask_url` (there is no masked in-painting; describe the region to change in the prompt), `background` / `transparent` (output is always opaque), `stream` and `partial_images` (results arrive by polling), and `model`, `moderation`, `response_format` and `tool_enablement`.

## Minimum Request

```
{
  "prompt": "Place the product from the first image on the table in the second image",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
  ]
}
```

## Full Request (all options)

```
{
  "prompt": "Place the product from the first image on the table in the second image",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/scene-end.jpg"
  ],
  "num_images": 1,
  "image_size": "1536x1024",
  "output_format": "webp",
  "quality": "high"
}
```

## Response

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Image to Image (Multi-Image Compose).

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Missing a required parameter
{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}
```

### Error via Status/Webhook

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

A request blocked by the content safety filter returns `status: "ERROR"` with a message asking you to rephrase the prompt or use a different reference image. Failed requests are **not charged**.

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  },
  "created_at": "2026-07-23T10:00:00.000Z",
  "updated_at": "2026-07-23 10:00:15",
  "completed_at": "2026-07-23 10:00:15"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated images (R2 CDN)

output.media\_type

string

MIME type of the output (image/webp)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error (e.g. bad inputs) — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Reference to Image

## Base URL

```
https://gateway.pixazo.ai/muse-image/v1/reference-to-image
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Reference to Image - Muse Image

Generate a new image that keeps the subject, style or product from one to three reference images. Use it to hold a character or a product identity steady across a series of shots. Muse Image is Meta’s image generation model, served through the Pixazo AI Gateway.

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/muse-image/v1/reference-to-image
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "The same product photographed on a marble kitchen counter in morning light",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ]
}
```

```
import requests

url = "https://gateway.pixazo.ai/muse-image/v1/reference-to-image"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
  "prompt": "The same product photographed on a marble kitchen counter in morning light",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const response = await fetch("https://gateway.pixazo.ai/muse-image/v1/reference-to-image", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
    "prompt": "The same product photographed on a marble kitchen counter in morning light",
    "reference_image_urls": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
    ]
  })
});

const data = await response.json();
console.log(data);
```

```
curl -X POST "https://gateway.pixazo.ai/muse-image/v1/reference-to-image" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "The same product photographed on a marble kitchen counter in morning light",
    "reference_image_urls": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
    ]
  }'
```

## Output

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=muse-image&operation=reference-to-image)

## Webhook (Optional)

Send an `X-Webhook-URL` header with your request and the finished result is POSTed to that URL, so you do not have to poll.

```
POST https://gateway.pixazo.ai/muse-image/v1/reference-to-image
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
X-Webhook-URL: https://your-server.example.com/hooks/pixelforge
```

### Webhook Payload (Success)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  }
}
```

### Webhook Payload (Failure)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

-   **Delivery** — one POST per terminal result, retried a few times on a non-2xx response.
-   **Respond quickly** — return 2xx within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Reference to Image

Pricing: **$0.011 per generated image**. Requests that set `num_images > 1` are billed per image (num\_images × $0.011).

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

1–4000 characters

A detailed description of the image you want. Be specific about the subject, style, lighting and composition.

reference\_image\_urls

Yes

array of string

—

1–3 items

Reference images that anchor the subject, product or style, as public HTTPS URLs or base64 data URIs. They condition the new image rather than being edited in place.

num\_images

No

integer

1

1–4

How many images to generate in one request. **Billed per image** — n images cost n × $0.011.

image\_size

No

string

auto

auto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscape

The shape of the output. This sets the **aspect ratio only** — the generator picks its own resolution and caps the long edge at roughly 1600 px, so the returned pixel dimensions will not match the numbers you supply. Omit it, or send `auto`, to let the model choose.

output\_format

No

string

webp

webp · png · jpeg · jpg

Encoding of the returned image. `webp` gives the smallest files at equivalent quality. `jpg` is accepted as a synonym for `jpeg`.

quality

No

string

high

standard · high

`high` lets the model reason for longer before drawing, which helps with complex prompts and legible text. `standard` is faster. **Both cost the same.**

**Not supported by this model.** Sending any of these returns `400` with an explanation rather than being silently ignored: `seed` (generation is non-deterministic — the same prompt returns a different image every time), `mask` / `mask_url` (there is no masked in-painting; describe the region to change in the prompt), `background` / `transparent` (output is always opaque), `stream` and `partial_images` (results arrive by polling), and `model`, `moderation`, `response_format` and `tool_enablement`.

## Minimum Request

```
{
  "prompt": "The same product photographed on a marble kitchen counter in morning light",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ]
}
```

## Full Request (all options)

```
{
  "prompt": "The same product photographed on a marble kitchen counter in morning light",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "num_images": 2,
  "image_size": "1024x1536",
  "output_format": "webp",
  "quality": "high"
}
```

## Response

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Reference to Image.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Missing a required parameter
{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}
```

### Error via Status/Webhook

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "muse-image",
  "error": "Description of the error",
  "output": null
}
```

A request blocked by the content safety filter returns `status: "ERROR"` with a message asking you to rephrase the prompt or use a different reference image. Failed requests are **not charged**.

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "muse-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/muse-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.webp"
    ],
    "media_type": "image/webp"
  },
  "created_at": "2026-07-23T10:00:00.000Z",
  "updated_at": "2026-07-23 10:00:15",
  "completed_at": "2026-07-23 10:00:15"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated images (R2 CDN)

output.media\_type

string

MIME type of the output (image/webp)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error (e.g. bad inputs) — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.