Blog

Guida all'uso

Guida all'integrazione di Ideogram V3 Character Edit: come preparare immagine sorgente, maschera e immagine di riferimento del personaggio

I tre tipi di input immagine hanno ciascuno il proprio ruolo: invia l'editing locale secondo i campi del contratto e verifica voce per voce la coerenza del personaggio e i bordi

Nov 18, 2026
Immagine di copertina del blog: su uno sfondo verde inchiostro scuro, due gruppi di ampie fasce piatte si intrecciano a formare una trama tecnica, con inserti verticali color ottone, dalla geometria sobria.
In questa pagina

Cosa controlla ciascuno dei tre input immagine

Prima di integrare ideogram-v3-character/edit, separa le responsabilità dei tre campi immagine: tutte le operazioni di preparazione successive diventeranno più chiare.

  • Immagine sorgente image_url: determina «quale scena modificare». Fornisce la composizione originale, lo sfondo e la posizione del soggetto, ed è la base dell'intera operazione di editing.
  • Maschera mask_url: determina «dove modificare». Delimita solo l'area da ridisegnare; il contenuto esterno all'area dovrebbe essere preservato.
  • Immagini di riferimento del personaggio reference_image_urls: determina «che aspetto ha il personaggio». Fornisce i tratti somatici del personaggio, allineando il risultato del ridisegno al personaggio di riferimento.

Non confondere i confini dei tre: l'immagine sorgente non è l'immagine di riferimento del personaggio, e l'immagine di riferimento del personaggio non può sostituire l'immagine sorgente; la maschera è un vincolo spaziale, non una descrizione del contenuto. Affidare i tratti del personaggio all'immagine di riferimento, scrivere il contenuto della scena nel prompt e l'ambito di modifica alla maschera è la suddivisione che riduce al minimo gli errori. Se li si confonde (ad esempio caricando solo l'immagine del personaggio senza maschera, oppure usando la maschera per «suggerire» l'aspetto del personaggio), nella risoluzione dei problemi si perde il criterio di valutazione.

A livello di contratto, l'immagine sorgente e la maschera sono campi URL di tipo stringa, mentre le immagini di riferimento del personaggio sono un campo array: tipi diversi suggeriscono anche usi diversi: i primi due sono una coppia spaziale uno a uno, le seconde una fonte indipendente di descrizione della persona.

I tre input non sono semplicemente affiancati: immagine sorgente, maschera e immagini di riferimento del personaggio controllano ciascuno aree diverse del fotogramma di output; la figura esprime la divisione dei compiti con tre linee convergenti.

Punti chiave nella preparazione di immagine sorgente e maschera

image_url e mask_url sono entrambi campi obbligatori, di formato URI, devono iniziare con http:// o https:// (pattern del contratto ^https?://), lunghezza minima 1.

Le proporzioni devono coincidere

L'unico vincolo geometrico rigido che il contratto impone a entrambi è: la maschera deve avere le stesse proporzioni dell'immagine sorgente. Non è un consiglio ma un presupposto; preparando i materiali, la pratica più sicura è generare prima localmente la maschera con le dimensioni dell'immagine sorgente e poi caricarle insieme, senza contare che sia il server ad allinearle.

Semantica della maschera: delimitare solo l'area da ridisegnare

