Vai al contenuto principale
Questo documento introduce l’integrazione dell’API Grok Videos Generation, che può generare video Grok Imagine (xAI) tramite input di testo, immagini e immagini di riferimento opzionali.

Processo di richiesta

Per utilizzare l’API Grok Videos Generation, prima vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno per ogni servizio. La prima richiesta offre un credito gratuito per un’esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: Grok Videos Generation API →

Descrizione dei modelli

È possibile selezionare i seguenti quattro modelli pubblici tramite model. Le funzionalità specifiche e le modalità di fatturazione sono le seguenti:
  • grok-imagine-video-1.5-fast:reverse (predefinito): supporta la generazione di video da testo (passando solo prompt) e la generazione di video da immagini (passando image_url), con durata da 6 a 30 secondi. La fatturazione è a fasce in base alla durata ed è l’opzione più economica.
  • grok-imagine-video:reverse: supporta la generazione di video da testo e da immagini, con durata da 1 a 15 secondi, e viene fatturato in base ai secondi di output.
  • grok-imagine-video:official: supporta la generazione di video da testo e da immagini, con durata da 1 a 15 secondi, e viene fatturato in base ai secondi di output; offre una qualità video superiore.
  • grok-imagine-video-1.5:official: supporta solo la generazione di video da immagini. È obbligatorio passare image_url; la durata va da 1 a 15 secondi, supporta fino a 1080p e viene fatturato in base ai secondi di output.

Utilizzo di base

Iniziamo a comprendere le modalità di utilizzo di base, passando i parametri come prompt, model, ecc., per generare il video corrispondente. Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:
  • accept: il formato di risposta desiderato, qui impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • prompt: il testo descrittivo per il contenuto del video da generare. Obbligatorio per i video generati da testo; opzionale quando si passa image_url.
  • model: il modello per generare il video, può essere grok-imagine-video-1.5-fast:reverse (predefinito), grok-imagine-video:reverse, grok-imagine-video:official o grok-imagine-video-1.5:official.
  • image_url: il link all’immagine di input per i video generati da immagini. Obbligatorio quando model è grok-imagine-video-1.5:official.
  • reference_image_urls: array di link a immagini di riferimento opzionali, utilizzati per guidare lo stile o il contenuto del video.
  • aspect_ratio: il rapporto d’aspetto del video generato, può essere 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution: risoluzione di output, può essere 480p (predefinito), 720p o 1080p.
  • duration: durata del video generato (secondi). grok-imagine-video-1.5-fast:reverse ha un intervallo di valori da 6 a 30, gli altri modelli hanno un intervallo di valori da 1 a 15, predefinito 6. Si consiglia di utilizzare 6 secondi o 10 secondi, queste due durate standard sono relativamente stabili.
  • callback_url: indirizzo di callback asincrono, una volta impostato, l’API restituirà immediatamente task_id, e al termine del compito, il risultato verrà inviato a tale indirizzo.
  • async: opzionale, impostato su true, l’interfaccia restituirà immediatamente task_id, senza necessità di fornire callback_url, successivamente si può ottenere il risultato tramite polling all’interfaccia di query del compito corrispondente.
Cliccando sul pulsante “Try” è possibile effettuare un test, e il risultato ottenuto sarà simile al seguente:
Il risultato restituito contiene diversi campi, descritti come segue:
  • success: indica se la richiesta di generazione del video è andata a buon fine.
  • task_id: ID del compito di generazione del video.
  • trace_id: ID di tracciamento della richiesta, utilizzato per la risoluzione dei problemi.
  • data: elenco dei risultati video generati.
    • id: identificatore unico del video generato.
    • video_url: indirizzo del link al video generato.
    • state: stato del compito di generazione del video, può essere pending / succeeded / failed.
Dobbiamo solo ottenere il video generato in base all’indirizzo video_url presente in data. Il codice CURL corrispondente è il seguente:
Il codice Python corrispondente è il seguente:

Video generati da immagini

Se desideri generare un video basato su un’immagine di input, puoi passare image_url. Quando utilizzi grok-imagine-video-1.5:official, è necessario fornire questo campo:

Guida tramite immagini di riferimento

Se desideri utilizzare una o più immagini di riferimento per guidare lo stile o il contenuto del video, puoi passare un array di link a immagini in reference_image_urls:

Callback asincrona

La generazione di video richiede un certo tempo di elaborazione. Se non si desidera mantenere una connessione lunga in attesa, è possibile fornire callback_url, in tal caso l’API restituirà immediatamente task_id, e una volta completato il compito, invierà il risultato finale a quell’indirizzo:
Il risultato restituito immediatamente è il seguente:

Verifica del risultato del compito

Se si utilizza un callback asincrono o si desidera controllare attivamente lo stato del compito, è possibile utilizzare Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) per controllare lo stato e il risultato più recenti del compito in base a task_id.

Informazioni sulla fatturazione

La modalità di fatturazione di questo servizio è determinata da model:
  • grok-imagine-video-1.5-fast:reverse: fatturazione a fasce in base alla durata, indipendente dalla risoluzione: 6–10 secondi, 11–20 secondi e 21–30 secondi corrispondono rispettivamente a fasce di prezzo diverse.
  • grok-imagine-video:reverse: fatturazione in base ai “secondi di output”; prezzo totale = prezzo unitario × duration.
  • grok-imagine-video:official e grok-imagine-video-1.5:official: fatturazione in base ai “secondi di output”; maggiore è la risoluzione, maggiore è il prezzo unitario. I modelli ufficiali vengono fatturati anche se la moderazione dei contenuti non viene superata.
Per i prezzi unitari specifici, fare riferimento alla pagina dei prezzi. Le richieste non riuscite non vengono fatturate e non consumano la quota gratuita.

Gestione degli errori

Quando si verifica un problema con la richiesta, l’API restituirà il codice di errore corrispondente e la spiegazione, i più comuni sono i seguenti:
  • 400: parametri della richiesta errati, ad esempio il video generato manca di prompt, o grok-imagine-video-1.5:official manca di image_url, o duration è fuori dal range (grok-imagine-video-1.5-fast:reverse è 6–30, gli altri modelli sono 1–15).
  • 401: autenticazione fallita, token non valido o non corrispondente all’API.
  • 403: saldo insufficiente, o il prompt ha colpito un rifiuto della revisione dei contenuti.
  • 429: richiesta troppo frequente, riprovare più tardi.
  • 500: generazione video fallita o servizio anomalo.