Vai al contenuto

API Mage · Generazione di immagini

L'API di intelligenza artificiale per generare immagini con ogni modello

Da testo a immagine, modifica di immagini e personaggi coerenti con 18 modelli, incluso Mango 4, il modello di punta di Mage, con una sola chiave e un solo saldo.

POST https://api.mage.space/v1/{model}/generate

In breve

L'API di generazione di immagini di Mage è un'API REST su https://api.mage.space/v1 che esegue 18 modelli da testo a immagine e di modifica immagini, tra cui Mango 4, Guava 2 Pro, GPT Image 2.6, Nano Banana 2, Flux 2 e Krea 2. Invii un prompt con POST a /{model}/generate, controlli lo stato della richiesta e scarichi l'immagine. Ogni immagine si paga in Gems, senza abbonamento.

  • 18modelli di immagini
  • $0.009Prezzo predefinito più basso, per immagine
  • 20Generazioni simultanee
  • $0Costo mensile

Modelli

Tutti i modelli di immagini nell'API di Mage

I prezzi sono per generazione, in Gems. 1.000 Gems costano 1 $ con il pacchetto standard, e i pacchetti più grandi aggiungono Gems bonus. Il prezzo dipende da modello, risoluzione e durata; qui è mostrato il prezzo con le impostazioni predefinite, e ogni risposta indica l'addebito esatto in billing.gems_charged. Una generazione non riuscita viene rimborsata; una bloccata dalla content policy di Mage no.

ModelloIdeale perValori di model_idPrezzo predefinito
AnimaCreato apposta per l'animeanima-v120 Gems ($0.02)
ChromaOpen-weights, basato su Fluxchroma-v1-hd35 Gems ($0.035)
Flux 2Prompt lunghi e modifiche con più riferimentiflux2-dev40 Gems ($0.04)
GPT Image 2Prompt precisi e testo leggibilegpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2.6-flare, gpt-image-2.6-sunburst9 Gems ($0.009)
Grok ImageGrok Imagine, in due livelligrok-imagine-image, grok-imagine-image-2.090 Gems ($0.09)
GuavaFotorealismo che sembra una fotografiaguava, guava-pro, guava-pro-v1-5, guava-2, guava-2-pro37 Gems ($0.037)
HiDreamVeloce e versatile, con prompt negativihidream-fast20 Gems ($0.02)
Krea 2Estetica splendida in pochi secondikrea-2-turbo20 Gems ($0.02)
MangoLa nostra famiglia di modelli di immagini di puntamango, mango-v2, mango-v3s, mango-v3, mango-v3-turbo, mango-v442 Gems ($0.042)
MiniMax H3 ImageImmagini native da 16 megapixel, pesi apertiminimax-h3-image15 Gems ($0.015)
MOSS-ImagePrompt lunghi e testo bilingue, pesi apertimoss-image25 Gems ($0.025)
Nano Banana 2Testo nitido e leggibile, fino a 4Knano-banana-v2, nano-banana-v2.151 Gems ($0.051)
SDXL PlusSDXL con volti e mani corretti6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8015 Gems ($0.015)
SeedreamSeedream, con filtro rigorososeedream-4.0, seedream-4.5, seedream-5.0-lite, seedream-5.0-pro, seedream-5.0-flash, seedream-5.542 Gems ($0.042)
Stable Diffusion v1.5Il classico, a basso costo15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D10 Gems ($0.01)
Stable Diffusion v3.5 LargeLo Stable Diffusion che ascolta megliosd-3-5-large10 Gems ($0.01)
Stable Diffusion XLSDXL ottimizzato per il fotorealismo6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8010 Gems ($0.01)
Z-ImageIl modello di immagini più veloce di Magez-image-turbo10 Gems ($0.01)

Guida rapida

Genera un'immagine con Anima v1

Imposta MAGE_API_KEY, invia la richiesta e controlla lo stato finché non è completata. Sostituisci anima nell'URL con uno qualsiasi dei modelli qui sopra.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/anima/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Editorial portrait in soft daylight, 35mm film look",
  "aspect_ratio": "4:5",
  "model_id": "anima-v1"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('anima', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'anima-v1',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("anima", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "anima-v1",
})

print(request["result"]["url"])

Come funziona

Dalla chiave API al media finito in tre chiamate

Tutti i modelli condividono un unico schema di autenticazione, un unico ciclo di vita asincrono delle richieste e gli stessi nomi dei campi.

  1. Crea una chiave API

    Accedi a Mage, apri API → API Keys e crea una chiave. Inizia con mage_sk_ e viene mostrata una sola volta. Un account può avere 10 chiavi attive.

  2. Invia una generazione

    Invia con POST un corpo JSON a https://api.mage.space/v1/{model}/generate con un header Authorization: Bearer. La risposta arriva subito con un request_id, uno status e uno status_url. Aggiungi un header Idempotency-Key così un nuovo tentativo non ti farà mai pagare due volte.

  3. Controlla lo stato e scarica

    Interroga status_url finché lo stato non è completed, failed o cancelled. Una richiesta completata contiene result.url con il file di immagine, video o audio, conservato per 30 giorni.

Pensata per la produzione

