API 문서 · 작업

비동기 작업 및 상태

상태 머신, 실패 코드 및 요청 필드.

POST /v1/videos/generations는 검증을 통과하면 즉시 202와 작업 객체를 반환합니다. 접수 이후에 발생한 실패는 이미 반환된 202를 바꾸지 않으며, 작업 객체의 error 필드에만 나타납니다. 계정 또는 Key의 동시 진행 작업 수가 한도에 도달하면 429 rate_limited(Retry-After: 10)를 반환합니다.

작업 상태

status	설명
대기 중	접수됨, 처리 대기 중
준비 중	입력 에셋을 처리 채널에 준비하는 중
생성 중	생성 중
복구 중	현재 채널에 문제가 생겨 다른 채널에서 처리를 복구하는 중. 작업 ID는 그대로 유지
확인 중	중복 생성이나 중복 과금을 막기 위해 업스트림의 최종 결과를 확인하는 중
정산 중	결과 저장 및 정산 중
성공	성공. result에 영상 주소가 있음. 최종 상태
실패	실패. error에 실패 코드와 설명이 있음. 최종 상태

최종 상태는 succeeded와 failed뿐입니다. 중간 상태의 순서에 의존하지 마세요. 플랫폼은 일부 상태를 건너뛰거나, 복구 중에 running에서 recovering으로 돌아갈 수 있습니다.

실패 코드

error.code	권장 조치
`no_available_channel`	현재 이 사이트에서 사용할 수 있는 처리 경로가 없습니다. 잠시 후 새 멱등 키로 다시 제출하세요.
`upstream_status_unknown`	플랫폼이 생성 결과를 확인하지 못했습니다. 비용 내역을 확인한 뒤 새 멱등 키로 다시 제출하세요.
`task_deadline_exceeded`	처리 제한 시간 내에 작업이 끝나지 않았습니다. 길이나 해상도를 낮춰 다시 제출하세요.
`content_rejected`	프롬프트 또는 생성된 콘텐츠가 콘텐츠 심사를 통과하지 못했습니다. 설명을 수정해 다시 제출하세요. 같은 내용으로 다시 제출하면 또 실패합니다.
`asset_rejected`	입력 에셋이 심사 또는 형식 검사를 통과하지 못했습니다. 에셋을 바꿔 다시 시도하세요.
`invalid_parameter`	지원하지 않는 파라미터 조합입니다. 모델 기능표를 참고해 해상도, 비율, 길이, 입력 개수를 확인하세요.
`account_suspended`	계정이 정지되었습니다. 운영팀에 문의하세요.
`result_unavailable`	생성 결과를 가져올 수 없습니다. 다시 제출하세요.
`internal_error`	플랫폼 내부 오류입니다. 잠시 후 다시 시도하고, 반복되면 요청 ID와 함께 운영팀에 문의하세요.

요청 필드

필드	설명
`model`	필수. 모델 ID. Key의 허용 목록에 있어야 하며 계정에 권한이 부여되어 있어야 함(아니면 403 permission_denied)
`prompt`	프롬프트. inputs가 없는 텍스트-영상 생성에서는 필수. 최대 길이는 기능표 참고
`inputs`	입력 에셋 배열 { type, asset_id, role }, 최대 20개. 첫 프레임·마지막 프레임은 참고 계열 역할과 함께 사용할 수 없음
`duration`	필수. 길이(초). 기능표에서 허용하면 -1을 전달해 모델이 자동으로 결정
`resolution / ratio`	필수. 해상도와 화면 비율. 사용 가능한 값은 기능표 참고
`max_budget`	선택. 작업당 예산 상한(문자열 금액). 예치 상한이 이 값을 넘으면 402 quota_exceeded 반환
`callback_url`	선택. 최종 상태가 되면 Webhook 전송
`metadata`	선택. 문자열 키-값, 그대로 반환. 최대 32개, 키 ≤ 64자, 값 ≤ 512자, 합계 ≤ 8 KiB
`provider_options`	선택. 모델 전용 파라미터(평면 키-값, 예: seed). 사용 가능한 키와 타입은 기능표 참고. 값은 불리언, 정수 또는 32자 이하 문자열
`fallback_models`	선택. 모델 간 대체: 요청한 모델에 사용 가능한 경로가 없으면 이 모델들을 순서대로 사용(최대 3개). 실제 사용한 모델 가격으로 청구하며, 예치금은 후보 중 가장 비싼 모델 기준. 응답의 model_used에 실제 모델 표시
`allow_fallback`	선택. true이면 플랫폼이 해당 모델에 설정한 기본 대체 체인(모델 목록의 default_fallbacks)을 사용. 생략하거나 false이면 대체하지 않음

결과 필드

작업이 성공하면 result에 video_url, last_frame_url, url_expires_at, retained_until이 포함되며, 유효 기간은 결과 보관을 참고하세요. 계정에 업스트림 원본 링크 반환이 활성화되어 있으면 upstream_video_url과 upstream_url_expires_at도 함께 제공됩니다(업스트림 원본 링크는 보통 생성 완료 후 24시간 동안 유효).

참고 이미지 + 참고 오디오

POST https://cn-api.aitoken.tools/v1/videos/generations
{
  "model": "seedance-2.0-standard",
  "prompt": "인물이 카메라를 보며 미소 짓는다, 배경은 흐리게",
  "inputs": [
    { "type": "image", "asset_id": "asset_xxx", "role": "reference_image" },
    { "type": "audio", "asset_id": "asset_yyy", "role": "reference_audio" }
  ],
  "duration": 8,
  "resolution": "1080p",
  "ratio": "9:16",
  "max_budget": "30.000000",
  "callback_url": "https://example.com/hooks/video",
  "metadata": { "order_id": "A-1001" }
}