미리보기, 구간 선택 및 목표 FPS 내보내기

원본은 한 번만 생성

/v1/video-generations로 생성하고 outputs[]의 동영상 에셋 ID를 보관하세요. 메타데이터, 미리보기, /v1/animation-exports에 재사용합니다. 구간·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가 있습니다. 사각형은 왼쪽 위 픽셀 기준이며 라벨을 제외합니다.

API·OAuth 인증 정보 없이 image.download_url을 다운로드하세요. 만료 시 image.id를 조회해 갱신하세요. 미리보기에는 AI, 배경 제거, 보간이 없으며 최종 알파 품질을 나타내지 않습니다.

현재 미리보기는 크레딧을 쓰지 않습니다. 캐시 이미지는 계정 저장 공간에 포함되고 별도 시간 만료 없이 일반 에셋 보관 정책을 따릅니다. 동일 요청은 사용 가능한 미리보기를 재사용합니다.

구간을 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, FPS F이면 구간은 [S,S+T), 샘플은 끝점을 제외한 S+i/F입니다.
• 수량은 ceil(T×F)입니다. 정수 프레임 경계의 10^-12 이내 상대 소수 직렬화 오차는 흡수하며 FPS 입력을 잘라내지 않습니다.
• 각 표시 시각에 보이는 원본 프레임을 선택합니다. 반복 샘플 또는 원본 평균 속도 초과 시 resolved_export.warnings에 SOURCE_FRAMES_REPEATED가 표시됩니다.
• 누적 재생 경계를 양수 half-up 방식으로 밀리초 반올림한 뒤 인접 경계 차이를 구합니다. 24FPS의 1초는 41/42ms 프레임으로 총 1000ms입니다.
• 12FPS의 1.1초는 14프레임이며 마지막 17ms를 포함해 총 1100ms입니다. 꼬리는 버리거나 다른 프레임에 분배하지 않습니다.
• 꼬리가 0ms로 양자화되면 TIME_PRECISION_UNSUPPORTED로 실패하므로 구간을 조정하세요.
• 재생은 Aseprite JSON의 프레임별 duration을 따릅니다. meta.animgen.fps는 요청 샘플링 주파수입니다. 길이가 불균일하면 frameDurationMs: null입니다.

견적과 작업은 같은 저장 샘플링 계획을 사용합니다. 성공 작업의 resolved_export는 매니페스트와 일치합니다. 조회는 모든 샘플 대신 확정 구간, FPS, 수량, 총 밀리초, 경고를 반환합니다.

한도, 호환성 및 복구

기본값: 최대 60FPS·240프레임, 프레임 크기 64–1024px, 구간 0.1–15초, 시트 한 변 최대 8192px·면적 최대 67,108,864픽셀입니다. 현재 설정은 OpenAPI의 스키마와 x-animgen-media-limits를 읽으세요. 초과 시 오류가 나며 FPS를 몰래 낮추지 않습니다.

미리보기는 최대 12개 시각, 썸네일 한 변 32–512px, 기본 최대 출력 4,194,304픽셀·10MiB입니다. 미디어 분석·미리보기는 서비스 프로세스당 동시 2개, 미디어 처리 30초, 다운로드 연결·읽기 각각 최대 5초입니다. 원본 한도는 256MiB, 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를 호출하세요. 이미지는 기존 업로드 도구를 사용합니다.