> 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. # 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](/docs/nl/eleven-api/guides/how-to/image-and-video/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. > **Warning** > > De Image & Video API vereist een Pro-abonnement of hoger. Calls vanuit een workspace met een lager abonnement worden > afgewezen met een `402 paid_plan_required`-fout. Je API-sleutel moet voor de workspace ook de machtiging Image & Video of > Flows hebben. ## Een afbeelding genereren #### Een API-sleutel maken [Maak hier een API-sleutel in het dashboard](https://elevenlabs.io/app/settings/api-keys), die je gebruikt voor veilige [toegang tot de API](/docs/nl/api-reference/authentication). Sla de sleutel op als beheerd geheim en geef deze aan de SDK's door als omgevingsvariabele via een `.env`-bestand, of rechtstreeks in de configuratie van je app, afhankelijk van je voorkeur. **`.env`** ```js title=".env" ELEVENLABS_API_KEY= ``` #### De SDK installeren #### SDK We gebruiken ook de `dotenv`-bibliotheek om onze API-sleutel uit een omgevingsvariabele te laden. ```python pip install elevenlabs pip install python-dotenv ``` ```typescript npm install @elevenlabs/elevenlabs-js npm install dotenv ``` #### CLI Installeer de ElevenLabs CLI. Homebrew (macOS) en Scoop (Windows) worden aanbevolen. **`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** > > Werk je met een AI-code-assistent? Voer `elevenlabs generate-skills` uit in je project om voor elke > commandogroep een `SKILL.md` naar `skills/` te schrijven, zodat je assistent alle mogelijkheden van de CLI kent > zonder dat je documentatie hoeft te plakken. Gebruik `--output-dir` om ze ergens anders te plaatsen. Dit leest de eigen > ingebouwde API-definitie van de CLI, dus er is geen API-sleutel nodig en het werkt offline — en het blijft afgestemd op > de versie van de CLI die je hebt geïnstalleerd. Verifieer je daarna — hiermee wordt je browser geopend om de CLI te autoriseren: ```bash elevenlabs auth login ``` #### De generatie indienen Elk model heeft een eigen requestklasse en de velden daarin zijn de parameters die dat model accepteert. Als je van model wisselt, kunnen dus andere velden beschikbaar zijn. Onbekende velden worden afgewezen in plaats van genegeerd. `webhook` vraagt om het voltooide resultaat bij de webhooks van je workspace af te leveren, zodat de call wordt geretourneerd zodra de generatie in de wachtrij staat. Hiervoor is een webhook vereist die is geabonneerd op generatie- gebeurtenissen. Raadpleeg [Image & Video- webhooks](/docs/nl/eleven-api/guides/how-to/image-and-video/webhooks) om er een in te stellen, of laat het veld weg en gebruik 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 De CLI dient dezelfde request in als JSON, voert vervolgens polling uit totdat de generatie is voltooid en downloadt het resultaat: ```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 "" ``` De response bevat alleen de generatie-ID. Een nieuw gemaakte generatie heeft altijd de status `pending`: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "pending" } ``` #### Het resultaat ophalen Omdat de request `webhook` gebruikt, post ElevenLabs een `flows_generation`-gebeurtenis naar je endpoint zodra de generatie `completed` of `failed` bereikt. De `data` van de gebeurtenis is identiek aan wat het GET-endpoint retourneert. In [Image & Video-webhooks](/docs/nl/eleven-api/guides/how-to/image-and-video/webhooks) lees je hoe je de handler maakt die deze ontvangt. Als je geen endpoint hebt om callbacks te ontvangen, verwijder je `webhook` uit de bovenstaande request en gebruik je polling. Haal de generatie op totdat de status `completed` of `failed` is, met minimaal twee seconden tussen requests voor een afbeelding — zie [Richtlijnen voor polling](#polling-guidelines) voor de intervallen per modaliteit. ```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())); ``` Een voltooide generatie bevat in beide gevallen dezelfde velden: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "completed", "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb", "content_mime_type": "image/png" } ``` #### De code uitvoeren ```python python example.py ``` ```typescript npx tsx example.mts ``` De generatie wordt in de wachtrij geplaatst en de ID wordt weergegeven. Bij levering via webhook komt de afbeelding aan bij je endpoint; met de pollingvariant wordt deze opgeslagen als `corgi.png`. ## 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. ```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); ``` 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](/docs/nl/eleven-api/guides/how-to/image-and-video/webhooks) voor het configureren van een webhook en het schrijven van de handler die dit ontvangt. > **Warning** > > `webhook` vereist minstens één workspace-webhook die is geabonneerd op generatiegebeurtenissen. Zonder zo'n webhook wordt > de create-call afgewezen, in plaats van een generatie te starten waarvan het resultaat nergens naartoe kan. Verwijder > het veld om terug te vallen op polling met `flows.video.get`, en voer polling niet vaker uit dan eens per 10 > seconden. ## Resultaten ophalen Webhooks en polling retourneren dezelfde payload, dus de keuze gaat over hoe je erop wacht en niet over wat je ontvangt. | | Levering via webhook | Polling | | ------------------ | ---------------------------------------------------------------- | ---------------------------------------------- | | Beste voor | De standaard voor beide modaliteiten en elk productiegebruik | Scripts en omgevingen zonder openbaar endpoint | | Vereist | Een HTTPS-endpoint dat is geabonneerd op generatiegebeurtenissen | Niets | | Kosten van wachten | Geen; je wordt aangeroepen zodra de generatie is voltooid | Eén request per polling, per generatie | 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: ```python from elevenlabs import WebhookTarget_Ids webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"]) ``` ```typescript const webhook = { type: "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](/docs/nl/eleven-api/guides/how-to/image-and-video/webhooks) 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](/docs/nl/eleven-api/resources/errors#rate-limiting-and-concurrency) 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. | Status | Betekenis | | ------------ | -------------------------------------------------------------------------------------- | | `pending` | De generatie staat in de wachtrij. Dit is de status van elke nieuw gemaakte generatie. | | `generating` | Het model wordt uitgevoerd. | | `completed` | De output is klaar. De response bevat `content_url` en `content_mime_type`. | | `failed` | De generatie heeft geen output opgeleverd. De response bevat de foutdetails. | > **Warning** > > `content_url` is een ondertekende URL die ongeveer een uur nadat de response is geretourneerd verloopt. Haal > de generatie opnieuw op voor een nieuwe URL, in plaats van de ondertekende URL zelf op te slaan. ## Fouten afhandelen Een mislukte generatie rapporteert een categorie `failure_reason` naast een leesbare `error_message`: ```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` | Oorzaak | | -------------------- | ------------------------------------------------------------------------------------- | | `timeout` | Het model retourneerde niet op tijd een resultaat. | | `model_error` | De modelprovider retourneerde een fout of produceerde geen output. | | `moderated` | De prompt of een invoer is afgewezen door contentmoderatie. | | `invalid_parameters` | De parameters zijn afgewezen toen de generatie het model bereikte. | | `dependency_failed` | Een generatie waarvan deze afhankelijk is, is mislukt. | | `charging_failed` | De kosten voor de generatie konden niet bij de workspace in rekening worden gebracht. | | `internal_error` | Er is een onverwachte fout opgetreden. | 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](/docs/nl/eleven-creative/playground/image-video) 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. ```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` 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. > **Warning** > > ByteDance-modellen zijn standaard uitgeschakeld en vereisen expliciete goedkeuring voordat je ze kunt gebruiken. Tot toegang is > verleend, wordt een request waarin een van deze modellen wordt genoemd afgewezen met een foutmelding `model_access_denied`. Enterprise- > klanten kunnen contact opnemen met support om toegang aan te vragen. ### Afbeeldingsmodellen | `model_id` | Referentieafbeeldingen | Uitvoerinstellingen | | ----------------------------- | ---------------------------- | ------------------------------------------------------------------------ | | `gpt-image-1` | Maximaal 5, plus een `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-1.5` | Maximaal 5, plus een `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-2` | Maximaal 10, plus een `mask` | 15 beeldverhoudingen, `resolution` (1K, 2K, 4K), `quality` | | `gpt-image-2.5-sunburst` | Maximaal 10, plus een `mask` | 15 beeldverhoudingen, `resolution` (1K, 2K, 4K), `quality` (tot `max`) | | `gpt-image-2.5-flare` | Maximaal 10, plus een `mask` | 15 beeldverhoudingen, `resolution` (1K, 2K, 4K), `quality` (tot `max`) | | `gemini-2.5-flash-image` | Maximaal 5 | `aspect_ratio` | | `gemini-3-pro-image` | Maximaal 10 | `aspect_ratio`, `resolution` (1K, 2K, 4K) | | `gemini-3.1-flash-image` | Maximaal 14 | `aspect_ratio` (inclusief 1:4, 4:1, 1:8, 8:1), `resolution` (512 tot 4K) | | `gemini-3.1-flash-lite-image` | Maximaal 14 | `aspect_ratio`, `resolution` (1K) | | `bytedance-seedream-5-lite` | Maximaal 10 | `aspect_ratio`, `resolution` (2K, 3K), `seed` | | `bytedance-seedream-5-pro` | Maximaal 10 | `aspect_ratio`, `resolution` (1K, 2K), `seed` | 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 | `model_id` | Media-inputs | Uitvoerinstellingen | | ---------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-001` | `start_frame`, `end_frame`, maximaal 3 `images` met een `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`, maximaal 3 `images` met een `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`, maximaal 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 tot 15), 7 beeldverhoudingen, `resolution` (480p tot 4k), `generate_audio` | | `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, maximaal 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 tot 15), 7 beeldverhoudingen, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, maximaal 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 tot 15), 7 beeldverhoudingen, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2.5` | `start_frame`, `end_frame`, maximaal 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (4 tot 30), 7 beeldverhoudingen, `resolution` (480p, 720p), `generate_audio` | | `creatify-aurora` | `image` en `audio`, beide vereist | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale` | Zie voor modelmogelijkheden, beschikbaarheid en prijzen het [overzicht van Afbeelding & Video](/docs/nl/overview/capabilities/image-video). ## Volgende stappen #### [Referenties en assets](/docs/nl/eleven-api/guides/how-to/image-and-video/references) Stuur een generatie aan met een eerdere generatie, een geüploade asset of inline media. #### [Webhooks](/docs/nl/eleven-api/guides/how-to/image-and-video/webhooks) Ontvang het resultaat van een generatie in plaats van ernaar te pollen. #### [API-referentie](/docs/nl/api-reference/flows/image/create) Bekijk de endpoints voor afbeeldingen, video's en assets.