> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# アセット優先：画像と動画の入力をより高速かつ確実に

> 画像または動画を含む Seedance の呼び出しでは、create-task エンドポイントがタスク ID を返すまでに数十秒かかることがあり、クライアント側でタイムアウトする場合もあります。先にメディアを取り込み、asset:// ID を取得して、代わりにそれを参照してください。リクエストボディは数メガバイトから数十バイト程度に減少し、送信はすぐに完了し、コンテンツチェックも取り込み時に前倒しされます。レイテンシの内訳、タイムアウト後の対応、移行手順も含まれています。

<Note>
  **要約**：テキストから動画への変換は影響を受けず、約1秒でタスク ID が返されます。**リクエストに画像または動画が含まれる場合は、そのメディアをまずアセットライブラリに取り込み、`asset://` アセット ID を取得して、動画生成リクエストでそれを参照してください。** リクエスト本文はメガバイト単位から数十バイト程度まで小さくなり、タスク作成エンドポイントは直ちに応答し、メディアのコンテンツチェックは代わりに取り込み時に実行されます。

  このページでは、**送信**の速度と信頼性について説明します。アセットライブラリのエンドポイントごとのドキュメントについては、[アセットライブラリ](/ja/api-capabilities/seedance2/asset-library)を参照してください。エンドツーエンドで実行できるコードについては、[アセット参照ガイド](/ja/api-capabilities/seedance2/asset-reference)を参照してください。
</Note>

## まず、遅いのは送信ですか、それとも生成ですか？

Seedance は**非同期のタスクベース** API です。1つのクリップには2つの独立したフェーズがあり、それぞれのレイテンシーの原因はまったく異なります。

| フェーズ                                                 | 返されるもの                       | 通常の所要時間                                       | 遅くなる理由                                                                                     |
| ---------------------------------------------------- | ---------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **1. 送信**: `POST .../generations/tasks`              | タスク ID、`{"id": "cgt-..."}`   | テキストから動画の場合は約1秒。メディアを添付すると、メディアのサイズに応じて長くなります | メディアはまず APIYI に上流転送され、その後 Volcengine に転送されて、そこでデコードと検証が行われます。タスク ID が返されるのは、これらすべてが完了した後です |
| **2. 生成**: `GET .../tasks/{id}` をポーリングして `succeeded` | 完成したクリップ、`content.video_url` | 通常は**2～5分**（1080p または長時間の動画ではさらに長くなります）       | プロバイダー側のキュー待ちと推論です。これは通常の速度です                                                              |

**この2つのフェーズは独立しています。**「送信に60秒かかった」と「生成に5分かかった」は別々の問題です。そのため、何かを変更する前に、どちらが遅いのかを特定してください。コンソールログの所要時間の列は**最初のバイトまでの時間**であり、フェーズ1に対応します。クリップの生成が完了するまでの合計時間ではありません。[コンソールの所要時間とクライアントの待機時間](/ja/faq/log-duration-vs-client-wait)を参照してください。

<Warning>
  **よくある誤診**: 画像を含むリクエストに60秒の読み取りタイムアウトを設定し、そのタイムアウトを「サービスが停止している」と判断して、すぐに再送信してしまうことです。実際には、メディアはまだ転送中でした。再送信すると同じペイロードをもう一度アップロードすることになり、同じ上り帯域幅を奪い合い、重複したタスクが作成されて課金される可能性があります。
</Warning>

## メディアの渡し方3通りの比較

同じ画像でも、送信時の挙動は3つの方法で大きく異なります。

