Tutorial para principiantes de la API de video Grok Imagine

La API de video de Grok permite a los desarrolladores generar videos a partir de indicaciones de texto y, para los flujos de trabajo compatibles, también pueden usar una imagen de inicio u otras referencias. A diferencia de las respuestas de texto sincrónicas, la generación de video es asíncrona: la primera solicitud devuelve un ID de tarea, y su aplicación debe sondear hasta que el resultado esté listo.

Este tutorial explica la arquitectura y proporciona un ejemplo mínimo en Python. Si deseas evaluar la calidad visual antes de escribir código, puedes probar los prompts en el espacio de trabajo Grok Imagine de Elser AI y luego migrar las especificaciones de toma exitosas a la API.

¿Qué necesitas?

• Una cuenta de desarrollador de xAI;
• Una clave API almacenada de forma segura;
• Python 3.10 o una versión más reciente;
• el paquete requests;
• Se ha completado el almacenamiento persistente de los archivos de video;
• Estrategias de presupuesto y reintento.

Nunca codifique las claves API directamente en el código fuente ni las exponga en JavaScript del lado del navegador.

Cómo funciona el flujo de trabajo de la API

1. Envía una solicitud de generación a /v1/videos/generations.
2. Recibir un request_id.
3. Sondeo /v1/videos/{request_id}.
4. Deténgase cuando el estado cambie a done o se produzca una falla terminal.
5. Por favor, descargue el video devuelto a tiempo, ya que la URL generada es temporal.
6. Guardar metadatos, indicaciones, modelo, configuración y costos para auditoría y reproducibilidad.

Ejemplo mínimo de conversión de texto a video

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 caja de producto negra mate se abre sobre una superficie reflectante. Una luz suave de color coral ilumina el producto mientras la cámara funciona. "Acercamiento lento. Iluminación de estudio avanzada, dinámica real, sin texto." ), "duration": 6, "resolution": "720p", }

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

deadline = time.time() + 15 * 60 mientras 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()

Si el resultado["Estado"] == "Completado":
    video_url = resultado["Vídeo"]["url"]
    video_response = requests.get(video_url, timeout=180)
    video_response.raise_for_status()
    Path("output.mp4").write_bytes(video_response.content)
    print("output.mp4 guardado")
    Interrupción

Si el resultado["Estado"] En {"expired", "failed", "cancelled"}:
    raise RuntimeError(f"Generación finalizada, estado: {result['status']}")

time.sleep(5)

else: Provoca un error de tiempo de espera ("La generación de video no se completó antes de la fecha límite")

Antes de la implementación, verifique la arquitectura actual de la API de xAI. Los nombres de los modelos, los parámetros compatibles y el estado de las respuestas pueden cambiar.

## Convertir imagen a video

La documentación de xAI admite el uso de URL de imágenes públicas o URI de datos base64 para la generación centrada en imágenes. Conceptualmente, la solicitud agrega un objeto de imagen:

```python
payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Conservar el sujeto, la vestimenta y el fondo."
        "El sujeto se gira hacia la ventana, mientras la cámara avanza lentamente."
    ),
    "imagen": {"url": "https://example.com/source-image.png"},
    "duration": 6,
    "resolution": "720p",
}

Si la entrada es privada, utilice URL firmadas de corta duración. No exponga públicamente el contenido multimedia del cliente solo para cumplir con los requisitos de la API.

Manejo de errores en entorno de producción

El entorno de producción del cliente debe manejar:

• Fallo de autenticación;
• Error de verificación;
• Rechazo de revisión;
• Límite de velocidad;
• Tiempo de espera de red agotado;
• Enlaces de puestos o resultados vencidos;
• Envío duplicado;
• Fallo parcial de almacenamiento;
• Presupuesto de la cuenta agotado.

Para errores reintentables, utiliza una estrategia de retroceso exponencial con fluctuación. No reintentes indefinidamente fallos de verificación o revisión. Añade una clave de idempotencia o mantén tu propio registro de tareas para evitar que los reintentos de red provoquen duplicados de video no deseados.

Control de costos

xAI fija el precio de los videos según los segundos generados, y la tarifa varía según el modelo y la resolución. La entrada de medios también puede generar costos. Almacena el modelo, la resolución, la duración y los datos de uso devueltos de cada trabajo.

Las medidas de seguridad útiles incluyen:

• Duración máxima de cada solicitud;
• Límite de gasto diario por usuario;
• Modo de borrador de baja resolución;
• Se requiere aprobación antes de volver a renderizar en alta resolución;
• Límite de número de reintentos automáticos;
• Alerta de generación anormal de excepciones;
• Cada informe de costos de fragmentos aprobados.

Diseño de Colas y Concurrencia

Las tareas de video deben entrar en una cola. Los nodos de trabajo envían solicitudes, realizan sondeos de manera responsable y transfieren los archivos completados al almacenamiento de objetos persistente. La base de datos de su aplicación debe rastrear:

• Identificación interna del puesto;
• ID de solicitud de xAI;
• usuarios y proyectos;
• Referencia de avisos y entradas;
• Estado y progreso;
• Marca de tiempo;
• Modelo y configuración;
• URL de almacenamiento de salida;
• Costo y resultado de la auditoría.

Cumplir con los límites de velocidad del nivel de cuenta actual. No es beneficioso si demasiadas operaciones en paralelo provocan limitación de flujo o pérdida de control de costos.

Seguridad y privacidad

Verificar los permisos del usuario para cargar imágenes y las autorizaciones de las personas identificables. Hacer que el sistema rechace intentos evidentes de crear imágenes íntimas no consentidas, suplantación fraudulenta, explotación o contenido ilegal. Conservar únicamente los medios y registros necesarios para el servicio, y publicar una política clara de eliminación.

No se debe eliminar la marca de agua o identificación de la fuente del proveedor. Para contenido de alta difusión, político, médico, financiero o sensible en cuanto a identidad, se debe incluir una revisión manual.

Evaluación sin código antes de la integración de API

Una vez que las especificaciones creativas han sido validadas, los proyectos de API son más fáciles de implementar. Usa Grok Imagine Video en Elser AI para probar indicaciones, la idoneidad de las imágenes de referencia, la relación de aspecto y los criterios de aceptación de tomas. Una vez que el equipo pueda describir de manera confiable tomas utilizables, se puede automatizar la parte repetitiva.

Lista de verificación de inicio

• La clave API se almacena en el administrador de claves.
• El modelo y los parámetros actuales han sido verificados según la documentación de xAI.
• Lógica de colas, tiempos de espera, reintentos e idempotencia probada.
• Salida transferida desde una URL temporal.
• Límites de consumo por usuario y globales habilitados.
• Manejo de fallos en la revisión, sin reintentos ciegos.
• Derechos de origen y consentimiento confirmados.
• Excluir medios sensibles y credenciales del registro.
• Las reglas de marcas de agua y divulgación de IA han sido documentadas.