Come chiamare grok-imagine/image-to-image tramite l'API HiAPI: guida con curl e Python

Cosa offre grok-imagine/image-to-image agli sviluppatori

grok-imagine/image-to-image è un endpoint di trasformazione delle immagini: gli fornisci un'immagine di riferimento e un prompt, e restituisce una nuova immagine che segue il prompt mantenendo al contempo un legame visivo con l'immagine di riferimento. Puoi pensarlo come una generazione guidata, non una generazione da zero. L'ID del modello che chiami su HiAPI è esattamente grok-imagine/image-to-image, e il resto della richiesta serve a descrivere le modifiche che desideri.

Ogni volta che l'output deve conservare qualcosa del materiale esistente — una foto prodotto il cui sfondo va cambiato, uno schizzo di un personaggio da rendere, una composizione da reinterpretare stilisticamente — conviene scegliere questo endpoint invece di una chiamata di generazione da testo. La generazione da testo è adatta quando non hai un'immagine sorgente ma solo una descrizione; image-to-image è adatta quando l'immagine sorgente stessa fa parte delle specifiche.

Poiché HiAPI lo espone come un'unica interfaccia unificata, il tuo lavoro di integrazione si limita a costruire una sola struttura di richiesta e a gestire una sola struttura di risposta. Non devi importare un SDK separato per ogni famiglia di modelli né reimparare l'autenticazione per ogni endpoint.

Anatomia della richiesta: modello, immagine di riferimento e prompt

Ogni chiamata valida si compone concettualmente di quattro parti. Sistemare ciascuna di esse prima di scrivere il codice elimina gran parte del debug successivo.

ID del modello

Il campo model contiene la stringa grok-imagine/image-to-image. Trattala come una costante nel tuo client, non come un letterale hardcoded sparso nel codebase — se in futuro vorrai provare altri modelli HiAPI, vorrai avere un solo punto da modificare.

Immagine di riferimento

L'immagine di riferimento è l'ancora. Come fornirla dipende dal metodo di trasporto scelto: può essere un URL che l'API può scaricare, oppure dati base64 inline, adatti a immagini generate al volo o non accessibili pubblicamente. Preferisci l'URL per materiale che già ospiti; preferisci i dati inline per caricamenti utente non ancora salvati in una posizione pubblica. In entrambi i casi, valida l'immagine prima di inviarla: formato supportato, dimensione non nulla, dimensioni sufficientemente significative.

Prompt

Il prompt descrive la trasformazione, non l'intera scena. Se l'immagine di riferimento contiene già il soggetto, descrivi ciò che deve cambiare — stile, illuminazione, sfondo, materiale — e lascia implicito ciò che resta invariato. Specificare eccessivamente ciò che è già visibile nell'immagine di riferimento tende a entrare in conflitto con il condizionamento dell'immagine invece di aiutare.

Gestione del rapporto d'aspetto

La parte restante riguarda come viene determinata la dimensione dell'output, argomento della prossima sezione. Tieni separate queste quattro parti nel codice che costruisce la richiesta, così da poterle validare e registrare nei log in modo indipendente.

Uso dell'opzione auto aspect

L'opzione auto aspect lascia che sia l'API a scegliere la dimensione dell'output, invece di fissare tu larghezza e altezza esplicite. Quando è attiva, il servizio deduce un rapporto d'aspetto adeguato dal contesto della richiesta — soprattutto dall'immagine di riferimento — così che la forma dell'output sia più ragionevole rispetto al tuo input, invece di essere forzata in un formato predefinito.

Questo è più importante di quanto sembri. Se fissi una dimensione incoerente con le proporzioni dell'immagine di riferimento, otterrai artefatti simili a letterbox, soggetti tagliati in modo sgraziato o composizioni che ignorano l'inquadratura della sorgente. auto aspect evita queste incongruenze facendo seguire la geometria all'input.

Quando mantenere auto attivo

• Le immagini di riferimento provengono dagli utenti e hanno forme varie.
• Stai facendo prototipazione e non sai ancora quale dimensione si adatti al caso d'uso.
• L'output finisce in una pipeline che comunque ritaglia o ridimensiona.

Quando fissare esplicitamente le dimensioni

