Krótkie wprowadzenie do Image & Video

API Image & Video działa asynchronicznie. Wysyłasz żądanie generowania, a po jego zakończeniu pobierasz wynik z podpisanego URL-a. Obrazy i wideo mają osobne endpointy, ale struktura żądań i odpowiedzi jest taka sama dla obu.

Wynik możesz odebrać na dwa sposoby. Zalecamy dostarczenie przez webhook, używane też w poniższych przykładach: ElevenLabs wywołuje twój endpoint, gdy generowanie osiągnie status końcowy, więc nie tracisz czasu na oczekiwanie. Odpytanie to opcja zapasowa, gdy nie masz endpointu do odbierania callbacków, a każdy przykład pokazuje, jak z niej skorzystać.

Wygeneruj obraz

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

Wygeneruj wideo

Generowanie wideo używa flows.video i przebiega według tego samego schematu wysłania żądania oraz odbioru wyniku. Wideo może trwać kilka minut, dlatego ten przykład korzysta z dostarczania przez webhook za pomocą webhook, zamiast czekać na wynik.

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)

Wywołanie zwraca odpowiedź, gdy tylko generowanie zostanie dodane do kolejki, a gotowy wynik jest dostarczany do każdego webhooka w twoim obszarze roboczym, który subskrybuje zdarzenia generowania. Wynik wideo to MP4, więc ukończony payload podaje content_mime_type o wartości video/mp4. Zobacz webhooki Image & Video, aby skonfigurować webhook i napisać handler, który to odbierze.

Odbieranie wyników

Webhooki i odpytywanie zwracają ten sam payload, więc wybór dotyczy sposobu oczekiwania na wynik, a nie tego, co otrzymasz.

Używaj webhooków, gdzie tylko możesz. Wybierz odpytywanie, gdy nie masz gdzie odebrać callbacku, i stosuj poniższe interwały.

Wybór celów webhooków

webhook przyjmuje dwie formy. WebhookTarget_All dociera do każdego webhooka subskrybującego zdarzenia generowania — to właściwy wybór domyślny, bo działa nawet po rotacji lub zastąpieniu webhooków. WebhookTarget_Ids ogranicza dostarczanie do konkretnych webhooków — przydaje się, gdy jeden workspace wysyła dane do kilku odbiorców, a dane zadanie powinno trafić tylko do jednego z nich:

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

Każde ID musi już subskrybować zdarzenia generowania; podanie webhooka bez subskrypcji powoduje odrzucenie żądania, a nie jego ciche zignorowanie. Dostarczony payload jest identyczny z tym, który zwraca endpoint GET, więc handler napisany dla jednego działa też z drugim. Przewodnik po webhookach opisuje konfigurację webhooka, weryfikację podpisu i obsługę zdarzenia.

Wskazówki dotyczące odpytywania

Czas generowania zależy od modelu, rozdzielczości, a w przypadku wideo także od czasu trwania, więc ustawiaj interwał odpytywania odpowiednio do żądanego wyniku, zamiast używać stałej pętli:

• Obrazy: odpytywanie nie częściej niż raz na 2 sekundy. Większość kończy się w ciągu kilku sekund.
• Wideo: odpytywanie nie częściej niż raz na 10 sekund. Spodziewaj się minut, nie sekund, i dostosuj interwał do duration_secs oraz resolution.

Dwie zasady dotyczą obu przypadków. Wydłużaj interwał, gdy generowanie trwa długo — podwajanie go aż do około minuty zapobiega wysłaniu setek żądań przy wolnym generowaniu. Ustaw też limit pętli, aby zablokowane generowanie kończyło się timeoutem w twoim kodzie, a nie nieograniczoną pętlą.

Szybsze odpytywanie nic nie daje: status generowania nie zmieni się szybciej tylko dlatego, że zapytasz dwa razy. Długotrwałe agresywne odpytywanie może zwrócić odpowiedzi 429, które należy obsłużyć za pomocą wykładniczego wydłużania interwału.

Cykl życia generowania

Generowanie przechodzi przez cztery statusy. Dwa końcowe statusy zawierają różne pola, dlatego sprawdź status, zanim odczytasz resztę odpowiedzi.

Obsługa błędów

Nieudane generowanie zgłasza kategorię failure_reason wraz z czytelnym dla człowieka komunikatem 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."
}

Nieudane generowania nie są płatne. Problemy z parametrami, które można wykryć z góry — nieobsługiwane pole, wartość poza dozwolonym zakresem modelu lub nieprawidłowe połączenie danych referencyjnych — są zamiast tego odrzucane przez żądanie utworzenia, zanim generowanie się rozpocznie.

Ceny

Generowania są rozliczane w kredytach. Koszt zależy od modelu, wybranych parametrów, takich jak rozdzielczość i czas trwania, oraz podanych danych wejściowych. Generowanie przez API kosztuje tyle samo, co w aplikacji ElevenLabs, gdzie cena jest widoczna przed wysłaniem. Zobacz Image & Video w playgroundzie, aby dowiedzieć się, jak prezentowany jest koszt danego modelu i kombinacji ustawień.

Lista generowań

Każdy endpoint wyświetla generowania utworzone przez niego, od najnowszych. Wyniki są ograniczone do twojego workspace’u i tego API, więc generowania utworzone w aplikacji ElevenLabs się nie pojawią.

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 przyjmuje wartości od 1 do 100, a domyślnie wynosi 30. Przekaż status, aby zwrócić tylko generowania w jednym stanie cyklu życia, oraz model_id, aby zwrócić tylko generowania z jednego modelu. Traktuj next_cursor jako nieprzezroczystą wartość: przekaż z powrotem dokładnie tę samą wartość i zakończ, gdy has_more ma wartość false.

Dostępne modele

API udostępnia część modeli dostępnych w aplikacji ElevenLabs. Każdy model przyjmuje tylko parametry dla niego wymienione — wysłanie pola obsługiwanego przez inny model zwraca błąd walidacji.

Modele obrazów

Modele GPT Image 2.5 przyjmują wartości quality: low, medium, high, xhigh i max, a domyślnie używają high. GPT Image 2 obsługuje maksymalnie high, a domyślnie używa medium.

Modele wideo

Informacje o możliwościach modeli, dostępności i cenach znajdziesz w przeglądzie Image & Video.

Kolejne kroki