Come si usa l'API Ideogram 3.0 Character? Crea la tua prima immagine di un personaggio in 5 minuti

TL;DR

• Ideogram 3.0 Character è un modello di generazione di personaggi da immagine di riferimento: carichi 1 immagine di riferimento del personaggio, scrivi un prompt di scena e lo stesso volto e lo stesso abbigliamento compaiono nella nuova scena. Apri la pagina del modello per provarlo online: i nuovi utenti ricevono 200 crediti alla registrazione.
• Il prezzo è per immagine: TURBO $0.09, BALANCED $0.13, QUALITY $0.18; l'immagine di riferimento è gratuita e i fallimenti non vengono addebitati (dettagli nella pagina dei prezzi).
• Le chiamate passano dall'endpoint HiAPI /v1/tasks: invii il task e ottieni un taskId, poi lo usi per interrogare il risultato e, in caso di successo, scarichi l'immagine da output[0].url.

Cosa può fare

• Generazione con coerenza del personaggio: un'immagine di riferimento blocca il personaggio, con volto e abbigliamento coerenti, mentre la scena cambia liberamente.
• Illustrazione e fotorealismo: style può essere AUTO / REALISTIC / FICTION, adatto sia a personaggi fotografici sia a personaggi illustrati.
• Formato che segue l'immagine di riferimento: un riferimento verticale produce 3:4 (864×1152), uno orizzontale produce 16:9 (1328×752); non serve specificare parametri di dimensione.
• Endpoint di modifica dedicato: ideogram-v3-character/edit usa una maschera per inserire il personaggio in un'area specifica di un'immagine esistente, lasciando invariato il resto.

Quella qui sotto è un risultato reale (immagine di riferimento: un personaggio illustrato in formato orizzontale):

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(In italiano: questo personaggio esploratore cammina in un mercato notturno pieno di lanterne, tiene in mano un bicchiere di carta con noodles caldi, ai lati bancarelle dalla luce calda, stile illustrazione da libro di fiabe, niente testo, niente insegne.)

ideogram-v3-character, TURBO, 16:9, 1328×752, $0.09.

Genera con questo prompt →

Come scegliere tra i due endpoint

	ideogram-v3-character	ideogram-v3-character/edit
Cosa fa	Genera da zero una nuova scena con il personaggio	Disegna il personaggio nell'area mascherata di un'immagine esistente
Input obbligatori	prompt + 1 immagine di riferimento	prompt + immagine originale + maschera + 1 immagine di riferimento
Prezzo (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
Output	WebP, formato che segue l'immagine di riferimento	WebP, dimensioni che seguono l'immagine originale
Ideale per	Poster, seriali, immagini di scene in serie	Sostituire o aggiungere personaggi su immagini finite

Convenzione della maschera: nero = ridisegna, bianco = mantieni; il rapporto d'aspetto della maschera deve essere identico a quello dell'immagine originale. L'endpoint di modifica non accetta negative_prompt: se lo passi restituisce 400.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → carica l'immagine di riferimento del personaggio, incolla il prompt → fai clic su genera, un'immagine TURBO costa $0.09.

API in 3 passi: POST /v1/tasks per inviare → ottieni il taskId → con GET /v1/tasks/<taskId> verifichi success e poi scarichi.

curl: la prima immagine

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Per l'endpoint di modifica cambia model in ideogram-v3-character/edit e aggiungi in input image_url (immagine originale) e mask_url (maschera):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Il taskId nella risposta è la chiave per interrogare il risultato.

Python: invio, polling, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# Invio: con Idempotency-Key, i retry di rete non creano task duplicati
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Polling: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # indirizzo temporaneo, scaricalo e salvalo al più presto
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Tabella dei parametri (ideogram-v3-character)

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–5000 caratteri	Descrive la scena in cui deve apparire il personaggio, non il suo aspetto (l'aspetto dipende dall'immagine di riferimento)
reference_image_urls	Sì	Esattamente 1, JPEG / PNG / WebP, ≤10 MB	Immagine di riferimento del personaggio; il suo formato determina il formato dell'output
rendering_speed	No	TURBO / BALANCED / QUALITY, predefinito BALANCED	Determina il livello e il prezzo
style	No	AUTO / REALISTIC / FICTION, predefinito AUTO	REALISTIC tende al look fotografico, FICTION mantiene l'aspetto illustrato
seed	No	Intero 0–2147483647	Con gli stessi parametri e lo stesso seed si riproduce l'immagine
expand_prompt	No	Predefinito true	Espande automaticamente il prompt; per rispettare rigorosamente il testo originale passa false
negative_prompt	No	≤5000 caratteri	Contenuti che non vuoi far apparire

L'endpoint di modifica richiede due campi obbligatori in più rispetto alla tabella, image_url e mask_url, e non supporta negative_prompt. Se nel body della richiesta compare un campo non previsto dalla tabella, restituisce subito 400 (additional properties ... not allowed).

Gli errori che incontrerai (messaggi originali dell'API)

Cosa hai fatto	Risposta
Non hai passato prompt	400 invalid input: prompt: missing required field "prompt"
Hai passato 2 immagini di riferimento	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed scritto male	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Hai passato un campo non riconosciuto dall'endpoint	400 invalid input: <root>: additional properties 'foo' not allowed
Hai passato negative_prompt all'endpoint di modifica	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Saldo insufficiente	402 insufficient account balance; top up and retry

Inviare di nuovo lo stesso Idempotency-Key restituisce 409 (in elaborazione) o 422 (parametri non corrispondenti): prova con una nuova key.

Da sapere prima della messa in produzione

• Callback: passa al livello superiore del body "callback": {"url": "https://..."}; quando il task raggiunge lo stato finale il tuo servizio viene notificato, evitando il polling.
• Salva subito: output[0].url è un indirizzo temporaneo; appena lo ottieni scarica e salva nel tuo storage, non usarlo come link permanente.
• Indica esplicitamente livello e formato: passa rendering_speed sempre in modo esplicito (se omesso viene fatturato come BALANCED); il formato dell'output è determinato dall'immagine di riferimento, quindi per scene verticali prepara un riferimento verticale.
• Chiavi di idempotenza separate per i task in batch: ogni invio deve avere un Idempotency-Key univoco; con i retry di rete la stessa key colpisce solo lo stesso task, senza crearne di duplicati né addebitare due volte i crediti.

Domande frequenti

L'immagine di riferimento può essere un URL?

Sì. Basta che sia un indirizzo http/https raggiungibile, in JPEG, PNG o WebP, massimo 10 MB.

Quante immagini di riferimento si possono passare?

Esattamente 1: è una regola rigida, con due immagini restituisce subito 400; per cambiare personaggio cambia l'immagine di riferimento.

Serve passare parametri di dimensione?

No. Il formato dell'output segue l'immagine di riferimento: un riferimento verticale produce 864×1152, uno orizzontale produce 1328×752.

I due endpoint si chiamano allo stesso modo?

Sì. Cambia solo model e i campi dentro input.

I fallimenti vengono addebitati?

No: i crediti prenotati vengono restituiti per intero dopo lo stato finale di fallimento.

Prossimo passo: con il prompt del mercato notturno qui sopra prova a generare un'immagine nella pagina del modello, poi scegli i prompt in base alla scena nella raccolta di prompt; per i tre livelli di prezzo e la tabella di budget vedi la pagina dei prezzi.