TokenLab Seedance 작업 취소 및 대기열 작업 과금 가이드

비디오 생성 작업은 비동기식으로 진행됩니다. POST /v1/videos/generations를 통해 비디오 생성 요청을 제출하면 TokenLab은 작업 식별자를 반환하고 작업을 대기열에 추가합니다. 요청이 실수로 제출되었거나 네트워크 재시도 중 중복되었거나 최종 사용자가 취소한 경우, 작업이 대기열에 있는 동안 취소하면 불필요한 컴퓨팅 및 생성 비용을 방지할 수 있습니다.

이 가이드에서는 작업 취소 엔드포인트를 호출하고, API 응답 코드를 처리하며, 결제 예약 및 폴링 전환을 관리하는 방법을 설명합니다.

작업 취소 작동 방식

작업 취소는 여전히 pending 상태로 대기열에 있는 비동기 작업을 대상으로 합니다. 모델 워커가 프레임 생성을 시작하거나(작업이 processing 상태로 전환됨) 작업이 최종 상태(completed 또는 failed)에 도달하면 더 이상 취소할 수 없습니다.

TokenLab은 seedance-2.0, seedance-2.0-fast, seedance-2.5를 포함하여 대기열에 있는 Seedance 비디오 모델의 취소를 지원합니다. Volcengine 호환성 엔드포인트를 사용하는 연동의 경우 Volc 호환 작업 취소 레퍼런스를 참조하세요.

작업 라이프사이클 상태

• pending: 작업이 대기열에 추가되어 사용 가능한 워커를 기다리는 중입니다. 이 기간 동안 취소가 지원됩니다.
• processing: 모델 실행이 시작되었습니다. 취소 요청이 거부됩니다.
• completed: 비디오 생성이 성공적으로 완료되었습니다. 결과가 준비되었습니다.
• failed: 작업에 오류가 발생했거나 실행 전에 취소되었습니다.

청구 및 예약 시맨틱

TokenLab의 결제 및 가격 정책 가이드에 따르면 비동기 미디어 작업에 대한 청구는 2단계 예약 및 정산 모델을 따릅니다:

1. 사전 승인 / 예약: 비동기 비디오 작업이 수락되면 TokenLab은 선택한 모델 및 매개변수를 기반으로 예상 금액을 보류하거나 예약할 수 있습니다.
2. 정산: 최종 청구 금액은 작업이 completed 상태에 도달했을 때만 정산됩니다. 완료된 작업에는 최종 원장 항목을 나타내는 billing_transaction_id가 첨부됩니다.
3. 취소 및 실패: 대기열에 있는 동안 취소된 작업을 포함하여 failed 상태로 끝난 작업에는 요금이 청구되지 않습니다. 사용하지 않은 예약금 또는 임시 보류 금액은 워크스페이스 잔액으로 다시 반환됩니다.

대기열에서 취소된 작업은 생성을 완료하지 않으므로 완료된 결제 정산이 발생하지 않습니다.

API를 통해 대기열 작업 취소하기

작업을 취소하려면 생성 중에 반환된 작업 ID와 함께 /v1/tasks/{id}로 DELETE 요청을 보냅니다. 전체 스키마 세부 정보는 작업 취소 API 레퍼런스를 참조하세요.

요청 예시

curl -X DELETE "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

성공 응답 (HTTP 200)

실행이 시작되기 전에 작업이 성공적으로 취소되면 API는 HTTP 200으로 응답합니다. 작업 상태는 cancelled: true로 표시되며 failed로 직접 전환됩니다:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

오류 코드 및 거부 처리

DELETE 호출이 항상 성공한다고 가정해서는 안 됩니다. 애플리케이션은 특정 HTTP 오류 상태를 처리해야 합니다:

HTTP 상태	오류 코드	의미	권장 조치
400	unsupported_task_cancel	모델 또는 작업 유형이 취소를 지원하지 않습니다.	작업이 정상적으로 완료되도록 두거나 모델 지원 여부를 검토하세요.
403	task_not_owned	API 키가 해당 작업을 소유하고 있지 않습니다.	워크스페이스 자격 증명 및 API 키 권한 범위를 확인하세요.
404	async_task_not_found	작업 ID가 존재하지 않거나 만료되었습니다.	로컬 큐 데이터베이스에 저장된 작업 ID를 확인하세요.
409	task_not_cancellable	작업이 이미 processing을 시작했거나 최종 상태(completed/failed)에 있습니다.	생성이 이미 진행 중임을 수용하고, 반복문으로 삭제 호출을 재시도하지 마세요.

취소된 작업 폴링

GET /v1/tasks/{id} 또는 반환된 poll_url을 통해 작업을 폴링할 때(비동기 작업 및 폴링 가이드에 설명된 대로) 다음 동작을 염두에 두세요:

1. 최종 상태 작업에 대한 HTTP 200 반환: 실패하거나 취소된 작업의 상태를 조회하면 HTTP 200이 반환됩니다. HTTP 응답 코드에 의존하지 말고 JSON 본문의 status 및 cancelled 필드를 확인하세요.
2. 상태 식별: 취소된 작업에는 "status": "failed", "cancelled": true, "cancellation_status": "cancelled"가 표시됩니다.
3. 정산 ID 부재: 청구 정산이 발생하지 않았으므로 취소된 작업에는 billing_transaction_id가 포함되지 않습니다.

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

프로덕션 대기열 연동 체크리스트

Seedance 비디오 워크플로를 워커 아키텍처에 연동할 때 다음 모범 사례를 따르세요:

• ID 즉시 유지: 다운스트림 작업을 디스패치하기 전에 POST /v1/videos/generations 응답의 id(또는 task_id)와 poll_url을 모두 저장합니다.
• 제출 시 중복 제거: 작업을 생성하기 전에 클라이언트 측의 더블 클릭 및 업스트림 네트워크 재시도를 중복 제거하여 우발적인 작업 생성을 방지합니다.
• 409를 비치명적으로 처리: 취소 요청이 409 task_not_cancellable을 반환하는 경우 처리가 시작되었음을 나타내는 것으로 처리합니다. 결과를 기다린 후 더 이상 필요하지 않은 경우 출력을 버리는 방식으로 대체합니다.
• 취소 마커 파싱: 폴링 루프에서 status == "failed"와 cancelled is True를 모두 확인하여 사용자가 시작한 취소와 인프라 오류를 구분합니다.
• 트랜잭션 ID를 사용한 결제 대사: 완료된 작업에 존재하는 경우에만 billing_transaction_id를 저장합니다. 취소되거나 실패한 작업에서는 트랜잭션 ID를 기대하지 마세요.

추가적인 연동 패턴은 비디오 생성 가이드 및 비디오 상태 조회 API 레퍼런스를 확인하세요.