Muse Image API reference

Limits at a glance

Everything Muse Image accepts and everything it does not, in one table. Check it before you build on the model: text-to-image, or image-to-image with 1 to 4 reference images; one image per request, about 2.5MP, no 4K, no masks.

Unsupported values and fields return a 400 before a task is created and cost nothing (the one exception is quality, which is accepted and ignored); the exact messages are listed under Errors below.

Not every request succeeds

Text-to-image and image-to-image

One model id and one endpoint; the mode follows from whether you send reference images. Both cost the same: $0.02 per image.

Put one reference image in image (or image_url) and several in images (or image_urls); if you send both, the single image comes first, and the total is at most 4. Each image is a public URL or a base64 data URI, PNG, JPEG or WebP, up to 10 MB each and 24 MB in total. Masks are not supported: describe the area to change in the prompt.

Authentication

Authorization: Bearer YOUR_API_KEY

Quick start

Text-to-image

# ─── Text-to-image, one image per request ────────────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "A bakery storefront at dawn, a hand-painted sign that reads \"MORNING LOAF\", warm window light",
    "aspect_ratio": "3:2"
  }'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-image" } }


# ─── Poll for the result ──────────────────────────────────
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."],
#     "images": [{ "url": "https://r2.apimodels.app/...", "width": 1920, "height": 1280 }] } }


# ─── One call, OpenAI style: an OpenAI-style size and no callback_url ──
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "A minimalist travel poster of Kyoto in autumn, the title \"KYOTO\" in bold letters at the top",
    "size": "2048x1152"
  }'
# { "created": ...,
#   "data": [{ "b64_json": "...", "url": "https://r2.apimodels.app/...", "width": 2048, "height": 1152 }],
#   "size": "2048x1152" }

By default the call is async: create a task for a taskId, then poll GET /v1/images/generations?task_id= until state is completed; the image is in data.resultUrls and its actual width and height in data.images. On failed, the reason is in data.failMsg and nothing is charged. In our tests each image took about 35-70 seconds, so polling every 5 seconds is plenty. For a one-call response, pass an OpenAI-style size and no callback_url: the request stays open until the image is ready, and the reply is { created, data: [{ b64_json, url, width, height }], size }; "response_format": "url" leaves out the base64 copy. The OpenAI SDK's images.generate gets the same one-call response.

Image-to-image (1 to 4 reference images)

Same model id, same endpoint: add reference images to the request, and the price stays the same. Use image for one picture and images for several; the first is the main image. Say in the prompt what stays and what changes, and with several images what each one is for. Poll the task exactly as in the text-to-image example.

# ─── Image-to-image: 1 to 4 reference images, the first is the main image ──
# Same endpoint, model id and price ($0.02 per image) as text-to-image.
# image for one picture, images for several (image_url / image_urls also work);
# public URLs or base64 data URIs, PNG / JPEG / WebP, up to 10 MB each and 24 MB in total.
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "Use the first image as the base and keep its lighting. Put the ceramic cup from the second image on the wooden table, next to the laptop",
    "images": [
      "https://example.com/desk-scene.jpg",
      "https://example.com/ceramic-cup.png"
    ],
    "aspect_ratio": "3:2"
  }'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-image" } }
# Poll the taskId exactly as in the text-to-image example.

Request parameters

These fields are not supported and return a 400: mask and mask_url (masks / inpainting), resolution: "4K", background: "transparent", negative_prompt and seed. More than 4 reference images also return a 400.

Output size

Each image is about 2.5 megapixels. aspect_ratio or size picks the proportions and the model picks the pixels: the same ratio always comes back at the same native size. There is no 4K and no other resolution tier: size only sets the proportions. A smaller size comes back at the native size, and a size above about 2.6 megapixels (3840x2160, 2048x2048) or resolution "4K" is rejected with a 400 instead of being delivered smaller. The table shows what our 7 test requests on 30 October 2026 returned.

• Images are delivered as JPEG (quality 95) by default; pass output_format: "png" for PNG or output_format: "webp" for WebP. There is no transparent background: background: "transparent" returns a 400.
• Speed: about 35-70 seconds per image in our tests (34-67 s across 7 requests).
• Read the delivered width and height from data.images; in one-call mode, from each item's width / height and the top-level size.
• Result files are deleted after 30 days, so download or re-host them promptly.

What is not supported

• Masks (inpainting): a non-empty mask or mask_url returns a 400. Describe the area to change in the prompt instead.
• More than 4 reference images return a 400; the images in image, image_url, images and image_urls count together.
• n above 1 returns a 400. For several images, send several requests in parallel; each is billed and tracked on its own.
• A size above about 2.6MP (3840x2160, 2048x2048) and resolution "4K" return a 400. There is no 4K; images are about 2.5MP.
• Transparent backgrounds: background: "transparent" returns a 400.
• negative_prompt and seed both return a 400. There is no negative prompt, so describe what you want in prompt; there is no seed, so the same prompt gives a different image each time.
• quality is accepted but has no effect; there are no quality tiers.
• These requests are rejected before a task is created and cost nothing, so a field is never silently ignored in favour of an image that skipped part of your request.

Pricing

You are charged only when an image is delivered; a request rejected with a 400 creates no task and costs nothing. Reference images cost nothing extra. Pricing examples: 10 images = $0.20, 100 images = $2.00.

Errors

Parameter problems come back synchronously as a 400 at creation ({"code": 400, "msg": "..."}): no task is created and nothing is charged. In one-call mode the same errors come back in OpenAI's shape: {"error": {"message": "...", "type": "invalid_request_error"}}. The msg strings below are the current wording; the values in brackets and after got follow your request.

• 401: the API key is missing or invalid.
• 402: the balance does not cover one image ($0.02).
• Failures during generation (content refused by the model, a temporary generation error, a timeout) end in state failed with the reason in data.failMsg, and are not charged. See "Not every request succeeds" above.

Tips

• For text in the image, put the exact words in quotes and say where they go (a sign, a headline, a label). Meta describes Muse Image as rendering text precisely. In one of our tests a chalkboard sign reading "MUSE BOOKS" came out spelled correctly; that is one test, not a guarantee.
• Spell out the composition: where the subject sits, what is in the foreground and background, what goes on the left and right.
• For image-to-image, say what stays and what changes, for example "keep the person and position, change the background to a beach, oil-painting style".
• With several reference images, say what each one is for, for example "use the first image as the base, put the cup from the second image on the table". The first image is the main one, so put the picture you want to keep first.
• Small text in a reference image may not be preserved, and long passages of text in the output are decorative only and can contain typos; if you need exact long copy, set it yourself after generation.
• In image-to-image, if the result should keep the shape of the main image, set aspect_ratio or size to the same proportions as the main image.
• Leave aspect_ratio at auto when the shape does not matter; set it, or size, when the image has to fit a fixed slot (a 21:9 banner, a 9:16 story).
• In one-call mode the request waits until the image is ready (about 35-70 seconds in our tests), so give your HTTP client a timeout of at least 2 minutes.
• For several variations of one prompt, send several requests in parallel.
• Do not assume the pixels from the size you sent; use the actual width and height in data.images for cropping or layout.

Try it in the Playground.

Related