Come usare ideogram-v4 tramite l'API hiapi: curl, Python e una richiesta funzionante

La reputazione dei modelli Ideogram si basa su una cosa che la maggior parte dei modelli di immagini ancora oggi non riesce a gestire: la tipografia. I titoli sui poster sono scritti correttamente, le lettere sui loghi sono nitide, il testo delle insegne non si trasforma in un ammasso di caratteri illeggibili. ideogram-v4, come tutti gli altri modelli di immagini e video, è disponibile su hiapi tramite la stessa API unificata per le attività, e questa guida percorre l'intera richiesta: la versione curl pronta da copiare e incollare, lo script Python completo, i parametri che lo schema verifica effettivamente (e che non coincidono con quelli esposti dall'API nativa di Ideogram), e gli errori che incontrerai nella pratica.

Cosa costruirai e cosa ti serve

Obiettivo: inviare un prompt testuale a POST /v1/tasks, attendere il completamento dell'attività, quindi scaricare un'immagine in cui il testo è renderizzato come richiesto.

Ti serve solo una cosa: una chiave API hiapi — creala nella console. Viene usata come Bearer token in ogni richiesta. Non esiste un livello gratuito non autenticato; tutte le chiamate seguenti presuppongono Authorization: Bearer sk-....

Come tutti i modelli su hiapi, ideogram-v4 è asincrono: crei un'attività, ricevi subito un taskId, poi o esegui il polling del risultato o ricevi un callback. Non esiste una modalità sincrona "aspetta 40 secondi su una singola connessione HTTP" — e per la generazione di immagini non la vorresti comunque.

Richiesta minima: curl

Crea l'attività:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "Un poster per un festival jazz in stile art déco vintage. Il titolo principale \"MIDNIGHT & BRASS\" è in grassetto dorato su sfondo blu navy scuro, il sottotitolo \"Live at the Riverside, Fridays\" è sotto in un sottile font sans-serif.",
      "rendering_speed": "BALANCED",
      "aspect_ratio": "3:4"
    }
  }'

La risposta torna immediatamente, con l'id dell'attività in data.taskId (nel formato tk-hiapi-...). Esegui il polling:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
  -H "Authorization: Bearer $HIAPI_KEY"

Durante la generazione dell'immagine, data.status passa da queued a handling. Al termine diventa success o fail. In caso di successo, l'URL dell'immagine si trova in data.output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-XXXXXXXX",
    "status": "success",
    "output": [
      { "url": "https://.../result.png?...expireAt=..." }
    ]
  }
}

Un dettaglio importante su questo URL: è firmato e scade (expireAt). Scarica i byte immediatamente dopo il successo dell'attività e salvali nel tuo storage. Non inserire mai hotlink in un database.

I parametri che ideogram-v4 accetta davvero

Questa è la parte da trattare con precisione. Se hai letto la documentazione di Ideogram, saprai che la sua API nativa espone preset di stile, interruttori magic prompt, prompt negativi e quantità batch. Lo schema delle attività di ideogram-v4 su hiapi è volutamente più ridotto, e il validatore rifiuta qualsiasi cosa al di fuori dello schema. Ecco l'intero insieme confermato sull'API live:

Campo	Obbligatorio	Tipo / valori
prompt	Sì	string
rendering_speed	Sì	"TURBO", "BALANCED", "QUALITY"
aspect_ratio	No	"1:1", "16:9", "4:3", "9:16", "3:4"
seed	No	intero

Entrambi i campi obbligatori sono validati con severità. Inviare un input vuoto restituisce:

invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"

Se scrivi male un valore dell'enum, l'errore ti indica i valori validi:

invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'

E qualsiasi cosa presente nell'interfaccia nativa di Ideogram ma non nella tabella sopra viene rifiutata come proprietà sconosciuta — style_type, magic_prompt, negative_prompt, num_images, size e input immagine restituiscono tutti un 400, ad esempio:

invalid input: <root>: additional properties 'style_type' not allowed

Conseguenze pratiche:

• Il controllo tipografico dipende interamente dal prompt. Inserisci il testo esatto che vuoi renderizzare tra virgolette doppie nel prompt e descrivi il font ("carattere art déco in grassetto", "sans-serif geometrico sottile", "carattere da insegna dipinta a mano"). È così che si ottiene l'effetto poster/logo/insegna per cui Ideogram è famoso — non c'è un parametro di stile separato su cui fare affidamento.
• Un'immagine per attività. Non esistono n né num_images. Se vuoi quattro candidati, invia quattro attività e interroga ciascun taskId separatamente.
• seed è la tua leva per la riproducibilità. Stesso prompt + stesso seed ti dà un punto di partenza stabile per iterare sulla formulazione.
• Solo testo-immagine. Lo schema del modello non accetta immagini di riferimento. Se il tuo flusso di lavoro richiede immagine-immagine, scegli un modello che supporti questa funzione — vedi come chiamare più modelli di immagini con una sola chiave API per cambiare modello senza modificare il codice di integrazione.

Su rendering_speed: TURBO è il livello veloce, adatto alle bozze mentre iteri sulla formulazione del prompt; QUALITY è il livello lento e curato per i rendering finali; BALANCED è un default ragionevole. Il prezzo è a consumo per immagine — consulta la pagina dei prezzi per le tariffe attuali.

Lo script Python completo

