HiAPI
It
Blog

Tutoriale

Come usare grok-imagine-quality/image-to-image tramite l'API hiapi: curl, Python e richieste funzionanti

Jul 11, 2026
Come usare grok-imagine-quality/image-to-image tramite l'API hiapi: curl, Python e richieste funzionanti

Questa guida ti mostra come trasformare un'immagine esistente con grok-imagine-quality/image-to-image (il livello a più alta fedeltà della famiglia Grok Imagine) tramite l'API unificata delle attività di hiapi. Invierai un'immagine sorgente e un prompt testuale, eseguirai il polling del risultato e scaricherai l'immagine generata. Ogni struttura di richiesta e risposta riportata di seguito è stata verificata rispetto all'API live.

Cosa ti serve

  • Una chiave API hiapi — creane una nella dashboard.
  • Da una a tre URL di immagini accessibili pubblicamente da usare come sorgente. La piattaforma recupera e normalizza i tuoi media di input lato server, quindi i percorsi di file locali e i payload base64 non funzionano — ospita prima le immagini in una posizione accessibile all'API.

Tutto qui. Nessun SDK necessario; l'API delle attività è semplice HTTPS + JSON.

Schema della richiesta

grok-imagine-quality/image-to-image funziona sull'endpoint delle attività asincrone: crei un'attività con POST /v1/tasks, poi esegui il polling di GET /v1/tasks/<taskId> (o registri un callback) finché non è completata.

Lo schema di input è rigoroso — i campi sconosciuti vengono rifiutati con 400:

Campo Tipo Obbligatorio Descrizione
prompt string ✅ Cosa fare con l'immagine sorgente
image_urls string[] ✅ Da 1 a 3 URL pubblici delle immagini sorgente/di riferimento
aspect_ratio string – Uno dei seguenti: 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 string – 1k o 2k — minuscolo (1K restituisce 400)
output_format string – jpeg, png o webp

Nota cosa non c'è: nessun size, nessun n, nessun seed, nessuna manopola strength o consistency. Quanto l'output segue l'immagine sorgente è controllato dal tuo prompt e dalle immagini di riferimento che passi — vedi le FAQ di seguito.

Esempio minimo funzionante (curl)

Crea l'attività:

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

Una creazione riuscita restituisce l'ID dell'attività:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx"
  }
}

Esegui il polling finché l'attività raggiunge lo stato finale:

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

Durante l'esecuzione, data.status è in corso; al termine diventa success e l'immagine si trova in data.output:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx",
    "status": "success",
    "output": [
      {
        "url": "https://.../result.png?...&expireAt=...",
        "expireAt": 1760000000
      }
    ]
  }
}

⚠️ Gli URL di output sono temporanei (nota expireAt). Scarica subito i byte dopo il successo dell'attività e salvali nel tuo storage — non fare hotlink dell'URL del risultato.

Se l'attività fallisce, data.status è fail e data.error contiene code e message.

Python: creare, eseguire il polling, scaricare

Uno script completo che usa solo requests:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"

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

def create_task(prompt: str, image_urls: list[str]) -> str:
    payload = {
        "model": "grok-imagine-quality/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # 1-3 public URLs
            "aspect_ratio": "1:1",
            "resolution": "2k",         # lowercase: "1k" or "2k"
            "output_format": "png",
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {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:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = r.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} still running after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt="Turn this product photo into a clean studio shot on a light gray background",
        image_urls=["https://your-cdn.example.com/source.jpg"],
    )
    print("task:", task_id)

    task = wait_task(task_id)
    url = task["output"][0]["url"]

    # The output URL expires -- download immediately and persist yourself
    img = requests.get(url, timeout=120).content
    with open("result.png", "wb") as f:
        f.write(img)
    print(f"saved result.png ({len(img)} bytes)")

Considerazioni per la produzione

Usa i callback invece del polling

Per qualsiasi scenario oltre a uno script usa e getta, registra un callback e salta il ciclo di polling. Aggiungi un oggetto callback di primo livello (allo stesso livello di model e input):

