Guida introduttiva a MiniMax H3 Image: text-to-image, modifica con riferimenti multipli, parametri e prezzi

MiniMax H3 Image è il modello di immagini di MiniMax e su HiAPI dispone di due ID di chiamata: minimax-h3-image/text-to-image (text-to-image) e minimax-h3-image/image-to-image (generazione o modifica con 1–16 immagini di riferimento). Questo articolo spiega come scegliere tra i due ID, come compilare i parametri, come si calcola il costo e i dettagli a cui prestare attenzione durante le chiamate.

Come scegliere tra i due ID

• Solo descrizione testuale: usa text-to-image, l'unico campo obbligatorio è prompt (massimo 5000 caratteri).
• Hai delle immagini da usare come riferimento: usa image-to-image, con image_urls obbligatorio aggiuntivo, da 1 a 16 immagini. Puoi cambiare lo scenario partendo da una foto prodotto, ridisegnare una foto in stile illustrazione o pittura a olio, oppure fornire più immagini di riferimento contemporaneamente.
• Il prezzo di generazione è lo stesso per entrambi gli ID; image-to-image applica un costo aggiuntivo in base al numero di immagini di riferimento, vedi «Prezzi» più avanti.

Parametri

• resolution: 1K / 2K / 4K, predefinito 2K. Ad esempio, 2K 1:1 restituisce 2048×2048, 1K 9:16 restituisce 768×1360, 4K 16:9 restituisce 5472×3072.
• aspect_ratio: auto, 1:1, 5:4, 4:5, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9. Per text-to-image il predefinito è 1:1; per image-to-image il predefinito è auto, il modello sceglie la proporzione in base al prompt e alle immagini di riferimento, e non necessariamente coincide con la prima immagine di riferimento — se vuoi un formato fisso, specifica esplicitamente la proporzione.
• output_format: jpeg (predefinito) oppure png. PNG ha dimensioni molto maggiori, un PNG 4K può raggiungere i 30MB; se non ne hai bisogno specifico, usa jpeg.
• seed: facoltativo, da 0 a 2147483647; impostalo fisso per riprodurre la stessa immagine.
• Ogni richiesta genera 1 immagine; non sono supportate larghezza/altezza personalizzate, sfondi trasparenti né inpainting con maschera.

Esempio di chiamata

Invio del task:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image/image-to-image",
    "input": {
      "prompt": "Place the serum bottle on a pale stone pedestal, soft side light, clean e-commerce product shot",
      "image_urls": ["https://example.com/bottle.png"],
      "resolution": "2K",
      "aspect_ratio": "3:4"
    }
  }'

Dopo aver ricevuto data.taskId, esegui il polling su GET https://api.hiapi.ai/v1/tasks/<taskId>. Quando status diventa success, l'indirizzo dell'immagine si trova in data.output[0].url. Le immagini 2K richiedono in genere 30–40 secondi. Il link del risultato ha una scadenza (campo expireAt); se devi conservarlo a lungo, scaricalo e salvalo altrove.

Prezzi

• 1K, 2K: $0.0129 per immagine.
• 4K: $0.0393 per immagine.
• Per image-to-image ogni immagine di riferimento aggiunge $0.0036. Ad esempio 2K con 3 immagini di riferimento: 0.0129 + 3 × 0.0036 = $0.0237.
• L'addebito avviene solo per i task che generano immagini con successo; in caso di fallimento del task è previsto il rimborso completo.

Come scrivere i prompt

• Scrivi in modo chiaro seguendo l'ordine «soggetto + scenario + luce + stile + composizione».
• In image-to-image specifica cosa conservare e cosa modificare, ad esempio «conserva i tratti del viso e la posa della persona, sostituisci lo sfondo con blocchi di grigio caldo, applica complessivamente pennellate a olio».
• Prova prima la composizione con 1K o 2K, poi passa a 4K una volta definita: il prezzo unitario di 4K è circa 3 volte quello di 2K.