Come usare grok-imagine image-to-image tramite l'API hiapi: curl, Python e una richiesta funzionante

grok-imagine/image-to-image riceve una o più immagini di riferimento e un prompt testuale e restituisce un'immagine modificata — puoi cambiare lo stile di una foto di prodotto, sostituire lo sfondo o fondere fino a tre immagini di riferimento in un unico output. Su hiapi funziona tramite l'API task unificata: crea un task, esegui il polling (o ricevi un callback), scarica il risultato. Questa guida ti accompagna nella struttura esatta della richiesta, con esempi curl e Python pronti da copiare e incollare e funzionanti subito.

Cosa costruirai + prerequisiti

Obiettivo: inviare un'immagine di riferimento e un prompt, ottenere l'URL di un'immagine modificata e scaricarla — prima in modo interattivo tramite polling, poi con una versione di produzione basata su callback.

Ti serve solo una cosa: una chiave API hiapi. Prendila dalla tua dashboard — ha l'aspetto di sk-... e va inserita nell'header Authorization: Bearer a ogni chiamata.

Le tue immagini di riferimento devono essere URL accessibili pubblicamente (il modello le recupera lato server), quindi ospitale prima sul tuo CDN o object storage.

Esempio minimo funzionante (curl)

Crea il task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

Ci sono due campi obbligatori — prompt e image_urls — e questa è già una richiesta completa. La risposta contiene l'ID del task sotto data.taskId:

{
  "data": {
    "taskId": "<task-id>"
  }
}

Esegui il polling del risultato:

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

Durante l'esecuzione del task, data.status riporta l'avanzamento. Quando diventa success, l'URL dell'immagine si trova in data.output[0].url. Se è fail, data.error contiene codice e messaggio di errore.

Un dettaglio importante: gli URL di output sono firmati e scadono (il payload contiene expireAt). Scarica il file subito dopo il successo del task — non memorizzare mai né usare hotlink sugli URL di output originali.

curl -o result.png "<data.output[0].url>"

Lo stesso esempio in Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

Lo schema di input completo

Campo	Obbligatorio	Tipo	Descrizione
prompt	✅	string	Cosa modificare / aspetto desiderato
image_urls	✅	array di URL	Da 1 a 3 immagini di riferimento, accessibili pubblicamente
aspect_ratio	Opzionale	enum	auto, 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2
resolution	Opzionale	enum	1k oppure 2k — minuscolo
output_format	Opzionale	enum	jpeg, png oppure webp

Lo schema è rigoroso: qualsiasi campo che non riconosce viene rifiutato con un 400. Non esiste size, né seed, né n — se stai portando codice di modelli che usano dimensioni in pixel (ad esempio size: "1024x1024"), qui usa aspect_ratio + resolution. Ogni task restituisce un'immagine; per ottenere varianti, invia più task.

Riferimenti multipli: fino a 3 immagini di input

image_urls accetta fino a tre immagini di riferimento, che il modello fonde — ad esempio una foto di prodotto più uno sfondo più un riferimento di stile. Se ne invii più di tre, l'API rifiuta direttamente la richiesta:

invalid input: image_urls: maxItems: got 4, want 3

Metti per prima l'immagine più importante (di solito il soggetto) e specifica nel prompt cosa contribuisce ciascun riferimento.

Proporzioni automatiche

aspect_ratio: "auto" fa sì che il modello ricavi le proporzioni dell'output dall'immagine di riferimento invece di imporre un formato fisso — è il valore predefinito adatto per foto di prodotto e modifiche in cui vuoi preservare la composizione. Imposta una proporzione esplicita solo quando il caso d'uso lo richiede chiaramente (ad esempio 9:16 per una posizione story, 16:9 per un banner hero).

Considerazioni per la produzione

Usa i callback invece del polling

Per workload batch o lato server, salta il loop di polling — registra un callback alla creazione del task e hiapi invierà il risultato finale via POST al tuo endpoint:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when supporta solo "final" — ricevi una chiamata quando il task raggiunge success o fail, non eventi di avanzamento intermedi.

