Come usare l'API di text-to-image grok-imagine-quality: curl, Python e una richiesta pronta all'uso

Riepilogo

• Di cosa si tratta: una soluzione funzionante per usare l'API grok-imagine-quality/text-to-image su hiapi — crea un'attività con POST /v1/tasks, esegui il polling di GET /v1/tasks/<taskId> (oppure usa un callback), scarica l'immagine da output[0].url.
• Schema rigoroso e minimale: prompt (obbligatorio), aspect_ratio (13 formati, predefinito 1:1), resolution (1k | 2k, minuscolo, predefinito 1k), output_format (jpeg | png | webp, predefinito jpeg). Qualsiasi altro campo viene rifiutato con 400.
• "Quality" è un livello, non un parametro di regolazione. Non esiste alcun parametro quality o rich_detail — dettagli, materiali e illuminazione più ricchi sono esattamente ciò che questa variante del modello offre di default. Se ti servono bozze economiche in batch, sullo stesso endpoint c'è il modello gemello di livello standard grok-imagine/text-to-image.
• Gli URL di output hanno una scadenza expireAt — scarica o salva in modo persistente per tempo.

Cosa costruirai e cosa ti serve

Obiettivo: inviare un prompt testuale a grok-imagine-quality/text-to-image e ottenere un file immagine finito utilizzabile come key visual — prima con curl, poi come piccolo script Python da inserire in una coda di lavoro.

Ti serve una sola cosa: una chiave API di hiapi. Ottienila dalla tua console hiapi ed esportala:

export HIAPI_API_KEY="sk-..."

Ogni richiesta si autentica con l'header bearer standard: Authorization: Bearer sk-<key>.

Richiesta minima funzionante (curl)

La generazione di immagini su hiapi è solo asincrona. Non devi attendere una lunga chiamata HTTP; invece crei un'attività e ne recuperi il risultato al completamento.

Passo 1 — crea l'attività:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "Key visual di prodotto di una macchina per espresso nera opaca su un piano in ardesia, luce direzionale drammatica, profondità di campo ridotta, finitura commerciale premium",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Mentre il modello lavora in background, ricevi immediatamente un taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

Passo 2 — esegui il polling fino allo stato terminale:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

L'attività passa per queued → handling → archiving, per arrivare infine a success o fail. Solo success contiene l'output:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Passo 3 — scarica prima di expireAt:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Lo stesso flusso in Python

