Referencias y recursos

Resumen

La mayoría de los modelos de Imagen y Video aceptan contenido multimedia junto con el prompt: un primer fotograma para un vídeo, imágenes que editar o audio con el que sincronizar los labios. Cada campo multimedia de la API recibe un objeto de referencia en lugar de bytes sin procesar con una estructura fija, y cada referencia se etiqueta con un type que indica de dónde procede el contenido.

Los tres tipos son intercambiables dondequiera que se acepte una referencia, por lo que el mismo campo puede recibir una generación en una solicitud y un recurso subido en la siguiente.

Encadena una generación con la siguiente

Una referencia generation no tiene que apuntar a una generación que haya terminado. Envía la imagen, obtén el ID de la respuesta y pásalo directamente a la solicitud de vídeo sin esperar: la API pone el vídeo en cola detrás de la imagen y lo inicia en cuanto esta termina. No se sube nada entre las dos llamadas.

Configura webhook en la última generación de la cadena y no tendrás que esperar nada. Ambas llamadas devuelven el resultado en cuanto su generación se pone en cola, todo el grafo se ejecuta en el servidor y se llama a tu ruta cuando la generación final alcanza un estado terminal.

from elevenlabs import (
    ImageGenerationRequest_Gemini3ProImage,
    ImageReference_Generation,
    VideoGenerationRequest_Veo31FastGenerate001,
    WebhookTarget_All,
)
still = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
        aspect_ratio="16:9",
    )
)
# `still` is still pending here. Submitting now queues the video behind it.
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The fog thickens and the beam sweeps across the water",
        start_frame=ImageReference_Generation(generation_id=still.id),
        duration_secs=8,
        webhook=WebhookTarget_All(),
    )
)
print(clip.id)

Solo la última generación necesita webhook. Configurarlo también en la imagen envía un evento para el resultado intermedio, lo que resulta útil para informar del progreso, pero no es necesario para ejecutar la cadena. Como en otros casos, el campo requiere un webhook suscrito a eventos de generación; consulta webhooks de Imagen y Video para configurar uno.

Si no tienes una ruta que reciba callbacks, elimina webhook y consulta el final de la cadena en su lugar. La imagen intermedia tampoco necesita consultas propias: espera una vez, en la última generación, con el intervalo correspondiente a su modalidad, que para vídeo no debe ser superior a una vez cada 10 segundos. Consulta las directrices de consulta.

import time
while True:
    result = elevenlabs.flows.video.get(clip.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(10)

Una generación que hace referencia a trabajo sin terminar se crea inmediatamente y permanece en pending hasta que termine todo aquello a lo que hace referencia, sin que tengas que hacer nada más para iniciarla. Las cadenas pueden tener cualquier profundidad y anchura: una generación puede esperar a varias referencias, cada una aún esperando a su vez, de modo que puedes enviar un grafo completo de una sola vez y recogerlo solo en sus hojas. El tiempo que pasa en cola no cuenta para el tiempo de espera de la generación.

Si falla una generación referenciada, la dependiente nunca se ejecuta: falla con el motivo dependency_failed y arrastra consigo todo lo que esté en cola detrás de ella. No se cobra nada en la cadena colapsada: una generación ya pagada se reembolsa, y otra cuyo precio depende de un resultado referenciado que aún no existe, como una sincronización labial cuyo precio depende de la duración de una generación de audio pendiente, solo se cobra cuando empieza. Un generation_id que no existe en tu espacio de trabajo se rechaza en la propia llamada de creación, por lo que una errata aparece inmediatamente en vez de como una generación fallida.

Sube contenido como recurso

Sube un archivo a la API de recursos cuando el contenido proceda de fuera de ElevenLabs y quieras reutilizarlo en varias generaciones. Los recursos pertenecen al espacio de trabajo y se conservan hasta que los eliminas.

from elevenlabs import ImageReference_Asset, VideoGenerationRequest_Veo31FastGenerate001
with open("lighthouse.png", "rb") as f:
    asset = elevenlabs.assets.create(asset=f, name="lighthouse.png")
print(asset.asset_id)
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The beam sweeps across the water as the fog thickens",
        start_frame=ImageReference_Asset(asset_id=asset.asset_id),
    )
)

La respuesta de la subida describe el recurso almacenado:

{
  "asset_id": "5xM2KqOnZyce22SPZ9d4",
  "name": "lighthouse.png",
  "mime_type": "image/png",
  "created_at_unix": 1721520000,
  "content_url": "https://storage.googleapis.com/assets/5xM2KqOnZyce22SPZ9d4"
}