Lo stesso flusso — creazione, polling, download — con timeout e gestione dello stato terminale. Unica dipendenza: requests (pip install requests).

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, rendering_speed: str = "BALANCED",
                aspect_ratio: str = "1:1", seed: int | None = None) -> str:
    input_obj = {
        "prompt": prompt,
        "rendering_speed": rendering_speed,
        "aspect_ratio": aspect_ratio,
    }
    if seed is not None:
        input_obj["seed"] = seed
    resp = requests.post(API_BASE, headers=HEADERS,
                         json={"model": "ideogram-v4", "input": input_obj},
                         timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt=('Crea un logo minimalista per un marchio di caffè chiamato "Driftwood", '
                'con il wordmark Driftwood in un caldo carattere serif, monocromatico, '
                'su sfondo color crema'),
        rendering_speed="QUALITY",
        aspect_ratio="1:1",
        seed=42,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    png = requests.get(url, timeout=120).content   # l'URL firmato scade - scarica subito
    with open("driftwood-logo.png", "wb") as f:
        f.write(png)
    print("saved driftwood-logo.png,", len(png), "bytes")

Considerazioni per la produzione: callback, idempotenza ed errori

Polling vs. callback. Per uno strumento interattivo che genera un'immagine alla volta, il polling ogni pochi secondi è più semplice e del tutto sufficiente. Per carichi batch o lato server, aggiungi un callback alla richiesta di creazione, così hiapi ti invia il risultato finale via POST:

{
  "model": "ideogram-v4",
  "input": { "prompt": "...", "rendering_speed": "BALANCED" },
  "callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}

Due vincoli, entrambi applicati alla creazione: l'URL deve essere https:// e accessibile pubblicamente, e when accetta solo "final" — se provi altri valori, l'API restituisce direttamente invalid callback.when: only 'final' is supported. Rendi il tuo handler idempotente rispetto a taskId, restituisci rapidamente 2xx e mantieni un fallback di polling per le attività il cui callback non arriva mai. Se il callback non arriva, esegui prima il debug seguendo perché il tuo callback delle attività hiapi non si attiva, prima di dare la colpa alla coda.

Idempotenza. La creazione di attività non è idempotente — ogni POST /v1/tasks andato a buon fine è una nuova attività e una nuova fatturazione. Appena ricevi il taskId, salvalo associandolo al tuo id di attività, e qualsiasi nuovo tentativo successivo dovrà interrogare il taskId salvato invece di reinviare la richiesta.

Gli errori che vedrai davvero.

• 401 con "code": "permission_denied" — chiave non valida o non abilitata a usare quel modello. Il messaggio lo dice chiaramente: "This API key cannot use the selected model. Please check permissions or use another key." Risolvi nella console, non ritentare.
• 400 con "error_code": "INVALID_REQUEST" — validazione fallita. Il message indica il campo specifico e i valori validi; leggilo e correggi il corpo della richiesta. Ritentare con lo stesso corpo fallirà sempre.
• 404 "task not found" su GET /v1/tasks/{id} — id attività errato, oppure attività creata con un'altra chiave.
• Stato fail su un'attività già accettata — controlla data.error.code / data.error.message nella risposta di polling. Questi possono essere ritentati in sicurezza come nuova attività.

Letture correlate

• Pagina del modello ideogram-v4 — capacità e livelli di prezzo attuali
• Perché il tuo callback delle attività hiapi non si attiva — lista di controllo per il debug dei callback
• Come chiamare più modelli di immagini con una sola chiave API — stessa API per le attività, stringa model diversa
• L'API di generazione immagini più economica — come confrontare il costo reale per immagine tra i modelli
• Documentazione API — riferimento completo di POST /v1/tasks / GET /v1/tasks/{id}

Domande frequenti

ideogram-v4 su hiapi supporta immagine-immagine o immagini di riferimento? No. Lo schema delle attività del modello accetta solo prompt, rendering_speed, aspect_ratio e seed — qualsiasi campo di input immagine viene rifiutato con un 400. Se devi modificare o ridisegnare un'immagine esistente, usa un modello che supporti immagine-immagine (ad esempio la famiglia gpt-image-2).

Quale rendering_speed dovrei usare? Mentre ottimizzi il prompt e la formulazione esatta del testo, itera con TURBO, poi ri-renderizza la versione vincente con QUALITY e lo stesso seed. Se renderizzi una sola volta, BALANCED è un buon default.

Come faccio a far renderizzare a ideogram-v4 il testo esatto? Inserisci il testo letterale tra virgolette doppie nel prompt e descrivi la tipografia intorno: titolo principale "SUMMER SALE", in sans-serif condensato extra-bold. Le stringhe brevi si renderizzano in modo più affidabile rispetto a frasi complete; se una riga lunga esce male, dividila in titolo principale e sottotitolo.

Posso generare più immagini in una sola richiesta? No — un'attività genera un'immagine. Invia invece più attività in parallelo; ognuna ha il proprio taskId e viene messa in coda in modo indipendente.

Perché la mia chiave funziona con altri modelli ma ricevo 401 permission_denied? L'accesso ai modelli è configurato per singola chiave. Controlla i permessi del modello per quella chiave nella console, oppure crea una nuova chiave con accesso a ideogram-v4.

Quanto dura l'URL di output? È un URL firmato con un timestamp expireAt. Trattalo come valido per minuti, non per giorni: scarica l'immagine appena l'attività raggiunge success e salva il file da solo.

Quali rapporti d'aspetto sono disponibili? Esattamente cinque: 1:1, 16:9, 4:3, 9:16 e 3:4. Non esiste un parametro size libero — una richiesta con size viene rifiutata come proprietà sconosciuta.