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

Cosa ti offre ideogram-v4.5 su HiAPI

Quando il testo nelle immagini conta davvero, ideogram-v4.5 è il modello da scegliere. Layout di poster, grafiche per loghi, mockup di packaging, card per i social: ogni scenario in cui un titolo scritto male o una didascalia sfocata rovinerebbe il materiale è proprio quello in cui questo modello dà il meglio di sé. Se invece devi generare texture astratte o paesaggi fotografici in cui nulla deve essere leggibile con chiarezza, i modelli di immagini generici sono di solito più economici e più veloci.

Questo articolo è una guida all'integrazione, non una recensione del modello. Al termine avrai una richiesta funzionante, un client Python che fa la stessa cosa e una funzione ausiliaria riutilizzabile che gestisce le parti in cui di solito si sbaglia: il parametro delle proporzioni, il polling del task asincrono e il recupero dell'output.

Un punto da interiorizzare subito: la generazione di immagini su HiAPI è un'API di task asincrona. Invii una richiesta, ricevi un identificatore e poi esegui il polling finché il task non è completato. Un codice che presume che il corpo della risposta contenga già l'immagine non funzionerà. Ogni sezione che segue converge verso questo schema.

Prima di inviare la richiesta

Prima della prima chiamata servono quattro cose.

1. La chiave API

Creane una nella console del tuo account HiAPI e tienila lontana dal controllo di versione. Esportala come variabile d'ambiente invece di incollarla nello script:

export HIAPI_API_KEY="your_key_here"

2. L'URL di base

Tutte le richieste vengono inviate all'URL di base dell'API HiAPI, con l'aggiunta del percorso specifico dell'endpoint di generazione. La documentazione della piattaforma elenca i percorsi attuali; se la documentazione dice qualcosa di diverso, non codificare in modo fisso il percorso che hai visto in un articolo di blog (compreso questo).

3. L'identificatore del modello

La stringa del modello che passi nel corpo della richiesta identifica ideogram-v4.5. Usa l'esatta combinazione di maiuscole e minuscole mostrata nell'elenco dei modelli della piattaforma: gli identificatori dei modelli corrispondono letteralmente e la minima differenza restituisce un errore di validazione, non un suggerimento utile.

4. Il riferimento dei parametri

La pagina del modello ideogram-v4.5 è la fonte autorevole su quali campi accetta il corpo della richiesta: limiti di lunghezza del prompt, proporzioni supportate, formato di output ed eventuali controlli di seed o stile. Leggila prima di scrivere il codice. I parametri non elencati lì possono essere ignorati o rifiutati in silenzio, e indovinare i valori è il modo più comune di sprecare tempo nel debugging.

Con queste quattro cose a disposizione, puoi inviare la tua prima richiesta.

Una richiesta curl funzionante

Quello che segue è un esempio minimo di invio. Se il tuo account mostra valori diversi, sostituisci il percorso dell'endpoint e l'identificatore del modello con quelli della documentazione della piattaforma.

curl -X POST "$HIAPI_BASE_URL/<generation-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4.5",
    "input": {
      "prompt": "Un poster di viaggio vintage per la Costiera Amalfitana, headline in grassetto serif che recita \"AMALFI\", palette calda da tramonto, texture di stampa granulosa"
    }
  }'

Il ruolo di ciascuna parte:

• Authorization — autenticazione con bearer token. Un header mancante o malformato è la causa più comune di 401.
• Content-Type — deve essere application/json. Alcuni client HTTP non lo impostano automaticamente nelle POST, causando errori di parsing confusi sul lato server.
• model — l'identificatore letterale del modello. Mettilo al livello superiore del corpo della richiesta come indicato nella documentazione.
• input.prompt — la tua istruzione di generazione. Come mostrato sopra, racchiudi tra virgolette il testo che vuoi renderizzato nell'immagine, così il modello lo tratterà come testo letterale e non come descrizione.
• input.* — tutti gli altri parametri di generazione (proporzioni, formato, seed, ecc.) appartengono a questo oggetto annidato, accanto a prompt.

Un invio riuscito restituisce un oggetto JSON contenente l'identificatore del task e un campo di stato. In questa risposta non c'è nessuna immagine: è il comportamento previsto. Conserva l'identificatore; servirà per la fase di polling.

Effettuare la stessa chiamata con Python

La versione Python è una traduzione uno a uno. Usiamo requests e condividiamo lo stesso corpo della richiesta, così puoi confrontare i due approcci affiancati.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
GEN_PATH = "/<generation-path>"  # confirm in platform docs

