画像＆ビデオクイックスタート

画像＆ビデオAPIは非同期です。生成を送信し、完了後に署名付きURLから結果をダウンロードします。画像とビデオには別々のエンドポイントがありますが、どちらもリクエストとレスポンスの形式は同じです。

結果を取得する方法は2つあります。推奨されるのは、以下の例で使用しているWebhook配信です。生成が最終ステータスに達した時点でElevenLabsがエンドポイントを呼び出すため、待機に時間を費やしません。ポーリングは、コールバックを受信するエンドポイントがない場合の代替手段であり、各例ではポーリングに切り替える方法も示しています。

画像を生成する

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

ビデオを生成する

ビデオ生成ではflows.videoを使用し、送信して結果を取得するという同じパターンに従います。ビデオには 数分かかる場合があるため、この例では結果を待つのではなく、webhookでWebhook配信を指定しています。

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)

生成がキューに追加されるとすぐに呼び出しが戻り、完了した結果は、生成イベントを購読しているワークスペース内のすべての Webhookに配信されます。ビデオ出力はMP4のため、完了ペイロードのcontent_mime_typeは video/mp4になります。Webhookの設定と、これを受信するハンドラーの実装については、 画像＆ビデオWebhookを参照してください。

結果の取得

Webhookとポーリングは同じペイロードを返します。違いは取得する内容ではなく、結果を待つ方法です。

可能な限りWebhookを使用してください。コールバックの受信先がない場合はポーリングを使用し、その際は以下の間隔に従ってください。

Webhookターゲットの選択

webhookには2つの形式があります。WebhookTarget_Allは、生成イベントを購読しているすべてのWebhookに配信します。Webhookがローテーションまたは置き換えられても機能するため、これが適切なデフォルトです。 WebhookTarget_Idsは配信先を特定のWebhookに絞り込みます。1つのワークスペースから複数のコンシューマーに配信し、特定のジョブをそのうち1つだけに届ける場合に使用します。

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

すべてのIDは、あらかじめ生成イベントを購読している必要があります。未購読のWebhookを指定すると、暗黙的に無視されるのではなく拒否されます。配信されるペイロードはGETエンドポイントが返すものと同一のため、一方に対応して作成したハンドラーはもう一方でも機能します。Webhookガイドでは、Webhookの設定、署名の検証、イベントの処理について説明しています。

ポーリングのガイドライン

生成時間はモデル、解像度、動画の場合は長さによって異なります。固定ループではなく、リクエスト内容に合わせた間隔でポーリングしてください。

• 画像：2秒に1回を超える頻度でポーリングしないでください。ほとんどは数秒以内に完了します。
• 動画：10秒に1回を超える頻度でポーリングしないでください。数秒ではなく数分かかることを想定し、duration_secsとresolutionに合わせて間隔を調整してください。

どちらにも2つのルールがあります。生成に時間がかかる場合はバックオフしてください。間隔を約1分まで倍増させると、遅い生成が数百件のリクエストになるのを防げます。また、ループには上限を設けてください。停止した生成を無制限ループではなく、自身のコード内でタイムアウトとして終了できます。

これより速くポーリングしても意味はありません。2回問い合わせても、生成のステータスが早く変わることはありません。継続的に過度なポーリングを行うと、429レスポンスが返ることがあります。指数バックオフで処理してください。

生成のライフサイクル

生成は4つのステータスを経ます。2つの終了ステータスでは含まれるフィールドが異なるため、レスポンスの残りを読み取る前にstatusで分岐してください。

失敗の処理

失敗した生成では、人が読めるerror_messageとともにfailure_reasonカテゴリが報告されます。

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

失敗した生成には料金はかかりません。サポートされていないフィールド、モデルで許可される範囲外の値、無効な参照入力の組み合わせなど、事前に検出できるパラメーターの問題は、生成が開始される前に作成リクエストで拒否されます。

料金

生成にはクレジットが課金されます。料金はモデル、解像度や長さなど選択したパラメーター、提供する入力によって異なります。API経由の生成料金は、送信前に料金が表示されるElevenLabsアプリと同じです。モデルと設定の組み合わせごとの料金表示については、プレイグラウンドの画像＆ビデオを参照してください。

生成の一覧

各エンドポイントでは、そのエンドポイントで作成された生成が新しい順に一覧表示されます。結果はワークスペースとこのAPIに限定されるため、ElevenLabsアプリで作成された生成は表示されません。

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には1～100を指定でき、デフォルトは30です。statusを渡すと、1つのライフサイクル状態にある生成のみを返します。model_idを渡すと、単一モデルの生成のみを返します。next_cursorは不透明な値として扱ってください。値をそのまま渡し戻し、has_moreがfalseになったら停止します。

利用可能なモデル

APIでは、ElevenLabsアプリで利用できるモデルの一部を提供しています。各モデルで使用できるのは一覧に記載されたパラメーターのみです。別のモデルがサポートするフィールドを送信すると、検証エラーが返ります。

画像モデル

GPT Image 2.5モデルでは、qualityにlow、medium、high、xhigh、maxを指定でき、デフォルトはhighです。GPT Image 2はhighまでで、デフォルトはmediumです。

動画モデル

モデルの機能、提供状況、料金については、画像＆ビデオの概要を参照してください。

次のステップ