| 方法                         | リクエストボディのサイズ                                              | タスク ID を取得するまでの時間                         | 主なリスク                                                 |
| -------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------- |
| **Base64 / データ URL、インライン** | ファイルと同程度のサイズに加え、エンコード分としておよそ3分の1増加します — 数 MB になることもよくあります | サイズと**お客様のアップリンク帯域幅**に比例して増加し、複数画像では累積します | クライアントの読み取りタイムアウト。リトライのたびにペイロード全体を再アップロードします          |
| **パブリック URL**              | 小さいですが、アップストリーム側でその場でファイルを取得する必要があります                     | **ホストがファイルを配信する速度**とファイルサイズによって異なります      | 低速、レート制限付き、認証保護された、またはリージョンをまたぐホストの場合、時間が長引くか完全に失敗します |
| **`asset://` アセット ID**     | 数十バイト程度                                                   | 通常のテキストから動画への変換と同程度です                     | 事前に1回の取り込み手順が必要です                                     |

最初の2つは、モデルや推論によって決まるものではありません。**両端の帯域幅とファイルサイズに左右されるため、どちらも遅く、予測しにくくなります** — 同じコードでも、今日は8秒で完了するのに、明日は90秒かかることがあります。`asset://` 参照では、このコストを**事前に1回だけ**取り込み手順へ移せます。その後の生成では、短い文字列だけを送信します。

## アセットファーストは速いだけではありません

<CardGroup cols={2}>
  <Card title="ファイルサイズに左右されない送信時間" icon="gauge">
    リクエストボディはプロンプトとアセット IDだけなので、タスク作成のレイテンシーはテキストから動画への変換と同等の水準に戻り、クライアントのタイムアウトは30～60秒あれば十分です。
  </Card>

  <Card title="リトライのコストはほぼゼロ" icon="rotate-ccw">
    異なるプロンプト、アスペクト比、または再生時間で再実行する場合も、数メガバイトのメディアを再送信する代わりに、数十バイトを再送信するだけです。
  </Card>

  <Card title="コンテンツチェックを早い段階で実行" icon="shield-check">
    メディアは**取り込み**時に検証され、`Active`までポーリングされるため、準拠していないコンテンツは生成タスクの途中で失敗するのではなく、その場で検出されます。
  </Card>

  <Card title="アセットを再利用可能" icon="repeat">
    一度取り込めば無期限に再利用できます。同じアセット IDをショットやエピソード間で参照することで、キャラクターの一貫性も向上します。
  </Card>
</CardGroup>

最適化ではなく**必須要件**となるケースが1つあります。フォトリアルな人間の顔を含むメディアは、直接参照画像として渡すことができないため（ディープフェイク対策）、取り込んだうえで`asset://`として参照する必要があります。[アセットライブラリ](/ja/api-capabilities/seedance2/asset-library)を参照してください。

## 3つのステップで移行

<Steps>
  <Step title="メディアを取り込み、アセット ID を取得する">
    コード不要でウェブ UI からアップロードすることも、API 経由で一括取り込みすることもできます。どちらの方法でも同じライブラリを使用します。[アセットライブラリ](/ja/api-capabilities/seedance2/asset-library)を参照してください。ステータスが `Active` になるまでポーリングします（単一画像の場合は約 13 秒）。その後、アセットを使用できるようになります。

    アセットライブラリは **Seedance API で無料です — 年額料金はかかりません**。
  </Step>

  <Step title="生成リクエスト内のインラインデータを asset:// に置き換える">
    `content` の構造、`role` の値、その他すべてのパラメータは変わりません。変わるのは `image_url.url` の値だけで、データ URL から `asset://<Id>` になります。プロンプト内では、渡した順序に従ってメディアを「image 1」「image 2」として参照してください — **アセット ID をプロンプトテキストに記述しないでください**。
  </Step>

  <Step title="アセット ID を独自のデータベースに保存する">
    アセット ID は長期間有効なので、同じファイルを二度アップロードしないでください。ローカルメディアとそのアセット ID の対応関係を保持し、それ以降の生成では毎回そこから読み取ってください。
  </Step>
</Steps>

変更前と変更後の違いは、フィールド値が正確に 1 つだけです。

```json 変更前: 画像全体をインラインで指定し、リクエストボディは数 MB theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... (millions of characters)" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}
```