payload = {
    "model": "ideogram-v4.5",
    "input": {
        "prompt": (
            "Un poster di viaggio vintage per la Costiera Amalfitana, headline "
            'in grassetto serif che recita "AMALFI", palette calda da tramonto, texture di stampa granulosa'
        )
    },
}

response = requests.post(
    BASE_URL + GEN_PATH,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=30,
)
response.raise_for_status()

job = response.json()
print(job)

Due scelte intenzionali:

• json.dumps invece di json= mantiene visibilmente coerente il formato di trasmissione con l'esempio curl. Entrambi funzionano; scriverlo esplicitamente rende più facile ispezionare ciò che stai effettivamente inviando durante il debugging.
• timeout=30 solo per l'invio. L'invio è veloce, la generazione no. Non lasciare mai che la chiamata di invio erediti un timeout breve impostato per il polling, altrimenti segnalerai come fallito un task che funziona correttamente.

Il dizionario job stampato contiene l'identificatore del task e lo stato corrente. Salva l'identificatore da qualche parte: il ciclo di polling dipende da esso.

Controllare proporzioni e formato di output

Proporzioni e formato di output sono parametri del corpo della richiesta, non endpoint separati. Si trovano nello stesso oggetto input del prompt:

{
  "model": "ideogram-v4.5",
  "input": {
    "prompt": "...",
    "aspect_ratio": "<ratio from docs>",
    "output_format": "<format from docs>"
  }
}

La disciplina importante qui è non indovinare i valori. Ogni modello di generazione espone enumerazioni fisse di proporzioni e formati, e modelli diversi accettano grafie diverse: 16:9 contro 16x9, png contro PNG, e così via. Passare un valore non supportato dal modello di solito produce un errore di validazione o, peggio, ripiega in silenzio sull'output predefinito, che sembra un bug nel tuo prompt.

Quindi il flusso di lavoro è:

1. Apri la pagina del modello ideogram-v4.5 sulla piattaforma e copia letteralmente l'elenco delle proporzioni supportate e quello dei formati di output.
2. Inserisci questi valori in una piccola whitelist nel codice, così gli input non validi falliscono nel punto di chiamata invece che all'API.
3. Usa come impostazione predefinita una proporzione che corrisponda al tuo layout a valle. Se l'immagine deve entrare in uno spazio da 1200×630 per una card social, scegli un valore vicino a quella proporzione invece di generare un quadrato e poi ritagliarne il contenuto.

Le immagini dense di testo meritano un avvertimento in più: le proporzioni estreme (banner ultra-larghi, poster ultra-alti) comprimono lo spazio disponibile per il rendering del testo. Per i titoli che devono davvero essere leggibili con chiarezza, una proporzione orizzontale o verticale intermedia è più sicura di una proporzione estrema e panoramica.

Gestire i task asincroni e scaricare i risultati

Il ciclo di vita di una generazione si articola in tre fasi: invio → polling → recupero.

Invio

Hai già padroneggiato questa fase nelle sezioni precedenti. La risposta ti fornisce un identificatore del task e uno stato, ad esempio queued o processing.

Polling

Esegui il polling dell'endpoint di stato del task con quell'identificatore finché lo stato non segnala il completamento. Due regole mantengono il processo decoroso:

• Attendi tra un polling e l'altro. Inizia con circa un secondo e applica un backoff progressivo. Tempestare l'endpoint di stato non farà completare il task più in fretta e rischia di attivare il rate limiting.
• Limita il tempo di attesa. Imposta un numero massimo di tentativi o una scadenza e, al superamento, lancia un errore esplicito invece di ciclare all'infinito.

import time

