Come si usa Muse Image API? Crea la tua prima immagine in 5 minuti

TL;DR

• Muse Image 1.0 è il modello di immagini rilasciato da Meta il 27 agosto 2026; su HiAPI è disponibile con due endpoint: muse-image-1.0/text-to-image (testo-immagine) e muse-image-1.0/image-to-image (modifica immagine, 1–10 immagini di riferimento). Apri la pagina del modello per provarlo online.
• Entrambi gli endpoint costano $0.015 per immagine. Ogni immagine è di circa 2,5 milioni di pixel, senza bisogno di impostare la risoluzione.
• Il modo più rapido per iniziare: POST /v1/tasks passando prompt e aspect_ratio, esegui il polling finché lo stato non è success, poi scarica output[0].url. Occorre controllare sia lo stato fail sia failed.

In cosa eccelle Muse Image?

• Prima pianifica, poi genera. Secondo Meta, Muse Image ragiona sull'immagine prima di disegnarla. All'atto pratico, richieste di impaginazione come «generous negative space» e brevi testi di brand come «DAWN» finiscono correttamente nell'immagine.
• Illustrazioni, poster, visual di prodotto: a $0.015 per immagine, ideale per contenuti in grandi volumi.
• Immagini grandi per impostazione predefinita: circa 2,5 milioni di pixel ciascuna, ad esempio 3:2 ≈ 1920×1280, 1:1 ≈ 1600×1600.
• 8° posto nella classifica testo-immagine di Artificial Analysis.

Una descrizione, un'immagine finita, 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.

Genera con questo prompt → (3:4)

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

Due percorsi per iniziare

Prova online (senza scrivere codice):

1. Apri la pagina testo-immagine o la pagina di modifica immagine e accedi (i nuovi utenti ricevono 200 crediti alla registrazione).
2. Incolla il prompt e scegli il formato. Per la modifica devi caricare da 1 a 10 immagini.
3. Clicca su genera e scarica il risultato.

Chiamata API:

1. Crea una API Key nella console.
2. Esegui POST /v1/tasks indicando come nome modello uno dei due endpoint.
3. Esegui il polling di GET /v1/tasks/{taskId} o ricevi la callback, poi salva output[0].url.

curl: genera la prima immagine

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"
    }
  }'

La risposta contiene data.taskId. Esegui il polling di GET /v1/tasks/{taskId} e, quando status diventa success, scarica output[0].url.

Python: prima genera, poi modifica

# pip install requests; export HIAPI_KEY=la_tua_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):
    # Riutilizza la stessa Idempotency-Key per lo stesso invio ritentato: addebita una sola volta
    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)

# Testo-immagine, immagine di intestazione 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")

# Trasforma la precedente in una scena notturna ($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)

Il link della prima immagine è ancora valido e accessibile pubblicamente, quindi può essere passato direttamente come immagine di riferimento. Per le immagini da conservare a lungo, scaricale prima.

Modificare con immagini di riferimento

muse-image-1.0/image-to-image richiede obbligatoriamente image_urls (1–10 immagini). Assegna un compito a ciascuna immagine: nell'immagine 1 qui sotto prendi il soggetto balena, dall'immagine 2 prendi solo l'impaginazione, e sostituisci tutto il testo vecchio.

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.

Apri la pagina di modifica con questo prompt → (carica le tue due immagini)

muse-image-1.0/image-to-image, due immagini di riferimento, $0.015.

Titolo principale e sottotitolo sono identici parola per parola, ma in fondo Muse ha aggiunto una riga di testo piccolo non richiesta. Quando il testo deve essere preciso, aggiungi «no other text» alla fine del prompt.

Parametri a colpo d'occhio

Campo	Valori	Descrizione
prompt	stringa, obbligatorio, max 5000 caratteri	Descrive l'immagine, oppure specifica cosa cambiare e cosa mantenere
image_urls	1–10 link pubblici	Obbligatorio per l'endpoint di modifica; non serve per l'endpoint testo-immagine
aspect_ratio	1:1 4:3 3:4 16:9 9:16 3:2 2:3 21:9 9:21	Opzionale; se omesso, il modello decide la composizione in base al contenuto dell'immagine
output_format	jpeg / png / webp, predefinito webp	Stesso prezzo per tutti e tre

Non esiste un campo resolution. Ogni immagine è di circa 2,5 milioni di pixel, con larghezza e altezza che variano in base al formato.

Da sapere prima della messa in produzione

• Per i posizionamenti fissi, specifica sempre aspect_ratio. Se lo ometti, decide il modello: va bene in fase esplorativa, ma non per uno spazio banner.
• Controlla sia fail sia failed. La documentazione riporta failed, ma controllare entrambi è più sicuro.
• Usa le callback invece del polling: aggiungi allo stesso livello di input "callback": {"url": "https://your-app.example.com/hiapi/callback"} e deduplica per taskId.
• Salva subito i risultati. output[0].url ha una scadenza: scarica tempestivamente o scegli l'archiviazione permanente alla creazione del task.
• Includi l'header Idempotency-Key: in caso di retry, la stessa Key crea il task una sola volta.

Domande frequenti

Quante immagini genera un task?

1. Per più varianti, invia task separati.

Si possono generare immagini più grandi o più piccole?

No, Muse Image è fisso a circa 2,5 milioni di pixel. Per il 4K scegli FLUX.3 Image o Nano Banana 2.1.

Si può usare l'endpoint di modifica senza immagini di riferimento?

No, l'endpoint di modifica richiede da 1 a 10 immagini. Per partire dal testo usa muse-image-1.0/text-to-image.

Una generazione fallita viene addebitata?

No. Si paga solo per le immagini generate con successo.

Per i prezzi vedi Prezzi Muse Image API, per altri prompt vedi Esempi di prompt per Muse Image, per il confronto con lo stesso prompt vedi Muse Image vs Nano Banana 2.1. Puoi anche andare direttamente alla pagina del modello per generare questa volpe in carta ritagliata.