预览源视频时间点

从源码生成 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
}

这篇文档有帮助吗？

允许文档使用分析

不收集搜索词、代码或自由文本。此开关只控制文档交互事件；站点通用分析仍遵循隐私政策。隐私政策

需要帮助？联系支持

搜索文档