Come usare l'API Grok Imagine per il text-to-video: curl, Python e una richiesta eseguibile

Grok Imagine è il modello di generazione video di xAI, e HiAPI espone la sua variante text-to-video sullo stesso endpoint asincrono unificato di tutti gli altri modelli di generazione: POST /v1/tasks. Invii un prompt (più durata, modalità, proporzioni e risoluzione opzionali), ricevi immediatamente un taskId e ottieni un URL .mp4 al completamento dell'attività.

Questa guida è il percorso più breve verso una richiesta eseguibile: lo schema di input esatto (verificato sull'API live, inclusi gli errori 400 che si incontrano quando si indovina male il nome di un campo), un flusso curl da copiare e incollare, un piccolo client Python con polling e il pattern di callback che useresti in produzione.

Cosa costruirai e cosa ti serve

Obiettivo: trasformare un prompt testuale in una clip video di 6–30 secondi tramite grok-imagine/text-to-video, completamente via HTTP.

Ti serve una sola cosa: una chiave API HiAPI. Creane una nella dashboard di HiAPI — una singola chiave funziona con tutti i modelli, quindi se hai già chiamato modelli di immagini su HiAPI, la stessa chiave vale anche qui. Le richieste si autenticano con l'header bearer standard:

Authorization: Bearer sk-<your-key>

Lo schema di input (prima di scrivere qualsiasi codice)

L'API delle attività valida rigorosamente input in base al modello — i campi sconosciuti vengono rifiutati con 400, non ignorati silenziosamente. Ecco lo schema completo di grok-imagine/text-to-video:

Campo	Tipo	Obbligatorio	Valori	Predefinito
prompt	string	Sì	Fino a 5000 caratteri, funziona meglio in inglese	—
duration	integer	No	6–30 (secondi)	6
mode	enum	No	fun, normal	normal
aspect_ratio	enum	No	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	No	480p, 720p	480p

Tre cose da sapere in anticipo:

• mode è l'interruttore della "modalità di movimento". normal è bilanciato; fun produce un movimento più creativo ed esagerato. Se altrove hai visto descrivere le modalità di Grok Imagine con altri nomi, il parametro API è mode — inviare qualcosa come motion_mode ti restituirà 400 additional properties 'motion_mode' not allowed.
• duration influisce linearmente sul costo. Grok Imagine fattura sui secondi di output, quindi una clip di 30 secondi costa 5 volte una di 6 secondi. Per la tariffa attuale al secondo vedi la pagina dei prezzi di HiAPI.
• Il rapporto d'aspetto predefinito è 2:3 (verticale). Se vuoi il widescreen, passa esplicitamente 16:9 — questo dettaglio coglie di sorpresa chi migra da modelli con orientamento orizzontale predefinito.

I valori fuori intervallo falliscono rapidamente con un messaggio descrittivo, ad esempio duration: 31 restituisce:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Esempio minimo eseguibile: curl

Due chiamate: crea l'attività, poi esegui il polling.

1. Crea l'attività:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Nota che l'id del modello è la stringa nuda grok-imagine/text-to-video — nessun prefisso del provider, nessun suffisso di versione.

2. Esegui il polling fino allo stato terminale:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

L'URL .mp4 è temporaneo — expireAt è un timestamp Unix circa una settimana dopo. Scarica i byte immediatamente dopo il successo dell'attività e rendili persistenti tu stesso; non fare hotlink degli URL temp.hiapi.ai da alcuna parte rivolta all'utente. (Se ti è mai capitato un link di output scaduto, la causa è qui — vedi URL di output hiapi scaduto: scarica prima della scadenza.)

Python: un piccolo client con polling

Uno script riutilizzabile per lo stesso flusso — crea, esegui polling con scadenza, scarica:

# pip install requests
import os
import time

import requests

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


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.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 = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.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} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

Una clip di 6 secondi di solito termina ben prima della scadenza di 15 minuti indicata sopra; durate più lunghe richiedono proporzionalmente più tempo, quindi mantieni questo timeout generoso per le attività da 30 secondi.

Considerazioni per la produzione

