Come si usa l'API text-to-image di Grok Image 2.0? Genera la tua prima immagine in 5 minuti

Come si usa l'API text-to-image di Grok Image 2.0? In tre passaggi: POST /v1/tasks per creare l'attività, una volta ottenuto il taskId fai polling (o imposta un callback), poi scarichi l'immagine da data.output[0].url. $0.052 per immagine, 1K e 2K allo stesso prezzo.

Grok Image 2.0 è già disponibile su HiAPI: apri la pagina del modello per generare direttamente. I nuovi utenti ricevono 200 crediti alla registrazione, sufficienti per generare subito 1 immagine e vedere il risultato.

TL;DR

• Cos'è: grok-imagine-image-2.0/text-to-image, il modello text-to-image di xAI, che utilizza l'interfaccia unificata per attività asincrone di HiAPI.
• Quanto costa: $0.052 per immagine, stesso prezzo per 1K / 2K, low / medium e qualsiasi formato; si paga solo per le immagini generate con successo, con rimborso automatico in caso di errore. Con $10 si generano circa 192 immagini.
• Come chiamarla più rapidamente: basta un prompt per generare un'immagine; sono disponibili facoltativamente i tre parametri aspect_ratio, resolution e quality.

Quali parametri ha il text-to-image di Grok Image 2.0?

input contiene solo quattro campi:

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Stringa	Descrizione dell'immagine
aspect_ratio	No	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto	Predefinito 1:1
resolution	No	1k, 2k	Predefinito 1k
quality	No	low, medium	Predefinito medium; medium offre dettagli migliori, low è più veloce

Ogni attività genera 1 immagine; per generarne più di una, invia più attività in parallelo. Campi o valori diversi da quelli della tabella restituiscono 400 e il messaggio di errore indica il campo specifico.

Due percorsi: prova online e integrazione API

Prova online (1 minuto)

1. Apri la pagina del modello text-to-image e accedi.
2. Inserisci il prompt e scegli formato e risoluzione.
3. Fai clic su «Esegui», poi visualizza e scarica l'immagine generata quando l'attività è completata.

Integrazione API (5 minuti)

1. Crea una API Key nella console.
2. Invia l'attività con POST /v1/tasks.
3. Fai polling su GET /v1/tasks/<taskId> oppure imposta un callback.
4. In caso di successo, scarica subito data.output[0].url.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Prima ottieni un prompt che funziona: quello qui sotto genera un'immagine prodotto in 3:2. Genera con questo prompt → (proporzioni 3:2, risoluzione 2K)

curl e Python: genera la prima immagine

Imposta prima la API Key:

export HIAPI_API_KEY="sk-..."

Tutte le richieste includono Authorization: Bearer sk-<key>. La generazione di immagini è asincrona e utilizza la stessa interfaccia per attività degli altri modelli di HiAPI.

Passaggio 1, crea l'attività:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Restituisce subito il taskId:

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

Passaggio 2, fai polling fino allo stato finale:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Controlla data.status: success indica successo, fail indica errore; per gli altri stati continua ad attendere. Esempio di risposta di successo:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Attenzione a storage: "temp" e expireAt: l'URL dell'immagine è temporaneo, quindi scaricala subito dopo il completamento dell'attività oppure trasferiscila nel tuo object storage.

Versione Python:

Installa prima requests (python3 -m pip install requests) e imposta la HIAPI_API_KEY come sopra. Lo script esegue il polling per un massimo di 10 minuti; dopo il timeout, conserva il taskId per continuare a interrogarlo.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

A cosa fare attenzione prima della messa in produzione?

• Per le elaborazioni in batch usa i callback, non un ciclo di polling serrato. Includi callback alla creazione dell'attività: al termine, HiAPI invierà una notifica al tuo indirizzo:

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

  when: "final" notifica quando l'attività raggiunge lo stato finale di successo o errore; il destinatario deve deduplicare in base al taskId. Usa il polling per le pagine interattive e i callback per l'elaborazione in batch.

• Trasferisci subito l'immagine generata. data.output[0].url è un indirizzo temporaneo che scade in base a expireAt.

• Invia ogni attività una sola volta. Dopo aver ricevuto la risposta, salva la corrispondenza tra taskId e l'attività di business; invii duplicati possono creare più attività e addebiti separati. Se la richiesta di creazione va in timeout senza restituire l'ID, verifica prima i record delle attività e poi decidi se reinviare.

• Specifica esplicitamente resolution. Il valore predefinito è 1k; poiché 1K e 2K costano lo stesso, per le immagini finali passa direttamente "resolution": "2k".

• Usa quality: low per mettere a punto i prompt. Stesso prezzo e risposta più rapida; passa a medium solo per la versione definitiva.

• Gestione degli errori. Controlla prima lo stato HTTP e i campi code e message della risposta, poi leggi data. In caso di errori di parametri o autenticazione, correggi e reinvia; quando l'attività restituisce fail, registra l'errore e interrompi il polling.

Letture correlate

• Quanto costa l'API di Grok Image 2.0? Text-to-image a $0.052 per immagine, 2K senza sovrapprezzo
• Prompt per il text-to-image di Grok Image 2.0: 5 scenari da copiare per generare subito
• Integrazione dell'API image-to-image di Grok Image 2.0: modificare un'immagine con un singolo riferimento
• Grok Image 2.0 vs GPT Image 2: confronto con lo stesso prompt
• Autenticazione e Guida rapida

Domande frequenti

Come si scrive l'ID del modello? Scrivi per intero grok-imagine-image-2.0/text-to-image, mantenendo il numero di versione 2.0 e /text-to-image.

Cosa fare se viene restituito "additional properties not allowed"? input accetta solo i quattro campi prompt, aspect_ratio, resolution e quality; i campi comuni ad altri modelli come size, n, seed, negative_prompt e output_format non sono supportati qui: rimuovili.

Si possono generare più immagini in una volta? No, ogni attività genera 1 immagine. Se ne servono di più, invia più attività in parallelo.

Per quanto tempo è valido l'URL di output? Lo storage è temporaneo; expireAt nella risposta è un timestamp Unix. Scarica o trasferisci l'immagine subito dopo il completamento dell'attività.

Bisogna attendere il risultato in modo sincrono? No. L'interfaccia di creazione restituisce la risposta immediatamente dopo l'accodamento dell'attività; per script brevi usa il polling su GET /v1/tasks/<taskId>, in produzione imposta callback.

Le attività fallite vengono addebitate? No, si paga solo per le immagini generate con successo, con rimborso automatico in caso di errore. Quando data.status è fail, interrompi il polling.

Genera ora la tua prima immagine

Imposta prima HIAPI_API_KEY, crea l'attività con il comando curl sopra e interroga con il data.taskId restituito; quando l'attività è completata, scarica da data.output[0].url. Se vuoi prima vedere il risultato, apri la pagina del modello text-to-image: i 200 crediti in omaggio alla registrazione bastano per 1 immagine.