Come usare ideogram-v3-character tramite l'API HiAPI: guida con curl e Python

Cos'è ideogram-v3-character e quando usarlo

ideogram-v3-character è un modello di generazione di immagini su HiAPI specializzato nella coerenza dei personaggi. Non tratta ogni generazione come un prompt indipendente: ti permette invece di fornire immagini di riferimento del personaggio, così che le renderizzazioni successive mantengano lo stesso volto, abbigliamento e identità complessiva.

Va usato quando chi e cosa fa sono ugualmente importanti:

• Storyboard e fumetti: lo stesso personaggio appare in più vignette.
• Varianti di asset per videogiochi: generare pose, espressioni o abbigliamenti diversi per un personaggio protagonista.
• Mascotte di brand: deve mantenere un aspetto coerente in molte scene e sfondi diversi.
• Direzione artistica iterativa: rifinire un personaggio in più cicli di modifiche senza perdere la somiglianza.

Se ti serve solo un'illustrazione una tantum e non ti interessa corrispondere a immagini precedenti, un modello generico di text-to-image è più semplice. La struttura aggiuntiva data dalle immagini di riferimento è proprio ciò che rende ideogram-v3-character degno di campi di richiesta aggiuntivi.

Il modello, come gli altri, è esposto tramite l'endpoint unificato di generazione immagini di HiAPI, quindi la struttura della richiesta risulterà familiare: invii un payload JSON, ricevi il riferimento al job di un'attività asincrona e esegui il polling finché il risultato non è pronto. Questo tutorial si concentra su come completare correttamente questo flusso.

Prima di inviare la richiesta: configurazione e autenticazione

Prima della prima chiamata, ti servono solo poche cose.

1. Chiave API

Crea una chiave API nella dashboard del tuo account HiAPI. Trattala come un segreto: autorizza ogni tua richiesta e viene conteggiata nella fatturazione del tuo account.

2. Gestione delle credenziali tramite variabili d'ambiente

Non codificare mai la chiave direttamente nei file sorgente e non salvarla in git. Usa invece le variabili d'ambiente:

export HIAPI_API_KEY="your_api_key_here"

In Python, puoi leggerla così:

import os
api_key = os.environ["HIAPI_API_KEY"]

Se usi un file .env nello sviluppo locale, aggiungilo a .gitignore prima di fare qualsiasi altra cosa.

3. URL delle immagini di riferimento

Poiché la coerenza dei personaggi dipende dalle immagini di riferimento, prepara un'immagine che possa essere passata tramite URL. Assicurati che l'URL sia accessibile pubblicamente o comunque raggiungibile dall'API: i link privati protetti da autenticazione falliranno. Le immagini quadrate o verticali che mostrano chiaramente il volto del personaggio funzionano meglio.

4. Modalità per inviare richieste HTTP

È sufficiente curl da riga di comando oppure un ambiente Python con requests installato. Gli esempi seguenti presuppongono che tu abbia uno dei due.

Con questi quattro elementi pronti, puoi inviare la tua prima richiesta.

Analisi riga per riga di una richiesta curl funzionante

Ecco una richiesta completa per inviare un job ideogram-v3-character a HiAPI. Sostituisci i segnaposto con i tuoi valori.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "Un amichevole meccanico robot in piedi in un'officina soleggiata, con una chiave inglese in mano, vista a tre quarti",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

Cosa fa ogni parte

• POST /v1/images/generations — l'endpoint unificato di generazione immagini di HiAPI. Tutti i modelli usano lo stesso percorso.
• Authorization: Bearer $HIAPI_API_KEY — autentica la chiamata. La shell espande la variabile d'ambiente che hai impostato prima.
• Content-Type: application/json — stai inviando un corpo JSON, quindi devi dichiararlo.
• model — seleziona ideogram-v3-character. Senza di esso, la richiesta non sa a quale modello instradare.
• prompt — descrizione della scena. Descrivi posa, ambiente, illuminazione e atmosfera; lascia l'identità del personaggio alle immagini di riferimento.
• reference_images — array di URL di immagini. Per un singolo personaggio, di solito basta una voce.
• aspect_ratio — forma dell'output. Correspondi all'uso previsto (quadrato, verticale, ecc.).
• num_images — quante varianti generare per job.

Un invio riuscito restituisce un corpo JSON contenente l'identificatore del job. Annota quel valore: servirà nella fase di polling. La risposta può anche contenere un campo di stato che indica che il job è in coda o in elaborazione. Se lo stato è già terminale, il risultato potrebbe essere incorporato direttamente nella risposta; in caso contrario, continua con il polling.

La stessa richiesta in Python

Ecco la chiamata identica in Python. Legge la chiave dalla variabile d'ambiente, invia la richiesta e stampa il riferimento al job.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "Un amichevole meccanico robot in piedi in un'officina soleggiata, con una chiave inglese in mano, vista a tre quarti",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Note sulla versione Python

• timeout=60 impedisce allo script di bloccarsi all'infinito in caso di rete instabile.
• raise_for_status() converte le risposte non 2xx in eccezioni, facendoti notare subito problemi di autenticazione e validazione.
• Estrazione dell'ID job — HiAPI restituisce l'identificatore del job nel corpo della risposta. A seconda della struttura della risposta, potrebbe trovarsi sotto id o job_id; l'esempio controlla entrambi, ma dovresti prima esaminare una risposta reale e poi codificare il nome del campo corretto per chiarezza.

Il payload è volutamente identico all'esempio curl. Copiare il corpo JSON avanti e indietro tra i due è un buon controllo di sanità durante il debug: se uno funziona e l'altro no, il problema è nel livello di trasporto, non nel modello.

Gestire le immagini di riferimento per la coerenza dei personaggi

