Skip to main content

簡潔な回答

Seedance はリクエスト内の各アイテムの role のみを読み取ります。 ツールでどのスイッチをオンにしたかは認識されず、このために prompt を読み取ることもありません。role のない画像は、第1フレーム(画像から動画への変換)として扱われます。そこに参照動画を追加すると、リクエストは「第1フレーム + 参照メディア」となり、プロバイダーによって拒否されます。 典型的なエラーは送信時に 400 として返されます。タスクは作成されず、課金も発生しません:
解決策:ネイティブの Seedance エンドポイント POST /seedance/api/v3/contents/generations/tasks 経由で送信し、画像には "role": "reference_image"、動画には "role": "reference_video" を設定した上で、プロバイダーが直接ダウンロードできる公開 URL として動画を渡すか、アセットライブラリに登録して asset:// として参照してください。

実際の事例

あるお客様がご自身で構築されたローカルの制作ツールを使用されていました。キャラクター画像1枚と動画1本を渡し、「omni reference」にチェックを入れ、「最初のフレーム/最後のフレーム」のチェックは外したままにし、さらに prompt に「画像1は最初のフレームではありません。最初/最後のフレームモードを使用しないでください」とまで記述していました。それにもかかわらず、実行するたびに上記のエラーで失敗していました。 ゲートウェイ側で生のリクエストをキャプチャしました(画像の base64 は省略):
このリクエストには2つの問題があります。どちらか一方だけでも失敗の原因となります: お客様のブラウザのコンソールにも同じ mp4 に対して 415 Unsupported Media Type が表示されており、これはツール独自のローカルプレビューエンドポイント(/api/media-preview/...localhost 上))からのものでした。ツールが動画を利用可能なアドレスに変換できず、ローカルパスをそのままリクエストに含めてしまっていました。

Seedance を汎用動画エンドポイント経由で送信しないでください

/v2/videos/generations(および /v1/videos/v1/video/generations)はゲートウェイの汎用動画エンドポイントです。これらのフィールドは複数の動画モデルで共有される共通サブセットであり、Seedance の入力モードを表現することはできません:
  • role がない: 先頭フレーム、先頭/末尾フレーム、マルチモーダルリファレンスを区別できないため、画像 1 枚と動画 1 本の組み合わせは常に「先頭フレーム + リファレンス」として扱われてしまいます
  • 解像度が完全には透過されない: 当社のテストでは、2.5 で 480p をリクエストしても 720p で出力され、2.0 シリーズで 1080p をリクエストしても 720p で出力されました。一方で、課金は実際に生成された解像度に基づいて行われます
  • 2.5 固有のパラメータomni_reference_task_typeoutput_format など)に対応するフィールドがありません
そのため、Seedance には必ずネイティブエンドポイントを使用してください: サードパーティ製ツールをご使用の場合は、その Seedance チャンネルが「ネイティブ」または「Volcengine Ark」フォーマットを提供しているか確認してください。汎用動画 API にのみ対応しているツールでは、参照動画を含むタスクを実行できません。

正しい方法: すべてのアイテムに role を設定する

重要なポイント:
  • 3つの入力モードは相互に排他的です: 最初/最後のフレーム(画像2枚、first_frame / last_frame)、最初のフレーム(画像1枚)、およびマルチモーダル参照(reference_image / reference_video / reference_audio)。参照動画または参照音声が含まれる場合、すべての画像は reference_image である必要があります
  • role がない場合は最初のフレームを意味します: role のない単一の画像は first_frame と同じです
  • prompt では、渡された順序でアイテムを参照してください(例: @image1@video1
  • 参照制限: 2.0シリーズでは最大9枚の画像 + 3本の動画 + 3つの音声クリップ、2.5では最大30枚の画像 + 10本の動画 + 10個の音声クリップまでです

参照動画を渡す方法

プロバイダーは自身のサーバー上でメディアをダウンロードするため、動画はプロバイダーが直接アクセスできるアドレスにある必要があります。 送信する前に、インターネットにアクセスできる任意のマシンからリンクを確認できます(<URL> を動画リンクに置き換えてください):
code=200typevideo/mp4 または video/quicktime)、および元のファイルと一致する size が表示されるはずです。HTMLページ、JSONボディ、またはいずれかの4xxが表示される場合は、プロバイダーがそのリンクを使用できないことを意味します。画像に関するリンク確認の詳細は、画像リンクは開くが失敗する場合をご覧ください。

関連ドキュメント

動画生成 API

ネイティブエンドポイントに加え、各入力モードのコンテンツレイアウトと role 値

アセットファーストワークフロー

参照動画を Base64 として送信すべきではない理由と、アセットの登録方法