Usa i callback invece del polling. Per qualsiasi scenario al di fuori di uno script, passa un oggetto callback di primo livello al momento della creazione e HiAPI invierà via POST lo stato terminale dell'attività al tuo endpoint — nessun ciclo di polling da sorvegliare:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when accetta solo "final" (ricevi un POST quando l'attività raggiunge success o fail, non progressi incrementali). Regola empirica: il polling va bene per CLI, job batch e qualsiasi scenario di breve durata; i callback vanno bene per i backend web, dove altrimenti occuperesti la capacità dei worker con rendering di più minuti. Se il tuo endpoint di callback sembra non ricevere nulla, indaga perché il tuo callback di attività hiapi non viene attivato.

Idempotenza. La creazione di attività non è idempotente — riprovare una richiesta di creazione andata in timeout può generare due attività fatturate. Registra il taskId nel momento stesso in cui lo ottieni e, in caso di fallimento ambiguo (timeout di rete durante la creazione), controlla la cronologia delle attività prima di inviare di nuovo. Poiché duration è fatturata al secondo, un'attività duplicata da 30 secondi è il tipo costoso di duplicato.

Gestione degli errori. Le due categorie di errori che vedrai davvero:

• Errori 400 di schema (error_code: "INVALID_REQUEST") — nome del campo errato, durata fuori intervallo, valore enum non valido. Sono deterministici; correggi la richiesta, non riprovare.
• Errori di autenticazione — una chiave non valida o una chiave senza accesso a questo modello restituisce 401, con "code": "permission_denied" e il messaggio "This API key cannot use the selected model." Controlla la chiave nella dashboard e verifica che il modello sia abilitato per essa.
• Fallimenti a livello di attività — la creazione riesce, ma l'attività passa poi allo stato terminale status: "fail" con un oggetto error (policy sui contenuti, capacità upstream). Vale la pena riprovare una volta con backoff. Se un'attività sembra bloccata su handling, vedi diagnosticare job /v1/tasks bloccati o in timeout.

Prossimi passi

• Pagina del modello Grok Imagine text-to-video — playground e prezzi attuali
• Riferimento input del modello — lo schema canonico di questo modello
• Creare un'attività e ottenere i dettagli di un'attività — l'involucro completo dell'API asincrona
• Avvio rapido — completa la tua prima chiamata HiAPI end-to-end, e autenticazione per la gestione delle chiavi

FAQ

Cos'è l'API Grok Imagine e come vi accedo? Grok Imagine è il modello di generazione video di xAI. Tramite HiAPI lo chiami come grok-imagine/text-to-video sull'endpoint unificato POST /v1/tasks usando una singola chiave HiAPI — nessun account xAI separato né SDK.

Quanto può essere lungo un video Grok Imagine? duration accetta numeri interi da 6 a 30 secondi (predefinito 6). I valori fuori da questo intervallo vengono rifiutati con 400 al momento della creazione; la fatturazione si basa sui secondi di output.

Qual è la differenza tra le modalità fun e normal? normal (predefinita) offre un movimento bilanciato e realistico; fun tende di più al creativo e all'esagerato. È l'unico interruttore di stile di movimento esposto dall'API — si sceglie per richiesta, non per account.

grok-imagine/text-to-video supporta il 1080p? Attualmente no — resolution accetta 480p (predefinito) o 720p. Se ti serve una risoluzione di output più alta, esegui l'upscaling a valle oppure confronta altri modelli video nella pagina dei modelli.

Posso usare Grok Imagine per animare un'immagine esistente? Non con questo modello — supporta solo testo. Sullo stesso endpoint delle attività c'è un modello separato grok-imagine/image-to-video che accetta input di immagini; il ciclo di vita asincrono (crea → polling/callback → download) è identico.

C'è un livello gratuito per l'API Grok Imagine? La generazione viene fatturata sui secondi di video dal tuo saldo HiAPI — non esistono endpoint gratuiti senza chiave. Per le tariffe attuali vedi la pagina dei prezzi; per capire cosa significhi realisticamente "gratuito" in questo ambito, questo confronto delle API text-to-video gratuite copre le varie opzioni.