• Hai slot fissi in una UI o in un obiettivo di stampa e ti serve una geometria di output precisa.
• Stai generando un lotto di immagini che devono essere visivamente coerenti nelle dimensioni.

Un approccio pratico: mantieni auto aspect attivo durante lo sviluppo, osserva le dimensioni che l'API restituisce per input reali, poi decidi se bloccare le dimensioni per la produzione. Registra i metadati dell'immagine restituita insieme alla richiesta, così la decisione si basa su prove e non su congetture.

Richiesta curl pronta all'uso

La richiesta seguente è completa tranne che per i segnaposto, indicati tra parentesi angolari. Sostituiscili con i tuoi valori e potrai eseguirla direttamente.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

Segnaposto da sostituire

• $HIAPI_API_KEY —— leggi la tua chiave da una variabile d'ambiente invece di incollarla nel comando. Se la variabile non è impostata, la richiesta fallisce con un errore di autenticazione e la chiave non finisce mai nella cronologia della shell.
• <describe the transformation you want> —— un'istruzione breve e specifica, ad esempio un cambio di stile o di sfondo.
• <publicly reachable URL of your reference image> —— un URL che il servizio può scaricare senza autenticazione. Se il tuo materiale è privato, usa invece dati base64 inline.

Lettura della risposta

Alla prima esecuzione fai passare l'output attraverso un formattatore JSON per esaminare chiaramente la struttura della risposta. Concentrati su due cose: il payload dell'immagine (a seconda della modalità di risposta, può essere un URL o dati codificati) e l'identificatore del job quando la chiamata è gestita in modo asincrono. Durante lo sviluppo conserva nei log la risposta grezza completa — è il modo più rapido per rispondere alla domanda "cosa è stato effettivamente restituito" quando qualcosa sembra sbagliato.

La stessa richiesta in Python

La versione Python deve corrispondere campo per campo alla richiesta curl. Il valore di tenerle allineate è che un bug riprodotto in una versione può essere confermato nell'altra senza dover indovinare la traduzione.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Dove collocare la gestione degli errori

Nel wrapper della chiamata, non nel chiamante. response.raise_for_status() converte le risposte non 2xx in eccezioni, quindi un singolo try/except attorno a generate_from_reference copre sia i fallimenti di trasporto sia i rifiuti dell'API. Se desideri una registrazione strutturata dei motivi del fallimento, controlla response.status_code e il corpo dell'errore all'interno della funzione prima di sollevare l'eccezione.

Mantenere il client pulito

Leggi la chiave API una sola volta all'avvio, imposta timeout espliciti e restituisci JSON analizzato invece dell'oggetto risposta grezzo. Il chiamante non dovrebbe aver bisogno di conoscere i dettagli HTTP. Nei test, punta API_URL a un server stub, così da poter verificare la logica di costruzione della richiesta senza spendere chiamate di generazione reali.

Risposte sincrone e asincrone

Alcune richieste image-to-image si completano abbastanza rapidamente da restituire il risultato nella stessa risposta HTTP. Altre vengono gestite come job: la chiamata iniziale restituisce un identificatore e l'immagine è disponibile più tardi. Il tuo client non dovrebbe presumere nessuno dei due casi.

Come distinguerli

Controlla il corpo della risposta dopo ogni chiamata. Se contiene direttamente il payload dell'immagine, sei sul percorso sincrono — estrailo e restituiscilo. Se contiene un identificatore di job o di attività, sei sul percorso asincrono e devi fare polling finché il job non raggiunge uno stato terminale.

Progettare per entrambi

Una piccola funzione di dispatch tiene i due percorsi fuori dalla logica di business:

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Regole di polling per evitare guai

• Usa un backoff esponenziale con limite massimo, non un ciclo serrato.
• Imposta un tempo massimo di attesa complessivo e fallisci in modo pulito al superamento.
• Tratta ogni stato non terminale come "continua ad attendere"; solo due stati sono finali: successo e fallimento.
• Registra l'ID del job a ogni polling, così da poter tracciare un job bloccato solo dai log.

Il dispatch significa che, passando dal comportamento sincrono a quello asincrono, il codice che chiama resolve_result non deve mai cambiare.

