¿Cómo usar la API de Veo 3.1? Genera tu primer video en 5 minutos

TL;DR

• Veo 3.1 es el modelo de generación de video de Google, disponible en HiAPI en tres niveles: Standard, Fast y Lite, con texto a video e imagen a video. Abre la página del modelo para generar en línea; los nuevos usuarios reciben 200 créditos al registrarse.
• Facturación por segundo: Lite 720p sin audio $0.06 por segundo, Fast 720p/1080p con audio $0.25 por segundo, Standard $0.57 por segundo; un borrador Lite de 4 segundos cuesta solo $0.24.
• La API en dos pasos: POST /v1/tasks para enviar y obtener el taskId para consultar el resultado. El curl y Python de abajo se copian y se ejecutan directamente.

¿Qué puede hacer Veo 3.1?

• Audio nativo: imagen y sonido se generan juntos; el ambiente, los efectos de sonido y los ruidos de la acción siguen a la imagen; generate_audio está activado por defecto, desactivarlo es más económico.
• Tres duraciones: 4, 6 y 8 segundos, en horizontal 16:9 o vertical 9:16.
• Hasta 4K: Standard y Fast admiten 720p, 1080p y 4K; Lite admite 720p y 1080p.
• Imagen a video: sube una imagen como primer fotograma y el modelo la anima; la relación de aspecto puede seguir a la imagen original.

Este video vertical de 6 segundos en 1080p se generó con una sola solicitud a partir de una imagen de producto de una zapatilla; el golpe sordo del aterrizaje y el pulso de bombo los añadió el propio modelo:

The sneaker slowly rotates about 90 degrees as the camera pushes in from a low angle. Dust particles drift through the rim light. The shoe settles onto the wet stone pedestal with a deep, satisfying thud, sending a soft ring of mist rolling off the edges. A warm light sweep travels across the suede texture. Subtle bass-heavy electronic pulse builds in the background with a low whoosh on the landing. Cinematic product commercial, smooth stabilized motion, no text overlays.

Genera con este prompt → (primero sube una imagen de producto en 9:16)

veo-3.1/image-to-video, 1080p, 6 segundos, con audio, $3.42, aproximadamente 115 segundos desde el envío hasta la finalización.

¿Cómo elegir entre los tres niveles?

Nivel	720p/1080p con audio	720p/1080p sin audio	4K con audio	Recomendado para
Lite veo-3.1-lite	$0.1 (720p) / $0.14 (1080p)	$0.06 (720p) / $0.1 (1080p)	—	Ajustar prompts, borradores por lotes
Fast veo-3.1-fast	$0.25	$0.17	$0.6	Videos cortos para redes sociales
Standard veo-3.1	$0.57	$0.29	$0.86	Publicidad, videos de marca

Todas las unidades son por segundo. 8 segundos con audio: Lite 1080p $1.12, Fast $2, Standard $4.56. Para un desglose más detallado, consulta Precios de la API de Veo 3.1.

Dos rutas para empezar

Prueba en línea (sin escribir código)

1. Abre la página del modelo Veo 3.1 Lite texto a video, regístrate o inicia sesión.
2. Pega el prompt, elige la duración, la resolución y la relación de aspecto, y decide si quieres audio.
3. Haz clic en generar y descarga el video directamente cuando esté listo.

Llamada a la API

1. Crea una API Key en la consola.
2. POST https://api.hiapi.ai/v1/tasks para enviar la tarea; devuelve el taskId.
3. GET /v1/tasks/{taskId} para consultar el estado; cuando status sea success, descarga el video desde output[0].url.

curl: el primer video

Primero prueba con el Lite más económico: 4 segundos, 720p, sin audio, $0.24:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "A matte-black wireless earbud case slowly rotates on a reflective black surface under a single overhead spotlight.",
      "duration": 4,
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "generate_audio": false
    }
  }'

Respuesta:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Consultar el resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: enviar, consultar y descargar

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="veo-3.1-lite/text-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "A barista pours hot water in a slow spiral over ground coffee, steam rising in morning light",
    duration=4, resolution="720p", aspect_ratio="16:9", generate_audio=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Una vez definido el prompt, cambia model a veo-3.1-fast/text-to-video o veo-3.1/text-to-video para generar el video final; el resto de parámetros no cambia.

Imagen a video

Cambia el nombre del modelo a …/image-to-video y añade una imagen en input (image_url es una cadena y solo acepta una imagen):

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The sneaker slowly rotates and settles onto the wet stone pedestal with a deep thud",
    "image_url": "https://your-cdn.example.com/sneaker-916.jpg",
    "aspect_ratio": "auto",
    "resolution": "1080p",
    "duration": 6
  }
}

• aspect_ratio con auto sigue a la imagen original; también puedes especificar 16:9 o 9:16; las imágenes con otras relaciones de aspecto se recortan.
• Se recomienda que la imagen original sea de 720p o más, en 16:9 o 9:16; no se admite SVG.
• El prompt describe "cómo se mueve en los próximos segundos"; no hace falta volver a describir toda la imagen.

Consideraciones antes de producción

• Usa callbacks en lugar de polling: añade en el nivel superior de la solicitud "callback": {"url": "https://tu-dominio/hiapi/callback"}; HiAPI notificará activamente al finalizar la tarea; deduplica por taskId.
• Guarda el archivo a tiempo: output[0].url es un enlace temporal; guárdalo en tu propio almacenamiento en cuanto lo obtengas.
• Especifica todos los parámetros: duration es 8 segundos por defecto; resolution es obligatorio en Standard y Fast; indica explícitamente la duración, la resolución y generate_audio para que el costo coincida con el presupuesto.
• Desactiva el audio si no lo necesitas: con generate_audio: false, Lite 720p baja de $0.1 a $0.06 por segundo y Standard de $0.57 a $0.29.
• Reembolso automático en caso de fallo: solo se cobra por los videos generados correctamente.

Preguntas frecuentes

¿Se puede escribir el prompt en chino?

Sí, tanto en chino como en inglés. Escribir la cámara, la acción y el sonido en frases separadas da los resultados más estables.

¿Se puede generar un video de 10 segundos?

Cada generación solo admite 4, 6 u 8 segundos. Para videos más largos, genera por segmentos y luego edítalos.

¿Se puede controlar el audio por separado?

Puedes describir en el prompt cada capa de sonido (sonidos de acción cercanos, voces ambientales, viento) y el modelo las generará por separado; si no quieres audio, establece generate_audio en false.

Si ajusté el prompt con Lite, ¿qué debo cambiar para usar Standard?

Solo el nombre del modelo. prompt, duration, aspect_ratio y generate_audio son compatibles; si quieres 4K, cambia resolution a 4k (Lite no tiene 4K).

Si quieres prompts listos para usar, consulta Casos de prompts de Veo 3.1; también puedes copiar el prompt de la zapatilla de arriba y ir a la página del modelo para generar.