def wait_for_job(job_id, headers, base_url, status_path,
                 max_attempts=60, initial_delay=1.0, factor=1.5):
    delay = initial_delay
    for _ in range(max_attempts):
        r = requests.get(
            f"{base_url}{status_path}/{job_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "completed", "success"):
            return data
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended with status {status}: {data}")
        time.sleep(delay)
        delay *= factor
    raise TimeoutError(f"job {job_id} did not finish in time")

Consulta la documentazione della piattaforma per le stringhe di stato e il percorso di stato esatti del tuo account: esegui il matching sui valori della documentazione e considera qualsiasi stato non riconosciuto come ancora in esecuzione, non come successo.

Recupero

Quando il task segnala il completamento, la risposta contiene la posizione dell'output (di solito un URL). Scaricalo con una normale GET e scrivi i byte su disco. Gli URL di output possono avere una scadenza, quindi scarica il prima possibile invece di conservare l'URL per dopo. Tutto ciò che serve per scrivere questo ciclo deriva dalla struttura della risposta di invio: non c'è nessuna API separata di "recupero immagine" da imparare.

Incapsulare in una funzione ausiliaria riutilizzabile

Tre script inline che reimplementano ciascuno il polling sono un problema di manutenzione. Impacchettalo una volta sola.

import os, json, time, requests

class IdeogramClient:
    def __init__(self, base_url, api_key, gen_path, status_path,
                 poll_attempts=60, poll_factor=1.5):
        self.base_url = base_url.rstrip("/")
        self.gen_path = gen_path
        self.status_path = status_path
        self.poll_attempts = poll_attempts
        self.poll_factor = poll_factor
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }

    def generate(self, prompt, **params):
        body = {"model": "ideogram-v4.5", "input": {"prompt": prompt, **params}}
        r = requests.post(self.base_url + self.gen_path,
                          headers=self.headers,
                          data=json.dumps(body), timeout=30)
        r.raise_for_status()
        job = r.json()
        done = self._wait(job["id"])
        url = done["output"]["url"]  # confirm shape in docs
        return self._download(url)

    def _wait(self, job_id):
        delay = 1.0
        for _ in range(self.poll_attempts):
            r = requests.get(f"{self.base_url}{self.status_path}/{job_id}",
                             headers=self.headers, timeout=30)
            r.raise_for_status()
            data = r.json()
            if data.get("status") in ("succeeded", "completed", "success"):
                return data
            if data.get("status") in ("failed", "error", "cancelled"):
                raise RuntimeError(data)
            time.sleep(delay)
            delay *= self.poll_factor
        raise TimeoutError(job_id)

    def _download(self, url):
        r = requests.get(url, timeout=60)
        r.raise_for_status()
        return r.content

Per usarlo basta una sola chiamata: img_bytes = IdeogramClient(...).generate("...", aspect_ratio="<from docs>"). Adatta l'accesso a done["output"]["url"] e le stringhe di stato in modo che corrispondano alla struttura della risposta in documentazione: sono i due punti che più probabilmente richiedono una messa a punto specifica per account.

Errori comuni e tecniche di debug

La maggior parte dei fallimenti della prima settimana rientra in cinque categorie.

401 / 403 — autenticazione. Chiave mancante, con spazi bianchi dovuti al copia-incolla, o prefisso Bearer assente. Stampa i primi quattro e gli ultimi quattro caratteri della chiave che stai effettivamente inviando; il carattere di newline finale proveniente dai file di ambiente è il classico colpevole.

400 — JSON malformato o campo sconosciuto. Se il corpo della richiesta è assemblato per concatenazione di stringhe, le virgolette non sottoposte a escape nel prompt rompono il JSON. Costruisci il corpo come dizionario e serializzalo con json.dumps. Se il JSON si analizza correttamente, il prossimo sospettato è il nome di un parametro non accettato dal modello: controlla le tue chiavi carattere per carattere rispetto alla pagina del modello.

404 / modello non trovato. Di solito è un errore di grafia o di maiuscole nell'identificatore del modello, oppure un percorso dell'endpoint obsoleto. Copia entrambi dalla documentazione della piattaforma, non a memoria o da un vecchio tutorial.

429 — rate limiting. Quasi sempre dovuto a un polling troppo aggressivo. Aumenta il ritardo iniziale di polling e il fattore di backoff. Sul lato invio, aggiungi retry con jitter per le risposte 429 e 5xx, ma non riprovare gli errori di validazione 4xx: falliranno allo stesso modo ogni volta.

Task riuscito ma immagine che non si apre. Verifica di aver scaricato byte e non una pagina JSON di errore; chiamare raise_for_status() sulla GET di download intercetta la maggior parte di questi problemi. Controlla anche di trattare l'URL di download come valido a breve termine, invece di metterlo in cache tra una sessione e l'altra.

In caso di dubbio, registra il corpo completo della risposta e il codice di stato di ogni chiamata lungo l'intera catena: invio, ogni singolo polling e download. L'API di solito dice chiaramente dove si è verificato l'errore; il bug è spesso che non siamo mai andati a guardare.

Con un invio funzionante, un ciclo di polling e una gestione ragionevole degli errori, ideogram-v4.5 si integra in una pipeline reale come qualsiasi altra chiamata a un modello HiAPI.