参照とアセット

概要

ほとんどのImage & Videoモデルでは、プロンプトとともにメディアを指定できます。たとえば、ビデオの最初のフレーム、編集する画像、リップシンクの対象となるオーディオなどです。APIのすべてのメディア値フィールドは、固定形式の生バイトではなく参照オブジェクトを受け取り、各参照にはメディアの取得元を示すtypeが付与されます。

参照を受け取れる場所であれば、この3種類はどれでも交換可能です。同じフィールドに、あるリクエストでは生成結果、次のリクエストではアップロード済みアセットを渡せます。

生成を連鎖させる

generation参照は、完了した生成を指す必要はありません。画像を送信してレスポンスからIDを取得し、待たずにそのままビデオリクエストへ渡せます。APIは画像の後にビデオをキューに入れ、画像が完了した時点で開始します。2つの呼び出しの間にアップロードは不要です。

チェーン内の最後の生成にwebhookを設定すれば、何も待つ必要がありません。両方の呼び出しは生成がキューに入るとすぐに返り、グラフ全体がサーバー側で実行され、最後の生成が終端ステータスに達するとエンドポイントが呼び出されます。

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)

webhookが必要なのは最後の生成だけです。画像にも設定すると中間結果のイベントも配信されます。進捗報告には便利ですが、チェーンの実行には不要です。ほかの場合と同様に、このフィールドには生成イベントを購読するWebhookが必要です。設定方法はImage & Video Webhookを参照してください。

コールバックを受け取るエンドポイントがない場合は、webhookを省略し、代わりにチェーンの末尾をポーリングします。中間画像を個別にポーリングする必要はありません。最後の生成だけを、そのモダリティの間隔で待機してください。ビデオの場合は10秒に1回以下です。ポーリングのガイドラインを参照してください。

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

未完了の処理を参照する生成はすぐに作成され、参照先がすべて完了するまでpending状態になります。開始のために追加の操作は必要ありません。チェーンは深さも幅も自由です。生成は複数の参照先を待機でき、それぞれがさらに別の参照先を待機していることもあります。そのため、グラフ全体を一度に送信し、末端でのみ取得できます。キューで待機した時間は、生成のタイムアウトにはカウントされません。

参照先の生成が失敗した場合、依存する生成は実行されず、dependency_failedの理由で失敗します。その後ろにキューイングされているものもすべて失敗します。中断されたチェーンでは課金されません。すでに支払い済みの生成は返金され、保留中のオーディオ生成の長さに基づいて料金が決まるリップシンクのように、まだ存在しない参照出力に価格が依存する生成は、開始した時点でのみ課金されます。ワークスペース内に存在しないgeneration_idは作成呼び出し自体で拒否されるため、タイプミスは失敗した生成としてではなく、すぐに検出されます。

メディアをアセットとしてアップロードする

メディアがElevenLabs外部からのもので、複数の生成で再利用したい場合は、assets APIにファイルをアップロードします。アセットはワークスペースに属し、削除するまで保持されます。

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),
    )
)

アップロードレスポンスには、保存されたアセットの情報が含まれます。

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

content_urlは約1時間有効な署名付きURLで、アップロードの処理中はnullです。新しいURLが必要な場合は、アセットを再取得してください。

ストレージ上限

アップロードしたアセットは、プランに応じたワークスペースの合計ストレージ上限にカウントされます。

上限にカウントされるのはアップロードしたファイルのみで、生成された出力は含まれません。ワークスペースの上限を超えるアップロードは、ファイルを読み取る前にasset_storage_limit_exceededエラーで拒否されます。不要になったアセットを削除して空き容量を確保するか、サポートに連絡して上限の引き上げを依頼してください。

アセットを管理する

アセットは新しい順に一覧表示できます。名前による絞り込みも可能で、前のレスポンスのカーソルを使ってページ送りできます。page_sizeには1〜100を指定でき、デフォルトは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)

IDで単一のアセットを取得または削除できます。アセットを削除しても、すでに使用した生成には影響しません。

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

メディアをインラインで渡す

inline_base64参照はリクエスト本文にメディアを含めるため、単発の入力では別途アップロードする必要がありません。標準のbase64アルファベットでファイルをエンコードし、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",
            )
        ],
    )
)

インラインコンテンツは、デコード後の参照1件あたり25MBが上限です。より大きなファイルはassets APIを使用してください。大幅に大きいアップロードを受け付け、base64によるサイズ増加の影響もありません。各モダリティで受け付けるMIMEタイプは固定されています。

モデル別の参照フィールド

参照フィールドの名前は、メディアが果たす役割に基づいています。start_frameとend_frameはビデオの範囲を定める単一画像、imageとaudioはリップシンクモデルに必須の入力、複数形のimages、videos、audiosはモデルが参照する自由形式の素材です。

モデルごとに、受け付けるフィールドと有効な組み合わせは異なります。end_frameには常にstart_frameが必要です。制約に違反すると、該当フィールドを示すバリデーションエラーが返されるため、生成は開始されず課金もされません。

Veo 3.1

どちらのVeoモデルもstart_frame、end_frame、および最大3件のimagesを受け付けます。他のモデルと異なり、imagesの各エントリは参照とその役割をまとめて指定します。

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

subject参照は画像の被写体またはシーン要素をビデオに配置し、style参照は視覚スタイルを転送します。参照画像はstart_frameまたはend_frameと組み合わせることはできず、8秒の長さが必要です。

Seedance

3つのSeedance 2.0ティアでは、start_frame、end_frame、最大9件のimages、最大3件のvideos、最大3件のaudiosを受け付けます。ただし、次の制約があります。

• 参照はstart_frameまたはend_frameと組み合わせることはできません。
• 参照オーディオには、たとえばリップシンクを動作させるために、少なくとも1つの参照画像またはビデオが必要です。
• 参照ファイルの合計数は12を超えることはできません。

Seedance 2.5では、上限がimages30件、videos10件、audios10件に引き上げられ、合計数の上限はなくなります。また、参照オーディオに画像またはビデオを伴わせるルールもなくなるため、オーディオのみの入力を受け付けます。参照は引き続きstart_frameまたはend_frameと組み合わせることはできません。

GPT Image

GPT Imageモデルは、imagesとともにmaskを受け付けます。マスクの完全に透明な領域は、最初の参照画像を編集できる場所を示します。参照画像なしのマスクは拒否されます。

次のステップ