```json 変更後: リクエストボディは数百バイトで、タスク ID がすぐに返される theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "asset://asset-2026090200000000-abcde" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}
```

実行可能な完全なスクリプト（アップロード、取り込み、生成、ダウンロード）については、[アセットリファレンスガイド](/ja/api-capabilities/seedance2/asset-reference)を参照してください。

## 最初/最後のフレームジョブについて

最初/最後のフレーム（`role: "first_frame"` / `"last_frame"`）とマルチモーダル参照（`role: "reference_image"`）は、意味の異なる**相互排他的な入力モード**です。一方をもう一方に無造作に置き換えないでください。

* **正確な開始フレームと終了フレームが本当に必要な場合** — たとえば、前のクリップと継ぎ目なく連結する場合 — 最初/最後のフレームモードを維持し、インライン data URL を**公開 URL**に置き換えてください。リクエストボディは直ちに数メガバイトから数百バイト程度まで小さくなり、残りの取得コストは上流側に移ります。画像は、高速で、認証不要かつ十分なリソースを備えた場所でホストしてください。
* **実際に必要なのが一貫したキャラクターやシーンであり、境界フレームをピクセル単位で一致させる必要がない場合**は、`asset://` アセット ID を使用したマルチモーダル参照生成に切り替えてください。これが最も信頼性の高い方法であり、本ページで推奨している方法です。

<Tip>
  クリップをつないで長い動画にする場合、最後のフレームを自分で抽出する必要はありません。`return_last_frame: true` を渡すと、次のタスクの最初のフレームとして使用できるウォーターマークなしの最後のフレームの png が取得できます。
</Tip>

## 参照動画と音声

参照動画（`role: "reference_video"`）は画像より桁違いに大きいため、**インライン Base64 が送信タイムアウトの最も可能性の高い原因です**。使用は避けてください。

* **パブリック URL を優先してください**。高速で、認証が不要で、十分なリソースを備えた場所でホストしてください。
* 本人確認済みユーザーのアセットグループでは、[アセットライブラリ](/ja/api-capabilities/seedance2/asset-library) の本人確認フローを通じて、動画と音声を取り込めます（動画：mp4 / mov、2～15秒、50MB未満、音声：mp3 / wav、2～15秒、15MB未満）。
* 注目すべき点として、参照動画を使用するタスクは**低い料金ティア**が適用されます。動画入力ありの場合は100万 tokensあたり \$7.56、なしの場合は \$12.60です。[概要のモデル料金](/ja/api-capabilities/seedance2/overview)を参照してください。

## タイムアウト後の対応

create-task POST がタイムアウトした場合、**クライアントはタスクが作成されたかどうかを判断できません**。レスポンスヘッダーが到着していないため、照会するタスク ID が存在しないからです。次の順序で対応してください。

<Steps>
  <Step title="何かを再送信する前にレコードを確認する">
    APIYI コンソールのログまたは課金情報で、その時刻の記録を確認します。**記録が存在する場合、タスクは作成され、課金されています**。タスク ID は記録内にあるため、その ID を直接ポーリングしてください。記録がない場合に限り、リクエストが完了していなかったことを意味します。何も確認せずに再送信すると、タスクが重複して作成され、重複分も課金されます。
  </Step>

  <Step title="読み取りタイムアウトとメディア方式を同時に変更する">
    読み取りタイムアウトだけを延長しても、症状に対処しているにすぎません。`asset://` を使用している場合、create リクエストのタイムアウトは **30～60 秒** あれば十分です。非同期エンドポイント自体は高速で、実際の処理はタスク側で行われるためです。大容量のメディアをインラインで送信し続ける必要がある場合は、接続タイムアウトと読み取りタイムアウトを**別々に**設定し、ファイルサイズとアップリンク帯域幅に基づいて読み取りタイムアウトを決めてください。
  </Step>

  <Step title="さらに調査する前に同時実行数を減らす">
    大容量のメディアを含む複数の同時 create リクエストは、同じアップリンクを競合して使用します。その結果、すべてのリクエストが設定したタイムアウト値ちょうどでタイムアウトすることがあります。まず単一のリクエストを成功させてから、同時実行数を徐々に増やしてください。
  </Step>

  <Step title="ベース URL を確認する">
    ベース URL が異なるとネットワーク経路も異なり、大容量のアップロードの挙動も変わる場合があります。利用可能な各エンドポイントに対する送信時間を自分のサーバーから測定し、最も高速なものを使用してください。エンドポイントの一覧と選び方については、[ベース URL の設定](/ja/faq/base-url-config) を参照してください。
  </Step>
