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

# 参照とアセット

> **Note**
>
> **ハウツーガイド** · [Image & Video クイックスタート](/docs/ja/eleven-api/guides/cookbooks/image-and-video)を完了していることを前提としています。

## 概要

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

| `type`          | 参照先                      | フィールド                         |
| --------------- | ------------------------ | ----------------------------- |
| `generation`    | 完了済みまたは実行中の別の生成の出力。      | `generation_id`               |
| `asset`         | assets APIにアップロードしたファイル。 | `asset_id`                    |
| `inline_base64` | リクエスト本文に直接エンコードされたメディア。  | `content_base64`, `mime_type` |

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

## 生成を連鎖させる

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

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

```python maxLines=0
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)
```

```typescript maxLines=0
const still = await elevenlabs.flows.image.create({
  modelId: "gemini-3-pro-image",
  prompt: "A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
  aspectRatio: "16:9",
});

// `still` is still pending here. Submitting now queues the video behind it.
const clip = await elevenlabs.flows.video.create({
  modelId: "veo-3.1-fast-generate-001",
  prompt: "The fog thickens and the beam sweeps across the water",
  startFrame: { type: "generation", generationId: still.id },
  durationSecs: 8,
  webhook: { type: "all" },
});

console.log(clip.id);
```

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

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

```python
import time

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

```typescript
let result = await elevenlabs.flows.video.get(clip.id);
while (result.status === "pending" || result.status === "generating") {
  await new Promise((resolve) => setTimeout(resolve, 10000));
  result = await elevenlabs.flows.video.get(clip.id);
}
```

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

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

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

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

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

```typescript
import { createReadStream } from "fs";

const asset = await elevenlabs.assets.create({
  asset: createReadStream("lighthouse.png"),
  name: "lighthouse.png",
});

console.log(asset.assetId);

const clip = await elevenlabs.flows.video.create({
  modelId: "veo-3.1-fast-generate-001",
  prompt: "The beam sweeps across the water as the fog thickens",
  startFrame: { type: "asset", assetId: asset.assetId },
});
```

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

```json
{
  "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が必要な場合は、アセットを再取得してください。

> **Warning**
>
> APIキーでassets APIにアクセスするには、生成エンドポイントと同じくPro以上のプランが必要です。

### ストレージ上限

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

| プラン      | アセットストレージ |
| -------- | --------- |
| プロ       | 11 GB     |
| スケール     | 33 GB     |
| ビジネス     | 111 GB    |
| エンタープライズ | 333 GB    |

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

### アセットを管理する

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

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

```typescript
let page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse" });

for (const asset of page.assets) {
  console.log(asset.assetId, asset.name, asset.mimeType);
}

if (page.hasMore) {
  page = await elevenlabs.assets.list({
    pageSize: 20,
    search: "lighthouse",
    cursor: page.nextCursor,
  });
}
```

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

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

```typescript
const asset = await elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4");
await elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4");
```

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

`inline_base64`参照はリクエスト本文にメディアを含めるため、単発の入力では別途アップロードする必要がありません。標準のbase64アルファベットでファイルをエンコードし、MIMEタイプを指定します。

```python
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",
            )
        ],
    )
)
```

```typescript
import { readFile } from "fs/promises";

const encoded = (await readFile("headshot.jpg")).toString("base64");

const generation = await elevenlabs.flows.image.create({
  modelId: "gpt-image-2",
  prompt: "Replace the background with a softly lit studio backdrop",
  images: [
    {
      type: "inline_base64",
      contentBase64: encoded,
      mimeType: "image/jpeg",
    },
  ],
});
```

> **Warning**
>
> インラインメディアは、保持を保証しない一時的なアセットとして保存され、生成が完了すると削除される場合があります。同じ入力を複数回参照する必要がある場合は、代わりにassets APIへファイルをアップロードしてください。

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

| 参照    | 対応する`mime_type`                                                     |
| ----- | ------------------------------------------------------------------- |
| 画像    | `image/jpeg`, `image/png`, `image/webp`, `image/heic`, `image/heif` |
| オーディオ | `audio/mpeg`, `audio/wav`                                           |
| ビデオ   | `video/mp4`, `video/quicktime`, `video/webm`                        |

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

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

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

### Veo 3.1

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

```json
{
  "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

> **Warning**
>
> ByteDanceモデルはデフォルトで無効になっており、使用前に明示的な承認が必要です。エンタープライズのお客様は、サポートに連絡してアクセスをリクエストできます。

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

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

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

### GPT Image

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

## 次のステップ

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

ポーリングではなく、生成結果を受け取ります。

#### [Image & Videoの概要](/docs/ja/overview/capabilities/image-video)

モデルの機能、対応フォーマット、提供状況を比較します。

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

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