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 é 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.

Gere uma imagem

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

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.

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)

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 para configurar um webhook e criar o handler que recebe isso.

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.

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:

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_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 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, 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.

Lidando com falhas

Uma geração com falha informa uma categoria em failure_reason junto com uma error_message legível:

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

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 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.

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 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.

Modelos de imagem

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

Para recursos, disponibilidade e preços dos modelos, consulte a visão geral de Imagem e Vídeo.

Próximas etapas