Korte introductie tot Afbeelding & Video

De Image & Video API is asynchroon. Je dient een generatie in en downloadt het resultaat via een ondertekende URL zodra deze is voltooid. Afbeeldingen en video’s hebben afzonderlijke endpoints, maar de request- en responsestructuur is voor beide hetzelfde.

Er zijn twee manieren om het resultaat op te halen. Levering via webhooks is de aanbevolen methode, die ook in de onderstaande voorbeelden wordt gebruikt: ElevenLabs roept je endpoint aan zodra een generatie een eindstatus bereikt, zodat er niets wordt besteed aan wachten. Polling is het alternatief als je geen endpoint hebt om een callback te ontvangen. Elk voorbeeld laat zien hoe je daarop terugvalt.

Een afbeelding genereren

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

Een video genereren

Videogeneraties gebruiken flows.video en volgen hetzelfde patroon van indienen en ophalen. Een video kan enkele minuten duren, dus dit voorbeeld gebruikt levering via webhook met webhook in plaats van op het resultaat te wachten.

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)

De call wordt geretourneerd zodra de generatie in de wachtrij staat en het voltooide resultaat wordt afgeleverd bij elke webhook in je workspace die is geabonneerd op generatiegebeurtenissen. Video-output is MP4, dus de voltooide payload rapporteert een content_mime_type van video/mp4. Zie Image & Video-webhooks voor het configureren van een webhook en het schrijven van de handler die dit ontvangt.

Resultaten ophalen

Webhooks en polling retourneren dezelfde payload, dus de keuze gaat over hoe je erop wacht en niet over wat je ontvangt.

Gebruik waar mogelijk webhooks. Gebruik polling wanneer je nergens een callback kunt ontvangen en houd je dan aan de onderstaande intervallen.

Webhookdoelen kiezen

webhook accepteert twee vormen. WebhookTarget_All bereikt elke webhook die is geabonneerd op generatie- gebeurtenissen. Dit is de juiste standaard, omdat deze blijft werken als webhooks worden geroteerd of vervangen. WebhookTarget_Ids beperkt de levering tot specifieke webhooks, voor wanneer één workspace wordt verdeeld over meerdere ontvangers en een bepaalde taak slechts één daarvan moet bereiken:

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

Elke ID moet al zijn geabonneerd op generatiegebeurtenissen. Het opgeven van een webhook zonder abonnement wordt afgewezen in plaats van stilzwijgend genegeerd. De afgeleverde payload is identiek aan wat het GET-endpoint retourneert, dus een handler die voor het ene is geschreven, werkt ook voor het andere. In de webhookshandleiding lees je hoe je een webhook configureert, de handtekening verifieert en de gebeurtenis afhandelt.

Richtlijnen voor polling

De uitvoeringstijd van een generatie hangt af van het model, de resolutie en, voor video, de duur. Voer polling daarom uit met een interval dat past bij wat je hebt aangevraagd, en niet in een vaste loop:

• Afbeeldingen: voer polling niet vaker uit dan eens per 2 seconden. De meeste zijn binnen enkele seconden klaar.
• Video: voer polling niet vaker uit dan eens per 10 seconden. Reken op minuten in plaats van seconden, en schaal het interval met duration_secs en resolution.

Voor beide gelden twee regels. Verhoog het interval wanneer een generatie lang duurt — door het interval te verdubbelen tot ongeveer een minuut voorkom je dat een langzame generatie honderden requests veroorzaakt. Geef de loop ook een limiet, zodat een vastgelopen generatie in je eigen code eindigt met een time-out in plaats van een onbeperkte loop.

Sneller pollen levert niets op: de status van een generatie verandert niet eerder omdat je twee keer hebt gevraagd. Aanhoudend agressieve polling kan 429-responses retourneren, die je moet afhandelen met exponentiële backoff.

Levenscyclus van een generatie

Een generatie doorloopt vier statussen. De twee eindstatussen bevatten verschillende velden, dus vertak op status voordat je de rest van de response leest.

Fouten afhandelen

Een mislukte generatie rapporteert een categorie failure_reason naast een leesbare error_message:

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

Voor mislukte generaties worden geen kosten in rekening gebracht. Parameterproblemen die vooraf kunnen worden gedetecteerd — een niet-ondersteund veld, een waarde buiten het toegestane bereik van een model of een ongeldige combinatie van referentie- invoer — worden in plaats daarvan door de create-request afgewezen, voordat een generatie begint.

Prijzen

Voor generaties worden credits in rekening gebracht. De kosten hangen af van het model, de parameters die je kiest, zoals resolutie en duur, en de invoer die je opgeeft. Een generatie kost via de API evenveel als in de ElevenLabs-app, waar de kosten worden weergegeven voordat je indient. Zie Image & Video in de playground voor hoe de kosten van een bepaalde combinatie van model en instellingen worden weergegeven.

Je generaties weergeven

Elk endpoint geeft de generaties weer die ermee zijn gemaakt, met de nieuwste eerst. Resultaten zijn beperkt tot je workspace en deze API, dus generaties die in de ElevenLabs-app zijn gemaakt, worden niet weergegeven.

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 accepteert 1 tot en met 100 en is standaard 30. Geef status door om alleen generaties in één levenscyclusstatus te retourneren, en model_id om alleen generaties van één model te retourneren. Behandel next_cursor als doorschijnend: geef de exacte waarde terug en stop wanneer has_more false is.

Beschikbare modellen

De API biedt toegang tot een subset van de modellen die beschikbaar zijn in de ElevenLabs-app. Elk model accepteert alleen de parameters die ervoor worden vermeld — als je een veld stuurt dat door een ander model wordt ondersteund, krijg je een validatiefout.

Afbeeldingsmodellen

De GPT Image 2.5-modellen accepteren quality-waarden van low, medium, high, xhigh en max, en gebruiken standaard high. GPT Image 2 gaat tot high en gebruikt standaard medium.

Videomodellen

Zie voor modelmogelijkheden, beschikbaarheid en prijzen het overzicht van Afbeelding & Video.

Volgende stappen