Skip to main content
GET
중국 본토 사용자 안내: 중국 본토 사용자는 https://toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://toapis.com 을 https://toapis.cn 로 바꿔 주세요.
  • Query async video generation task execution status and results
  • Real-time status updates and progress tracking
  • Get generated videos when task completes
  • Multi-language support (zh/en/ko/ja)
All video generation tasks are executed asynchronously. After submitting a task, you need to query the status and results via the query endpoint.
소재 심사가 필요한 Seedance 동영상 작업도 이 API로 조회합니다. queued에는 소재 준비와 심사 대기가 포함될 수 있으며, 작업 접수가 생성 시작을 뜻하지는 않습니다. 준비 기한은 기본 라운드당 20분이며 이후 동영상 생성 시간은 별도입니다. 실패 시 error.message를 확인하세요.
일반 이미지와 동영상 작업은 GET /v1/tasks/{task_id}로도 조회할 수 있으며 usage와 billing의 정의는 같습니다. 이 페이지는 상단에 표시된 생성 작업 조회 경로의 응답을 설명합니다. 예시는 필드 구조를 보여 주며 모델의 현재 가격이나 고정 과금 방식을 나타내지 않습니다. 실제 작업에서 반환된 필드와 금액을 확인하세요.

Seedance 원본 URL과 대체 URL

원본 URL 전달이 활성화된 Seedance 작업에서 result.data[].url은 공급자의 원본 동영상 URL을 유지합니다. url을 우선 사용하고 접근할 수 없을 때만 같은 결과 항목의 fallback_url로 전환하세요. 플랫폼은 클라이언트 지역에 따라 URL을 자동 전환하지 않습니다. 대체 필드는 선택 사항이며 사본을 사용할 수 있을 때만 반환됩니다. 원본 URL 전달이 비활성화되었거나 사본을 사용할 수 없거나 이전 작업에 사본이 없으면 생략될 수 있습니다. 생략은 생성 실패를 의미하지 않습니다. 마지막 프레임도 last_frame_url을 우선 사용하고 접근할 수 없을 때만 fallback_last_frame_url을 사용하세요. 대체 URL은 원본 URL의 유효 기간을 연장하지 않습니다. 장기 보관이 필요하면 즉시 다운로드하세요.

Authorizations

string
필수
All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:

Path 파라미터

string
필수
Task ID returned by the video generation API

응답

string
Unique task identifier
string
선택적 고객 업무 ID입니다. 작업 생성 시 client_business_id를 전달한 경우에만 반환합니다.
string
Object type, always generation.task
string
Task status
  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
integer
Task progress percentage (0-100)
string
Video generation model used
integer
선택적 플랫폼 작업 갱신 시각, Unix 타임스탬프입니다. 현재 Seedance Global에 반환합니다. generation.updated_at는 상위 공급자의 갱신 시각입니다.
integer
Task creation time (Unix timestamp)
integer
작업 종료 시각, Unix 타임스탬프입니다. 이 조회 경로에서는 성공 또는 실패한 작업에 종료 시각이 저장된 경우 반환합니다.
integer
Task completion time (Unix timestamp, only returned when completed)
integer
Video URL expiration time (Unix timestamp, only returned on completion)
object
Task result (only returned on success)
object
선택적 Seedance 생성 메타데이터입니다. 저장되어 있고 공개 가능한 필드만 반환하며 기본값을 채우지 않습니다. 생성 매개변수이며 최상위 usage의 과금 수량을 대체하지 않습니다.generation.usage는 기존 호환 필드이며 completion_tokens와 total_tokens를 포함할 수 있습니다. 누락되거나 최종 과금 수량과 다를 수 있습니다. 최상위 usage와 합산하지 말고 과금 수량은 최상위 usage를 사용하세요.
object
선택적 과금 수량, 동영상 토큰 내역, 도구 사용 횟수입니다. 단위와 생략 조건은 작업 사용량 필드를 참고하세요.charge_type부터 input_images까지는 과금 수량이며 billing.status=settled와 함께만 반환합니다. 고정 가격 동영상은 제출 시 확인된 수량을, 실제 길이나 토큰으로 정산하는 동영상은 최종 정산 수량을 반환합니다. 반환하지 않는 필드는 0으로 채우지 않고 생략합니다.
object
선택적인 플랫폼 청구 상태와 확정 금액입니다. 과금 상태는 생성 상태와 별개이므로 completed여도 정산이 완료되었다고 단정할 수 없습니다. 객체가 없다고 해서 무료인 것은 아닙니다. 가격 및 실제 청구 금액을 참고하세요.Task Webhook의 data.billing도 같은 확인 조건과 값을 사용합니다.
object
오류 information (only returned on failure)오류 코드와 메시지는 일반적으로 문자열입니다. Seedance Global은 error.code와 error.message에 숫자나 null을 포함한 원래 공급자의 JSON 값을 유지합니다. 공급자가 제공하지 않은 필드를 플랫폼 기본값으로 채우지 않습니다.

Task 상태 Reference

Polling Strategy

Python Polling Example

Resource Expiration

Generated video URLs are valid for 24 hours
  • Please download and save videos within the validity period
  • expires_at field indicates video expiration time (Unix timestamp)
  • Expired videos cannot be accessed; to regenerate, submit a new task
  • Thumbnails expire simultaneously with videos

오류와 실패 원인

요청 오류, 작업 실패의 구체적인 원인과 복구 방법은 오류 코드 빠른 참조 를 확인하세요. 조회 성공 후에도 작업 상태를 확인하고 HTTP 상태와 비즈니스 코드를 구분하세요.

Performance Tips

Video generation takes longer, recommendations:
  1. ToAPIs Task Webhook: Webhook을 기본으로, 조회를 대체 경로로 사용
  2. 조회 간격: 5~10초 이상과 지터. 429는 Retry-After를 읽고 지수 백오프
  3. Set Timeout: Long videos may take 5-10 minutes, set reasonable timeout
  4. Download Promptly: Videos expire after 24 hours, save to your storage immediately
비동기 작업 속도 제한을 참조하세요. 배치 조회는 최대 100개입니다.