API 빠른 시작: 이미지에서 다운로드까지

사전 준비

공개 API는 공개 베타입니다. 인증된 AnimGen 계정, animations:read·animations:write 권한의 키, 신뢰할 수 있는 서버·로컬 기기가 필요합니다. 생성에는 충분한 크레딧이 필요합니다. 구독은 개발자 한도를 높이지만 접근 필수 조건은 아닙니다.

계정 → 개발자에서 키를 만드세요. 비밀 관리자나 비공개 셸 세션을 통해 ANIMGEN_API_KEY 환경 변수로 전달하세요. 브라우저 JavaScript, 배포 게임, 저장소, AI 대화에 넣지 마세요.

기본 URL은 https://api.animgen.com/v1입니다. URL 호환 버전은 v1, 문서화된 스키마 버전은 1.4.0입니다.

1. 지원 모델 조회

curl --fail-with-body https://api.animgen.com/v1/models \
  -H "Authorization: Bearer $ANIMGEN_API_KEY"

data에서 입력 모드를 지원하는 id를 고르고 길이, 해상도, 비율, 기능 플래그를 확인하세요. 오래된 글의 모델 이름을 복사하지 마세요.

아래 첫 프레임 예제는 supports_first_frame: true이며 modes에 첫 프레임 지원이 있는 모델을 사용합니다. 공개된 기본 옵션을 사용합니다.

2. 생성 없이 준비 및 견적

Python 워크플로 예제를 받아 검토하세요. Python 3.10+와 표준 라이브러리만 사용합니다.

curl --fail-with-body -o animation-workflow.py \
  https://animgen.com/examples/animation-workflow.py

python3 animation-workflow.py prepare \
  --image character.png \
  --model 'PROVIDER:MODEL_FROM_CATALOG' \
  --prompt 'A character runs in place, side view, fixed camera.' \
  --state hero-run.json

이미지 경로·모델 ID를 바꾸세요. 준비 단계는 목록 검사, 인라인 Base64 요청 생성, 견적·잔액 조회, 비공개 상태 파일 저장을 수행하며 유료 생성 엔드포인트는 호출하지 않습니다.

상태 파일에는 입력 이미지·프롬프트가 들어갑니다. 버전 관리 밖에서 접근을 제한하고 불필요해지면 제거하세요. API 키는 포함하지 않습니다.

3. 생성 명시적 승인

견적을 검토하고 동의하는 금액을 APPROVED_CREDITS로 정한 뒤 실행하세요.

python3 animation-workflow.py run \
  --state hero-run.json \
  --approve-credits "$APPROVED_CREDITS" \
  --output ./hero-output

스크립트는 최초 생성 전 재견적하고 로컬 승인액 초과를 거부하며 멱등 키를 저장해 변경 없는 요청을 논리적으로 한 번 제출합니다. 이후 조회하고 사용 가능한 출력을 다운로드합니다.

4. 안전한 재개 및 결과 확인

시간 초과 시 같은 상태 파일로 재실행하세요. 작업 ID가 저장되었으면 새 생성 대신 조회를 재개합니다. 생성 응답이 불확실하면 보수적인 재시도 기간 안에서 원래 키·페이로드를 재사용합니다.

“재시도”하려고 상태 파일을 지우고 처음부터 시작하지 마세요. 새 논리 작업이 되어 두 번 지출할 수 있습니다. 예제는 24시간 후 미해결 생성 재시도를 거부합니다. 계속하기 전에 작업 목록이나 지원팀을 확인하세요.

모든 종료 상태에서 사용 가능한 에셋을 먼저 저장한 뒤 실패·취소를 보고합니다. 미완료는 0이 아닌 종료 코드이며 부분 내보내기를 전체 성공으로 처리하지 않습니다. 파일명은 원격 서버 이름이 아닌 에셋 ID를 사용합니다.

요청의 동작

예제는 일반 전체 길이 애니메이션, PNG 프레임 ZIP, 24프레임, 512 × 512 출력을 요청합니다. 이는 예제 선택이며 API 기본값이나 보편적인 품질 권장은 아닙니다.

재사용 업로드·공개 URL은 인증 및 이미지 입력, 수명 주기는 상태 조회 및 다운로드, 오류 및 재시도를 참고하세요. 정확한 계약은 OpenAPI JSON에 있습니다.

Python 예제는 프로덕션 크레딧 지출이 아닌 로컬 모의 환경으로 테스트합니다. 실제 통합 검사는 작고 명시적으로 승인한 작업으로 진행하세요. 다른 언어·검증 범위는 실행 예제, 정확한 매개변수는 API 레퍼런스에 있습니다.