預覽源影片時間點

從原始碼生成 POST /assets/{asset_id}/preview 的鑑權、欄位、響應、錯誤與安全呼叫參考。

公開測試API v1 · 1.4.0最後核實 2026-09-15

本頁目錄

操作

POST /assets/{asset_id}/preview

operationId: preview_video_asset_v1_assets__asset_id__preview_post

生成或複用帶時間標籤的源影片聯絡表，不呼叫 AI、不扣點數。快取預覽計入儲存配額並遵循普通資產保留規則；每格返回請求時間和實際顯示的源幀時間。簽名 URL 獨立過期，通過資產查詢重新整理。預覽展示源影片，不代表最終 Alpha 質量。最多 12 個時間點、單幀最長邊 512 畫素；媒體預算見 x-animgen-media-limits。

鑑權與副作用

使用可信環境中的 Bearer API Key。所需權限：animations:read

此操作不啟動付費生成，其他狀態變化見上文說明。

引數

引數	位置	型別	必填	約束 / 預設值	含義
`asset_id`	`path`	`string`	是	`format`: `uuid`	所屬公共資源 UUID；任務、資產、檔案 ID 不能互換。

請求體 (application/json)

請求體必填：true

欄位	型別	必填	預設值	約束	含義
`max_frame_size`	`integer`	否	`256`	`minimum`: `32`; `maximum`: `512`	縮圖最長邊畫素數，保持寬高比。
`timestamps_seconds`	array<`number`>	是	—	`minItems`: `1`; `maxItems`: `12`; 元素：`minimum`: `0`	按請求順序提供源時間點，每個點嚴格小於可播放終點，最多 12 個。

完整巢狀結構：VideoPreviewRequest

請求示例

json

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

響應

HTTP	正文	含義
`200`	VideoPreviewResponse	成功的公開響應，示例數值僅用於說明。
`400`	APIErrorEnvelope	輸入錯誤，修正請求後再嘗試。
`401`	APIErrorEnvelope	API Key 缺失、到期或被撤銷。
`402`	APIErrorEnvelope	點數不足，不自動購買。
`403`	APIErrorEnvelope	帳戶資格、帳戶狀態或 Key 權限不允許此操作。
`404`	APIErrorEnvelope	資源不可用、不屬於當前使用者，或簽名無效/過期。
`413`	APIErrorEnvelope	請求或解碼後的圖片超過配置限制。
`415`	APIErrorEnvelope	使用支援的圖片媒體型別。
`422`	APIErrorEnvelope	圖片解碼後尺寸超過限制。
`429`	APIErrorEnvelope	觸發帳戶級速率或佇列限制，遵循 Retry-After 等待。
`500`	APIErrorEnvelope	內部錯誤，保留任務 ID 和冪等鍵，僅標記可重試時重試。
`503`	APIErrorEnvelope	服務或供應商不可用，僅 error.retryable 為 true 時重試。

響應頭

HTTP	響應頭	型別	含義
`429`	`Retry-After`	`integer`	建議等待秒數，遵循服務值並設定總體截止時間。
`503`	`Retry-After`	`integer`	建議等待秒數，遵循服務值並設定總體截止時間。

響應示例

json

{
  "cells": [
    {
      "index": 0,
      "rect": {
        "height": 256,
        "width": 256,
        "x": 0,
        "y": 0
      },
      "requested_time_seconds": 0,
      "source_time_seconds": 0
    },
    {
      "index": 1,
      "rect": {
        "height": 256,
        "width": 256,
        "x": 256,
        "y": 0
      },
      "requested_time_seconds": 1,
      "source_time_seconds": 1
    },
    {
      "index": 2,
      "rect": {
        "height": 256,
        "width": 256,
        "x": 512,
        "y": 0
      },
      "requested_time_seconds": 2,
      "source_time_seconds": 2
    }
  ],
  "height": 280,
  "image": {
    "byte_size": 1024,
    "created_at": "2026-08-30T00:00:00Z",
    "download_expires_at": "2026-08-30T01:00:00Z",
    "download_url": "https://downloads.example.invalid/illustrative-asset",
    "format": "video_preview",
    "id": "00000000-0000-4000-8000-000000000006",
    "media": null,
    "mime_type": "image/png",
    "object": "asset"
  },
  "object": "video_preview",
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "width": 768
}

這篇文件有幫助嗎？

允許文件互動分析

不收集搜尋字詞、程式碼或自由文字。此開關僅控制文件互動事件。隱私權政策

需要協助？聯絡支援

搜尋文件