비동기 작업

Seedance 2.0의 모든 영상 생성 요청은 비동기로 처리됩니다. 요청을 제출하면 즉시 작업 ID가 반환되고, 실제 생성은 백그라운드에서 진행됩니다. 결과를 받는 방법은 두 가지입니다.

폴링 — 이 페이지에서 설명하는 엔드포인트를 주기적으로 호출해 진행 상태를 확인
웹훅 — 요청 시 callback_url을 전달하면 시스템이 결과를 해당 URL로 푸시. Webhooks 참고

작업 상태 조회

GET https://api.evolink.ai/v1/tasks/{task_id}

경로 매개변수

매개변수	유형	필수	설명
`task_id`	string	예	생성 엔드포인트가 반환한 작업 ID

cURL 예제

curl https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

작업 라이프사이클

pending  →  processing  →  completed
                      ↘    failed
                      ↘    cancelled

상태	의미
`pending`	작업 생성됨, 큐 대기 중, 아직 시작되지 않음
`processing`	생성 중. `progress`가 지속적으로 업데이트됨
`completed`	생성 완료. `results` 배열에 영상 URL이 들어 있음
`failed`	생성 실패. 과금되지 않음
`cancelled`	요청에 의해 작업이 취소됨

응답 예제

Pending (방금 제출됨)

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "pending",
    "progress": 0,
    "type": "video",
    "task_info": {
        "can_cancel": true,
        "estimated_time": 165,
        "video_duration": 5
    },
    "usage": {
        "billing_rule": "per_second",
        "credits_reserved": 50,
        "user_group": "default"
    }
}

Processing (생성 중)

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "processing",
    "progress": 65,
    "type": "video",
    "task_info": {
        "can_cancel": true
    }
}

Completed

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "completed",
    "progress": 100,
    "results": [
        "https://cdn.example.com/videos/task-unified-1774857405-abc123.mp4"
    ],
    "type": "video",
    "task_info": {
        "can_cancel": false
    }
}

영상 URL은 24시간 동안 유효합니다. 만료되기 전에 자체 객체 스토리지(OSS / S3 / R2)로 다운로드해 두세요.

Failed

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "failed",
    "progress": 0,
    "type": "video",
    "task_info": {
        "can_cancel": false
    }
}

실패한 작업은 과금되지 않습니다.

응답 필드

필드	유형	설명
`id`	string	작업 ID
`object`	string	항상 `video.generation.task`
`created`	integer	작업 생성 Unix 타임스탬프
`model`	string	실제로 사용된 모델 ID (제출 시점과 일치)
`status`	string	현재 상태 — 라이프사이클 표 참고
`progress`	integer	0~100 퍼센트
`results`	array<string>	`completed` 상태에서만 존재. 영상 URL을 포함
`type`	string	출력 유형. 항상 `video`
`task_info.can_cancel`	boolean	취소 엔드포인트를 아직 호출할 수 있는지
`task_info.estimated_time`	integer	남은 예상 시간(초)
`task_info.video_duration`	integer	요청한 영상 길이(초)
`usage.billing_rule`	string	항상 `per_second`
`usage.credits_reserved`	number	예약된 크레딧
`usage.user_group`	string	사용자 그룹

폴링 모범 사례

5초 간격이 폴링 빈도와 응답 지연 사이의 합리적인 균형점입니다
짧은 영상(4~~6초)은 보통 1~~3분 안에 완료되며, 긴 영상이나 복잡한 멀티모달 작업은 더 오래 걸립니다
프로덕션 파이프라인에서는 폴링보다 웹훅을 우선 사용하세요. callback_url은 요청 수와 비용을 최소화합니다
progress를 정확한 ETA로 다루지 마세요. 단계마다 모델이 다른 속도로 진행하기 때문에 진행 표시기에 가깝습니다

전체 Python 예제

import os
import time
import requests

API_KEY = os.environ["EVOLINK_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}

# 작업 제출
response = requests.post(
    "https://api.evolink.ai/v1/videos/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "seedance-2.0-text-to-video",
        "prompt": "Rainy streets of Tokyo at night, neon reflections on wet asphalt",
        "duration": 6,
        "quality": "720p"
    }
)
task_id = response.json()["id"]

# 상태 폴링
while True:
    result = requests.get(
        f"https://api.evolink.ai/v1/tasks/{task_id}",
        headers=headers
    ).json()

    status = result["status"]
    print(f"[{status}] progress={result.get('progress', 0)}%")

    if status == "completed":
        print(f"Video URL: {result['results'][0]}")
        break
    if status in ("failed", "cancelled"):
        print(f"Task ended with status: {status}")
        break

    time.sleep(5)