Tutoriale per principianti sull'API video Grok Imagine

L'API video di Grok consente agli sviluppatori di generare video a partire da prompt testuali e, per i flussi di lavoro supportati, di utilizzare anche un'immagine iniziale o altri riferimenti. A differenza delle risposte testuali sincrone, la generazione video è asincrona: la prima richiesta restituisce un ID attività e la tua applicazione deve eseguire il polling finché il risultato non è pronto.

Questo tutorial spiega l'architettura e fornisce un esempio minimale in Python. Se vuoi valutare la qualità visiva prima di scrivere codice, puoi testare i prompt nell'area di lavoro Grok Imagine di Elser AI, quindi trasferire le specifiche dei fotogrammi riuscite nell'API.

Di cosa hai bisogno

• Un account sviluppatore xAI;
• Una chiave API memorizzata in modo sicuro;
• Python 3.10 o versione successiva;
• pacchetto requests;
• Memorizzazione persistente dei file video completata;
• Strategia di budget e di ripetizione.

Non incorporare mai le chiavi API direttamente nel codice sorgente né esporle in JavaScript lato browser.

Come funziona il flusso di lavoro API

1. Invia una richiesta di generazione a /v1/videos/generations.
2. Ricevere un request_id.
3. Interroga /v1/videos/{request_id}.
4. Fermati quando lo stato diventa done o si verifica un guasto terminale.
5. Scarica tempestivamente il video restituito, poiché l'URL generato è temporaneo.
6. Salva metadati, prompt, modello, impostazioni e costi per audit e riproducibilità.

Esempio minimo di conversione da testo a video

OUTPUT SOLO TRADUZIONE:
import os
import time
from pathlib import Path

import requests


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

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        Una scatola di prodotto nera opaca si apre su una superficie riflettente.
        Una luce soffusa color corallo illumina il prodotto mentre la fotocamera è in funzione.
        "Movimento lento in avvicinamento. Illuminazione da set fotografico avanzato, dinamica reale, senza testo."
    ),
    "duration": 6,
    "resolution": "720p",
}

create = requests.post(
    f"{BASE_URL}/videos/generations"
    headers=HEADERS,
    json=carico,
    timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]

deadline = time.time() + 15 * 60
while time.time() < deadline:
    _status_response = requests.get(
        f"{BASE_URL}/videos/{request_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60，
    )
    status_response.raise_for_status()
    result = status_response.json()

    Se il risultato["Stato"] == "Completato":
        video_url = risultati["Video"]["url"]
        video_response = requests.get(video_url, timeout=180)
        video_response.raise_for_status()
        Path("output.mp4").write_bytes(video_response.content)
        print("Salvato output.mp4")
        Interrotto

    Se il risultato["Stato"] Tra {"expired", "failed", "cancelled"}:
        raise RuntimeError(f"Generazione terminata, stato: {result['status']}")

    time.sleep(5)
else:
    Errore di timeout ("La generazione del video non è stata completata entro la scadenza")

Prima della distribuzione, controlla l'architettura API corrente di xAI. I nomi dei modelli, i parametri supportati e lo stato delle risposte potrebbero subire modifiche.

Da immagine a video

La documentazione di xAI supporta la generazione guidata da immagini utilizzando URL di immagini pubbliche o URI di dati base64. Concettualmente, la richiesta aggiunge un oggetto immagine:

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Mantenere soggetto, abbigliamento e sfondo."
        "Il soggetto si gira verso la finestra, mentre la telecamera avanza lentamente."
    ),
    "immagine": {"url": "https://example.com/source-image.png"},
    "duration": 6,
    "resolution": "720p",
}

Se l'input è privato, utilizza URL firmati con validità breve. Non esporre pubblicamente i contenuti multimediali dei clienti solo per soddisfare i requisiti dell'API.

Gestione degli errori in produzione

L'ambiente di produzione del client dovrebbe gestire:

• Autenticazione fallita;
• Errore di validazione;
• Rifiuto della revisione;
• limiti di velocità;
• Timeout di rete;
• Collegamenti a posizioni o risultati scaduti;
• Invio duplicato;
• Guasto parziale dello storage;
• Budget del conto esaurito.

Per gli errori che possono essere ritentati, utilizza una strategia di backoff esponenziale con jitter. Non ripetere all'infinito i tentativi di verifica o di controllo. Aggiungi una chiave di idempotenza o mantieni un tuo registro delle attività per evitare che i tentativi di rete portino a duplicazioni impreviste dei video.

Controllo dei costi

xAI fissa il prezzo dei video in base ai secondi generati, con tariffe che variano a seconda del modello e della risoluzione. I supporti di input possono anche comportare costi. Per ogni lavoro vengono memorizzati il modello, la risoluzione, la durata e i dati di utilizzo restituiti.

Misure di sicurezza utili includono:

• Durata massima per ogni richiesta;
• Il limite di spesa giornaliero per ciascun utente;
• Modalità bozza a bassa risoluzione;
• È necessaria l'approvazione prima del re-rendering ad alta risoluzione;
• Limite del numero di tentativi automatici;
• Allarme per quantità anomala di generazione;
• Costo di ogni segmento approvato del report.

Progettazione di code e concorrenza

I compiti video dovrebbero entrare in coda. I nodi di lavoro inviano richieste, eseguono il polling in modo responsabile e trasferiscono i file completati in un archivio di oggetti persistente. Il database della tua applicazione dovrebbe tenere traccia di:

• ID posizione interna;
• ID richiesta xAI;
• Utenti e progetti;
• Suggerimenti e riferimenti agli input;
• Stato e avanzamento;
• timestamp;
• Modello e impostazioni;
• URL di archiviazione dell'output;
• Costo e risultato della verifica.

Rispetta i limiti di frequenza del livello dell'account corrente. Non c'è alcun vantaggio se troppe operazioni parallele causano limitazioni di flusso o costi fuori controllo.

Sicurezza e Privacy

Verifica i permessi dell'utente per le immagini caricate e le autorizzazioni per le persone identificabili. Impedisci al sistema di accettare tentativi evidenti di creare immagini intime non consensuali, impersonazioni ingannevoli, contenuti di sfruttamento o illegali. Conserva solo i media e i log necessari al servizio e pubblica una chiara politica di cancellazione.

Non rimuovere la filigrana o l'indicazione della fonte del fornitore. Per contenuti ad alta diffusione, politici, medici, finanziari o sensibili all'identità, è necessario includere una revisione manuale.

Valutazione senza codice prima dell'integrazione API

Quando le specifiche creative sono state validate, i progetti API risultano più facili da implementare. Usa Grok Imagine Video su Elser AI per testare i prompt, l'idoneità delle immagini di riferimento, le proporzioni e i criteri di accettazione delle inquadrature. Una volta che il team è in grado di descrivere in modo affidabile le inquadrature utilizzabili, è possibile automatizzare le parti ripetitive.

Lista di controllo per l'avvio

• La chiave API è memorizzata nel gestore delle chiavi.
• Il modello e i parametri correnti sono stati verificati secondo la documentazione xAI.
• Logica di coda, timeout, tentativi e idempotenza è stata testata.
• Output trasferito da un URL temporaneo.
• Limiti di consumo per utente e globali attivati.
• Gestione del fallimento della revisione, senza tentativi ciechi di riprova.
• Diritti di origine e consenso confermati.
• Esclusione di media sensibili e credenziali dai log.
• Le regole per le filigrane e la divulgazione dell'IA sono state documentate.