> ## 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 Integración

> Grok API guide - Ace Data Cloud

Este documento presentará la integración de la API de Generación de Videos de Grok, que puede generar videos de Grok Imagine (xAI) a través de la entrada de texto, imágenes y, opcionalmente, imágenes de referencia.

## Proceso de Solicitud

Para usar la API de Generación de Videos de Grok, primero dirígete a [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) para obtener tu Token de API, que debes guardar para uso futuro.

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

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual.

**Un Token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno para cada servicio.** La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito se agota, puedes recargar el saldo general en [la consola](https://platform.acedata.cloud/console/coin).

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

## Descripción del Modelo

Esta API selecciona el punto final superior a través del sufijo del nombre del modelo: `:reverse` utiliza el punto final rápido/estándar (más barato), `:official` utiliza el punto final oficial (mayor calidad de imagen, facturación por segundos de salida). Se admiten cuatro modelos:

* `grok-imagine-video-1.5-fast:reverse` (predeterminado): admite videos generados a partir de texto (solo se pasa `prompt`) y videos generados a partir de imágenes (se pasa `image_url`), duración de 6 a 30 segundos, facturación por duración, el más barato.
* `grok-imagine-video:reverse`: admite videos generados a partir de texto y de imágenes, duración de 1 a 15 segundos, facturación por segundos de salida.
* `grok-imagine-video:official`: punto final oficial, admite videos generados a partir de texto y de imágenes, duración de 1 a 15 segundos, facturación por segundos de salida, mayor calidad de imagen.
* `grok-imagine-video-1.5:official`: punto final oficial, **solo admite videos generados a partir de imágenes**, **debe** pasar `image_url`, duración de 1 a 15 segundos, admite hasta `1080p`, facturación por segundos de salida.

## Uso Básico

Primero, comprende la forma básica de uso, ingresando el texto de aviso `prompt`, el modelo `model` y otros parámetros, podrás generar el video correspondiente.

Aquí podemos ver que hemos configurado los Encabezados de Solicitud, que incluyen:

* `accept`: el formato de respuesta que deseas recibir, aquí se establece como `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.

Además, se ha configurado el Cuerpo de Solicitud, que incluye:

* `prompt`: texto que describe el contenido del video que deseas generar. **Obligatorio** al hacer videos generados a partir de texto; opcional al pasar `image_url`.
* `model`: el modelo para generar el video, puede ser `grok-imagine-video-1.5-fast:reverse` (predeterminado), `grok-imagine-video:reverse`, `grok-imagine-video:official` o `grok-imagine-video-1.5:official`.
* `image_url`: enlace de la imagen de entrada para videos generados a partir de imágenes. **Obligatorio** cuando `model` es `grok-imagine-video-1.5:official`.
* `reference_image_urls`: array de enlaces de imágenes de referencia opcionales, utilizados para guiar el estilo o contenido del video.
* `aspect_ratio`: relación de aspecto del video generado, puede ser `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`.
* `resolution`: resolución de salida, puede ser `480p` (predeterminado), `720p` o `1080p`.
* `duration`: duración del video generado (segundos). `grok-imagine-video-1.5-fast:reverse` tiene un rango de 6 a 30, los demás modelos tienen un rango de 1 a 15, predeterminado 6. Se recomienda usar 6 segundos o 10 segundos, estas dos duraciones estándar son relativamente estables.
* `callback_url`: dirección de callback asíncrona, al configurarla, la API devolverá inmediatamente `task_id`, y cuando la tarea esté completa, enviará el resultado a esa dirección.
* `async`: opcional, si se establece en `true`, la interfaz devolverá inmediatamente `task_id`, sin necesidad de proporcionar `callback_url`, y luego podrás consultar el resultado a través de la interfaz de consulta de tareas correspondiente.

Haz clic en el botón "Try" para realizar pruebas, y el resultado obtenido será similar al siguiente:

```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"
    }
  ]
}
```

El resultado devuelto tiene varios campos, que se describen a continuación:

* `success`: indica si la solicitud de generación de video fue exitosa.
* `task_id`: ID de la tarea de generación de video.
* `trace_id`: ID de seguimiento de la solicitud, utilizado para resolver problemas.
* `data`: lista de resultados de video generados.
  * `id`: identificador único del video generado.
  * `video_url`: dirección del enlace del video generado.
  * `state`: estado de la tarea de generación de video, puede ser `pending` / `succeeded` / `failed`.

Solo necesitamos obtener el video generado a través de la dirección del enlace `video_url` en `data`.

El código CURL correspondiente es el siguiente:

```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
}'
```

El código Python correspondiente es el siguiente:

```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)
```

## Videos Generados a partir de Imágenes

Si deseas generar un video basado en una imagen de entrada, puedes pasar `image_url`. Al usar `grok-imagine-video-1.5:official`, este campo debe ser proporcionado:

```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
}
```

## Guía de Imágenes de Referencia

Si deseas utilizar una o más imágenes de referencia para guiar el estilo o contenido del video, puedes pasar un array de enlaces de imágenes en `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 Asíncrono

La generación de video requiere un tiempo de procesamiento. Si no desea mantener una conexión larga esperando, puede pasar `callback_url`, en este caso, la API devolverá inmediatamente `task_id`, y una vez que la tarea esté completa, enviará el resultado final a esa dirección:

```json theme={null}
{
  "prompt": "Una toma cinematográfica de un gatito persiguiendo una mariposa en un jardín iluminado por el sol",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

El resultado devuelto inmediatamente es el siguiente:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## Consulta de resultados de tareas

Si se utilizó una devolución de llamada asíncrona o se desea consultar activamente el estado de la tarea, se puede consultar el estado y resultado más reciente de la tarea a través de [Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks) (`POST https://api.acedata.cloud/grok/tasks`) según `task_id`.

## Descripción de facturación

El método de facturación de este servicio está determinado por `model`:

* `grok-imagine-video-1.5-fast:reverse`: facturación por duración, sin relación con la resolución — `6–10` segundos, `11–20` segundos, `21–30` segundos corresponden a diferentes precios por tramos.
* `grok-imagine-video:reverse`: facturación por "segundos de salida", precio total = precio unitario × `duration`.
* `grok-imagine-video:official` y `grok-imagine-video-1.5:official`: punto final oficial, facturación por "segundos de salida", a mayor resolución, mayor precio unitario; el modelo oficial cobrará incluso si la revisión de contenido falla.

El precio unitario específico se basa en la página de precios. Las solicitudes fallidas no se facturan y no ocupan el límite gratuito.

## Manejo de errores

Cuando hay un problema con la solicitud, la API devolverá el código de error correspondiente y la descripción, los más comunes son:

* `400`: Parámetros de solicitud incorrectos, por ejemplo, falta `prompt` en video generado, o falta `image_url` en `grok-imagine-video-1.5:official`, o `duration` fuera de rango (para `grok-imagine-video-1.5-fast:reverse` es 6–30, para otros modelos es 1–15).
* `401`: Fallo de autenticación, token inválido o no coincide con la API.
* `403`: Saldo insuficiente, o la palabra clave activó la revisión de contenido y fue rechazada.
* `429`: Solicitudes demasiado frecuentes, por favor intente de nuevo más tarde.
* `500`: Fallo en la generación de video o error en el servicio.


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