Come si usa l'API Ideogram 4.5? Generazione, modifica e interrogazione delle attività

TL;DR

• Ideogram 4.5 è una serie text-to-image che privilegia la tipografia: ideogram-v4.5/text-to-image genera poster, loghi, marchi denominativi e packaging bilingue con testo, mentre ideogram-v4.5/image-to-image usa Precise Edit per modificare con precisione i testi, cambiare lo stile con un'immagine di riferimento e modificare aree locali con una maschera. Puoi selezionare l'attività dalla pagina del modello oppure chiamare l'API come descritto di seguito.
• Il prezzo è per immagine e varia con il livello di qualità: LOW $0.043, MEDIUM (predefinito) $0.086, HIGH $0.3145; il livello di modifica parte da VERY_LOW $0.0115; attualmente ogni richiesta restituisce 1 immagine, num_images può essere solo 1. Per i dettagli vedi la pagina dei prezzi.
• La chiamata passa per l'API HiAPI /v1/tasks: dopo l'invio leggi data.taskId, poi interroga data.status; in caso di successo scarica l'URL con type=image da data.output.

Cosa può fare

• Organizzare la gerarchia del testo nell'immagine: metti tra virgolette il testo che deve apparire e specifica separatamente la posizione di titolo, sottotitolo, data e lineup; dopo la generazione controlla parola per parola.
• Esplorare la composizione con attività singole: ogni richiesta restituisce 1 immagine; modifica il prompt o il seed e invia più attività separatamente per confrontare le direzioni.
• API di modifica complementare: Precise Edit (edit_precision=high) è utile per modifiche limitate come nomi di brand o date; confronta con l'immagine sorgente per verificare le aree conservate.
• Immagini di riferimento + maschera: fino a 4 immagini di riferimento (3 se con maschera); nella maschera il nero = ridipingere, il bianco = conservare.

