Referencia de la API de Muse Image

Límites en resumen

Todo lo que Muse Image acepta y todo lo que no, en una sola tabla. Revísala antes de construir sobre el modelo: texto a imagen, o imagen a imagen con 1 a 4 imágenes de referencia; una imagen por petición, unos 2.5MP, sin 4K y sin máscaras.

Los valores y campos no admitidos devuelven un 400 antes de crear la tarea y no cuestan nada (la única excepción es quality, que se acepta y se ignora); los mensajes exactos están en Errores, más abajo.

No todas las peticiones tienen éxito

Texto a imagen e imagen a imagen

Un único id de modelo y un único endpoint; el modo depende de si envías imágenes de referencia. Los dos cuestan lo mismo: $0.02 por imagen.

Pon una imagen de referencia en image (o image_url) y varias en images (o image_urls); si envías ambos, la imagen suelta va primero y el total es de 4 como máximo. Cada imagen es una URL pública o un data URI en base64, en PNG, JPEG o WebP, de hasta 10 MB cada una y 24 MB en total. No hay máscaras: describe en el prompt la zona que quieres cambiar.

Autenticación

Authorization: Bearer YOUR_API_KEY

Inicio rápido

Texto a imagen

# ─── 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" }

Por defecto la llamada es asíncrona: crea una tarea para obtener un taskId y consulta GET /v1/images/generations?task_id= hasta que state sea completed; la imagen está en data.resultUrls y su ancho y alto reales en data.images. Con failed, el motivo está en data.failMsg y no se cobra nada. En nuestras pruebas cada imagen tardó unos 35-70 segundos, así que basta con consultar cada 5 segundos. Para recibir la imagen en una sola llamada, pasa un size al estilo OpenAI y no pases callback_url: la petición queda abierta hasta que la imagen esté lista y la respuesta es { created, data: [{ b64_json, url, width, height }], size }; con "response_format": "url" se omite la copia en base64. images.generate del SDK de OpenAI recibe esa misma respuesta en una sola llamada.

Imagen a imagen (de 1 a 4 imágenes de referencia)

Mismo id de modelo y mismo endpoint: añade imágenes de referencia a la petición y el precio no cambia. Usa image para una imagen e images para varias; la primera es la principal. Indica en el prompt qué se mantiene y qué cambia y, con varias imágenes, para qué sirve cada una. Consulta la tarea igual que en el ejemplo de texto a imagen.

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

Parámetros de la petición

Estos campos no están admitidos y devuelven un 400: mask y mask_url (máscaras / inpainting), resolution: "4K", background: "transparent", negative_prompt y seed. Más de 4 imágenes de referencia también devuelven un 400.

Tamaño de salida

Cada imagen tiene unos 2.5 megapíxeles. aspect_ratio o size eligen las proporciones y el modelo elige los píxeles: la misma proporción siempre vuelve con el mismo tamaño nativo. No hay 4K ni ningún otro nivel de resolución: size solo fija las proporciones. Un size más pequeño vuelve al tamaño nativo, y un size de más de unos 2.6 megapíxeles (3840x2160, 2048x2048) o resolution "4K" se rechaza con un 400 en lugar de entregarse más pequeño. La tabla muestra lo que devolvieron nuestras 7 peticiones de prueba del 30 de octubre de 2026.

• Las imágenes se entregan en JPEG (calidad 95) por defecto; pasa output_format: "png" para PNG u output_format: "webp" para WebP. No hay fondo transparente: background: "transparent" devuelve un 400.
• Velocidad: unos 35-70 segundos por imagen en nuestras pruebas (34-67 s en 7 peticiones).
• Lee el ancho y el alto entregados en data.images; en el modo de una sola llamada, en width / height de cada elemento y en el size de nivel superior.
• Los archivos de resultado se borran a los 30 días, así que descárgalos o guárdalos en otro sitio a tiempo.

Lo que no está admitido

