애니메이션 생성

POST /animations의 인증, 필드, 응답, 오류, 안전한 운영을 원본에서 생성한 레퍼런스입니다.

공개 베타API v1 · 1.4.0최종 확인 2026-09-15

이 페이지의 내용

작업

POST /animations

operationId: create_one_click_animation_v1_animations_post

유료 비동기 작업을 시작합니다. 먼저 견적·사용자 승인을 받고 반환 ID를 저장하세요. HTTP 202는 접수이지 완료가 아닙니다. 응답이 불확실하면 같은 Idempotency-Key, 인증 식별, 변경 없는 본문을 재사용하세요. 생성 시 가격을 재계산하며 공개 API 견적은 가격을 고정하지 않습니다. max_credits, quote_id는 API 본문 필드가 아닙니다. Retry-After에 따라 조회하고 실패를 포함한 모든 종료 상태의 출력을 확인하세요.

인증 및 부수 효과

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

유료 작업을 만듭니다. 제출 전 승인을 받으세요. API 견적은 가격 고정이나 최대 예산 강제가 아닙니다.

매개변수

매개변수	위치	유형	필수	제약 / 기본값	설명
`Idempotency-Key`	`header`	`string`	예	`minLength`: `8`; `maxLength`: `200`	Persist once per logical operation; reuse with the same credential and unchanged body. Changing credentials changes the deduplication scope.

요청 본문 (application/json)

본문 필수: true

필드	유형	필수	기본값	제약	설명
`export`	ExportOptions	아니요	`{"fps":null,"frame_count":24,"output_formats":["spritesheet"],"output_height":512,"output_width":512,"transparent":{"enabled":false},"unity":{"pivot":"bottom_center","pixels_per_unit":100}}`	—	Export after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export.
`input`	GenerationInput	예	—	—	Images owned by the caller or supplied for this generation.
`metadata`	`object`	아니요	`{}`	—	Caller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.
`negative_prompt`	`string`	아니요	`""`	`maxLength`: `4000`	Optional exclusions, only when the model supports negative prompts.
`prompt`	`string`	아니요	`""`	`maxLength`: `8000`	Motion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.
`selection`	Selection	아니요	`{"duration_seconds":null,"mode":"full","start_seconds":0}`	—	Interval selected after generation; full by default.
`video`	VideoOptions	아니요	`{"duration_seconds":null,"input_canvas":null,"model":null,"ratio":null,"resolution":null,"seed":null,"style_preset":null,"transparency":{"key_color":null,"key_selection":"auto","mode":"standard"},"watermark":null}`	—	Model-compatible generation settings.

전체 중첩 스키마: AnimationCreateRequest

요청 예제

json

{
  "export": {
    "frame_count": 24,
    "output_formats": [
      "frames_zip"
    ],
    "output_height": 512,
    "output_width": 512
  },
  "input": {
    "first_frame": {
      "file_id": "00000000-0000-4000-8000-000000000001",
      "type": "file"
    }
  },
  "prompt": "A character runs in place, side view, fixed camera.",
  "selection": {
    "mode": "full"
  }
}

응답

HTTP	본문	설명
`202`	TaskResponse	Accepted asynchronously; poll the task ID.
`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.
`409`	APIErrorEnvelope	Idempotency conflict; only IDEMPOTENCY_IN_PROGRESS is retryable with the original request.
`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	헤더	유형	설명
`202`	`Retry-After`	`integer`	Suggested wait in seconds; respect the server value and an overall deadline.
`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

{
  "created_at": "2026-08-30T00:00:00Z",
  "credits": {
    "charged": 0,
    "held": 1,
    "quoted": 1
  },
  "error": null,
  "finished_at": null,
  "id": "00000000-0000-4000-8000-000000000002",
  "metadata": {},
  "normalized_input": {},
  "object": "animation",
  "outputs": [],
  "progress": 0,
  "stage": "queued",
  "started_at": null,
  "status": "queued"
}

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

문서 이용 분석 허용

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

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

문서 검색