Snabbstart för Image & Video

Image & Video API är asynkront. Du skickar in en generering och laddar ned resultatet från en signerad URL när den är klar. Bilder och videor har separata slutpunkter, men strukturen för begäran och svaret är densamma för båda.

Det finns två sätt att hämta resultatet. Webhook-leverans är det rekommenderade alternativet och används i exemplen nedan: ElevenLabs anropar din slutpunkt när en generering når en slutgiltig status, så ingen tid går åt till väntan. Pollning är ett alternativ när du inte har någon slutpunkt som kan ta emot en callback, och varje exempel visar hur du använder det i stället.

Generera en bild

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

Generera en video

Videogenereringar använder flows.video och följer samma mönster för att skicka in och hämta resultat. En video kan ta flera minuter, så det här exemplet använder webhook-leverans med webhook i stället för att vänta på resultatet.

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)

Anropet returnerar så snart genereringen har köats och det färdiga resultatet levereras till varje webhook i din arbetsyta som prenumererar på genereringshändelser. Videoutdata är MP4, så den slutförda nyttolasten rapporterar en content_mime_type på video/mp4. Se Image & Video-webhooks för att konfigurera en webhook och skriva hanteraren som tar emot detta.

Hämta resultat

Webhooks och pollning returnerar samma nyttolast, så valet handlar om hur du väntar på den snarare än vad du får.

Använd webhooks när du kan. Välj pollning när du inte har någonstans att ta emot en callback, och följ intervallen nedan när du gör det.

Välja webhook-mål

webhook accepterar två former. WebhookTarget_All når varje webhook som prenumererar på genererings- händelser, vilket är rätt standardval eftersom det fungerar även om webhooks roteras eller ersätts. WebhookTarget_Ids begränsar leveransen till specifika webhooks, när en arbetsyta distribuerar till flera konsumenter och ett visst jobb bara ska nå en av dem:

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

Varje ID måste redan prenumerera på genereringshändelser; att ange en webhook utan prenumeration avvisas i stället för att tyst ignoreras. Den levererade nyttolasten är identisk med vad GET-slutpunkten returnerar, så en hanterare som skrivits för den ena fungerar även för den andra. I webhook-guiden beskrivs hur du konfigurerar en webhook, verifierar signaturen och hanterar händelsen.

Riktlinjer för pollning

En genererings körtid beror på modellen, upplösningen och, för video, längden. Polla därför med ett intervall som motsvarar vad du har begärt i stället för i en fast loop:

• Bilder: polla högst en gång varannan sekund. De flesta blir klara inom några sekunder.
• Video: polla högst en gång var tionde sekund. Räkna med minuter, inte sekunder, och anpassa intervallet efter duration_secs och resolution.

Två regler gäller för båda. Backa när en generering tar lång tid – att fördubbla intervallet upp till ungefär en minut hindrar en långsam generering från att resultera i hundratals begäranden. Och sätt en övre gräns för loopen, så att en fastnad generering avslutas med en timeout i din egen kod i stället för en obegränsad loop.

Att polla snabbare ger dig inget: en genererings status ändras inte snabbare för att du frågar två gånger. Ihållande aggressiv pollning kan returnera 429-svar, som du bör hantera med exponentiell backoff.

Genereringens livscykel

En generering går igenom fyra statusar. De två slutgiltiga statusarna innehåller olika fält, så kontrollera status innan du läser resten av svaret.

Hantera fel

En misslyckad generering rapporterar kategorin failure_reason tillsammans med ett läsbart 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."
}

Misslyckade genereringar debiteras inte. Parameterproblem som kan upptäckas direkt – ett fält som inte stöds, ett värde utanför modellens tillåtna intervall eller en ogiltig kombination av referens- inmatningar – avvisas i stället av begäran om att skapa en generering, innan någon generering startar.

Priser

Genereringar debiteras i krediter. Kostnaden beror på modellen, parametrarna du väljer, till exempel upplösning och längd, samt inmatningarna du tillhandahåller. En generering kostar lika mycket via API:t som den gör i ElevenLabs-appen, där kostnaden visas innan du skickar in den. Se Image & Video i playground för hur kostnaden för en viss kombination av modell och inställningar visas.

Lista dina genereringar

Varje slutpunkt listar genereringarna som skapats genom den, med de senaste först. Resultaten är begränsade till din arbetsyta och detta API, så genereringar som skapats i ElevenLabs-appen visas inte.

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 accepterar 1 till 100 och har standardvärdet 30. Skicka status för att bara returnera genereringar i ett livscykeltillstånd och model_id för att bara returnera genereringar från en enskild modell. Behandla next_cursor som ogenomskinlig: skicka tillbaka exakt värde och sluta när has_more är false.

Tillgängliga modeller

API:et exponerar en delmängd av modellerna som finns i ElevenLabs-appen. Varje modell accepterar bara de parametrar som anges för den – om du skickar ett fält som stöds av en annan modell får du ett valideringsfel.

Bildmodeller

GPT Image 2.5-modellerna accepterar quality-värdena low, medium, high, xhigh och max, och använder high som standard. GPT Image 2 går bara till high och använder medium som standard.

Videomodeller

Information om modellfunktioner, tillgänglighet och priser finns i översikten över Bild och video.

Nästa steg