プレビュー、区間選択、指定FPSでの書き出し

元動画は一度だけ生成する

/v1/video-generationsで動画を作り、outputs[]の動画素材IDを保存します。メディア情報、プレビュー、/v1/animation-exportsに同じIDを使います。区間やFPSの変更だけで動きを再生成する必要はありません。

タスク確認とGET /v1/assets/{id}が返す動画mediaには実測のduration_seconds、平均fps、復号済みframe_count、表示widthとheightが含まれます。不明値はnullで、要求された長さや推定枚数で代用しません。可変フレームレート動画では平均FPSを個別フレーム位置とみなせません。

新しい生成動画は表示時刻列を記録し、古い動画は素材検索・プレビュー・FPS書き出し時に調べられます。信頼できる時刻情報がなければFPS書き出しは失敗しますが、元動画はダウンロードできます。

元動画の時刻を調べる

/v1/assets/{asset_id}/previewに送る例です。

{
  "timestamps_seconds": [0, 1, 2, 3, 4],
  "max_frame_size": 256
}

各時刻は[0, 実測動画長)の範囲内です。重複や順不同も使用できます。応答のラベル付きコンタクトシートは指定順で、imageは更新可能な画像素材、width／heightはシート寸法、cells[]にはindex、requested_time_seconds、source_time_seconds、rectがあります。矩形は左上原点の画素座標でラベル部分を含みません。

image.download_urlはAPI／OAuth認証情報を付けず取得し、期限切れならimage.idから更新します。プレビューはAI、背景除去、補間を行わず、最終Alpha品質の見本でもありません。現在クレジット消費はありませんが、キャッシュ画像はアカウント容量に計上され通常の素材保持方針に従います。別の時間期限はなく、同じリクエストは利用可能なプレビューを再利用します。

区間を指定FPSで書き出す

まず/v1/animation-exports/quoteで見積もり、クレジットとresolved_exportを確認します。同じリクエストを新しいIdempotency-Key付きで/v1/animation-exportsへ送ります。例のUUIDは所有する動画素材IDに置き換えます。

{
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "selection": {"mode": "range", "start_seconds": 1, "duration_seconds": 2},
  "export": {
    "fps": 12,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "output_width": 512,
    "output_height": 512,
    "transparent": {"enabled": true}
  }
}

透過書き出しにはalpha_keyの元動画が必要で、このフラグは任意の背景を除去しません。不要ならtransparentを省きます。最初のFPS版ではspritesheetとspritesheet_jsonを両方指定する必要があり、形式省略時もこの組になります。ほかの組み合わせは拒否されます。従来のフレーム枚数指定は既存の形式を利用できます。

時刻の契約

• FPSは元動画の再生速度でサンプリングします。速度変更でもAI補間でもありません。
• 開始S、長さT、FPSFでは区間は[S,S+T)、標本時刻はS+i/Fで終端は含みません。
• 枚数はceil(T×F)です。整数境界からの相対的な小数表現誤差10^-12以内を吸収し、入力FPSを切り捨てません。
• 表示時刻の元フレームを選びます。繰り返しや平均元レート超過はresolved_export.warningsのSOURCE_FRAMES_REPEATEDで知らせます。
• 再生境界の累積時刻を正のhalf-upでミリ秒に丸め、隣接境界の差を取ります。24 FPSの1秒は41／42 msのフレーム時間で合計1000 msになります。
• 1.1秒を12 FPSで取ると14枚で、最後は17 ms、合計1100 msです。端の時間を捨てたり他フレームへ分配したりしません。
• 端が0 msへ量子化される場合はTIME_PRECISION_UNSUPPORTEDになり、区間調整が必要です。
• Aseprite JSONの各durationが再生時間を決め、meta.animgen.fpsは要求した標本周波数のままです。時間が不均一ならframeDurationMs: nullになります。

見積もりとタスクは同じ保存済みサンプリング計画を使います。成功時のresolved_exportはマニフェストと一致します。ポーリングには確定区間、FPS、枚数、総ミリ秒、警告が返り、全標本は並びません。

上限、互換性、復旧

既定の上限は60 FPS、240フレーム、1辺64～1024 px、選択長0.1～15秒、シートの1辺8192 px、面積67,108,864 pxです。設定値はOpenAPIのスキーマとx-animgen-media-limitsを読みます。超過はエラーでありFPSは黙って下げません。

プレビューは時刻12個まで、縮小画像の1辺32～512 px、既定の総出力画素4,194,304と10 MiBです。メディア調査・プレビューはサービスプロセス当たり同時2件、30秒のメディア予算、各ダウンロードの接続・読み取り5秒までです。元動画は256 MiB、120秒、復号18,000フレーム、各元フレーム16,777,216画素まで。設定で変わり得ます。混雑は再試行可能なMEDIA_BUSY、復号タイムアウトはMEDIA_TIMEOUTです。

fpsとframe_countは併用できません。両方省略なら従来の24枚です。既存タスクと枚数指定は従来のサンプリング・範囲許容を保ち、FPS指定は範囲外を拒否します。fullは実測長を使い、開始0で長さを指定しません。

ワンクリックの/v1/animationsとMCPのgenerate_animationは引き続き枚数指定で、FPSを拒否します。FPSには段階的な動画生成と元動画に対する書き出し見積もりを使います。公開APIの見積もりは価格を固定せず、MCP専用のquote_idとmax_creditsは受け付けません。

同じ認証主体、冪等性キー、本文なら同じタスクへ戻ります。区間やFPSを変更するなら新キーにします。失敗タスクを再送しても同じ失敗が返るため、修正した書き出しには同じ元素材と新キーを使います。書き出し中止・失敗は元動画を削除しません。動画素材に独立した時間期限はありませんが、素材／タスク削除やアカウント方針でアクセスは変わり、永久バックアップではありません。署名付きURLの期限は保持期限と別です。重要な納品物を保存してください。

MCPで対応する操作

1. quote_video_generation → 支出承認 → generate_video → get_video_generation。
2. 動画素材IDを保持し、download_assetでmediaを、preview_videoで区間を調べます。
3. quote_animation_export → 支出承認 → export_animation → get_animation_export。
4. 成果物を保存し、マニフェストの各フレーム時間で再生します。

作成時のquote_id／max_creditsとidempotency_keyはrequestと同じ階層です。見積もりは操作の種類に結び付き、書き出し見積もりは元素材・区間・設定にも結び付きます。中止はtask_idを使ってcancel_video_generationまたはcancel_animation_exportを呼びます。画像アップロードには既存のツールを使います。