Materiały referencyjne i zasoby

Omówienie

Większość modeli Image & Video przyjmuje media wraz z promptem: pierwszą klatkę filmu, obrazy do edycji czy audio do synchronizacji ruchu ust. Każde pole API przyjmujące media oczekuje obiektu referencji zamiast surowych bajtów w określonym formacie, a każda referencja ma type, który wskazuje źródło mediów.

Trzy rodzaje są wymienne wszędzie tam, gdzie można użyć referencji, więc to samo pole może przyjąć wynik generacji w jednym żądaniu, a przesłany zasób w kolejnym.

Połącz generacje w łańcuch

Referencja generation nie musi wskazywać na zakończoną generację. Wyślij obraz, pobierz ID z odpowiedzi i od razu przekaż je w żądaniu filmu bez czekania: API ustawi film w kolejce za obrazem i uruchomi go, gdy tylko obraz będzie gotowy. Między tymi dwoma wywołaniami nic nie jest przesyłane.

Ustaw webhook w ostatniej generacji łańcucha i nie musisz w ogóle czekać. Oba wywołania zwracają odpowiedź, gdy ich generacja trafi do kolejki, cały graf działa po stronie serwera, a twój endpoint zostanie wywołany, gdy ostatnia generacja osiągnie status końcowy.

from elevenlabs import (
    ImageGenerationRequest_Gemini3ProImage,
    ImageReference_Generation,
    VideoGenerationRequest_Veo31FastGenerate001,
    WebhookTarget_All,
)
still = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
        aspect_ratio="16:9",
    )
)
# `still` is still pending here. Submitting now queues the video behind it.
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The fog thickens and the beam sweeps across the water",
        start_frame=ImageReference_Generation(generation_id=still.id),
        duration_secs=8,
        webhook=WebhookTarget_All(),
    )
)
print(clip.id)

Tylko ostatnia generacja potrzebuje webhook. Ustawienie go także dla obrazu dostarczy zdarzenie również dla wyniku pośredniego. Przydaje się to do raportowania postępu, ale nie jest potrzebne do uruchomienia łańcucha. Tak jak w innych miejscach, pole wymaga webhooka subskrybującego zdarzenia generacji; aby go skonfigurować, zobacz webhooki Image & Video.

Jeśli nie masz endpointu do odbierania callbacków, pomiń webhook i zamiast tego odpytywać końcową część łańcucha. Pośredni obraz nadal nie wymaga własnego odpytywania — zaczekaj tylko raz, na ostatnią generację, w interwale dla jej typu. W przypadku filmu to maksymalnie raz na 10 sekund. Zobacz zasady odpytywania.

import time
while True:
    result = elevenlabs.flows.video.get(clip.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(10)

Generacja odwołująca się do niezakończonej pracy jest tworzona od razu i pozostaje w stanie pending, aż zakończą się wszystkie generacje, do których się odwołuje. Nie musisz nic robić, by ją uruchomić. Łańcuchy mogą mieć dowolną głębokość i szerokość — generacja może czekać na kilka referencji, z których każda sama jeszcze czeka — więc cały graf można wysłać za jednym razem i odebrać tylko na jego końcach. Czas w kolejce nie wlicza się do limitu czasu generacji.

Jeśli wskazana generacja się nie powiedzie, zależna od niej generacja nigdy nie ruszy: zakończy się z powodem dependency_failed i pociągnie za sobą wszystko, co czeka za nią w kolejce. Za nic w przerwanym łańcuchu nie zostanie naliczona opłata — generacja, za którą już zapłacono, zostanie zwrócona, a generacja, której cena zależy od wskazanego wyniku, który jeszcze nie istnieje, na przykład synchronizacja ruchu ust wyceniana według długości oczekującej generacji audio, zostanie naliczona dopiero po uruchomieniu. generation_id, które nie istnieje w twoim workspace, zostanie odrzucone już przy wywołaniu tworzenia, więc literówka pojawi się od razu, a nie jako nieudana generacja.

Prześlij media jako zasób

Prześlij plik do API zasobów, gdy media pochodzą spoza ElevenLabs i chcesz używać ich ponownie w różnych generacjach. Zasoby należą do workspace i są przechowywane, dopóki ich nie usuniesz.

from elevenlabs import ImageReference_Asset, VideoGenerationRequest_Veo31FastGenerate001
with open("lighthouse.png", "rb") as f:
    asset = elevenlabs.assets.create(asset=f, name="lighthouse.png")
print(asset.asset_id)
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The beam sweeps across the water as the fog thickens",
        start_frame=ImageReference_Asset(asset_id=asset.asset_id),
    )
)

Odpowiedź na przesłanie opisuje zapisany zasób:

{
  "asset_id": "5xM2KqOnZyce22SPZ9d4",
  "name": "lighthouse.png",
  "mime_type": "image/png",
  "created_at_unix": 1721520000,
  "content_url": "https://storage.googleapis.com/assets/5xM2KqOnZyce22SPZ9d4"
}