• Máscaras (inpainting): un mask o mask_url no vacío devuelve un 400. Describe en el prompt la zona que quieres cambiar.
• Más de 4 imágenes de referencia devuelven un 400; las de image, image_url, images e image_urls cuentan juntas.
• n mayor que 1 devuelve un 400. Para varias imágenes, envía varias peticiones en paralelo; cada una se factura y se consulta por separado.
• Un size de más de unos 2.6MP (3840x2160, 2048x2048) y resolution "4K" devuelven un 400. No hay 4K; las imágenes tienen unos 2.5MP.
• Fondos transparentes: background: "transparent" devuelve un 400.
• negative_prompt y seed devuelven un 400. No hay prompt negativo, así que describe en prompt lo que quieres; no hay seed, así que el mismo prompt da una imagen distinta cada vez.
• quality se acepta pero no tiene efecto; no hay niveles de calidad.
• Estas peticiones se rechazan antes de crear la tarea y no cuestan nada, así que ningún campo se ignora en silencio para entregarte una imagen que se saltó parte de tu petición.

Precios

Solo se cobra cuando se entrega una imagen; una petición rechazada con un 400 no crea tarea y no cuesta nada. Las imágenes de referencia no cuestan nada extra. Ejemplos de precio: 10 imágenes = $0.20, 100 imágenes = $2.00.

Errores

Los problemas de parámetros vuelven de forma síncrona como un 400 al crear la tarea ({"code": 400, "msg": "..."}): no se crea ninguna tarea y no se cobra nada. En el modo de una sola llamada, los mismos errores llegan con el formato de OpenAI: {"error": {"message": "...", "type": "invalid_request_error"}}. Los textos de msg de abajo son la redacción actual; los valores entre paréntesis y tras got dependen de tu petición.

• 401: falta la clave API o no es válida.
• 402: el saldo no cubre una imagen ($0.02).
• Los fallos durante la generación (contenido rechazado por el modelo, un error temporal de generación, tiempo agotado) terminan en state failed con el motivo en data.failMsg, y no se cobran. Consulta "No todas las peticiones tienen éxito", más arriba.

Consejos

• Si quieres texto en la imagen, pon las palabras exactas entre comillas y di dónde van (un letrero, un titular, una etiqueta). Meta describe Muse Image como un modelo que renderiza el texto con precisión. En una de nuestras pruebas, un letrero de pizarra con "MUSE BOOKS" salió bien escrito; es una sola prueba, no una garantía.
• Describe la composición: dónde está el sujeto, qué hay en primer plano y en el fondo, qué va a la izquierda y a la derecha.
• En imagen a imagen, di qué se mantiene y qué cambia, por ejemplo "mantén a la persona y su posición, cambia el fondo por una playa, estilo pintura al óleo".
• Con varias imágenes de referencia, di para qué sirve cada una, por ejemplo "usa la primera imagen como base y pon la taza de la segunda imagen sobre la mesa". La primera es la imagen principal, así que pon primero la que quieres conservar.
• El texto pequeño de una imagen de referencia puede no conservarse, y los pasajes largos de texto en el resultado son solo decorativos y pueden tener erratas; si necesitas un texto largo exacto, colócalo tú después de generar la imagen.
• En imagen a imagen, si el resultado debe conservar la forma de la imagen principal, fija aspect_ratio o size con sus mismas proporciones.
• Deja aspect_ratio en auto cuando la forma no importe; fíjalo, o usa size, cuando la imagen tenga que encajar en un espacio fijo (un banner 21:9, una historia 9:16).
• En el modo de una sola llamada la petición espera hasta que la imagen esté lista (unos 35-70 segundos en nuestras pruebas), así que dale a tu cliente HTTP un tiempo de espera de al menos 2 minutos.
• Para varias variaciones del mismo prompt, envía varias peticiones en paralelo.
• No supongas los píxeles a partir del size que enviaste; usa el ancho y el alto reales de data.images para recortar o maquetar.

Pruébalo en el Playground.

Relacionado