> 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. # 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](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks), 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ć. > **Warning** > > API Image & Video wymaga planu Pro lub wyższego. Żądania z obszaru roboczego poniżej tego poziomu są > odrzucane z błędem `402 paid_plan_required`. Twój klucz API musi też mieć uprawnienie Image & Video lub > Flows dla obszaru roboczego. ## Wygeneruj obraz #### Utwórz klucz API [Utwórz klucz API w panelu tutaj](https://elevenlabs.io/app/api/api-keys), którego użyjesz, aby bezpiecznie [uzyskać dostęp do API](/docs/pl/api-reference/authentication). Przechowuj klucz jako zarządzany sekret i przekaż go do SDK jako zmienną środowiskową w pliku `.env` lub bezpośrednio w konfiguracji aplikacji — zależnie od preferencji. **`.env`** ```js title=".env" ELEVENLABS_API_KEY= ``` #### Zainstaluj SDK #### SDK Użyjemy też biblioteki `dotenv`, aby wczytać klucz API ze zmiennej środowiskowej. ```python pip install elevenlabs pip install python-dotenv ``` ```typescript npm install @elevenlabs/elevenlabs-js npm install dotenv ``` #### CLI Zainstaluj CLI ElevenLabs. Zalecamy Homebrew (macOS) lub Scoop (Windows). **`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** > > Pracujesz z asystentem AI do kodowania? Uruchom `elevenlabs generate-skills` w projekcie, aby zapisać > `SKILL.md` dla każdej grupy poleceń w `skills/`. Dzięki temu asystent zna pełny zakres CLI > bez wklejania dokumentacji. Użyj `--output-dir`, aby zapisać je w innym miejscu. Polecenie odczytuje > wbudowaną definicję API CLI, więc nie potrzebuje klucza API i działa offline — oraz jest zgodne > z zainstalowaną wersją CLI. Następnie się uwierzytelnij — otworzy się przeglądarka, aby autoryzować CLI: ```bash elevenlabs auth login ``` #### Wyślij żądanie generowania Każdy model ma własną klasę żądania, a jej pola to parametry obsługiwane przez ten model, więc zmiana modelu może zmienić dostępne pola. Nieznane pola są odrzucane, a nie ignorowane. `webhook` prosi o dostarczenie gotowego wyniku do webhooków twojego obszaru roboczego, więc wywołanie zwraca odpowiedź, gdy tylko generowanie zostanie dodane do kolejki. Wymaga webhooka subskrybującego zdarzenia generowania; zobacz [webhooki Image & Video](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks), aby go skonfigurować, lub pomiń to pole i użyj odpytywania. #### 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 CLI wysyła to samo żądanie jako JSON, a następnie odpytuje o status do zakończenia generowania i pobiera wynik: ```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 "" ``` Odpowiedź zawiera identyfikator generowania i nic więcej. Nowo utworzone generowanie zawsze ma status `pending`: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "pending" } ``` #### Odbierz wynik Ponieważ żądanie używa `webhook`, ElevenLabs wysyła zdarzenie `flows_generation` do twojego endpointu, gdy generowanie osiągnie status `completed` lub `failed`. Pole `data` zdarzenia jest identyczne z tym, co zwraca endpoint GET, a [webhooki Image & Video](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks) pokazują handler, który je odbiera. Jeśli nie masz endpointu do odbierania callbacków, usuń `webhook` z powyższego żądania i użyj odpytywania. Pobieraj dane generowania, aż jego status będzie `completed` lub `failed`, zachowując co najmniej dwie sekundy między żądaniami obrazu — zobacz [wytyczne dotyczące odpytywania](#polling-guidelines), aby sprawdzić interwały dla poszczególnych typów mediów. ```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())); ``` W obu przypadkach ukończone generowanie zawiera te same pola: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "completed", "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb", "content_mime_type": "image/png" } ``` #### Uruchom kod ```python python example.py ``` ```typescript npx tsx example.mts ``` Generowanie zostanie dodane do kolejki, a jego identyfikator wyświetlony. Przy dostarczaniu przez webhook obraz trafi do twojego endpointu; w wariancie z odpytywaniem zostanie zapisany jako `corgi.png`. ## 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. ```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); ``` 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](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks), aby skonfigurować webhook i napisać handler, który to odbierze. > **Warning** > > `webhook` wymaga co najmniej jednego webhooka obszaru roboczego subskrybującego zdarzenia generowania. Bez niego > wywołanie create zostanie odrzucone, zamiast rozpoczynać generowanie, którego wynik nie ma dokąd trafić. Usuń > to pole, aby użyć odpytywania przez `flows.video.get`, i odpytywać nie częściej niż raz na 10 > sekund. ## Odbieranie wyników Webhooki i odpytywanie zwracają ten sam payload, więc wybór dotyczy sposobu oczekiwania na wynik, a nie tego, co otrzymasz. | | Dostarczanie przez webhook | Odpytywanie | | ----------------- | ------------------------------------------------------ | ---------------------------------------------- | | Najlepsze dla | Domyślnie dla obu typów i każdego użycia produkcyjnego | Skryptów i środowisk bez publicznego endpointu | | Wymaga | Endpointu HTTPS subskrybującego zdarzenia generowania | Niczego | | Koszt oczekiwania | Brak; otrzymasz wywołanie po zakończeniu generowania | Jedno żądanie na każde odpytanie i generowanie | 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: ```python from elevenlabs import WebhookTarget_Ids webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"]) ``` ```typescript const webhook = { type: "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](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks) 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](/docs/pl/eleven-api/resources/errors#rate-limiting-and-concurrency), 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. | Status | Znaczenie | | ------------ | ----------------------------------------------------------------------------- | | `pending` | Generowanie czeka w kolejce. Taki status ma każde nowo utworzone generowanie. | | `generating` | Model działa. | | `completed` | Wynik jest gotowy. Odpowiedź zawiera `content_url` i `content_mime_type`. | | `failed` | Generowanie nie zwróciło wyniku. Odpowiedź zawiera szczegóły błędu. | > **Warning** > > `content_url` to podpisany URL, który wygasa około godzinę po zwróceniu odpowiedzi. Pobierz > generowanie ponownie, aby uzyskać nowy URL, zamiast zapisywać sam podpisany URL. ## Obsługa błędów Nieudane generowanie zgłasza kategorię `failure_reason` wraz z czytelnym dla człowieka komunikatem `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` | Przyczyna | | -------------------- | ------------------------------------------------------------------- | | `timeout` | Model nie zwrócił wyniku na czas. | | `model_error` | Dostawca modelu zwrócił błąd lub model nie wygenerował wyniku. | | `moderated` | Prompt lub dane wejściowe zostały odrzucone przez moderację treści. | | `invalid_parameters` | Parametry odrzucono po dotarciu generowania do modelu. | | `dependency_failed` | Nie udało się generowanie, od którego zależy to generowanie. | | `charging_failed` | Nie udało się obciążyć workspace'u za generowanie. | | `internal_error` | Wystąpił nieoczekiwany błąd. | 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](/docs/pl/eleven-creative/playground/image-video), 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ą. ```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` 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. > **Warning** > > Modele ByteDance są domyślnie wyłączone i wymagają wyraźnej zgody przed użyciem. Do czasu przyznania > dostępu żądanie wskazujące jeden z nich zostanie odrzucone z błędem `model_access_denied`. Klienci > Enterprise mogą skontaktować się ze wsparciem, aby poprosić o dostęp. ### Modele obrazów | `model_id` | Obrazy referencyjne | Kontrole wyjścia | | ----------------------------- | ------------------- | -------------------------------------------------------------------- | | `gpt-image-1` | Do 5, plus `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-1.5` | Do 5, plus `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-2` | Do 10, plus `mask` | 15 proporcji obrazu, `resolution` (1K, 2K, 4K), `quality` | | `gpt-image-2.5-sunburst` | Do 10, plus `mask` | 15 proporcji obrazu, `resolution` (1K, 2K, 4K), `quality` (do `max`) | | `gpt-image-2.5-flare` | Do 10, plus `mask` | 15 proporcji obrazu, `resolution` (1K, 2K, 4K), `quality` (do `max`) | | `gemini-2.5-flash-image` | Do 5 | `aspect_ratio` | | `gemini-3-pro-image` | Do 10 | `aspect_ratio`, `resolution` (1K, 2K, 4K) | | `gemini-3.1-flash-image` | Do 14 | `aspect_ratio` (w tym 1:4, 4:1, 1:8, 8:1), `resolution` (512 do 4K) | | `gemini-3.1-flash-lite-image` | Do 14 | `aspect_ratio`, `resolution` (1K) | | `bytedance-seedream-5-lite` | Do 10 | `aspect_ratio`, `resolution` (2K, 3K), `seed` | | `bytedance-seedream-5-pro` | Do 10 | `aspect_ratio`, `resolution` (1K, 2K), `seed` | 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 | `model_id` | Dane wejściowe mediów | Kontrole wyjścia | | ---------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-001` | `start_frame`, `end_frame`, do 3 `images` z `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`, do 3 `images` z `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`, do 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 do 15), 7 proporcji obrazu, `resolution` (480p do 4k), `generate_audio` | | `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, do 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 do 15), 7 proporcji obrazu, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, do 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 do 15), 7 proporcji obrazu, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2.5` | `start_frame`, `end_frame`, do 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (4 do 30), 7 proporcji obrazu, `resolution` (480p, 720p), `generate_audio` | | `creatify-aurora` | `image` i `audio`, oba wymagane | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale` | Informacje o możliwościach modeli, dostępności i cenach znajdziesz w [przeglądzie Image & Video](/docs/pl/overview/capabilities/image-video). ## Kolejne kroki #### [Materiały referencyjne i zasoby](/docs/pl/eleven-api/guides/how-to/image-and-video/references) Poprowadź generowanie za pomocą poprzedniego generowania, przesłanego zasobu lub mediów inline. #### [Webhooki](/docs/pl/eleven-api/guides/how-to/image-and-video/webhooks) Odbierz wynik generowania zamiast go odpytywać. #### [Dokumentacja API](/docs/pl/api-reference/flows/image/create) Poznaj endpointy obrazów, wideo i zasobów.