Grok Videos Generation API Integrazione

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 del modello

Questa API seleziona il punto finale upstream tramite il suffisso del nome del modello: :reverse utilizza il punto finale veloce/standard (più economico), :official utilizza il punto finale ufficiale (qualità video più alta, fatturato in base ai secondi di output). Sono supportati quattro modelli:

grok-imagine-video-1.5-fast:reverse (predefinito): supporta video generati da testo (solo prompt) e video generati da immagini (passando image_url), durata 6–30 secondi, fatturato in base alla durata, il più economico.
grok-imagine-video:reverse: supporta video generati da testo e immagini, durata 1–15 secondi, fatturato in base ai secondi di output.
grok-imagine-video:official: punto finale ufficiale, supporta video generati da testo e immagini, durata 1–15 secondi, fatturato in base ai secondi di output, qualità più alta.
grok-imagine-video-1.5:official: punto finale ufficiale, supporta solo video generati da immagini, deve passare image_url, durata 1–15 secondi, supporta fino a 1080p, 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:

{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}

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:

curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'

Il codice Python corrispondente è il seguente:

import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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:

{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}

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:

{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}

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:

{
  "prompt": "Una ripresa cinematografica di un gattino che insegue una farfalla in un giardino illuminato dal sole",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}

Il risultato restituito immediatamente è il seguente:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

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 di fatturazione

Il metodo di fatturazione di questo servizio è determinato da model:

grok-imagine-video-1.5-fast:reverse: fatturazione in base alla durata, indipendentemente dalla risoluzione—6–10 secondi, 11–20 secondi, 21–30 secondi corrispondono a diversi livelli di prezzo.
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: endpoint ufficiale, fatturazione in base ai “secondi di output”, maggiore è la risoluzione, maggiore è il prezzo unitario; i modelli ufficiali verranno fatturati anche se la revisione dei contenuti fallisce.

Il prezzo unitario specifico è quello indicato nella pagina dei prezzi. Le richieste fallite non vengono fatturate e non consumano il limite gratuito.

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.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Grok Videos Generation API Integrazione

Processo di richiesta

Descrizione del modello

Utilizzo di base

Video generati da immagini

Guida tramite immagini di riferimento

Callback asincrona

Verifica del risultato del compito

Informazioni di fatturazione

Gestione degli errori

​Processo di richiesta

​Descrizione del modello

​Utilizzo di base

​Video generati da immagini

​Guida tramite immagini di riferimento

​Callback asincrona

​Verifica del risultato del compito

​Informazioni di fatturazione

​Gestione degli errori

Processo di richiesta

Descrizione del modello

Utilizzo di base

Video generati da immagini

Guida tramite immagini di riferimento

Callback asincrona

Verifica del risultato del compito

Informazioni di fatturazione

Gestione degli errori