Guía de inicio rápido de Imagen y Video

La API de Imagen y Video es asíncrona. Envías una generación y, cuando termina, descargas el resultado desde una URL firmada. Las imágenes y los vídeos tienen rutas de API independientes, pero las estructuras de solicitud y respuesta son las mismas para ambos.

Hay dos formas de obtener el resultado. La entrega mediante webhook es la recomendada y la que usan los ejemplos siguientes: ElevenLabs llama a tu ruta de API en cuanto una generación alcanza un estado final, por lo que no se pierde tiempo esperando. El sondeo es la alternativa si no tienes una ruta de API para recibir una devolución de llamada, y cada ejemplo muestra cómo recurrir a él.

Genera una imagen

ELEVENLABS_API_KEY=<your_api_key_here>

pip install elevenlabs
pip install python-dotenv

# example.py
import os
from dotenv import load_dotenv
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
        aspect_ratio="16:9",
        resolution="2K",
        webhook=WebhookTarget_All(),
    )
)
print(generation.id, generation.status)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}

import time
import requests
while True:
    result = elevenlabs.flows.image.get(generation.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(2)
if result.status == "failed":
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")
with open("corgi.png", "wb") as f:
    f.write(requests.get(result.content_url).content)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}

python example.py

Genera un vídeo

Las generaciones de vídeo usan flows.video y siguen el mismo patrón de envío y recogida. Un vídeo puede tardar varios minutos, así que este ejemplo usa la entrega mediante webhook con webhook en lugar de esperar el resultado.

from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All
generation = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
        duration_secs=8,
        aspect_ratio="16:9",
        resolution="1080p",
        generate_audio=True,
        webhook=WebhookTarget_All(),
    )
)
print(generation.id)

La llamada devuelve el control en cuanto la generación se pone en cola, y el resultado terminado se entrega a todos los webhooks de tu espacio de trabajo suscritos a eventos de generación. La salida de vídeo es MP4, por lo que la carga completada informa de un content_mime_type de video/mp4. Consulta los webhooks de Imagen y Video para configurar un webhook e implementar el controlador que recibe este evento.

Recopilar resultados

Los webhooks y el polling devuelven la misma carga útil, así que la elección depende de cómo esperas a recibirla, no de lo que recibes.

Usa webhooks siempre que puedas. Recurre al polling cuando no tengas dónde recibir una devolución de llamada y, cuando lo hagas, sigue los intervalos que indicamos a continuación.

Elegir destinos de webhook

webhook acepta dos formatos. WebhookTarget_All llega a todos los webhooks suscritos a eventos de generación, que es la opción predeterminada adecuada porque sigue funcionando aunque los webhooks se roten o sustituyan. WebhookTarget_Ids limita la entrega a webhooks específicos, para cuando un espacio de trabajo distribuye a varios consumidores y un trabajo concreto solo debe llegar a uno de ellos:

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

Todos los ID ya deben estar suscritos a eventos de generación; indicar un webhook no suscrito se rechaza en lugar de ignorarse sin aviso. La carga útil entregada es idéntica a la que devuelve la ruta de API GET, así que un controlador creado para uno sirve para el otro. La guía sobre webhooks explica cómo configurar un webhook, verificar la firma y gestionar el evento.

Pautas para el polling

El tiempo de ejecución de una generación depende del modelo, la resolución y, en el caso del vídeo, la duración, así que haz polling a un intervalo adaptado a lo que has solicitado, en lugar de hacerlo en un bucle fijo:

• Imágenes: no hagas polling más de una vez cada 2 segundos. La mayoría terminan en unos segundos.
• Vídeo: no hagas polling más de una vez cada 10 segundos. Espera minutos, no segundos, y ajusta el intervalo según duration_secs y resolution.

Hay dos reglas para ambos casos. Aumenta el intervalo si una generación tarda mucho — duplicarlo hasta aproximadamente un minuto evita que una generación lenta se convierta en cientos de solicitudes. Y establece un límite para el bucle, para que una generación bloqueada termine como un tiempo de espera en tu propio código en lugar de como un bucle ilimitado.

Hacer polling más rápido no aporta nada: el estado de una generación no cambia antes porque lo hayas consultado dos veces. Un polling agresivo y continuado puede devolver respuestas 429, que debes gestionar con una espera exponencial.

Ciclo de vida de una generación

Una generación pasa por cuatro estados. Los dos estados finales contienen campos distintos, así que depende de status antes de leer el resto de la respuesta.

Gestionar errores

Una generación fallida informa de una categoría failure_reason junto con un error_message legible para las personas:

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

Las generaciones fallidas no se cobran. Los problemas de parámetros que pueden detectarse de antemano — un campo no compatible, un valor fuera del rango permitido de un modelo o una combinación no válida de entradas de referencia — se rechazan en la solicitud de creación antes de que comience ninguna generación.

Precios

Las generaciones se cobran en créditos. El coste depende del modelo, de los parámetros que elijas, como la resolución y la duración, y de las entradas que proporciones. Una generación cuesta lo mismo mediante la API que en la app de ElevenLabs, donde se muestra el coste antes de enviarla. Consulta Imagen y Video en el playground para saber cómo se presenta el coste de una combinación concreta de modelo y ajustes.

Consulta tus generaciones

Cada ruta de API enumera las generaciones creadas a través de ella, empezando por las más recientes. Los resultados se limitan a tu espacio de trabajo y a esta API, por lo que las generaciones creadas en la app de ElevenLabs no aparecen.

page = elevenlabs.flows.image.list(page_size=20, status="completed")
for item in page.generations:
    print(item.id, item.content_url)
while page.has_more:
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
    for item in page.generations:
        print(item.id, item.content_url)

page_size acepta valores de 1 a 100 y el valor predeterminado es 30. Pasa status para devolver solo las generaciones en un estado del ciclo de vida y model_id para devolver solo las generaciones de un único modelo. Trata next_cursor como un valor opaco: devuelve el valor exacto y detente cuando has_more sea false.

Modelos disponibles

La API expone un subconjunto de los modelos disponibles en la app de ElevenLabs. Cada modelo acepta solo los parámetros indicados para él; enviar un campo compatible con otro modelo devuelve un error de validación.

Modelos de imagen

Los modelos GPT Image 2.5 aceptan los valores low, medium, high, xhigh y max para quality, y el valor predeterminado es high. GPT Image 2 llega hasta high y el valor predeterminado es medium.

Modelos de vídeo

Para consultar las capacidades, la disponibilidad y los precios de los modelos, consulta la visión general de Imagen y Video.

Próximos pasos