Image & Video quickstart

The Image & Video API is asynchronous. You submit a generation, and once it finishes you download the result from a signed URL. Images and videos have separate endpoints, but the request and response shapes are the same for both.

There are two ways to collect the result. Webhook delivery is the recommended one, and what the examples below use: ElevenLabs calls your endpoint the moment a generation reaches a terminal status, so nothing is spent waiting. Polling is the fallback for when you have no endpoint to receive a callback, and each example shows how to drop back to it.

Generate an image

1
ELEVENLABS_API_KEY=<your_api_key_here>

1
pip install elevenlabs
2
pip install python-dotenv

1
# example.py
2
import os
3
4
from dotenv import load_dotenv
5
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
6
from elevenlabs.client import ElevenLabs
7
8
load_dotenv()
9
10
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
11
12
generation = elevenlabs.flows.image.create(
13
    request=ImageGenerationRequest_Gemini3ProImage(
14
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
15
        aspect_ratio="16:9",
16
        resolution="2K",
17
        webhook=WebhookTarget_All(),
18
    )
19
)
20
21
print(generation.id, generation.status)

1
{
2
  "id": "JWr5N6X9ZTqf8jD2LmQb",
3
  "status": "pending"
4
}

1
import time
2
3
import requests
4
5
while True:
6
    result = elevenlabs.flows.image.get(generation.id)
7
    if result.status in ("completed", "failed"):
8
        break
9
    time.sleep(2)
10
11
if result.status == "failed":
12
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")
13
14
with open("corgi.png", "wb") as f:
15
    f.write(requests.get(result.content_url).content)

1
{
2
  "id": "JWr5N6X9ZTqf8jD2LmQb",
3
  "status": "completed",
4
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
5
  "content_mime_type": "image/png"
6
}

1
python example.py

Generate a video

Video generations use flows.video and follow the same submit-and-collect pattern. A video can take several minutes, so this example opts into webhook delivery with webhook rather than waiting on the result.

1
from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All
2
3
generation = elevenlabs.flows.video.create(
4
    request=VideoGenerationRequest_Veo31FastGenerate001(
5
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
6
        duration_secs=8,
7
        aspect_ratio="16:9",
8
        resolution="1080p",
9
        generate_audio=True,
10
        webhook=WebhookTarget_All(),
11
    )
12
)
13
14
print(generation.id)

The call returns as soon as the generation is queued, and the finished result is delivered to every webhook in your workspace subscribed to generation events. Video output is MP4, so the completed payload reports a content_mime_type of video/mp4. See Image & Video webhooks for configuring a webhook and writing the handler that receives this.

Collecting results

Webhooks and polling return the same payload, so the choice is about how you wait for it rather than what you get.

Use webhooks wherever you can. Reach for polling when you have nowhere to receive a callback, and follow the intervals below when you do.

Choosing webhook targets

webhook accepts two forms. WebhookTarget_All reaches every webhook subscribed to generation events, which is the right default because it survives webhooks being rotated or replaced. WebhookTarget_Ids narrows delivery to specific webhooks, for when one workspace fans out to several consumers and a given job should reach only one of them:

1
from elevenlabs import WebhookTarget_Ids
2
3
webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

Every ID must already be subscribed to generation events; naming an unsubscribed webhook is rejected rather than silently ignored. The delivered payload is identical to what the GET endpoint returns, so a handler written against one works for the other. The webhooks guide covers configuring a webhook, verifying the signature, and handling the event.

Polling guidelines

A generation’s runtime depends on the model, the resolution, and, for video, the duration, so poll on an interval matched to what you asked for rather than on a fixed loop:

• Images: poll no more than once every 2 seconds. Most finish within a few seconds.
• Video: poll no more than once every 10 seconds. Expect minutes, not seconds, and scale the interval with duration_secs and resolution.

Two rules apply to both. Back off when a generation runs long — doubling the interval up to about a minute keeps a slow generation from turning into hundreds of requests. And give the loop a ceiling, so a stuck generation ends as a timeout in your own code rather than an unbounded loop.

Polling faster than this earns you nothing: a generation’s status does not change any sooner because you asked twice. Sustained aggressive polling can return 429 responses, which you should handle with exponential backoff.

Generation lifecycle

A generation moves through four statuses. The two terminal statuses carry different fields, so branch on status before reading the rest of the response.

Handling failures

A failed generation reports a failure_reason category alongside a human-readable error_message:

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

Failed generations are not charged. Parameter problems that can be detected up front — an unsupported field, a value outside a model’s allowed range, or an invalid combination of reference inputs — are rejected by the create request instead, before any generation starts.

Pricing

Generations are charged in credits. The cost depends on the model, the parameters you choose such as resolution and duration, and the inputs you provide. A generation costs the same through the API as it does in the ElevenLabs app, where the cost is shown before you submit. See Image & Video in the playground for how the cost of a given model and setting combination is presented.

List your generations

Each endpoint lists the generations created through it, newest first. Results are scoped to your workspace and to this API, so generations created in the ElevenLabs app do not appear.

1
page = elevenlabs.flows.image.list(page_size=20, status="completed")
2
3
for item in page.generations:
4
    print(item.id, item.content_url)
5
6
while page.has_more:
7
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
8
    for item in page.generations:
9
        print(item.id, item.content_url)

page_size accepts 1 to 100 and defaults to 30. Pass status to return only generations in one lifecycle state, and model_id to return only generations of a single model. Treat next_cursor as opaque: pass the exact value back and stop when has_more is false.

Available models

The API exposes a subset of the models available in the ElevenLabs app. Each model accepts only the parameters listed for it — sending a field another model supports returns a validation error.

Image models

Video models

For model capabilities, availability, and pricing, see the Image & Video overview.

Next steps