{
  "model": "grok-imagine-quality/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

when supporta solo "final" — riceverai esattamente un POST quando l'attività raggiunge lo stato finale (success o fail). Regola pratica:

  • Il polling va bene per CLI, notebook e job batch, dove il processo resta comunque vivo. Esegui il polling ogni 3–5 secondi; non martellare con intervalli sotto il secondo.
  • I callback sono migliori per i backend web: nessuna connessione in sospeso, nessun thread di lavoro occupato durante la generazione. Recupera di nuovo GET /v1/tasks/<taskId> lato server per verificare il payload, invece di fidarti ciecamente del corpo del webhook.

Idempotenza

La creazione di un'attività non è di per sé idempotente — se il tuo processo va in crash dopo POST /v1/tasks ma prima di aver persistito il taskId, un nuovo tentativo creerà (e fatturerà) una seconda attività. Persisti il taskId nel tuo storage, con chiave il tuo ID job interno, prima di iniziare l'attesa; al riavvio riprendi eseguendo il polling del taskId memorizzato invece di ricreare l'attività.

Gestione degli errori

Gli errori che incontrerai davvero:

  • 401 permission_denied — chiave API non valida o senza accesso a questo modello. Il corpo della risposta contiene un request_id che puoi inviare al supporto:

    {
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

  • 400 INVALID_REQUEST — violazione dello schema, con un messaggio preciso. Esempi reali per questo modello:

    • prompt: missing required field "prompt" — hai dimenticato un campo obbligatorio.
    • image_urls: maxItems: got 12, want 3 — troppe immagini di riferimento (massimo 3).
    • resolution: value must be one of '1k', '2k' — hai inviato 1K/4K.
    • additional properties 'seed' not allowed — hai passato un campo che questo modello non accetta.

  • Stato finale fail — l'attività è stata accettata ma la generazione è fallita (ad esempio perché l'URL sorgente non è recuperabile). Controlla data.error.message, correggi l'input e crea una nuova attività.

Usa un retry con backoff per 5xx ed errori di rete; non ritentare i 400 — falliranno allo stesso modo finché non correggi il payload.

Scegliere il livello di qualità (e che ne è della "consistency"?)

La famiglia Grok Imagine su hiapi è suddivisa in ID modello separati per livello e modalità. Per l'immagine a immagine puoi scegliere:

Il livello è l'ID del modello — non esiste alcun parametro quality dentro input (inviarlo restituisce 400 additional properties 'quality' not allowed). Il prezzo per immagine di entrambi i livelli è nella pagina dei prezzi.

Letture correlate

Domande frequenti

Esiste un parametro di consistenza o di intensità? No. Lo schema di input accetta solo prompt, image_urls, aspect_ratio, resolution e output_format; qualsiasi altro contenuto viene rifiutato con 400. Per controllare quanto l'output segue l'immagine sorgente, indica chiaramente nel prompt cosa deve essere preservato ("mantieni il prodotto e l'etichetta identici, cambia solo lo sfondo") e passa fino a 3 immagini di riferimento tramite image_urls.

Posso caricare file locali o inviare base64? Non direttamente — image_urls accetta URL e la piattaforma li recupera lato server. Carica i file su qualsiasi storage accessibile pubblicamente (S3, R2, CDN) e passa quell'URL.

Quante immagini sorgente posso passare? Da 1 a 3. Un array vuoto fallisce con minItems: got 0, want 1; più di 3 fallisce con maxItems.

Quali risoluzioni e proporzioni sono supportate? resolution è 1k o 2k (solo minuscolo). aspect_ratio supporta 14 valori da 2:1 a 1:2, inclusi auto, 16:9, 1:1, 9:16 e i formati adatti al mobile 9:19.5/9:20.

Quanto durano gli URL di output? Ogni output porta un timestamp expireAt. Considera i risultati effimeri: scarica subito i byte dopo il successo dell'attività e archiviali tu stesso.

Come genero più varianti? Non c'è alcun parametro n — crea un'attività per ogni variante. Le attività vengono eseguite in modo indipendente, quindi puoi inviarne più in parallelo.

Se la mia chiave è corretta, cosa significa 401 permission_denied? La chiave esiste ma non può usare questo modello (piano o ambito di permessi). Controlla i permessi del modello della chiave nella dashboard, oppure contatta il supporto usando il request_id presente nel corpo della risposta di errore.

Tagimmagine-in-immagineEsercitazioneAPI

Articoli correlati

Vedi tutti gli articoli →

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API