Debug dei codici di errore comuni

La maggior parte delle chiamate fallite su questo endpoint rientra in poche categorie. Controlla la checklist seguente in ordine — va dal motivo più comune a quello meno comune.

Errori di autenticazione

Se la risposta segnala un problema di autenticazione, la chiave è mancante, malformata o non inviata. Verifica che la variabile d'ambiente sia effettivamente popolata nel processo che effettua la chiamata e che l'header sia esattamente Authorization: Bearer <key>. Una chiave valida nella tua shell ma non nel servizio di solito significa che l'ambiente del servizio è diverso da quello della tua shell.

Errori di validazione dell'immagine di riferimento

Un rifiuto legato all'immagine di solito significa una di quattro cose: l'URL non è scaricabile pubblicamente, il formato non è supportato, il payload è troppo grande, oppure l'immagine è troppo piccola o corrotta. Prova l'URL in un browser senza credenziali — se non si carica lì, l'API non può scaricarla. Per il base64 inline, verifica che la codifica sia base64 puro e che non ci sia un prefisso data-URL (a meno che il parametro non lo preveda).

Errori di prompt e parametri

Prompt vuoti o troppo grandi, o valori di parametro sconosciuti, producono risposte di validazione. Registra nei log il payload esatto inviato insieme all'errore — una buona parte dei fallimenti è dovuta a nomi di campo scritti male, non a problemi di valore.

Limiti di frequenza

Una risposta di limite di frequenza significa backoff, non retry immediato. Segui le indicazioni di retry negli header della risposta, aggiungi jitter e limita il numero di tentativi. Un retry senza backoff trasforma un limite temporaneo in un limite persistente.

Errori lato server

Le risposte 5xx sono responsabilità del servizio. Ritenta un numero limitato di volte con backoff; se il problema persiste, cattura l'ID richiesta e il timestamp dalla risposta e riduci la concorrenza durante l'indagine.

Checklist di produzione prima del lancio

Una richiesta funzionante è solo l'inizio, non la fine. Prima che questo endpoint gestisca traffico reale, verifica ciascuno dei punti seguenti.

Valida gli input al confine

Prima che la richiesta lasci il tuo servizio, controlla formato e dimensione dell'immagine di riferimento, lunghezza del prompt e valori dei parametri. Rifiutare localmente input errati è più veloce, più economico e produce messaggi di errore più chiari per gli utenti.

Ritenta solo le richieste ritentabili in sicurezza

Usa backoff esponenziale con jitter per fallimenti di trasporto, limiti di frequenza e risposte 5xx. Non ritentare errori di validazione o autenticazione — falliranno allo stesso modo, aumentando solo il carico.

Registra informazioni sufficienti a ricostruire un fallimento

Registra l'ID del modello, una forma hashata o troncata del prompt, l'identificatore dell'immagine di riferimento (non il payload completo), lo stato della risposta, l'ID del job (se presente) e l'ID richiesta. Questo insieme di informazioni di solito basta a rispondere alla domanda "cosa è successo" senza dover memorizzare contenuti sensibili.

Tieni le chiavi fuori dal codice

Leggi la chiave API dall'ambiente o da un gestore di segreti, mai da un letterale nel codice sorgente. Ruota periodicamente le chiavi e revocale immediatamente se sospetti una compromissione.

Monitora il comportamento dei costi

La fatturazione di questo endpoint è guidata dalle generazioni, quindi le leve chiave sono il volume di richieste, i retry e la frequenza di polling. Evita tempeste di retry, applica backoff al polling e, per scenari in cui la stessa trasformazione viene richiesta ripetutamente, memorizza nella cache i risultati per prompt e immagine di riferimento. Consulta il pannello prezzi di HiAPI per le tariffe attuali, invece di codificare ipotesi.

Testa i percorsi sfortunati

Scrivi test per URL di immagini non validi, risposte di limite di frequenza e job asincroni che non si completano mai. Questi tre coprono i fallimenti più probabilmente destinati a entrare in produzione inosservati.

Con la costruzione delle richieste, il dispatch delle risposte e la gestione degli errori a posto, grok-imagine/image-to-image diventa una parte ordinaria della tua pipeline, non un caso speciale.