원본 동영상 타임스탬프 미리보기

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 만료는 별개이며 에셋 조회로 갱신합니다. 불투명 원본 미리보기로 최종 알파 품질을 나타내지 않습니다. 최대 12개 시각·한 변 512px이며 미디어 예산은 x-animgen-media-limits를 확인하세요.

인증 및 부수 효과

서버 측 Bearer API 키를 사용하세요. 필요한 권한: animations:read

유료 생성을 시작하지 않습니다. 다른 상태 변경은 위 설명을 확인하세요.

매개변수

매개변수	위치	유형	필수	제약 / 기본값	설명
`asset_id`	`path`	`string`	예	`format`: `uuid`	Owned public resource UUID; task, asset, and file IDs are not interchangeable.

요청 본문 (application/json)

본문 필수: true

필드	유형	필수	기본값	제약	설명
`max_frame_size`	`integer`	아니요	`256`	`minimum`: `32`; `maximum`: `512`	Maximum thumbnail side in pixels, preserving aspect ratio.
`timestamps_seconds`	array<`number`>	예	—	`minItems`: `1`; `maxItems`: `12`; 항목: `minimum`: `0`	Source timeline timestamps in request order, each strictly before the playable end. At most 12.

전체 중첩 스키마: VideoPreviewRequest

요청 예제

json

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

응답

HTTP	본문	설명
`200`	VideoPreviewResponse	Successful public response. Example values are illustrative.
`400`	APIErrorEnvelope	Invalid input; correct the request before retrying.
`401`	APIErrorEnvelope	Missing, expired, or revoked API key.
`402`	APIErrorEnvelope	Insufficient credits; do not automatically purchase.
`403`	APIErrorEnvelope	Account eligibility, account status, or key scope does not allow this operation.
`404`	APIErrorEnvelope	Resource is unavailable, not owned, or its signature is invalid/expired.
`413`	APIErrorEnvelope	Request or decoded image exceeds the configured limit.
`415`	APIErrorEnvelope	Use supported image media types.
`422`	APIErrorEnvelope	Decoded image dimensions exceed the allowed size.
`429`	APIErrorEnvelope	Account-wide rate or queue limit; wait for Retry-After.
`500`	APIErrorEnvelope	Internal failure; preserve the task/key and retry only when marked retryable.
`503`	APIErrorEnvelope	Service/provider unavailable; retry only when error.retryable is true.

응답 헤더

HTTP	헤더	유형	설명
`429`	`Retry-After`	`integer`	Suggested wait in seconds; respect the server value and an overall deadline.
`503`	`Retry-After`	`integer`	Suggested wait in seconds; respect the server value and an overall deadline.

응답 예제

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
}

이 문서가 도움이 되었나요?

문서 이용 분석 허용

검색어, 코드 또는 자유 입력 텍스트는 수집하지 않습니다. 이 설정은 문서 상호작용 이벤트만 제어합니다. 개인정보 처리방침

도움이 필요하신가요? 지원팀 문의

문서 검색