> 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. # Início rápido de Imagem e Vídeo A API de Imagem e Vídeo é assíncrona. Você envia uma geração e, quando ela termina, baixa o resultado por uma URL assinada. Imagens e vídeos têm endpoints separados, mas os formatos de solicitação e resposta são os mesmos para ambos. Há duas formas de coletar o resultado. A [entrega por webhook](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) é a recomendada e é usada pelos exemplos abaixo: a ElevenLabs chama seu endpoint no momento em que uma geração atinge um status terminal, para que não haja espera. O polling é a alternativa quando você não tem um endpoint para receber um callback, e cada exemplo mostra como usá-lo. > **Warning** > > A API de Imagem e Vídeo exige um plano Pro ou superior. Chamadas de um workspace abaixo desse nível são > rejeitadas com o erro `402 paid_plan_required`. Sua chave de API também precisa ter a permissão de Imagem e Vídeo ou > Flows para o workspace. ## Gere uma imagem #### Crie uma chave de API [Crie uma chave de API no painel aqui](https://elevenlabs.io/app/settings/api-keys), que você usará para [acessar a API](/docs/pt/api-reference/authentication) com segurança. Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo `.env` ou diretamente na configuração do seu app, conforme sua preferência. **`.env`** ```js title=".env" ELEVENLABS_API_KEY= ``` #### Instale o SDK #### SDK Também usaremos a biblioteca `dotenv` para carregar nossa chave de API de uma variável de ambiente. ```python pip install elevenlabs pip install python-dotenv ``` ```typescript npm install @elevenlabs/elevenlabs-js npm install dotenv ``` #### CLI Instale a CLI da ElevenLabs. Recomendamos Homebrew (macOS) e Scoop (Windows). **`Homebrew (macOS)`** ```bash title="Homebrew (macOS)" brew install elevenlabs/tap/elevenlabs ``` **`Scoop (Windows)`** ```powershell title="Scoop (Windows)" scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket scoop install elevenlabs ``` **`npm`** ```bash title="npm" npm install -g @elevenlabs/cli ``` **`curl`** ```bash title="curl" curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh ``` > **Tip** > > Está trabalhando com um assistente de programação com IA? Execute `elevenlabs generate-skills` no seu projeto para criar um > `SKILL.md` para cada grupo de comandos em `skills/`, para que seu assistente conheça toda a superfície da CLI > sem que você precise colar a documentação. Use `--output-dir` para colocá-los em outro lugar. Isso lê a própria > definição de API incorporada da CLI, portanto não precisa de chave de API e funciona off-line — além de acompanhar > a versão da CLI que você tiver instalado. Em seguida, autentique-se — isso abrirá seu navegador para autorizar a CLI: ```bash elevenlabs auth login ``` #### Envie a geração Cada modelo tem sua própria classe de solicitação, e os campos dela são os parâmetros aceitos pelo modelo. Portanto, trocar de modelo pode mudar quais campos estão disponíveis. Campos desconhecidos são rejeitados em vez de ignorados. `webhook` solicita que o resultado concluído seja entregue aos webhooks do seu workspace, portanto, a chamada retorna assim que a geração é colocada na fila. Isso 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 ou omita o campo e use polling. #### SDK ```python # 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) ``` ```typescript // example.mts import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; import "dotenv/config"; const elevenlabs = new ElevenLabsClient(); const generation = await elevenlabs.flows.image.create({ modelId: "gemini-3-pro-image", prompt: "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", aspectRatio: "16:9", resolution: "2K", webhook: { type: "all" }, }); console.log(generation.id, generation.status); ``` #### CLI A CLI envia a mesma solicitação como JSON, depois faz polling até a geração ser concluída e baixa o resultado: ```bash # 1. Submit the generation (note the returned id) elevenlabs flows image create --json '{ "model_id": "gemini-3-pro-image", "prompt": "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", "aspect_ratio": "16:9", "resolution": "2K" }' # 2. Poll until the status is "completed" elevenlabs flows image get --generation-id --query status # 3. Read the signed content URL, then download the image elevenlabs flows image get --generation-id --query content_url curl -o corgi.png "" ``` A resposta contém o ID da geração e nada mais. Uma geração recém-criada sempre fica como `pending`: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "pending" } ``` #### Colete o resultado Como a solicitação incluiu `webhook`, a ElevenLabs envia um evento `flows_generation` ao seu endpoint quando a geração atinge `completed` ou `failed`. O `data` do evento é idêntico ao que o endpoint GET retorna, e os [webhooks de Imagem e Vídeo](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) explicam o handler que o recebe. Sem um endpoint para receber callbacks, remova `webhook` da solicitação acima e use polling. Busque a geração até que o status seja `completed` ou `failed`, deixando pelo menos dois segundos entre as solicitações para uma imagem — consulte as [diretrizes de polling](#polling-guidelines) para saber os intervalos de cada modalidade. ```python maxLines=0 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) ``` ```typescript maxLines=0 import { writeFile } from "fs/promises"; let result = await elevenlabs.flows.image.get(generation.id); while (result.status === "pending" || result.status === "generating") { await new Promise((resolve) => setTimeout(resolve, 2000)); result = await elevenlabs.flows.image.get(generation.id); } if (result.status === "failed") { throw new Error(`${result.failureReason}: ${result.errorMessage}`); } const response = await fetch(result.contentUrl); await writeFile("corgi.png", Buffer.from(await response.arrayBuffer())); ``` De qualquer forma, uma geração concluída contém os mesmos campos: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "completed", "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb", "content_mime_type": "image/png" } ``` #### Execute o código ```python python example.py ``` ```typescript npx tsx example.mts ``` A geração é colocada na fila e seu ID é exibido. Com a entrega por webhook, a imagem chega ao seu endpoint; com a variante de polling, ela é salva em `corgi.png`. ## Gere um vídeo As gerações de vídeo usam `flows.video` e seguem o mesmo padrão de envio e coleta. Um vídeo pode levar vários minutos, portanto, este exemplo usa a entrega por webhook com `webhook`, em vez de esperar pelo resultado. ```python 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) ``` ```typescript const generation = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic", durationSecs: 8, aspectRatio: "16:9", resolution: "1080p", generateAudio: true, webhook: { type: "all" }, }); console.log(generation.id); ``` A chamada retorna assim que a geração é colocada na fila, e o resultado concluído é entregue a todos os webhooks do seu workspace inscritos em eventos de geração. A saída de vídeo é MP4, portanto, o payload concluído informa um `content_mime_type` de `video/mp4`. Consulte os [webhooks de Imagem e Vídeo](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) para configurar um webhook e criar o handler que recebe isso. > **Warning** > > `webhook` exige pelo menos um webhook do workspace inscrito em eventos de geração. Sem um, > a chamada de criação é rejeitada, em vez de iniciar uma geração cujo resultado não tem para onde ir. Remova > o campo para usar polling com `flows.video.get` e faça polling no máximo uma vez a cada 10 > segundos. ## Coletando resultados Webhooks e polling retornam a mesma carga, então a escolha é sobre como você espera por ela, e não sobre o que recebe. | | Entrega por webhook | Polling | | --------------- | ------------------------------------------------------------- | ----------------------------------------- | | Ideal para | O padrão para ambas as modalidades e qualquer uso em produção | Scripts e ambientes sem endpoint público | | Requer | Um endpoint HTTPS inscrito em eventos de geração | Nada | | Custo da espera | Nenhum; chamamos você quando a geração termina | Uma solicitação por consulta, por geração | Use webhooks sempre que puder. Use polling quando não houver onde receber um callback e, nesse caso, siga os intervalos abaixo. ### Escolhendo destinos de webhook `webhook` aceita duas formas. `WebhookTarget_All` alcança todos os webhooks inscritos em eventos de geração, que é o padrão ideal porque continua funcionando mesmo que os webhooks sejam alternados ou substituídos. `WebhookTarget_Ids` limita a entrega a webhooks específicos, para quando um workspace distribui para vários consumidores e um determinado trabalho deve chegar a apenas um deles: ```python from elevenlabs import WebhookTarget_Ids webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"]) ``` ```typescript const webhook = { type: "ids", ids: ["Q8mVr2LpXcT4nB6yJdKw"] }; ``` Cada ID já precisa estar inscrito em eventos de geração; informar um webhook não inscrito é rejeitado, em vez de ser ignorado silenciosamente. A carga entregue é idêntica à retornada pelo endpoint GET, então um manipulador criado para um funciona para o outro. O [guia de webhooks](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) explica como configurar um webhook, verificar a assinatura e processar o evento. ### Diretrizes de polling O tempo de execução de uma geração depende do modelo, da resolução e, no caso de vídeo, da duração. Portanto, faça polling em um intervalo adequado ao que você solicitou, em vez de usar um loop fixo: * **Imagens**: faça polling no máximo uma vez a cada 2 segundos. A maioria termina em poucos segundos. * **Vídeos**: faça polling no máximo uma vez a cada 10 segundos. Espere minutos, não segundos, e ajuste o intervalo de acordo com `duration_secs` e `resolution`. Duas regras valem para ambos. Reduza a frequência quando uma geração demorar — dobrar o intervalo até cerca de um minuto evita que uma geração lenta se transforme em centenas de solicitações. E defina um limite para o loop, para que uma geração travada termine em timeout no seu próprio código, em vez de em um loop sem fim. Fazer polling mais rápido que isso não traz benefício: o status de uma geração não muda antes só porque você perguntou duas vezes. Um polling agressivo e contínuo pode retornar [respostas 429](/docs/pt/eleven-api/resources/errors#rate-limiting-and-concurrency), que você deve tratar com recuo exponencial. ## Ciclo de vida da geração Uma geração passa por quatro status. Os dois status finais contêm campos diferentes, então use `status` para definir o fluxo antes de ler o restante da resposta. | Status | Significado | | ------------ | --------------------------------------------------------------------------- | | `pending` | A geração está na fila. Esse é o status de toda geração recém-criada. | | `generating` | O modelo está em execução. | | `completed` | A saída está pronta. A resposta contém `content_url` e `content_mime_type`. | | `failed` | A geração não produziu uma saída. A resposta contém os detalhes da falha. | > **Warning** > > `content_url` é uma URL assinada que expira aproximadamente uma hora após o retorno da resposta. > Busque a geração novamente para obter uma URL atualizada, em vez de armazenar a própria URL assinada. ## Lidando com falhas Uma geração com falha informa uma categoria em `failure_reason` junto com uma `error_message` legível: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "failed", "failure_reason": "moderated", "error_message": "The prompt was rejected by content moderation. You were not charged for this generation." } ``` | `failure_reason` | Causa | | -------------------- | ----------------------------------------------------------------- | | `timeout` | O modelo não retornou um resultado a tempo. | | `model_error` | O provedor do modelo retornou um erro ou não produziu saída. | | `moderated` | O prompt ou uma entrada foi rejeitada pela moderação de conteúdo. | | `invalid_parameters` | Os parâmetros foram rejeitados quando a geração chegou ao modelo. | | `dependency_failed` | Uma geração referenciada da qual esta depende falhou. | | `charging_failed` | Não foi possível cobrar o workspace pela geração. | | `internal_error` | Ocorreu um erro inesperado. | Gerações com falha não são cobradas. Problemas de parâmetros que podem ser detectados antecipadamente — um campo não compatível, um valor fora do intervalo permitido pelo modelo ou uma combinação inválida de entradas de referência — são rejeitados pela solicitação de criação antes de qualquer geração começar. ## Preços As gerações são cobradas em créditos. O custo depende do modelo, dos parâmetros que você escolhe, como resolução e duração, e das entradas fornecidas. Uma geração custa o mesmo pela API e pelo app da ElevenLabs, onde o custo é exibido antes do envio. Consulte [Imagem e Vídeo no playground](/docs/pt/eleven-creative/playground/image-video) para saber como o custo de uma combinação específica de modelo e configurações é apresentado. ## Liste suas gerações Cada endpoint lista as gerações criadas por ele, das mais recentes para as mais antigas. Os resultados são limitados ao seu workspace e a esta API, portanto, as gerações criadas no app da ElevenLabs não aparecem. ```python 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) ``` ```typescript let page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed" }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } while (page.hasMore) { page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed", cursor: page.nextCursor, }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } } ``` `page_size` aceita valores de 1 a 100 e o padrão é 30. Passe `status` para retornar apenas gerações em um estado do ciclo de vida e `model_id` para retornar apenas gerações de um único modelo. Trate `next_cursor` como opaco: passe de volta o valor exato e pare quando `has_more` for `false`. ## Modelos disponíveis A API disponibiliza um subconjunto dos modelos disponíveis no app da ElevenLabs. Cada modelo aceita apenas os parâmetros listados para ele — enviar um campo aceito por outro modelo retorna um erro de validação. > **Warning** > > Os modelos da ByteDance ficam desativados por padrão e exigem aprovação explícita antes do uso. Até > que o acesso seja concedido, uma solicitação que informe um deles será rejeitada com um erro > `model_access_denied`. Clientes Enterprise podem entrar em contato com o suporte para solicitar acesso. ### Modelos de imagem | `model_id` | Imagens de referência | Controles de saída | | ----------------------------- | -------------------------- | ---------------------------------------------------------------------- | | `gpt-image-1` | Até 5, além de uma `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-1.5` | Até 5, além de uma `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-2` | Até 10, além de uma `mask` | 15 proporções, `resolution` (1K, 2K, 4K), `quality` | | `gpt-image-2.5-sunburst` | Até 10, além de uma `mask` | 15 proporções, `resolution` (1K, 2K, 4K), `quality` (até `max`) | | `gpt-image-2.5-flare` | Até 10, além de uma `mask` | 15 proporções, `resolution` (1K, 2K, 4K), `quality` (até `max`) | | `gemini-2.5-flash-image` | Até 5 | `aspect_ratio` | | `gemini-3-pro-image` | Até 10 | `aspect_ratio`, `resolution` (1K, 2K, 4K) | | `gemini-3.1-flash-image` | Até 14 | `aspect_ratio` (incluindo 1:4, 4:1, 1:8, 8:1), `resolution` (512 a 4K) | | `gemini-3.1-flash-lite-image` | Até 14 | `aspect_ratio`, `resolution` (1K) | | `bytedance-seedream-5-lite` | Até 10 | `aspect_ratio`, `resolution` (2K, 3K), `seed` | | `bytedance-seedream-5-pro` | Até 10 | `aspect_ratio`, `resolution` (1K, 2K), `seed` | Os modelos GPT Image 2.5 aceitam valores de `quality` como `low`, `medium`, `high`, `xhigh` e `max`, e o padrão é `high`. O GPT Image 2 vai até `high` e o padrão é `medium`. ### Modelos de vídeo | `model_id` | Entradas de mídia | Controles de saída | | ---------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-001` | `start_frame`, `end_frame`, até 3 `images` com um `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `veo-3.1-fast-generate-001` | `start_frame`, `end_frame`, até 3 `images` com um `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `bytedance-seedance-v2` | `start_frame`, `end_frame`, até 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 a 15), 7 proporções, `resolution` (480p a 4k), `generate_audio` | | `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, até 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 a 15), 7 proporções, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, até 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 a 15), 7 proporções, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2.5` | `start_frame`, `end_frame`, até 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (4 a 30), 7 proporções, `resolution` (480p, 720p), `generate_audio` | | `creatify-aurora` | `image` e `audio`, ambos obrigatórios | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale` | Para recursos, disponibilidade e preços dos modelos, consulte a [visão geral de Imagem e Vídeo](/docs/pt/overview/capabilities/image-video). ## Próximas etapas #### [Referências e recursos](/docs/pt/eleven-api/guides/how-to/image-and-video/references) Oriente uma geração com uma geração anterior, um recurso enviado ou mídia inline. #### [Webhooks](/docs/pt/eleven-api/guides/how-to/image-and-video/webhooks) Receba o resultado de uma geração em vez de fazer polling. #### [Referência da API](/docs/pt/api-reference/flows/image/create) Explore os endpoints de imagem, vídeo e recursos.