content_url to podpisany URL ważny przez około godzinę. Ma wartość null, gdy przesyłanie jest jeszcze przetwarzane. Pobierz zasób ponownie, aby uzyskać nowy URL.

Limity miejsca

Przesłane zasoby wliczają się do łącznego limitu miejsca w workspace, który zależy od planu:

Do limitu wliczają się tylko przesłane pliki, nie wygenerowane wyniki. Przesłanie, które przekroczyłoby limit workspace, zostanie odrzucone z błędem asset_storage_limit_exceeded zanim plik zostanie odczytany. Usuń niepotrzebne zasoby, by zwolnić miejsce, lub skontaktuj się z pomocą, aby zwiększyć limit.

Zarządzanie zasobami

Wyświetl zasoby od najnowszych, opcjonalnie filtrując po nazwie, i przechodź przez wyniki stronami za pomocą kursora z poprzedniej odpowiedzi. page_size przyjmuje wartości od 1 do 100, a domyślnie wynosi 30.

page = elevenlabs.assets.list(page_size=20, search="lighthouse")
for asset in page.assets:
    print(asset.asset_id, asset.name, asset.mime_type)
if page.has_more:
    page = elevenlabs.assets.list(page_size=20, search="lighthouse", cursor=page.next_cursor)

Pobierz lub usuń pojedynczy zasób według ID. Usunięcie zasobu nie wpływa na generacje, które już go użyły.

asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4")
elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4")

Przekaż media inline

Referencja inline_base64 zawiera media w treści żądania, więc nie trzeba osobno przesyłać plików używanych jednorazowo. Zakoduj plik standardowym alfabetem base64 i podaj jego typ MIME.

import base64
from elevenlabs import ImageGenerationRequest_GptImage2, ImageReference_InlineBase64
with open("headshot.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_GptImage2(
        prompt="Replace the background with a softly lit studio backdrop",
        images=[
            ImageReference_InlineBase64(
                content_base64=encoded,
                mime_type="image/jpeg",
            )
        ],
    )
)

Zawartość inline jest ograniczona do 25 MB na referencję po zdekodowaniu. Większe pliki należy przesyłać do API zasobów, które przyjmuje znacznie większe pliki i nie ponosi narzutu rozmiaru base64. Każdy typ mediów akceptuje określony zestaw typów MIME:

Pola referencji według modelu

Pola referencji są nazwane zgodnie z rolą, jaką pełnią media. start_frame i end_frame to pojedyncze obrazy wyznaczające początek i koniec filmu, image i audio to wymagane dane wejściowe modelu synchronizacji ruchu ust, a same liczby mnogie images, videos i audios to dowolne materiały referencyjne, z których korzysta model.

Pola akceptowane przez model oraz prawidłowe kombinacje różnią się zależnie od modelu. end_frame zawsze wymaga start_frame. Naruszenie ograniczenia zwraca błąd walidacji wskazujący problematyczne pole, więc generacja nigdy się nie rozpoczyna i nie jest naliczana.

Veo 3.1

Oba modele Veo akceptują start_frame, end_frame i maksymalnie trzy wpisy w images. W przeciwieństwie do innych modeli każdy wpis w images łączy referencję z rolą, jaką pełni:

{
  "images": [
    {
      "image": { "type": "asset", "asset_id": "5xM2KqOnZyce22SPZ9d4" },
      "role": "subject"
    },
    {
      "image": { "type": "asset", "asset_id": "7pQ4LnBvXkR2mT9wYcHd" },
      "role": "style"
    }
  ]
}

Referencja subject umieszcza obiekt lub elementy sceny z obrazu w filmie, a referencja style przenosi jego styl wizualny. Obrazy referencyjne nie mogą być łączone z start_frame ani end_frame i wymagają ośmiosekundowego czasu trwania.

Seedance

Trzy warianty Seedance 2.0 akceptują start_frame, end_frame, do 9 images, do 3 videos i do 3 audios, z tymi ograniczeniami:

• Referencje nie mogą być łączone z start_frame ani end_frame.
• Referencyjne audio wymaga co najmniej jednego obrazu lub filmu referencyjnego, na przykład do synchronizacji ruchu ust.
• Łączna liczba plików referencyjnych nie może przekraczać 12.

Seedance 2.5 zwiększa limity do 30 images, 10 videos i 10 audios, bez łącznego limitu, oraz usuwa zasadę, że referencyjne audio potrzebuje towarzyszącego obrazu lub filmu, więc akceptowane jest samo audio. Referencji nadal nie można łączyć z start_frame ani end_frame.

GPT Image

Modele GPT Image akceptują mask wraz z images. W pełni przezroczyste obszary maski wskazują, gdzie można edytować pierwszy obraz referencyjny. Maska bez obrazów referencyjnych zostanie odrzucona.

Kolejne kroki