預覽、選區與 FPS 匯出

先生成影片，再決定如何匯出

用 /v1/video-generations 生成影片，儲存任務 outputs[] 中的影片資產 ID。用這個 ID 查詢後設資料、預覽和建立匯出。改變選區或 FPS 只調用 /v1/animation-exports，無需重新呼叫生成模型。

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 查詢資產重新整理。預覽展示原影片，不做生成、摳圖、補幀，也不代表最終 Alpha 質量。

當前預覽不扣點數，快取圖片計入帳戶儲存。同一源資產與相同引數會複用仍有效的預覽。快取遵循普通資產保留規則，沒有獨立的按時間到期策略。

按 FPS 匯出

先向 /v1/animation-exports/quote 傳送下面的請求，核對費用及 resolved_export；確認後向 /v1/animation-exports 傳送相同請求，並提供新的 Idempotency-Key。示例 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 的組合；省略格式時自動選擇這兩個格式。其他組合明確拒絕。舊 frame_count 模式繼續支援已有格式。

時間契約

• FPS 是按源影片原速取樣的頻率，不是播放變速或 AI 補幀。
• 起點 S、時長 T、FPS F 的選區是 [S, S+T)；取樣點是 S+i/F，不採終點。
• 幀數為 ceil(T×F)。僅在整數幀邊界吸收相對 10^-12 內的十進位制序列化誤差，不截斷 FPS 輸入。
• 按實際呈現時間戳選擇當時正在顯示的源幀。重複採到源幀或目標 FPS 超過源平均幀率時，resolved_export.warnings 提供 SOURCE_FRAMES_REPEATED，不自動插幀。
• 對累計播放邊界做正數半入的毫秒取整，再相減生成各幀 duration。1 秒／24 FPS 的幀時長為 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 與 Manifest 對應。摘要只包含選區、目標 FPS、幀數、總毫秒數和警告，不在輪詢中重複返回全部取樣點。

限額、相容與恢復

預設 FPS 上限為 60、幀數上限為 240，單幀尺寸為 64～1024 畫素，選區時長為 0.1～15 秒。圖集每邊最多 8192 畫素、總畫素最多 67,108,864。實際配置以 OpenAPI 中的 Schema 和 x-animgen-media-limits 為準。超限報錯，不自動降低 FPS。

預覽最多 12 個時間點，單幀最長邊為 32～512 畫素；預設總畫素上限 4,194,304、輸出上限 10 MiB。媒體探測／預覽預設最多同時處理 2 個請求（每個服務程序），媒體處理預算 30 秒，下載每次連線／讀取最多 5 秒。源影片最多 256 MiB、120 秒、18,000 個解碼幀、單幀 16,777,216 畫素。繁忙返回可重試的 MEDIA_BUSY；解碼超時返回 MEDIA_TIMEOUT。所有預算均可由服務配置調整。

fps 與 frame_count 互斥；兩者均省略仍預設 24 幀。歷史任務和 frame_count 請求保留舊取樣、預設值與選區容差。新 FPS 請求嚴格拒絕越界，full 使用實際完整時長，禁止非零起點或額外時長。

一鍵 /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. 下載產物，按 Manifest 逐幀時長匯入。

兩種建立工具的 quote_id／max_credits 和 idempotency_key 都與 request 同級。報價繫結操作型別；匯出報價還繫結源影片、選區與匯出引數。取消分別使用 cancel_video_generation 或 cancel_animation_export，引數為 task_id。圖片上傳沿用現有上傳工具。