Uno script completo: crea, esegue il polling, salva. Copia, imposta HIAPI_API_KEY, esegui.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "Key visual di prodotto di una macchina per espresso nera opaca su un piano in ardesia, "
            "luce direzionale drammatica, profondità di campo ridotta, finitura commerciale premium"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # minuscolo! "2K" viene rifiutato con 400
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # un 4xx qui = richiesta stessa rifiutata
task_id = resp.json()["data"]["taskId"]
print("Attività creata:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("Salvato hero.png")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Attività non riuscita: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving — continua il polling

Le generazioni a 2k di solito si completano in uno o due minuti; un intervallo di polling di 5 secondi è sufficiente.

I parametri che esistono davvero

Lo schema di input è rigoroso — i campi sconosciuti falliscono con 400 INVALID_REQUEST: additional properties not allowed, invece di essere ignorati silenziosamente. È una buona cosa: gli errori di battitura non passano in produzione. Ambito completo dell'interfaccia:

Campo	Obbligatorio	Valori	Predefinito
input.prompt	Sì	Testo libero	—
input.aspect_ratio	No	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	1:1
input.resolution	No	1k, 2k (solo minuscolo)	1k
input.output_format	No	jpeg, png, webp	jpeg

Tre cose da sapere prima di costruirci sopra:

• "quality" nel nome è un livello, non un parametro. Potresti vedere questo modello descritto come dotato di dettagli, materiali e illuminazione più ricchi — è la variante del modello stessa. Non ci sono campi rich_detail, quality o style da attivare.
• 1k e 2k hanno prezzi a livelli diversi. Schema comune: iterare sul prompt a 1k, poi rieseguirlo a 2k con il prompt vincente per generare il materiale finale. I prezzi attuali per immagine sono nella pagina dei prezzi di hiapi.
• Niente n, niente seed, niente negative_prompt. Un'attività genera un'immagine. Per varianti, invia più attività in parallelo — sono indipendenti e accodate in concorrenza.

Note per la produzione: callback, idempotenza ed errori

In produzione preferisci i callback al polling. Passa callback al livello superiore del corpo della richiesta (non dentro input), e hiapi chiamerà il tuo servizio quando l'attività raggiunge lo stato terminale:

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

Con when: "final" riceverai notifica sia per success che per fail, quindi deduplica per taskId dal tuo lato. Mantieni un polling a bassa frequenza come fallback in caso di callback persi — l'endpoint di dettaglio attività è sempre la fonte di verità.

Rendi sicuri i retry con Idempotency-Key. La creazione dell'attività accetta l'header Idempotency-Key (massimo 255 byte). Riprovare con la stessa key non crea mai attività duplicate — la ripetizione restituisce il taskId originale:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Distingui e gestisci tre forme di errore:

1. Errore di autenticazione — HTTP 401 e {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Controlla la chiave e se ha il permesso di usare questo modello; non riprovare alla cieca.
2. Input non valido — HTTP 400 e "error_code": "INVALID_REQUEST", il messaggio indica il campo specifico (ad esempio resolution: value must be one of '1k', '2k'). Correggi il payload; riprovare con lo stesso corpo fallirà allo stesso modo.
3. Errore a livello di attività — la chiamata di creazione riesce, ma l'attività termina con status: "fail" e un oggetto data.error. Controlla error.code prima di reinviare.

Fai attenzione a expireAt. Gli URL di output sono temporanei. Scarica il file subito dopo il successo dell'attività, oppure passa storage: "persistent" alla creazione per conservare l'output a lungo termine.

Pagine correlate

• Pagina del modello grok-imagine-quality/text-to-image — area di prova e prezzi per livello
• Riferimento completo dei parametri nella documentazione
• Riferimento API di creazione attività — header, idempotenza, callback
• Come usare grok-imagine-quality image-to-image — stesso livello, modifica di immagini esistenti
• Tutti i modelli per immagini, video e musica

Domande frequenti

Qual è la differenza tra grok-imagine-quality e grok-imagine/text-to-image? Stesso endpoint, stessa struttura di richiesta, livello diverso. Il livello quality è pensato per key visual e materiali commerciali, con dettagli e illuminazione più ricchi, con prezzi per livelli di risoluzione 1k/2k; la versione standard grok-imagine/text-to-image è l'opzione più veloce ed economica per batch e ideazione.

Perché "resolution": "2K" restituisce 400? L'enumerazione è case-sensitive e in minuscolo: 1k o 2k. I valori in maiuscolo vengono rifiutati con INVALID_REQUEST.

Posso impostare dimensioni esatte in pixel come 1920x1080? No. Controlli la forma con aspect_ratio (13 opzioni, da 2:1 ultra-wide a 9:20 ultra-tall) e la nitidezza con i livelli 1k/2k. Questo modello non ha un campo size libero.

Posso generare più immagini in una sola richiesta? No — non c'è il parametro n. Invia più attività in parallelo; ogni attività restituisce il proprio taskId ed è elaborata in concorrenza.

grok-imagine-quality supporta image-to-image? Sì, con un id modello separato: grok-imagine-quality/image-to-image. Il suo schema è nella guida image-to-image — è diverso da quello text-to-image.

Quanto durano gli URL dei risultati? Ogni voce di output[] ha un timestamp Unix expireAt. Scarica prima di quella scadenza, oppure usa storage: "persistent" alla creazione dell'attività (o promuovi l'output in seguito) per conservarlo.

Come appare un'attività accodata ma non completata? GET /v1/tasks/<taskId> restituisce status pari a queued, handling o archiving, senza output ancora. Solo success contiene output scaricabile; fail contiene data.error.