Referência da API do Muse Image

Limites em resumo

Tudo o que o Muse Image aceita e tudo o que não aceita, numa única tabela. Confira antes de integrar o modelo: texto para imagem, ou imagem para imagem com 1 a 4 imagens de referência; uma imagem por requisição, cerca de 2.5MP, sem 4K e sem máscaras.

Valores e campos não suportados retornam 400 antes de a tarefa ser criada e não custam nada (a única exceção é quality, que é aceito e ignorado); as mensagens exatas estão em Erros, mais abaixo.

Nem toda requisição tem sucesso

Texto para imagem e imagem para imagem

Um único id de modelo e um único endpoint; o modo depende de você enviar ou não imagens de referência. Os dois custam o mesmo: $0.02 por imagem.

Coloque uma imagem de referência em image (ou image_url) e várias em images (ou image_urls); se enviar os dois, a imagem avulsa vem primeiro, e o total é de no máximo 4. Cada imagem é uma URL pública ou um data URI em base64, em PNG, JPEG ou WebP, com até 10 MB cada e 24 MB no total. Não há máscaras: descreva no prompt a área que deve mudar.

Autenticação

Authorization: Bearer YOUR_API_KEY

Início rápido

Texto para imagem

# ─── 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 padrão a chamada é assíncrona: crie uma tarefa para obter um taskId e consulte GET /v1/images/generations?task_id= até state ser completed; a imagem está em data.resultUrls e a largura e a altura reais em data.images. Em failed, o motivo está em data.failMsg e nada é cobrado. Nos nossos testes cada imagem levou cerca de 35-70 segundos, então consultar a cada 5 segundos é suficiente. Para receber a imagem numa única chamada, passe um size no estilo OpenAI e não passe callback_url: a requisição fica aberta até a imagem ficar pronta, e a resposta é { created, data: [{ b64_json, url, width, height }], size }; "response_format": "url" omite a cópia em base64. O images.generate do SDK da OpenAI recebe essa mesma resposta numa única chamada.

Imagem para imagem (de 1 a 4 imagens de referência)

Mesmo id de modelo e mesmo endpoint: acrescente imagens de referência à requisição, e o preço continua o mesmo. Use image para uma imagem e images para várias; a primeira é a principal. Diga no prompt o que fica e o que muda e, com várias imagens, para que serve cada uma. Consulte a tarefa exatamente como no exemplo de texto para imagem.

# ─── 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 da requisição

Estes campos não são suportados e retornam 400: mask e mask_url (máscaras / inpainting), resolution: "4K", background: "transparent", negative_prompt e seed. Mais de 4 imagens de referência também retornam 400.

Tamanho de saída

Cada imagem tem cerca de 2.5 megapixels. aspect_ratio ou size escolhem as proporções e o modelo escolhe os pixels: a mesma proporção sempre volta no mesmo tamanho nativo. Não existe 4K nem qualquer outro nível de resolução: size só define as proporções. Um size menor volta no tamanho nativo, e um size acima de cerca de 2.6 megapixels (3840x2160, 2048x2048) ou resolution "4K" é recusado com 400 em vez de ser entregue menor. A tabela mostra o que nossos 7 pedidos de teste de 30 de outubro de 2026 devolveram.

• As imagens são entregues em JPEG (qualidade 95) por padrão; passe output_format: "png" para PNG ou output_format: "webp" para WebP. Não há fundo transparente: background: "transparent" retorna 400.
• Velocidade: cerca de 35-70 segundos por imagem nos nossos testes (34-67 s em 7 requisições).
• Leia a largura e a altura entregues em data.images; no modo de chamada única, em width / height de cada item e no size de nível superior.
• Os arquivos de resultado são apagados após 30 dias, então baixe ou hospede-os em outro lugar a tempo.

O que não é suportado

• Máscaras (inpainting): um mask ou mask_url não vazio retorna 400. Descreva no prompt a área que deve mudar.
• Mais de 4 imagens de referência retornam 400; as de image, image_url, images e image_urls contam juntas.
• n maior que 1 retorna 400. Para várias imagens, envie várias requisições em paralelo; cada uma é cobrada e consultada separadamente.
• Um size acima de cerca de 2.6MP (3840x2160, 2048x2048) e resolution "4K" retornam 400. Não existe 4K; as imagens têm cerca de 2.5MP.
• Fundos transparentes: background: "transparent" retorna 400.
• negative_prompt e seed retornam 400. Não há prompt negativo, então descreva no prompt o que você quer; não há seed, então o mesmo prompt gera uma imagem diferente a cada vez.
• quality é aceito, mas não tem efeito; não há níveis de qualidade.
• Essas requisições são recusadas antes de a tarefa ser criada e não custam nada, então nenhum campo é ignorado em silêncio para entregar uma imagem que deixou de lado parte do seu pedido.

Preços

A cobrança só acontece quando uma imagem é entregue; uma requisição recusada com 400 não cria tarefa e não custa nada. Imagens de referência não custam nada a mais. Exemplos de preço: 10 imagens = $0.20, 100 imagens = $2.00.

Erros

Problemas de parâmetro voltam de forma síncrona como 400 na criação ({"code": 400, "msg": "..."}): nenhuma tarefa é criada e nada é cobrado. No modo de chamada única, os mesmos erros voltam no formato da OpenAI: {"error": {"message": "...", "type": "invalid_request_error"}}. Os textos de msg abaixo são a redação atual; os valores entre parênteses e depois de got dependem da sua requisição.

• 401: a chave de API está ausente ou é inválida.
• 402: o saldo não cobre uma imagem ($0.02).
• Falhas durante a geração (conteúdo recusado pelo modelo, um erro temporário de geração, tempo esgotado) terminam em state failed com o motivo em data.failMsg, e não são cobradas. Veja "Nem toda requisição tem sucesso", mais acima.

Dicas

• Para ter texto na imagem, coloque as palavras exatas entre aspas e diga onde ficam (uma placa, um título, um rótulo). A Meta descreve o Muse Image como um modelo que renderiza texto com precisão. Num dos nossos testes, uma placa de lousa com "MUSE BOOKS" saiu escrita corretamente; é um único teste, não uma garantia.
• Descreva a composição: onde fica o assunto, o que está em primeiro plano e ao fundo, o que vai à esquerda e à direita.
• Em imagem para imagem, diga o que fica e o que muda, por exemplo "mantenha a pessoa e a posição, troque o fundo por uma praia, estilo pintura a óleo".
• Com várias imagens de referência, diga para que serve cada uma, por exemplo "use a primeira imagem como base e coloque a xícara da segunda imagem sobre a mesa". A primeira é a imagem principal, então coloque primeiro a que você quer manter.
• Texto pequeno numa imagem de referência pode não ser preservado, e trechos longos de texto no resultado são só decorativos e podem ter erros de digitação; se precisar de um texto longo exato, aplique-o você mesmo depois de gerar a imagem.
• Em imagem para imagem, se o resultado precisar manter o formato da imagem principal, defina aspect_ratio ou size com as mesmas proporções dela.
• Deixe aspect_ratio em auto quando o formato não importar; defina-o, ou use size, quando a imagem precisar caber num espaço fixo (um banner 21:9, um story 9:16).
• No modo de chamada única a requisição espera até a imagem ficar pronta (cerca de 35-70 segundos nos nossos testes), então configure o timeout do seu cliente HTTP para pelo menos 2 minutos.
• Para várias variações do mesmo prompt, envie várias requisições em paralelo.
• Não presuma os pixels a partir do size enviado; use a largura e a altura reais de data.images para recortar ou diagramar.

Teste no Playground.

Relacionado