Le immagini di riferimento sono ciò che distingue ideogram-v3-character dai modelli generici di text-to-image. Gestirle bene significa aver fatto gran parte del lavoro.

Come vengono fornite le immagini di riferimento

Il campo reference_images è un array di URL. Ogni URL deve puntare a un'immagine che l'API possa recuperare direttamente. Se archivi contenuti caricati dagli utenti, servili da un bucket o CDN che consente richieste GET non autenticate, oppure genera un URL firmato valido per tutta la durata del job.

Tecniche per immagini di riferimento che mantengono davvero la coerenza

• Un solo personaggio per immagine di riferimento. Le foto di gruppo rendono difficile capire quale volto preservare.
• Volto nitido e ben illuminato. Evita ombre pesanti, angolazioni estreme e occlusioni.
• Posa neutra o caratteristica. La vista frontale o a tre quarti preserva meglio l'identità.
• Se vuoi mantenere l'abbigliamento, l'abbigliamento nell'immagine di riferimento deve essere coerente — il modello riprodurrà ciò che vede.
• La risoluzione conta, ma non esagerare. Un'immagine di dimensioni ragionevoli con un volto nitido è meglio di una gigantesca e sfocata.

Mantenere il personaggio riconoscibile tra più generazioni

Quando generi una seconda scena per lo stesso personaggio, riutilizza la stessa immagine di riferimento, non un output generato in precedenza. L'uso concatenato di immagini generate può accumulare sottili derive. Se ti serve una nuova immagine di riferimento — ad esempio con un abbigliamento diverso — generala una volta, controllala, poi riutilizza quel file come nuova immagine di riferimento per i job successivi.

Verificare la coerenza

Genera due o tre varianti con pose diverse per lo stesso personaggio e confrontale affiancate. Se il volto o l'abbigliamento cambiano, di solito la causa è un'immagine di riferimento debole o ambigua. Prima di modificare il prompt, migliora l'immagine di riferimento.

Job asincroni: inviare, eseguire polling e ottenere i risultati

La generazione di immagini richiede tempo, quindi HiAPI la gestisce in modo asincrono. Il modello è sempre lo stesso: invia, cattura l'ID del job, esegui il polling finché il job raggiunge lo stato terminale, poi leggi gli URL di output.

Ciclo di vita del job

1. Inviato — invii la richiesta degli esempi precedenti.
2. In coda — il job è stato accettato ed è in attesa di capacità.
3. In elaborazione — il modello sta renderizzando.
4. Completato o fallito — stato terminale; il risultato (o l'errore) è disponibile.

Polling in Python

Dopo aver catturato job_id, esegui il polling dell'endpoint del job:

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Ottenere i risultati

Al termine del job, il corpo della risposta contiene l'output — di solito un array di URL di immagini o un singolo URL, più metadati. Scarica l'immagine da quell'URL il prima possibile; alcuni URL hanno una scadenza. Se hai bisogno di archiviazione a lungo termine, copia il file nel tuo bucket subito dopo il successo del job.

Buone maniere nel polling

• Backoff. Un intervallo di due secondi va bene per job brevi; se stai facendo polling su molti job, aumenta l'intervallo o usa il jitter.
• Limita i tentativi. La protezione max_attempts evita loop infiniti e fornisce al codice un percorso di errore esplicito.
• Non fare polling più spesso del necessario. Ogni polling è una richiesta; martellare l'endpoint non farà terminare il rendering prima.

Errori comuni e come diagnosticarli

Quando qualcosa va storto, la via più rapida è di solito isolare se il problema è nella tua richiesta, nell'immagine di riferimento o nel job stesso.

Errori di autenticazione

401 indica una chiave mancante, malformata o revocata. Controlla che la variabile d'ambiente sia effettivamente impostata nella shell o nel processo che esegue la richiesta. Trappola comune: impostare la variabile in un terminale ed eseguire lo script in un altro.

Errori di validazione

400 indica quasi sempre il payload. Verifica:

• Che il campo model sia esattamente ideogram-v3-character.
• Che reference_images sia un array, non una stringa.
• Che ogni URL nell'array sia accessibile pubblicamente.
• Che aspect_ratio usi un valore supportato.

Se hai dubbi, invia un payload minimo — solo model, prompt e reference_images — e aggiungi i campi uno alla volta.

Job che non terminano mai

Se il polling supera il limite di tentativi, non riprovare semplicemente alla cieca. Controlla se nella risposta di stato del job c'è un messaggio. Le cause comuni sono URL di riferimento non raggiungibili o coda sovraccarica. Invia di nuovo una volta; se si blocca ancora, semplifica il prompt e le immagini di riferimento.

Immagini di riferimento ignorate silenziosamente

Il job riesce, ma il personaggio non corrisponde. Di solito è un problema dell'immagine di riferimento, non del codice: l'URL potrebbe restituire una pagina di errore, un PDF o un'immagine segnaposto. Recupera tu stesso l'URL nel browser per confermare che restituisca l'immagine prevista e il content type corretto.

Limiti di frequenza

429 indica che stai inviando richieste troppo velocemente. Usa il backoff esponenziale; se stai generando in batch, scagliona gli invii invece di mandarli tutti insieme.

Checklist rapida

• La chiave è impostata nell'ambiente corretto?
• L'URL di riferimento è accessibile senza autenticazione?
• I nomi dei campi del payload sono scritti correttamente?
• Il polling ha un limite e un backoff?
• L'output viene scaricato prima che il suo URL scada?

Seguendo questa checklist in ordine, la maggior parte dei fallimenti si risolve rapidamente. Dopo il primo run end-to-end riuscito, conservalo come esempio funzionante noto e confronta con esso ogni nuova richiesta. Man mano che ti espandi su molti personaggi e scene, questa sola abitudine ti farà risparmiare tempo.