Di seguito un risultato reale generato (livello LOW):

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(Traduzione: poster di brand minimalista e moderno per una conferenza sul design, titolo enorme in grassetto "DESIGN FORWARD" centrato, sottotitolo più piccolo "Typography Summit 2026" sotto, layout a griglia svizzera pulito, palette arancione caldo e blu navy profondo, forme geometriche, lettering nitido e definito. Dimensioni: landscape_16_9.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, $0.043.

Genera con questo prompt →

Quale delle due API scegliere

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
Cosa fa	Genera immagini con impaginazione a partire dal testo	Modifica un'immagine esistente
Input obbligatori	prompt	image_url + prompt
Livello di qualità	low / medium / high	very_low / low / medium / high
Parametri caratteristici	num_images: 1, enable_prompt_expansion	edit_precision (Precise), reference_image_urls, mask_url
Dimensioni	6 preset, predefinito square_hd	auto (predefinito) o 6 preset; con maschera / Precise solo auto
Adatto a	Poster, loghi, packaging, nuove bozze di insegne	Modifica di testi, cambio palette, versioni stagionali, ridipintura locale

Pipeline tipica: genera il poster di brand, poi usa Edit per cambiare il nome del brand o la data nella versione del cliente. Una generazione LOW costa $0.043 e una modifica Precise LOW $0.043, per un totale di $0.086.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → incolla il prompt, scegli il livello di qualità → clicca su genera.

API in 3 passi: POST /v1/tasks per inviare → leggi data.taskId → GET /v1/tasks/<taskId> per interrogare data.status e, quando è success, scarica.

curl: la prima immagine

Imposta prima nel terminale HIAPI_IDEMPOTENCY_KEY come identificatore univoco di questa operazione; riutilizza lo stesso valore quando ritenti la stessa richiesta. L'esempio usa esplicitamente LOW, formato orizzontale e espansione attiva.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

API di modifica: cambia model in ideogram-v4.5/image-to-image e passa l'immagine sorgente e le istruzioni. Di seguito si usa Precise Edit per richiedere la modifica del testo e la conservazione del layout; il risultato va comunque verificato confrontandolo con l'immagine sorgente:

Per questa attività di modifica imposta separatamente HIAPI_EDIT_IDEMPOTENCY_KEY; non riutilizzare la chiave dell'attività di generazione.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python: invio, polling, download

Installa prima requests e imposta HIAPI_API_KEY; per il primo invio imposta anche HIAPI_IDEMPOTENCY_KEY, usando un valore distinto per ogni nuova operazione e mantenendolo invariato per i tentativi della stessa richiesta. Il programma stampa prima l'ID dell'attività; se si interrompe, impostando HIAPI_TASK_ID puoi riprendere l'interrogazione e il download senza inviare di nuovo la generazione.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

Se durante l'interrogazione o il download si verifica un errore di rete, conserva l'ID dell'attività già stampato e riprendi; lo script non invia automaticamente una nuova richiesta di creazione. Il limite di polling dell'esempio è di 600 secondi, con un'attesa di 3 secondi per ciclo; il download scrive prima un file .part e solo al termine lo rinomina con il nome definitivo.

Tabella dei parametri

Generazione ideogram-v4.5/text-to-image

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–10000 caratteri	Struttura in quattro parti: che immagine fare → testo e palette → impaginazione → texture e vincoli
quality	No	low / medium / high, predefinito medium	low per esplorazione in batch, medium per l'uso quotidiano, high per la versione finale con molto testo piccolo
image_size	No	6 preset, predefinito square_hd	Nessuna larghezza/altezza personalizzata
num_images	No	Fisso a 1	Ogni attività restituisce 1 immagine
enable_prompt_expansion	No	Predefinito true	Espansione del prompt; false disattiva l'espansione, ma il testo finale va comunque verificato
seed	No	Intero	Riproducibilità con gli stessi parametri

Modifica ideogram-v4.5/image-to-image

Campo	Obbligatorio	Valori	Descrizione
image_url	Sì	URL immagine	Immagine sorgente
prompt	Sì	1–10000 caratteri	Istruzioni di modifica; specifica cosa cambiare e cosa mantenere
edit_precision	No	regular / high, predefinito regular	high = Precise Edit, adatto a modifiche limitate di testo
quality	No	very_low / low / medium / high, predefinito medium	very_low solo con regular
image_size	No	auto o 6 preset, predefinito auto	Con maschera o Precise solo auto
reference_image_urls	No	Massimo 4	Massimo 3 con maschera
mask_url	No	URL immagine	Nero = ridipingere, bianco = conservare
num_images	No	Fisso a 1	Ogni attività restituisce 1 immagine
seed	No	Intero

Se in input compaiono campi al di fuori della tabella dei parametri del modello, viene restituito 400; i campi di primo livello model, callback ecc. vanno compilati secondo il formato dell'API delle attività.

Errori che incontrerai

Codice di stato	Significato	Come procedere
400 INVALID_REQUEST	Corpo della richiesta non valido (prompt o image_url mancante, valore enum errato, campo non previsto)	Correggi il corpo della richiesta confrontandolo con la tabella dei parametri
402 INSUFFICIENT_QUOTA	Saldo insufficiente (nessun addebito)	Ricarica e riprova
429 RATE_LIMITED	Limite di frequenza raggiunto	Riduci la frequenza di invio
409 IDEMPOTENCY_KEY_PROCESSING	Attività con la stessa chiave in fase di creazione	Attendi e riprova con la stessa chiave e lo stesso corpo della richiesta
422 IDEMPOTENCY_KEY_MISMATCH	Stessa chiave con corpo della richiesta diverso	Ripristina il corpo originale; usa una nuova chiave solo per una nuova operazione

Il fallimento definitivo di un'attività può includere codici di errore come CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT. Conserva taskId e il messaggio di errore e verifica la fatturazione incrociando lo stato finale dell'attività con i registri dell'account; non considerare un errore di interrogazione o di download come un fallimento della generazione.

Note prima del go-live

• Callback: passa al livello superiore del corpo della richiesta "callback": {"url": "https://..."} per ricevere la notifica automatica allo stato finale.
• Salva tempestivamente: i link ai risultati in data.output hanno scadenza; scarica subito dopo il successo.
• Attività singole e idempotenza: ogni esecuzione produce 1 immagine; quando ritenti per timeout la stessa richiesta operativa, riutilizza la chiave di idempotenza originale; usa una nuova chiave solo per una nuova operazione.
• Testo piccolo in cinese: confronta i livelli di qualità sul testo reale; controlla parola per parola prima della consegna, perché anche medium o high non sostituiscono la verifica.

Domande frequenti

Quante immagini si possono generare al massimo con una richiesta?

Attualmente generazione e modifica restituiscono 1 immagine per volta, num_images può essere solo 1. Invia attività separate per più direzioni.

Il livello di qualità predefinito è LOW?

No. Il predefinito è MEDIUM, $0.086 per immagine; per avere LOW a $0.043 per immagine passa esplicitamente quality: "low".

Quale modalità usare per cambiare solo nome del brand e data?

Puoi usare Precise Edit passando esplicitamente edit_precision: "high", quality: "low", image_size: "auto"; $0.043 per immagine.

Cosa rappresentano le aree bianche e nere della maschera?

Le aree nere vengono ridipinte, quelle bianche conservate. La maschera deve avere le stesse dimensioni dell'immagine sorgente; quando usi una maschera, imposta image_size su auto.

Dopo un timeout dell'invio devo cambiare la chiave di idempotenza?

Per ritentare la stessa richiesta operativa non cambiare chiave: riutilizza lo stesso Idempotency-Key e lo stesso corpo della richiesta; usa una nuova chiave solo quando serve davvero una nuova attività.

Passo successivo: prendi il prompt del poster DESIGN FORWARD e genera un'immagine dalla pagina del modello, poi con una singola istruzione Precise sostituisci il titolo con il nome del tuo evento. Letture correlate: tre livelli di prezzo e budget · 4 esempi di prompt di modifica.

Se vuoi iniziare subito a creare marchi denominativi o poster per eventi, puoi copiare questa raccolta di esempi di prompt.