Regola pratica: polling per strumenti interattivi (c'è un utente che guarda; un loop con sleep di 5 secondi va bene), callback per le pipeline (ci sono decine di task in esecuzione; non vuoi un poller per ogni task). Il tuo handler di callback deve comunque scaricare subito l'output — l'URL che riceve scade come tutti gli altri.

Idempotenza e retry

L'API task separa "invio" e "risultato", il che rende i retry sicuri semplici e diretti:

• Persisti il taskId nel momento in cui create lo restituisce. Se il tuo processo si blocca in seguito, riprendi interrogando l'ID memorizzato — non ricrearlo.
• Riprova solo se la chiamata create fallisce senza restituire un taskId (errori di rete, 5xx). Rinviare una richiesta che ha già restituito un ID genera un secondo task fatturato separatamente.
• Considera status: "fail" come stato terminale. Correggi l'input (o passa a un piano B) e invia un nuovo task; un task fallito non riparte.

Errori comuni

Cosa vedi	Significato	Come risolvere
401 — permission_denied	Chiave errata, o chiave senza accesso a questo modello	Controlla la chiave nella dashboard
400 INVALID_REQUEST — missing required field "prompt" / "image_urls"	Manca un input obbligatorio	Entrambi i campi sono obbligatori
400 INVALID_REQUEST — additional properties '...' not allowed	Campo sconosciuto (ad esempio size, seed, n)	Schema rigoroso — usa solo i campi della tabella sopra
400 INVALID_REQUEST — image_urls: maxItems	Più di 3 immagini di riferimento	Riduci a 3
404 — task not found	taskId errato nella GET o appartenente a un altro account	Controlla l'ID memorizzato
status: "fail" durante il polling	Accettato ma generazione fallita	Leggi data.error, correggi l'input, invia di nuovo

Nota che il fallimento di autenticazione è un 401 con "code": "permission_denied" nel corpo dell'errore — vale la pena gestirlo esplicitamente, perché copre anche il caso in cui la chiave esiste ma non ha accesso a questo modello.

Passi successivi

• Dettagli del modello e prova online: grok-imagine/image-to-image
• Ti serve una fedeltà maggiore? La fascia di qualità usa la stessa struttura di richiesta: grok-imagine-quality/image-to-image
• Parti solo dal prompt (senza immagini di riferimento): grok-imagine text-to-image
• Costo per immagine delle due fasce: prezzi
• Riferimento completo dell'API task: documentazione

Domande frequenti

Quante immagini di riferimento posso passare? Fino a 3 in image_urls. L'API rifiuta in modo netto le eccedenze (maxItems: got N, want 3).

Posso impostare le dimensioni di output in pixel? No. Non esiste un campo size — controlli la forma con aspect_ratio (14 valori enum) e la nitidezza con resolution (1k o 2k, minuscolo). Qualsiasi altra cosa restituisce un 400.

Cosa fa aspect_ratio: "auto"? Fa sì che il modello segua le proporzioni dell'immagine di riferimento invece di imporre un formato fisso — è la scelta comune per le modifiche in cui la composizione va preservata.

Quanto durano gli URL dei risultati? Sono URL firmati con una scadenza (expireAt nel payload di output). Scarica i byte il prima possibile dopo il successo del task; non usare hotlink.

Devo fare polling o usare i callback? Per l'uso interattivo basta un polling ogni ~5 secondi. Per pipeline batch, passa callback: {"url": ..., "when": "final"} e gestisci un POST per ogni task — "final" è l'unico trigger supportato.

Posso ottenere più varianti in una singola chiamata? No — non c'è un parametro n. Invia un task per variante; tanto vengono eseguiti in parallelo.

Che differenza c'è con grok-imagine-quality/image-to-image? Stessa struttura di richiesta, con un livello di rendering a fedeltà superiore (e costo maggiore). Fai il prototipo con la fascia standard, poi riesegui le immagini da conservare sulla fascia di qualità; confronta il costo per immagine nella pagina dei prezzi.