> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Videos Generation API Integrazione

> Grok API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentazione completa: [Grok Videos Generation API →](https://platform.acedata.cloud/documents/grok-videos)

## 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:

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/grok-tasks) (`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.