Pixazo API→Models→Text to Image API→Muse Image
Pixazo API→Models→Text to Image API→Muse Image

Muse Image API: Pricing, Documentation

by Meta

View as Markdown

Muse Image API delivers an advanced, cloud-based visual generation engine designed to transform descriptive text into high-fidelity digital artwork and photorealistic imagery. Built on state-of-the-art latent diffusion models, this programmatic interface allows developers and enterprises to seamlessly embed automated graphic creation directly into their existing applications, content management systems, and creative workflows. It offers fine-grained control over artistic styles, aspect ratios, color palettes, and structural composition, enabling the dynamic rendering of custom assets on demand.

Get API Key
Muse Image API

Models Version

WELCOME BONUS

Get $5 Free Credit on First Payment

No strings attached — add funds and get $5 bonus instantly

Claim Your $5 →

Muse Image API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour 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

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

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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring—1–4000 charactersA detailed description of the image you want. Be specific about the subject, style, lighting and composition.
num_imagesNointeger11–4How many images to generate in one request. Billed per image — n images cost n × $0.011.
image_sizeNostringautoauto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscapeThe 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_formatNostringwebpwebp · png · jpeg · jpgEncoding of the returned image. webp gives the smallest files at equivalent quality. jpg is accepted as a synonym for jpeg.
qualityNostringhighstandard · highhigh 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

HeaderValue
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYour API subscription key

Response Handling

Common status codes for Text to Image.

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated images (R2 CDN)
output.media_typestringMIME type of the output (image/webp)
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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.

Muse Image API Pricing

Your request will cost $0.011 per image.
Image to Image (Image Editing)

Muse Image API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour 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

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

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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring—1–4000 charactersA detailed description of the image you want. Be specific about the subject, style, lighting and composition.
image_urlYesstring—Public HTTPS URL or base64 data URIThe 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_imagesNointeger11–4How many images to generate in one request. Billed per image — n images cost n × $0.011.
image_sizeNostringautoauto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscapeThe 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_formatNostringwebpwebp · png · jpeg · jpgEncoding of the returned image. webp gives the smallest files at equivalent quality. jpg is accepted as a synonym for jpeg.
qualityNostringhighstandard · highhigh 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

HeaderValue
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYour API subscription key

Response Handling

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

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated images (R2 CDN)
output.media_typestringMIME type of the output (image/webp)
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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.

Muse Image API Pricing

Your request will cost $0.011 per image.
Image to Image (Multi-Image Compose)

Muse Image API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour 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

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

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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring—1–4000 charactersA detailed description of the image you want. Be specific about the subject, style, lighting and composition.
image_urlsYesarray of string—2–6 itemsThe 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_imagesNointeger11–4How many images to generate in one request. Billed per image — n images cost n × $0.011.
image_sizeNostringautoauto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscapeThe 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_formatNostringwebpwebp · png · jpeg · jpgEncoding of the returned image. webp gives the smallest files at equivalent quality. jpg is accepted as a synonym for jpeg.
qualityNostringhighstandard · highhigh 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

HeaderValue
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYour API subscription key

Response Handling

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

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated images (R2 CDN)
output.media_typestringMIME type of the output (image/webp)
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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.

Muse Image API Pricing

Your request will cost $0.011 per image.
Reference to Image

Muse Image API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour 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

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

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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring—1–4000 charactersA detailed description of the image you want. Be specific about the subject, style, lighting and composition.
reference_image_urlsYesarray of string—1–3 itemsReference 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_imagesNointeger11–4How many images to generate in one request. Billed per image — n images cost n × $0.011.
image_sizeNostringautoauto · 1024x1024 · 1024x1536 · 1536x1024 · 1792x1024 · 1024x1792 · 1:1 · 3:2 · 2:3 · 16:9 · 9:16 · square · portrait · landscapeThe 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_formatNostringwebpwebp · png · jpeg · jpgEncoding of the returned image. webp gives the smallest files at equivalent quality. jpg is accepted as a synonym for jpeg.
qualityNostringhighstandard · highhigh 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

HeaderValue
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYour API subscription key

Response Handling

Common status codes for Reference to Image.

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated images (R2 CDN)
output.media_typestringMIME type of the output (image/webp)
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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.

Muse Image API Pricing

Your request will cost $0.011 per image.

⚡ Performance

Live usage measured on Pixazo's gateway, split by model version. Generation time is how long a generation takes end-to-end (lower is better). Success rate is the percent of generations that complete (higher is better).

Show data for the last
Generations
1,200last 30d
~40 per day
Success rate
91.7%
of completed generations
Generation time
41.9savg
p95 55.6s
Requests
Aug 1max 1,100Aug 30
Muse ImageAvg 40/day
Generation Time
Aug 1max 41.9sAug 30
Muse ImageAvg 41.9s
Error Rate
Aug 1max 100.0%Aug 30
Muse ImageAvg 8.3%

〰 Uptime

Percent of generations that succeeded over the selected period, per model version.

Avg. Success Rate (30d)
91.67%
across all generations of this model family
Uptime
Aug 1max 100%Aug 30
SuccessfulAvg 91.67%