> 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.

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

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

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

> **Warning**
>
> 画像＆ビデオAPIを使用するには、プロ以上のプランが必要です。それより下のティアのワークスペースからの呼び出しは、
> `402 paid_plan_required`エラーで拒否されます。APIキーには、ワークスペースの画像＆ビデオまたは
> Flows権限も必要です。

## 画像を生成する

#### APIキーを作成する

[ダッシュボードでAPIキーを作成](https://elevenlabs.io/app/settings/api-keys)し、安全に[APIへアクセス](/docs/ja/api-reference/authentication)するために使用します。

キーは管理されたシークレットとして保存し、好みに応じて`.env`ファイルによる環境変数として、またはアプリの設定で直接SDKに渡してください。

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### SDKをインストールする

#### SDK

`dotenv`ライブラリも使用して、環境変数からAPIキーを読み込みます。

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

ElevenLabs CLIをインストールします。Homebrew（macOS）と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**
>
> AIコーディングアシスタントを使っていますか？プロジェクトで`elevenlabs generate-skills`を実行すると、各コマンドグループ用の
> `SKILL.md`が`skills/`に作成されます。これにより、ドキュメントを貼り付けなくても、アシスタントがCLIのすべての機能を把握できます。
> 別の場所に配置するには`--output-dir`を使ってください。CLIに組み込まれたAPI定義を読み取るため、APIキーは不要で、オフラインでも動作します。また、
> インストールしているCLIのバージョンに常に対応します。

次に認証します。ブラウザが開き、CLIを承認できます。

```bash
elevenlabs auth login
```

#### 生成を送信する

各モデルには固有のリクエストクラスがあり、そのフィールドがモデルで利用可能なパラメータです。
そのため、モデルを切り替えると利用できるフィールドが変わることがあります。不明なフィールドは無視されず、
拒否されます。

`webhook`は、完了した結果をワークスペースのWebhookへ配信するよう指定するため、呼び出しは生成がキューに追加されるとすぐに
戻ります。生成イベントを購読するWebhookが必要です。設定方法は[画像＆ビデオ Webhook](/docs/ja/eleven-api/guides/how-to/image-and-video/webhooks)を参照するか、フィールドを省略して
代わりにポーリングしてください。

#### 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は同じリクエストをJSONで送信し、生成が完了するまでポーリングして結果をダウンロードします。

```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 <id> --query status

# 3. Read the signed content URL, then download the image
elevenlabs flows image get --generation-id <id> --query content_url
curl -o corgi.png "<content_url>"
```

レスポンスには生成IDのみが含まれます。新しく作成された生成のステータスは常に
`pending`です。

```json
{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}
```

#### 結果を取得する

リクエストで`webhook`を指定しているため、生成が`completed`または`failed`に達すると、ElevenLabsは
エンドポイントに`flows_generation`イベントを送信します。イベントの`data`はGETエンドポイントが返す内容と同一で、
[画像＆ビデオWebhook](/docs/ja/eleven-api/guides/how-to/image-and-video/webhooks)では、それを受信する
ハンドラーについて説明しています。

コールバックを受信するエンドポイントがない場合は、上記のリクエストから`webhook`を削除して、代わりにポーリングします。
ステータスが`completed`または`failed`になるまで生成を取得し、画像の場合はリクエストの間隔を少なくとも2秒空けます。
モダリティごとの間隔については、[ポーリングのガイドライン](#polling-guidelines)を参照してください。

```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()));
```

どちらの方法でも、完了した生成には同じフィールドが含まれます。

```json
{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}
```

#### コードを実行する

```python
python example.py
```

```typescript
npx tsx example.mts
```

生成がキューに追加され、IDが表示されます。Webhook配信では画像がエンドポイントに届き、
ポーリングの場合は`corgi.png`に保存されます。

## ビデオを生成する

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

```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);
```

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

> **Warning**
>
> `webhook`には、生成イベントを購読しているワークスペースWebhookが少なくとも1つ必要です。Webhookがない場合、
> 結果の配信先がない生成を開始するのではなく、作成呼び出しが拒否されます。フィールドを削除すると、
> `flows.video.get`によるポーリングに切り替えられます。ポーリングの頻度は10秒に1回以下にしてください。

## 結果の取得

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

|        | Webhook配信                      | ポーリング                |
| ------ | ------------------------------ | -------------------- |
| 最適な用途  | 両方のモダリティのデフォルト、および本番環境でのあらゆる用途 | 公開エンドポイントのないスクリプトや環境 |
| 必要なもの  | 生成イベントを購読するHTTPSエンドポイント        | なし                   |
| 待機のコスト | なし。生成の完了時に呼び出されます              | ポーリングごと、生成ごとに1リクエスト  |

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

### Webhookターゲットの選択

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

```python
from elevenlabs import WebhookTarget_Ids

webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])
```

```typescript
const webhook = { type: "ids", ids: ["Q8mVr2LpXcT4nB6yJdKw"] };
```

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

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

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

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

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

これより速くポーリングしても意味はありません。2回問い合わせても、生成のステータスが早く変わることはありません。継続的に過度なポーリングを行うと、[429レスポンス](/docs/ja/eleven-api/resources/errors#rate-limiting-and-concurrency)が返ることがあります。指数バックオフで処理してください。

## 生成のライフサイクル

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

| ステータス        | 意味                                                          |
| ------------ | ----------------------------------------------------------- |
| `pending`    | 生成はキューに入っています。新しく作成されたすべての生成はこのステータスです。                     |
| `generating` | モデルが実行中です。                                                  |
| `completed`  | 出力の準備ができました。レスポンスには`content_url`と`content_mime_type`が含まれます。 |
| `failed`     | 生成は出力を作成できませんでした。レスポンスには失敗の詳細が含まれます。                        |

> **Warning**
>
> `content_url`は、レスポンスの返却から約1時間で期限切れになる署名付きURLです。署名付きURL自体を保存するのではなく、生成を再度取得して新しいURLを取得してください。

## 失敗の処理

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

```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`     | 原因                                 |
| -------------------- | ---------------------------------- |
| `timeout`            | モデルが時間内に結果を返しませんでした。               |
| `model_error`        | モデルプロバイダーがエラーを返したか、出力を生成しませんでした。   |
| `moderated`          | プロンプトまたは入力がコンテンツモデレーションにより拒否されました。 |
| `invalid_parameters` | 生成がモデルに到達した時点でパラメーターが拒否されました。      |
| `dependency_failed`  | この生成が依存している参照先の生成が失敗しました。          |
| `charging_failed`    | ワークスペースに生成の料金を請求できませんでした。          |
| `internal_error`     | 予期しないエラーが発生しました。                   |

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

## 料金

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

## 生成の一覧

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

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

## 利用可能なモデル

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

> **Warning**
>
> ByteDanceモデルはデフォルトで無効になっており、使用前に明示的な承認が必要です。アクセスが許可されるまで、これらのモデルのいずれかを指定したリクエストは`model_access_denied`エラーで拒否されます。エンタープライズのお客様は、サポートに連絡してアクセスをリクエストできます。

### 画像モデル

| `model_id`                    | 参照画像              | 出力コントロール                                                |
| ----------------------------- | ----------------- | ------------------------------------------------------- |
| `gpt-image-1`                 | 最大5枚、`mask`を追加可能  | `aspect_ratio`（1:1、3:2、2:3）、`quality`、`background`      |
| `gpt-image-1.5`               | 最大5枚、`mask`を追加可能  | `aspect_ratio`（1:1、3:2、2:3）、`quality`、`background`      |
| `gpt-image-2`                 | 最大10枚、`mask`を追加可能 | 15種類のアスペクト比、`resolution`（1K、2K、4K）、`quality`            |
| `gpt-image-2.5-sunburst`      | 最大10枚、`mask`を追加可能 | 15種類のアスペクト比、`resolution`（1K、2K、4K）、`quality`（最大`max`）   |
| `gpt-image-2.5-flare`         | 最大10枚、`mask`を追加可能 | 15種類のアスペクト比、`resolution`（1K、2K、4K）、`quality`（最大`max`）   |
| `gemini-2.5-flash-image`      | 最大5枚              | `aspect_ratio`                                          |
| `gemini-3-pro-image`          | 最大10枚             | `aspect_ratio`、`resolution`（1K、2K、4K）                   |
| `gemini-3.1-flash-image`      | 最大14枚             | `aspect_ratio`（1:4、4:1、1:8、8:1を含む）、`resolution`（512～4K） |
| `gemini-3.1-flash-lite-image` | 最大14枚             | `aspect_ratio`、`resolution`（1K）                         |
| `bytedance-seedream-5-lite`   | 最大10枚             | `aspect_ratio`、`resolution`（2K、3K）、`seed`               |
| `bytedance-seedream-5-pro`    | 最大10枚             | `aspect_ratio`、`resolution`（1K、2K）、`seed`               |

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

### 動画モデル

| `model_id`                   | メディア入力                                                          | 出力コントロール                                                                                      |
| ---------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `veo-3.1-generate-001`       | `start_frame`、`end_frame`、`role`付きの最大3つの`images`                | `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`、`role`付きの最大3つの`images`                | `duration_secs`（4、6、8）、`aspect_ratio`（16:9、9:16）、`resolution`（720p、1080p、4K）、`generate_audio` |
| `bytedance-seedance-v2`      | `start_frame`、`end_frame`、最大9つの`images`、3つの`videos`、3つの`audios` | `duration_secs`（4～15）、7種類のアスペクト比、`resolution`（480p～4k）、`generate_audio`                       |
| `bytedance-seedance-v2-fast` | `start_frame`、`end_frame`、最大9つの`images`、3つの`videos`、3つの`audios` | `duration_secs`（4～15）、7種類のアスペクト比、`resolution`（480p、720p）、`generate_audio`                     |
| `bytedance-seedance-v2-mini` | `start_frame`、`end_frame`、最大9つの`images`、3つの`videos`、3つの`audios` | `duration_secs`（4～15）、7種類のアスペクト比、`resolution`（480p、720p）、`generate_audio`                     |
| `bytedance-seedance-v2.5`    | `start_frame`、`end_frame`、最大30の`images`、10の`videos`、10の`audios` | `duration_secs`（4～30）、7種類のアスペクト比、`resolution`（480p、720p）、`generate_audio`                     |
| `creatify-aurora`            | `image`と`audio`、両方必須                                            | `resolution`（480p、720p）、`guidance_scale`、`audio_guidance_scale`                               |

モデルの機能、提供状況、料金については、[画像＆ビデオの概要](/docs/ja/overview/capabilities/image-video)を参照してください。

## 次のステップ

#### [参照とアセット](/docs/ja/eleven-api/guides/how-to/image-and-video/references)

過去の生成、アップロードしたアセット、またはインラインメディアで生成をガイドします。

#### [Webhook](/docs/ja/eleven-api/guides/how-to/image-and-video/webhooks)

ポーリングする代わりに、生成結果を受け取ります。

#### [APIリファレンス](/docs/ja/api-reference/flows/image/create)

画像、動画、アセットのエンドポイントを確認します。