API per immagini Grok Imagine: testo-immagine, immagine-immagine e Quality

Punti chiave

• L'API per immagini Grok Imagine su HiAPI dispone di quattro endpoint: standard e Quality, ciascuno con testo-immagine e immagine-immagine. La struttura delle richieste è identica per tutti e quattro; cambia solo l'id del modello.
• Lo standard costa $0.03 per immagine sia a 1K che a 2K. Quality costa $0.07 a 1K e $0.10 a 2K. L'immagine-immagine applica un piccolo costo aggiuntivo per ogni immagine di riferimento (da 1 a 3 riferimenti).
• Con lo stesso prompt, lo standard ha disegnato un cono generico senza manico né alette di scanalatura; Quality ha invece prodotto un dripper per caffè filtro riconoscibile. Usa lo standard per bozze e grandi volumi, Quality per i risultati finali. Apri la pagina del modello testo-immagine e provalo; i nuovi account ricevono 200 crediti gratuiti.

Quale endpoint usare

Id modello	Input	Prezzo per immagine	Caso d'uso
grok-imagine/text-to-image	Prompt	$0.03 (1K e 2K)	Bozze, generazione in batch, banner ultra-wide
grok-imagine-quality/text-to-image	Prompt	$0.07 (1K) / $0.10 (2K)	Immagini finali di prodotto, dettagli e materiali
grok-imagine/image-to-image	Prompt + 1–3 immagini	$0.03 + $0.003 per immagine di riferimento	Inserire prodotti in una scena, ritocco in batch
grok-imagine-quality/image-to-image	Prompt + 1–3 immagini	$0.08 (1K) / $0.10 (2K) + $0.015 per immagine di riferimento	Rilluminare e cambiare stile mantenendo il soggetto perfettamente identico

Prezzi HiAPI in tempo reale, rilevati il 19 ottobre 2026. Le attività fallite non vengono addebitate.

La modifica con una singola immagine di riferimento costa $0.033 con lo standard e $0.095 con Quality 1K. Per la gamma completa, inclusi video e Grok Imagine Image 2.0, consulta Prezzi dell'API Grok Imagine.

Stesso prompt, standard vs Quality

1:1, 2K, PNG, una esecuzione ciascuno:

matte ceramic pour-over coffee dripper on a pure white seamless background, studio softbox lighting, centered, no shadow gradient beyond a soft contact shadow, no text, no watermark, no props, e-commerce product photography, sharp focus

Standard:

grok-imagine/text-to-image, 1:1, 2K, 2048×2048, $0.03, circa 80 secondi.

Quality:

Genera questo prompt su Quality →

grok-imagine-quality/text-to-image, 1:1, 2K, 2048×2048, $0.10, circa 78 secondi.

Differenze:

• L'oggetto stesso: lo standard ha reso un cono pulito ma generico, più simile a una ciotola che a un dripper. Quality ha disegnato i componenti che lo rendono un dripper per caffè filtro: le alette a spirale interne, il manico e la base con foro di drenaggio.
• Entrambi hanno rispettato i requisiti dello sfondo: bianco puro, centrato, solo una morbida ombra di contatto, senza oggetti di scena o testo.
• Dimensioni e velocità identiche: entrambi hanno restituito un'immagine 2048×2048 in circa 80 secondi. Il livello cambia il dettaglio, non le dimensioni di output.

Per prodotti noti, vale la pena spendere $0.07 in più per Quality. Per moodboard o layout in cui l'oggetto è generico, lo standard è sufficiente.

Immagine-immagine: inserisci il tuo prodotto nella scena

Passa da 1 a 3 URL pubblici di immagini in image_urls e descrivi le modifiche da apportare. Quando aspect_ratio è impostato su auto (il valore predefinito per immagine-immagine), l'output assume la forma della prima immagine della lista. Stesso prompt, stesse due immagini, solo l'ordine invertito, e si ottengono due ritagli diversi:

grok-imagine/image-to-image, immagine prodotto per prima, restituisce 1248×832 (3:2).

Stessa richiesta, immagine della scena per prima, restituisce 1024×1024 (1:1).

Per controllare il ritaglio, metti per prima l'immagine con la forma desiderata oppure imposta esplicitamente aspect_ratio.