La maschera indica le posizioni in cui «è consentito ridisegnare». Quindi:

  • le parti da preservare non devono cadere nell'area della maschera;
  • il soggetto da modificare (ad esempio cambio d'abito o di posa) deve ricadere interamente nella maschera, evitando che i bordi vengano tagliati;
  • la maschera non deve essere troppo frammentata: frammenti sparsi rendono difficile al modello comprendere l'intento dell'editing.

Disponibilità degli URL

Entrambi i campi sono URL remoti: prima dell'invio verifica che il link sia accessibile in modo anonimo, che non ci siano reindirizzamenti non funzionanti e che non richieda autenticazione. Per la maschera si consiglia un'immagine con canale trasparente o con contrasto netto bianco/nero, per evitare ambiguità dei bordi causate da gradienti semitrasparenti.

Specifiche e limiti delle immagini di riferimento del personaggio

reference_image_urls è un campo array obbligatorio, con vincoli espliciti nel contratto: minItems: 1, maxItems: 1, ovvero una e una sola immagine. Inviarne due o zero viene considerato input non valido: questo contraddice l'intuizione comune dei «riferimenti multipli» ed è un errore frequente in fase di integrazione.

Formato e dimensione

  • Formati supportati: JPEG, PNG, WebP;
  • dimensione massima per immagine: 10 MB.

Consigli sulla scelta dell'immagine

L'immagine di riferimento del personaggio serve a fornire tratti somatici stabili, quindi:

  1. scegli un'immagine nitida, frontale o quasi frontale, con il volto non coperto;
  2. evita controluce forti, filtri pesanti e foto di gruppo (il modello non può capire a chi allinearsi);
  3. figura intera e mezzobusto hanno compromessi diversi: usa il mezzobusto o più se servono dettagli dell'abbigliamento, la figura intera per l'aspetto complessivo;
  4. non usare immagini con sfondi complessi per «suggerire» la scena: la scena va descritta nel prompt.

Sebbene l'array contenga un solo elemento, va comunque inviato come array: ad esempio racchiudi un singolo URL in un elemento, invece di inserire direttamente la stringa.

Come combinare campi obbligatori e opzionali

I campi obbligatori sono quattro: prompt, image_url, mask_url, reference_image_urls. I parametri opzionali includono expand_prompt, style, seed, rendering_speed.

Il prompt descrive la nuova scena, non è un'istruzione di editing

La definizione di prompt nel contratto è cruciale: «descrive la scena in cui si trova il personaggio di riferimento, ovvero il contenuto dell'immagine da generare con questo editing», lunghezza 1–5000 caratteri. In altre parole, non scrivere istruzioni operative come «cambia il suo vestito con una giacca rossa», ma descrizioni della scena come «è in piedi su una strada dopo la pioggia, indossa una giacca rossa, le luci al neon si riflettono sull'asfalto bagnato». L'ambito dell'editing è compito della maschera; il prompt riguarda il contenuto stesso dell'immagine.

expand_prompt è attivo per impostazione predefinita

expand_prompt è un interruttore booleano, predefinito true: quando attivo, MagicPrompt espande automaticamente il prompt. Ciò significa che la descrizione breve che invii viene rielaborata una volta dal modello. In fase di diagnosi si consiglia di mantenere il valore predefinito e di decidere se disattivarlo solo dopo aver chiarito la differenza tra descrizioni lunghe e risultato dell'espansione.

style e seed

  • L'enumerazione di style è AUTO, REALISTIC, FICTION, predefinito AUTO. Usa REALISTIC per personaggi realistici, FICTION per illustrazioni stilizzate, e lascia AUTO se non sei sicuro.
  • seed è un intero, intervallo da 0 a 2147483647, usato per riprodurre il risultato di generazione dello stesso prompt. Per confrontare «stesso input con parametri diversi», fissare il seed elimina l'interferenza della casualità.

Scelta del livello di rendering_speed

rendering_speed è un'enumerazione di stringhe, predefinita BALANCED, con tre livelli:

  • TURBO: generazione più rapida, adatta alla fase di bozza per verificare rapidamente l'area della maschera e la corrispondenza del personaggio;
  • BALANCED: livello predefinito, compromesso tra velocità e dettaglio, punto di partenza per l'integrazione quotidiana;
  • QUALITY: dettaglio più ricco, adatto ai round di definizione prima della generazione finale.

L'approccio è cambiare livello in base alla fase, non fissarlo una volta per tutte: prima usa TURBO per verificare che geometria e orientamento del personaggio siano corretti, poi passa a BALANCED o QUALITY per rifinire i dettagli. Così, durante le iterazioni di debug, non si perde tempo in rendering di alta qualità.

Da sottolineare: i tre livelli hanno differenze nella modalità di tariffazione (in base al livello di generazione); per i prezzi specifici fai riferimento al pannello prezzi del sito, in questo articolo non si riportano cifre. In fase di diagnosi dei problemi di input immagine, fissare prima il livello predefinito elimina una variabile.

I tre livelli sono come variazioni di densità di una stessa trama: più in alto è la trama, più fitti sono i dettagli e più lenta è la velocità.

Checklist di autoverifica prima dell'invio

Verificando voce per voce secondo il contratto si può bloccare la maggior parte degli errori prima dell'invio:

  • prompt non vuoto e non superiore a 5000 caratteri; il contenuto è una descrizione della scena e non un'istruzione di editing;
  • image_url è un link accessibile in modo anonimo che inizia con http:// o https://;
  • mask_url è anch'esso accessibile e ha proporzioni identiche all'immagine sorgente;
  • reference_image_urls è un array di lunghezza esattamente 1;
  • il formato dell'immagine di riferimento è JPEG/PNG/WebP e la dimensione non supera 10 MB;
  • i campi opzionali sono scritti correttamente e i valori di enumerazione sono corretti (style e rendering_speed usano i valori in maiuscolo elencati nel contratto);
  • se è impostato seed, verifica che sia un intero tra 0 e 2147483647;
  • se expand_prompt è disattivato, verifica che il prompt stesso sia già sufficientemente completo.

Questa checklist è anche il primo passo per la risoluzione dei problemi: se una voce non è soddisfatta, correggi prima l'input invece di ritoccare ripetutamente la descrizione.

Approccio alla diagnosi di deviazioni del personaggio e problemi di bordo

Quando il risultato non è quello atteso, classificare prima il problema e poi intervenire in modo mirato è più efficace che rigenerare l'intera immagine.

Tipo 1: il personaggio non somiglia

Si manifesta con tratti del volto, acconciatura e corporatura che si discostano dall'immagine di riferimento. Direzioni di intervento:

  • sostituisci l'immagine di riferimento: immagine frontale più nitida, illuminazione migliore, soggetto singolo;
  • verifica che l'immagine di riferimento non sia tagliata o troppo compressa;
  • aggiungi nel prompt la descrizione del personaggio (abbigliamento, corporatura, età e carattere) così che testo e immagine si corroborino a vicenda;
  • riduci la complessità della scena, evitando che gli elementi di sfondo rubino i dettagli del personaggio.

Tipo 2: bordi sfocati

Si manifesta con contenuto esterno alla maschera modificato inaspettatamente, oppure con giunzioni e immagini fantasma sui bordi della maschera. Direzioni di intervento:

  • verifica prima che le proporzioni tra immagine sorgente e maschera coincidano rigorosamente;
  • controlla se la maschera include anche le parti da preservare;
  • fai ricadere interamente il soggetto nella maschera, evitando tagli sui bordi;
  • usa bordi della maschera più netti, riducendo le transizioni semitrasparenti.

Non intervenire contemporaneamente sui due tipi di problema: per il problema del personaggio modifica immagine di riferimento e descrizione, per il problema dei bordi modifica maschera e geometria. Cambia una sola variabile alla volta per capire quale ha effetto.

Dagli esempi all'integrazione

Tradurre i requisiti di contratto sopra in un processo significa quattro passi: preparare immagine sorgente e maschera con le stesse proporzioni, scegliere un'immagine di riferimento del personaggio conforme, descrivere la nuova scena con un prompt orientato alla scena, e verificare i campi secondo la checklist prima di inviare.

Il punto di accesso all'integrazione è la pagina del modello; definizioni dei campi e valori di enumerazione fanno fede alla pagina e possono essere confrontati voce per voce con la checklist di questo articolo: pagina del modello Ideogram V3 Character Edit. Solo se i materiali sono preparati correttamente l'ottimizzazione successiva ha senso.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API