Como usar a Muse Image API? Gere sua primeira imagem em 5 minutos

TL;DR

• Muse Image 1.0 é um modelo de imagem lançado pela Meta em 27 de agosto de 2026, com dois endpoints na HiAPI: muse-image-1.0/text-to-image (texto para imagem) e muse-image-1.0/image-to-image (edição de imagem, 1–10 imagens de referência). Abra a página do modelo para testar online.
• Os dois endpoints custam $0.015 por imagem. Cada imagem tem cerca de 2,5 milhões de pixels; não é preciso definir resolução.
• O jeito mais rápido de ajustar: POST /v1/tasks com prompt e aspect_ratio, fazer polling até success e baixar output[0].url. Os estados de falha fail e failed precisam ser verificados.

Para que a Muse Image é boa?

• Planeja antes de gerar. A Meta diz que a Muse Image pensa na cena com clareza antes de desenhar. Na prática, requisitos de layout como "generous negative space" e marcas curtas como "DAWN" aparecem na imagem.
• Ilustração, pôster, visual de produto, a $0.015 por imagem, ideal para conteúdo em grande volume.
• Já vem em alta resolução por padrão: cerca de 2,5 milhões de pixels por imagem, por exemplo 3:2 em torno de 1920×1280 e 1:1 em torno de 1600×1600.
• 8º lugar no ranking de text-to-image do Artificial Analysis.

Uma descrição, uma imagem pronta, 3:4:

Editorial paper-cut illustration of a coral fox curled beneath a midnight-blue
tree, scattered warm stars, layered tactile paper edges, clear silhouette and
generous negative space, quiet book-cover composition, no text.

Gerar com este prompt → (3:4)

muse-image-1.0/text-to-image, 3:4, $0.015.

Dois caminhos para começar

Teste online (sem programar):

1. Abra a página de texto para imagem ou a página de edição de imagem e faça login (novos usuários ganham 200 créditos ao se cadastrar).
2. Cole o prompt e escolha a proporção. Para edição, envie de 1 a 10 imagens.
3. Clique em gerar e baixe o resultado.

Chamada de API:

1. Crie uma API Key no console.
2. Faça POST /v1/tasks com um dos dois nomes de modelo.
3. Faça polling em GET /v1/tasks/{taskId} ou receba callback e salve output[0].url.

curl: gere a primeira imagem

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image-1.0/text-to-image",
    "input": {
      "prompt": "Editorial paper-cut illustration of a coral fox curled beneath a midnight-blue tree, warm stars, generous negative space, no text",
      "aspect_ratio": "3:4",
      "output_format": "png"
    }
  }'

A resposta contém data.taskId. Faça polling em GET /v1/tasks/{taskId} e, quando status virar success, baixe output[0].url.

Python: primeiro gerar, depois editar

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

# 文生图，16:9 头图（$0.015）
header = run("muse-image-1.0/text-to-image",
             prompt="A sophisticated editorial illustration of a terracotta desert observatory under an oversized pale moon, winding turquoise river, no text",
             aspect_ratio="16:9", output_format="png")

# 把上一张改成夜景（$0.015）
night = run("muse-image-1.0/image-to-image",
            prompt="Turn the illustration into night: deep indigo sky, silver crescent moon, warm amber windows. Keep the buildings and river.",
            image_urls=[header], aspect_ratio="16:9", output_format="png")

with open("night.png", "wb") as f:
    f.write(requests.get(night).content)

O link da primeira imagem ainda está dentro da validade e pode ser acessado publicamente, então pode ser passado diretamente como imagem de referência. Imagens que precisam ser mantidas a longo prazo devem ser baixadas e salvas primeiro.

Editar imagens com referências

muse-image-1.0/image-to-image exige image_urls (1–10 imagens). Dê uma função a cada imagem: abaixo, a imagem 1 fornece o corpo da baleia, a imagem 2 empresta apenas o layout, e todo o texto antigo é substituído.

Design a polished illustrated travel poster using the indigo whale and warm
stars from Image 1 as the central artwork. Borrow the cream paper, forest-green
framing and clean heading hierarchy from Image 2. Replace all old poster text
with a single large heading SEABOUND at the top and the smaller line STORIES
UNDER THE STARS below. Keep the whale recognizable, use balanced spacing and
delicate layered paper detail.

Abrir a página de edição com este prompt → (envie suas duas imagens)

muse-image-1.0/image-to-image, duas imagens de referência, $0.015.

O título principal e o subtítulo saíram exatamente iguais, mas a Muse acrescentou uma linha extra de texto pequeno no rodapé que não foi solicitada. Quando o texto precisa ser exato, adicione "no other text" ao final do prompt.

Referência rápida de parâmetros

Campo	Valores	Descrição
prompt	string, obrigatório, até 5000 caracteres	Descreva a cena ou especifique o que deve ser alterado e o que deve ser mantido
image_urls	1–10 links públicos	Obrigatório no endpoint de edição; não usado no de texto para imagem
aspect_ratio	1:1 4:3 3:4 16:9 9:16 3:2 2:3 21:9 9:21	Opcional; se omitido, o modelo define a composição conforme o conteúdo da cena
output_format	jpeg / png / webp, padrão webp	Os três têm o mesmo preço

Não existe o campo resolution. Cada imagem tem cerca de 2,5 milhões de pixels, e a largura e a altura variam conforme a proporção.

Atenção antes de ir para produção

• Sempre defina aspect_ratio em posições fixas. Se não definir, o modelo decide; isso serve para exploração, mas não para um espaço de banner.
• Verifique tanto fail quanto failed. A documentação menciona failed, mas verificar os dois é mais seguro.
• Use callback em vez de polling: adicione "callback": {"url": "https://your-app.example.com/hiapi/callback"} no mesmo nível de input e deduplique por taskId.
• Salve o resultado imediatamente. output[0].url tem validade; baixe a tempo ou escolha armazenamento permanente ao criar a tarefa.
• Inclua o cabeçalho Idempotency-Key; em retentativas, a mesma Key cria a tarefa apenas uma vez.

Perguntas frequentes

Quantas imagens são geradas por tarefa?

1 imagem. Para várias direções, envie tarefas separadas.

É possível gerar imagens maiores ou menores?

Não, a Muse Image tem tamanho fixo de cerca de 2,5 milhões de pixels. Para 4K, escolha FLUX.3 Image ou Nano Banana 2.1.

Posso usar o endpoint de edição sem enviar imagens de referência?

Não, o endpoint de edição exige de 1 a 10 imagens. Para começar a partir de texto, use muse-image-1.0/text-to-image.

Falhas na geração são cobradas?

Não. Só há cobrança quando a imagem é gerada com sucesso.

Veja os preços em Preços da Muse Image API, mais exemplos de prompts em Exemplos de prompts da Muse Image, e a comparação com o mesmo prompt em Muse Image vs Nano Banana 2.1. Você também pode gerar esta raposa de papel na página do modelo.