Cosa ottiene ogni richiesta all'API di Mage

  • Una chiave, tutti i modelli

    37 modelli per immagini, video e audio dietro una sola API REST e un solo saldo di Gems. Cambi modello modificando il percorso dell'URL.

  • Paghi per generazione

    Nessun abbonamento e nessuna spesa minima. Acquisti Gems e ogni richiesta costa il prezzo indicato. Se una generazione fallisce, ti viene rimborsata, a meno che non sia stata bloccata dalla content policy di Mage.

  • Nuovi tentativi sicuri

    Con le chiavi di idempotenza, un nuovo invio restituisce la richiesta originale senza addebitarti di nuovo.

  • Personaggi coerenti

    Salva un personaggio o un riferimento una volta sola, poi scrivi @handle in qualsiasi prompt per usarlo con tutti i modelli che lo supportano.

  • File di grandi dimensioni

    Invia input di immagini, video e audio come URL o data URL, oppure carica file fino a 100 MB con un upload firmato.

  • 20 generazioni in parallelo

    Ogni account può eseguire 20 generazioni contemporaneamente e il limite può essere aumentato in base alle tue esigenze. Le richieste rifiutate non vengono mai addebitate.

Casi d'uso

Cosa creano gli sviluppatori con l'API di immagini

  • Immagini per prodotti e marketing

    Crea al volo foto di prodotto, varianti di annunci e post per i social, con testo leggibile grazie a GPT Image 2.6 o Nano Banana 2.

  • Personaggi coerenti

    Salva un personaggio una volta e mantieni lo stesso volto in un'intera serie con Mango 4, Guava 2 Pro e altri modelli che supportano le menzioni @handle.

  • Pipeline di editing delle immagini

    Invia un'immagine di partenza con un'istruzione per cambiare esattamente ciò che chiedi e lasciare invariato il resto.

  • App e giochi

    Genera avatar, sticker, carte e scene dentro il tuo prodotto senza ospitare nemmeno una GPU.

  • Ritratti fotorealistici

    Guava 2 Pro crea ritratti, scatti di moda e lifestyle con pelle, tessuti e luce fedeli alla realtà.

  • Bozze veloci su larga scala

    Z-Image Turbo e Krea 2 tengono i prezzi bassi per miniature e prime versioni in grandi volumi.

FAQ

Domande frequenti

Qual è la migliore API per generare immagini con l'IA?
Dipende dal lavoro. Su Mage, Mango 4 è la scelta predefinita per la maggior parte delle immagini: segue istruzioni precise, mantiene la coerenza dei personaggi e modifica senza toccare il resto dell'immagine. Guava 2 Pro è ideale per il fotorealismo, GPT Image 2.6 e Nano Banana 2 per il testo nelle immagini, Z-Image Turbo o Krea 2 per bozze veloci ed economiche. Tutti funzionano con la stessa API.
L'API per le immagini supporta l'editing e le immagini di riferimento?
Sì. I modelli che accettano immagini le ricevono nei campi image e additional_images come URL, data URL o upload. La pagina di ogni modello elenca i suoi input e quante immagini di riferimento accetta.
Quali risoluzioni supporta l'API per le immagini?
Dipende dal modello: 1K e 2K sulla maggior parte dei modelli, 3K su Mango 3S e fino a 4K su Mango 2 e Nano Banana 2. La pagina di ogni modello elenca le opzioni di risoluzione e proporzioni.
Quanto costa l'API di Mage?
Non ci sono abbonamenti né canoni mensili. Ogni generazione si paga in Gems al prezzo indicato per il suo modello, e 1.000 Gems costano 1 $ con il pacchetto standard. La pagina di ogni modello riporta il prezzo con le impostazioni predefinite e ogni risposta indica l'addebito esatto. Se una generazione fallisce, viene rimborsata; se la blocca la content policy di Mage, no. Una richiesta che il tuo saldo non copre viene rifiutata prima di qualsiasi addebito.
Mi serve un abbonamento a Mage per usare l'API?
No. L'API funziona solo con i Gem. I piani di abbonamento e la generazione illimitata nell'app non valgono per le richieste API. L'account deve prima aver effettuato un pagamento andato a buon fine, con un pacchetto di Gem o un piano qualsiasi; i Gem bonus di registrazione funzionano solo nell'app di Mage.
Posso usare a fini commerciali i contenuti generati con l'API?
Sì. I contenuti che crei con Mage, anche tramite l'API e il server MCP, possono essere usati a fini commerciali. L'attribuzione è gradita ma non obbligatoria.
Quali sono i limiti di richieste?
Un account può avere fino a 20 generazioni in coda o in corso contemporaneamente. Un invio oltre questo limite viene rifiutato con errore 429 e non costa nulla. Scrivi a [email protected] per aumentare il limite in base al tuo caso d'uso.
Il mio agente AI può usare l'API di Mage?
Sì. Gli agenti possono chiamare l'API REST con una chiave oppure collegarsi al server MCP di Mage, che offre a Claude, ChatGPT, Claude Code, Grok e Cursor sedici strumenti già pronti per scegliere un modello, calcolare il prezzo, generare e recuperare il risultato. Vedi il server MCP.
Esiste un SDK per l'API di Mage?
Sì. Il pacchetto ufficiale @mage-space/sdk su npm e mage-space su PyPI sono open source e tipizzati per ogni modello. Inviano la richiesta, attendono il risultato, riprovano in sicurezza e caricano i file per te. Chi usa ComfyUI può installare il pacchetto di nodi comfyui-mage. Vedi gli SDK di Mage.
Uso già un'altra API di generazione. Cosa devo cambiare?
Punta il tuo client a https://api.mage.space/v1, invia la tua chiave Mage come Bearer token e associa i tuoi campi a quelli della pagina del modello: prompt, aspect_ratio, resolution, duration e model_id funzionano allo stesso modo su tutti i modelli Mage. Le richieste sono asincrone: invia la richiesta e poi interroga status_url a intervalli regolari.

Inizia a creare con Mage

Un solo account, un solo saldo di Gems, tutti i modelli. Paghi solo ciò che generi.

CharactersCommunity