Su Quality, il punto di forza è cambiare una cosa sola mantenendo tutto il resto invariato. Questa rilluminazione ha preservato viso, giacca, tazza e composizione:

Relight this photo as late golden hour: warm low sun coming from the left,
long soft shadows across the table, amber rim light on her hair and jacket.
Keep her face, expression, pose, the corduroy jacket, the marble table, the
coffee cup and the entire composition exactly the same. Photorealistic, same
camera angle, same framing.

grok-imagine-quality/image-to-image, 1K, auto (input 3:2, output 1248×832), un'immagine di riferimento, $0.095, 39 secondi.

Schema che funziona: una frase che indica cosa cambiare, poi l'elenco di tutto ciò che deve restare invariato. Per altre ricette, consulta Prompt per immagine-immagine Grok Imagine Quality.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "A lighthouse on a rocky cliff at golden hour, waves crashing below, photorealistic",
      "aspect_ratio": "2:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Riceverai un taskId. Esegui polling su GET https://api.hiapi.ai/v1/tasks/{taskId} finché data.status non è success, poi scarica data.output[0].url. Il link scade, quindi salva subito il file.

Python: tutti e quattro gli endpoint

# pip install requests; export HIAPI_KEY=your-key first
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, prompt, image_urls=None, timeout_s=300, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    if image_urls:
        body["input"]["image_urls"] = image_urls
    # Reuse the same Idempotency-Key if you retry a submit, so a retry never bills twice
    r = requests.post(API, json=body, headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)  # 400s list every invalid field
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

# Draft on standard, then re-run the keeper on Quality
draft = generate("grok-imagine/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="1k")
final = generate("grok-imagine-quality/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="2k")

# Composite a product into a scene; the first image sets the shape
edit = generate("grok-imagine/image-to-image",
                "Place the product from the first image on the desk in the second image, matching its light",
                image_urls=["https://your-cdn.example.com/product.jpg",
                            "https://your-cdn.example.com/scene.jpg"])

Parametri

Campo	Obbligatorio	Valori	Note
prompt	Sì	Testo	Scrivi qui tutto ciò che vuoi o vuoi evitare
image_urls	Solo immagine-immagine	1–3 URL	jpeg, png o webp; SVG non supportato; ogni immagine di riferimento aumenta il prezzo
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; immagine-immagine accetta anche auto	auto segue la prima immagine
resolution	No	1k (predefinito), 2k	minuscolo; influisce sul prezzo solo con Quality
output_format	No	jpeg (predefinito), png, webp

I formati ultra-wide 2:1 e 20:9 sono adatti ai banner. Non esiste 21:9; usa 20:9.

Errori che incontrerai

Tutti gli errori seguenti restituiscono HTTP 400 al momento dell'invio, quindi non viene creata alcuna attività e non viene addebitato nulla:

• resolution: value must be one of '1k', '2k': hai inviato 2K. Usa il minuscolo.
• aspect_ratio: value must be one of ...: di solito è 21:9. Usa 20:9.
• additional properties 'n' not allowed (o seed, negative_prompt, size): questi campi non esistono. Un'attività genera un'immagine; per più immagini invia più attività.
• image_urls: missing required field: immagine-immagine richiede almeno un'immagine.

Una chiave non valida restituisce 401. I fallimenti dopo la creazione dell'attività compaiono durante il polling come status: "fail", quindi controlla data.status, non solo il codice di stato HTTP.

Domande frequenti

Standard o Quality?

Usa lo standard per le bozze a $0.03. Una volta che prompt e layout funzionano, riesegui il risultato finale con Quality. Con lo standard 2K costa come 1K, quindi richiedi sempre 2k.

È lo stesso di Grok Imagine Image 2.0?

No. grok-imagine-image-2.0 è un modello separato e più recente, a $0.052 per immagine. Consulta la guida testo-immagine di Grok Imagine Image 2.0.

Si possono ottenere più immagini da una singola richiesta?

No. Non esiste il campo n. Invia un'attività per ogni immagine; verranno eseguite in parallelo.

Per quanto tempo è disponibile l'output?

I link output[0].url scadono. Scarica e archivia il prima possibile dopo il completamento dell'attività.

Altri output reali: immagini di catalogo prodotto con lo standard e compositing di scene da foto prodotto. Per i video, consulta la guida all'API video di Grok Imagine.