작업 상태 조회 및 사용 가능한 출력 다운로드

생성 응답은 완성된 애니메이션이 아닙니다

POST /animations는 작업 ID와 Retry-After를 포함한 HTTP 202를 반환합니다. 무엇보다 ID를 먼저 저장하세요. 대기열 접수가 제작 완료를 의미하지는 않습니다.

GET /animations/{id}를 조회하세요. 서버 Retry-After(현재 일반적으로 5초)를 우선하고 일시적 오류에는 제한된 백오프와 총 기한을 사용하세요. 조회가 느리다고 새 작업을 만들지 마세요. 현재 공개 흐름은 웹훅이 아닌 폴링 방식입니다.

상태 및 단계

stage는 해당하는 경우 video_generation 또는 animation_export입니다. progress는 0–1 값이며 완료 시간 보장이 아닙니다. 조회 사이에 중간 상태를 모두 보여 주지 않고 진행할 수 있습니다.

credits.quoted, credits.held, credits.charged는 서로 다른 회계 상태입니다. 최초 견적을 최종 차감으로 보거나 셋을 합산하지 마세요.

부분 출력도 중요합니다

원클릭 작업은 유효한 원본 동영상을 만든 뒤 내보내기에서 실패할 수 있습니다. 종료 상태에서는 status가 succeeded가 아니어도 항상 outputs를 읽으세요.

사용 가능한 에셋을 다운로드하고 오류·누락 형식을 기록해 부분 성공을 정확히 보고하세요. 필요한 작업만 재시도하세요. 기존 동영상은 동작 재생성 없이 /animation-exports로 내보낼 수 있습니다.

안전한 다운로드

각 에셋에는 id, format, mime_type, byte_size, download_url, download_expires_at이 있습니다.

1. 지속 상태용 작업·에셋 ID를 저장합니다.
2. 반환된 서명 URL로 바이트를 다운로드합니다.
3. 서명 URL이나 리디렉션된 저장 호스트에 API Bearer 헤더를 추가하지 않습니다.
4. 앱이 정한 파일명으로 저장하고 완료를 검증합니다.
5. 링크가 만료되면 API 키로 GET /assets/{asset_id}를 호출해 갱신합니다.

수명은 하드코딩하지 말고 download_expires_at을 사용하세요. 에셋 조회는 저장·보관 정책상 사라진 파일을 복원하지 않습니다.

서명 URL은 임시 인증 정보처럼 취급해 로그, 분석, 이슈 관리, AI 대화에 공개하지 마세요.

취소

소유 작업에 POST /animations/{id}/cancel을 사용하세요. 취소는 최선 노력 방식이며 중간 상태를 반환할 수 있습니다. 완료가 취소보다 먼저 끝날 수 있으므로 종료까지 조회하세요.

이미 수행한 작업은 과금될 수 있습니다. 미사용 예약은 해제될 수 있으므로 전액 환불을 약속하지 말고 반환된 사용량을 확인하세요.

내보내기 전 검토: 2단계 흐름

POST /video-generations와 GET /video-generations/{id}로 동영상 에셋을 얻으세요. 검토 후 source_video_asset_id, 구간, 내보내기 설정으로 POST /animation-exports를 만들고 GET /animation-exports/{id}를 조회하세요.

새 유료 생성마다 견적과 멱등 키가 필요합니다. 원본 에셋 ID와 작업 ID는 다른 리소스이므로 혼동하지 마세요. 더 간단한 원클릭 흐름은 빠른 시작 예제에 있습니다.