content_url es una URL firmada válida durante aproximadamente una hora y tiene el valor null mientras la subida sigue procesándose. Vuelve a obtener el recurso para conseguir una URL nueva.

Límites de almacenamiento

Los recursos subidos cuentan para un límite total de almacenamiento del espacio de trabajo, que depende de tu plan:

Solo los archivos que subes cuentan para el límite; los resultados generados no. Una subida que hiciera que el espacio de trabajo superase su límite se rechaza con un error asset_storage_limit_exceeded antes de leer el archivo. Elimina recursos que ya no necesites para liberar espacio o contacta con soporte para aumentar el límite.

Gestiona recursos

Enumera los recursos del más reciente al más antiguo, opcionalmente filtrando por nombre, y pagina los resultados con el cursor de la respuesta anterior. page_size acepta de 1 a 100 y su valor predeterminado es 30.

page = elevenlabs.assets.list(page_size=20, search="lighthouse")
for asset in page.assets:
    print(asset.asset_id, asset.name, asset.mime_type)
if page.has_more:
    page = elevenlabs.assets.list(page_size=20, search="lighthouse", cursor=page.next_cursor)

Obtén o elimina un único recurso por ID. Eliminar un recurso no afecta a las generaciones que ya lo usaron.

asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4")
elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4")

Incluye contenido en línea

Una referencia inline_base64 transporta el contenido en el cuerpo de la solicitud, lo que evita una subida independiente para entradas puntuales. Codifica el archivo con el alfabeto base64 estándar e indica su tipo MIME.

import base64
from elevenlabs import ImageGenerationRequest_GptImage2, ImageReference_InlineBase64
with open("headshot.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_GptImage2(
        prompt="Replace the background with a softly lit studio backdrop",
        images=[
            ImageReference_InlineBase64(
                content_base64=encoded,
                mime_type="image/jpeg",
            )
        ],
    )
)

El contenido en línea está limitado a 25 MB por referencia tras la descodificación. Los archivos más grandes deben ir a la API de recursos, que acepta subidas mucho mayores y no tiene la penalización de tamaño de base64. Cada modalidad acepta un conjunto fijo de tipos MIME:

Campos de referencia por modelo

Los campos de referencia reciben el nombre del papel que desempeña el contenido. start_frame y end_frame son imágenes individuales que delimitan un vídeo, image y audio son las entradas necesarias de un modelo de sincronización labial, y los plurales simples images, videos y audios son material de referencia libre del que se sirve el modelo.

Los campos que acepta un modelo y las combinaciones válidas varían según el modelo. Un end_frame siempre requiere un start_frame. Incumplir una restricción devuelve un error de validación que indica el campo problemático, así que la generación nunca se inicia ni se cobra.

Veo 3.1

Ambos modelos Veo aceptan start_frame, end_frame y hasta tres entradas en images. A diferencia de otros modelos, cada entrada de images incluye la referencia junto con el papel que desempeña:

{
  "images": [
    {
      "image": { "type": "asset", "asset_id": "5xM2KqOnZyce22SPZ9d4" },
      "role": "subject"
    },
    {
      "image": { "type": "asset", "asset_id": "7pQ4LnBvXkR2mT9wYcHd" },
      "role": "style"
    }
  ]
}

Una referencia subject incorpora el sujeto o los elementos de escena de la imagen al vídeo; una referencia style transfiere su estilo visual. Las imágenes de referencia no se pueden combinar con start_frame ni end_frame, y requieren una duración de ocho segundos.

Seedance

Los tres niveles de Seedance 2.0 aceptan start_frame, end_frame, hasta 9 images, hasta 3 videos y hasta 3 audios, sujetos a estas restricciones:

• Las referencias no se pueden combinar con start_frame ni end_frame.
• El audio de referencia requiere al menos una imagen o vídeo de referencia, por ejemplo, para realizar sincronización labial.
• El número total de archivos de referencia no debe superar 12.

Seedance 2.5 aumenta los límites a 30 images, 10 videos y 10 audios sin un total combinado, y elimina la regla de que el audio de referencia necesita una imagen o vídeo que lo acompañe, por lo que se acepta una entrada de solo audio. Las referencias siguen sin poder combinarse con start_frame ni end_frame.

GPT Image

Los modelos GPT Image aceptan una mask junto con images. Las áreas completamente transparentes de la máscara indican dónde puede editarse la primera imagen de referencia. Se rechaza una máscara sin imágenes de referencia.

Siguientes pasos