Referências e recursos

Visão geral

A maioria dos modelos de Imagem e Vídeo aceita mídia junto ao prompt: um primeiro quadro para um vídeo, imagens para editar, áudio para sincronizar os lábios. Cada campo da API que recebe mídia aceita um objeto de referência em vez de bytes brutos em um formato fixo, e cada referência é identificada com um type que indica de onde a mídia vem.

Os três tipos são intercambiáveis onde quer que uma referência seja aceita, portanto o mesmo campo pode receber uma geração em uma solicitação e um asset enviado na próxima.

Encadeie uma geração na próxima

Uma referência de generation não precisa apontar para uma geração concluída. Envie a imagem, extraia o ID da resposta e passe-o diretamente para a solicitação de vídeo sem esperar: a API coloca o vídeo na fila após a imagem e o inicia assim que a imagem for concluída. Nada é enviado entre as duas chamadas.

Defina webhook na última geração da cadeia e não haverá nada para esperar. Ambas as chamadas retornam assim que suas gerações entram na fila, todo o grafo é executado no servidor, e seu endpoint é chamado quando a geração final atinge um status 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)

Apenas a última geração precisa de webhook. Defini-lo também na imagem envia um evento para o resultado intermediário, o que é útil para informar o progresso, mas não é necessário para executar a cadeia. Como em outros casos, o campo exige um webhook inscrito em eventos de geração; consulte webhooks de Imagem e Vídeo para configurar um.

Sem um endpoint para receber callbacks, remova webhook e consulte o fim da cadeia. A imagem intermediária ainda não precisa ser consultada — espere apenas uma vez, na última geração, no intervalo da sua modalidade, que para vídeo é no máximo uma vez a cada 10 segundos. Consulte as diretrizes de consulta.

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

Uma geração que referencia trabalho ainda não concluído é criada imediatamente e fica em pending até que tudo o que ela referencia seja concluído, sem que você precise fazer mais nada para iniciá-la. As cadeias podem ter qualquer profundidade e largura — uma geração pode aguardar várias referências, cada uma também aguardando outras —, então um grafo inteiro pode ser enviado de uma vez e coletado apenas em suas extremidades. O tempo na fila não conta para o tempo limite da geração.

Se uma geração referenciada falhar, a dependente nunca é executada: ela falha com o motivo dependency_failed e leva consigo qualquer coisa que esteja na fila depois dela. Nada na cadeia interrompida é cobrado — uma geração que já foi paga é reembolsada, e uma cujo preço depende de uma saída referenciada que ainda não existe, como uma sincronização labial precificada pela duração de uma geração de áudio pendente, só é cobrada quando começa. Um generation_id que não existe no seu workspace é rejeitado na própria chamada de criação, então um erro de digitação aparece imediatamente, em vez de como uma geração com falha.

Envie mídia como asset

Envie um arquivo para a API de assets quando a mídia vier de fora da ElevenLabs e você quiser reutilizá-la em várias gerações. Os assets pertencem ao workspace e permanecem até você excluí-los.

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

A resposta do envio descreve o asset armazenado:

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

content_url é uma URL assinada válida por cerca de uma hora e é null enquanto o envio ainda está sendo processado. Busque o asset novamente para obter uma URL atualizada.

Limites de armazenamento

Os assets enviados contam para um limite total de armazenamento do workspace, que depende do seu plano:

Apenas os arquivos que você envia contam para o limite; as saídas geradas não. Um envio que ultrapassaria o limite do workspace é rejeitado com um erro asset_storage_limit_exceeded antes que o arquivo seja lido. Exclua assets de que você não precisa mais para liberar espaço ou entre em contato com o suporte para aumentar o limite.

Gerencie assets

Liste os assets do mais recente para o mais antigo, com filtro opcional por nome, e navegue pelos resultados com o cursor da resposta anterior. page_size aceita valores de 1 a 100 e o padrão é 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)

Recupere ou exclua um único asset pelo ID. Excluir um asset não afeta gerações que já o utilizaram.

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

Passe mídia inline

Uma referência inline_base64 inclui a mídia no corpo da solicitação, evitando um envio separado para entradas pontuais. Codifique o arquivo usando o alfabeto base64 padrão e declare o 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",
            )
        ],
    )
)

O conteúdo inline é limitado a 25 MB por referência após a decodificação. Arquivos maiores devem ser enviados pela API de assets, que aceita uploads muito maiores e não sofre a penalidade de tamanho do base64. Cada modalidade aceita um conjunto fixo de tipos MIME:

Campos de referência por modelo

Os campos de referência recebem o nome da função que a mídia desempenha. start_frame e end_frame são imagens únicas que delimitam um vídeo, image e audio são as entradas obrigatórias de um modelo de sincronização labial, e os plurais simples images, videos e audios são materiais de referência de formato livre dos quais o modelo se baseia.

Os campos que um modelo aceita e quais combinações são válidas variam conforme o modelo. Um end_frame sempre exige um start_frame. Violar uma restrição retorna um erro de validação que nomeia o campo em questão, portanto a geração nunca é iniciada e nunca é cobrada.

Veo 3.1

Ambos os modelos Veo aceitam start_frame, end_frame e até três entradas em images. Ao contrário de outros modelos, cada entrada em images agrupa a referência com a função que ela desempenha:

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

Uma referência subject coloca o assunto ou os elementos da cena da imagem no vídeo; uma referência style transfere seu estilo visual. Imagens de referência não podem ser combinadas com start_frame ou end_frame e exigem a duração de oito segundos.

Seedance

Os três níveis do Seedance 2.0 aceitam start_frame, end_frame, até 9 images, até 3 videos e até 3 audios, sujeitos a estas restrições:

• Referências não podem ser combinadas com start_frame ou end_frame.
• Áudio de referência exige pelo menos uma imagem ou vídeo de referência, por exemplo, para conduzir a sincronização labial.
• O número combinado de arquivos de referência não pode exceder 12.

O Seedance 2.5 aumenta os limites para 30 images, 10 videos e 10 audios, sem total combinado, e elimina a regra de que o áudio de referência precisa de uma imagem ou vídeo acompanhante, aceitando assim entrada somente de áudio. As referências ainda não podem ser combinadas com start_frame ou end_frame.

GPT Image

Os modelos GPT Image aceitam uma mask junto com images. Áreas totalmente transparentes da máscara marcam onde a primeira imagem de referência pode ser editada. Uma máscara sem imagens de referência é rejeitada.

Próximas etapas