> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Referências e recursos > **Note** > > **Guia prático** · Pressupõe que você tenha concluído o [guia de início rápido de Imagem e Vídeo ](/docs/pt/eleven-api/guides/cookbooks/image-and-video). ## 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. | `type` | Aponta para | Campos | | --------------- | --------------------------------------------------------- | ----------------------------- | | `generation` | A saída de outra geração, concluída ou ainda em execução. | `generation_id` | | `asset` | Um arquivo enviado à API de assets. | `asset_id` | | `inline_base64` | Mídia codificada diretamente no corpo da solicitação. | `content_base64`, `mime_type` | 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. ```python maxLines=0 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) ``` ```typescript maxLines=0 const still = await elevenlabs.flows.image.create({ modelId: "gemini-3-pro-image", prompt: "A lighthouse on a cliff at dawn, heavy fog rolling in from the sea", aspectRatio: "16:9", }); // `still` is still pending here. Submitting now queues the video behind it. const clip = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "The fog thickens and the beam sweeps across the water", startFrame: { type: "generation", generationId: still.id }, durationSecs: 8, webhook: { type: "all" }, }); console.log(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](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) 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](/docs/pt/eleven-api/guides/cookbooks/image-and-video#polling-guidelines). ```python import time while True: result = elevenlabs.flows.video.get(clip.id) if result.status in ("completed", "failed"): break time.sleep(10) ``` ```typescript let result = await elevenlabs.flows.video.get(clip.id); while (result.status === "pending" || result.status === "generating") { await new Promise((resolve) => setTimeout(resolve, 10000)); result = await elevenlabs.flows.video.get(clip.id); } ``` 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. ```python 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), ) ) ``` ```typescript import { createReadStream } from "fs"; const asset = await elevenlabs.assets.create({ asset: createReadStream("lighthouse.png"), name: "lighthouse.png", }); console.log(asset.assetId); const clip = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "The beam sweeps across the water as the fog thickens", startFrame: { type: "asset", assetId: asset.assetId }, }); ``` A resposta do envio descreve o asset armazenado: ```json { "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. > **Warning** > > O acesso à API de assets com uma chave de API exige o plano Pro ou superior, o mesmo nível dos > endpoints de geração. ### Limites de armazenamento Os assets enviados contam para um limite total de armazenamento do workspace, que depende do seu plano: | Plano | Armazenamento de assets | | ---------- | ----------------------- | | Pro | 11 GB | | Scale | 33 GB | | Business | 111 GB | | Enterprise | 333 GB | 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. ```python 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) ``` ```typescript let page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse" }); for (const asset of page.assets) { console.log(asset.assetId, asset.name, asset.mimeType); } if (page.hasMore) { page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse", cursor: page.nextCursor, }); } ``` Recupere ou exclua um único asset pelo ID. Excluir um asset não afeta gerações que já o utilizaram. ```python asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4") elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4") ``` ```typescript const asset = await elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4"); await 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. ```python 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", ) ], ) ) ``` ```typescript import { readFile } from "fs/promises"; const encoded = (await readFile("headshot.jpg")).toString("base64"); const generation = await elevenlabs.flows.image.create({ modelId: "gpt-image-2", prompt: "Replace the background with a softly lit studio backdrop", images: [ { type: "inline_base64", contentBase64: encoded, mimeType: "image/jpeg", }, ], }); ``` > **Warning** > > A mídia inline é armazenada como um asset temporário, sem garantia de retenção, e pode ser excluída quando > a geração for concluída. Em vez disso, envie o arquivo à API de assets quando precisar referenciar a > mesma entrada mais de uma vez. 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: | Referência | `mime_type` aceitos | | ---------- | ------------------------------------------------------------------- | | Imagem | `image/jpeg`, `image/png`, `image/webp`, `image/heic`, `image/heif` | | Áudio | `audio/mpeg`, `audio/wav` | | Vídeo | `video/mp4`, `video/quicktime`, `video/webm` | ## 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: ```json { "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 > **Warning** > > Os modelos ByteDance são desativados por padrão e exigem aprovação explícita antes do uso. Clientes Enterprise > podem entrar em contato com o suporte para solicitar acesso. 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 #### [Webhooks](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) Receba o resultado de uma geração em vez de consultá-lo. #### [Visão geral de Imagem e Vídeo](/docs/pt/overview/capabilities/image-video) Compare os recursos dos modelos, os formatos compatíveis e a disponibilidade. #### [Referência da API](/docs/pt/api-reference/flows/image/create) Explore os endpoints de imagem, vídeo e assets.