</Steps>

一般的なタイムアウトのトラブルシューティング、つまりクライアントのタイムアウトをどの程度に設定すべきか、また問題のあるレイヤーを切り分ける方法については、[API タイムアウトを回避する方法](/ja/faq/timeout-configuration) を参照してください。

## FAQ

<AccordionGroup>
  <Accordion title="テキストから動画を生成する場合もアセットライブラリが必要ですか？">
    いいえ。メディアを添付しない場合、リクエストボディは prompt だけになり、タスク作成エンドポイントは約1秒でタスクIDを返すため、ここで説明している内容は該当しません。
  </Accordion>

  <Accordion title="取り込み自体にはどのくらい時間がかかりますか？単にコストを別の場所に移しているだけではありませんか？">
    1枚の画像の前処理と`Active`への到達には約13秒かかります。すべて自動で行われ、手動レビューは必要ありません。

    重要なのは、**これが一度だけ発生する**ことです。同じアセットはその後、無期限に参照できます。一方、インラインアップロードでは、生成するたびに転送全体を**毎回繰り返す**必要があります。生成するクリップが増えるほど、その差は大きくなります。
  </Accordion>

  <Accordion title="アセットIDには有効期限がありますか？">
    いいえ。完成したクリップの URL とは異なり、アセットIDは長期間使用できます。アセットはお客様の icover.ai アカウントに紐付けられるため、ご自身のアセットだけを表示・使用できます。
  </Accordion>

  <Accordion title="アセットライブラリには追加料金がかかりますか？">
    いいえ。**Seedance API に無料で含まれており、年間料金はかかりません**。Volcengine 独自のプライベートアセットライブラリは、フレームワーク契約のないお客様向けに別途購入するアドオンで、年間契約額は CNY で6桁です。
  </Accordion>

  <Accordion title="生成された動画 URL の有効期間はどのくらいですか？">
    `content.video_url`は**24時間**有効な署名付き直接リンクです。タスクが成功したら、できるだけ早くファイルを自分のストレージにコピーし、その URL を永続的なアドレスとして他者に渡さないでください。
  </Accordion>

  <Accordion title="アセットライブラリの KEY は Seedance の token と同じものですか？">
    いいえ。2つのキーは混同しないでください。**アセットライブラリの KEY** は icover.ai で作成し、アセットのアップロード、取り込み、照会にのみ使用します。**APIYI Seedance 動画 token** は api.apiyi.com で作成し、`SeeDance2`グループを選択する必要があり、動画生成 API にのみ使用します。
  </Accordion>
</AccordionGroup>

## 関連ページ

<CardGroup cols={3}>
  <Card title="アセットライブラリ" icon="images" href="/ja/api-capabilities/seedance2/asset-library">
    すべてのアセットライブラリエンドポイント、コード不要のWeb UI、本人確認
  </Card>

  <Card title="アセットリファレンスガイド" icon="clapperboard" href="/ja/api-capabilities/seedance2/asset-reference">
    アップロードと取り込みからダウンロードまでのエンドツーエンドで実行可能なスクリプト
  </Card>

  <Card title="Seedance 2.0 / 2.5 概要" icon="sparkles" href="/ja/api-capabilities/seedance2/overview">
    モデル選択、料金表、解像度表、よくある質問
  </Card>
</CardGroup>