TokenLab

비디오 및 자료

작업 생성 (Volc 호환)

Volc 호환 API를 사용하여 Seedance 작업을 생성합니다.

POST
/api/v3/contents/generations/tasks

개요

기존 Volc 스타일의 Seedance 클라이언트는 API 주소와 키를 변경하여 TokenLab을 사용할 수 있습니다.

이 예제는 Seedance 2.0을 사용합니다. 이 엔드포인트는 아래의 모델별 차이점을 포함하여 Seedance 2.5도 지원합니다. 이 페이지의 재사용 가능한 TokenLab 머티리얼 URI 예제는 Seedance 2.0에 적용됩니다.

Seedance 2.0 비디오 모델 및 비디오 생성도 참조하십시오.

인증 및 엔드포인트

  • Authorization: Bearer <TOKENLAB_API_KEY>를 사용하십시오.
  • Volc AK/SK 서명은 허용되지 않습니다. 요청에는 반드시 TokenLab Bearer 키가 포함되어야 합니다.
  • 공식 작업 경로인 POST /api/v3/contents/generations/tasks를 사용하십시오.

콘텐츠 규칙

  • type: "text"는 프롬프트 텍스트입니다.
  • role이 없거나 role: "first_frame"인 type: "image_url"은 첫 번째 프레임으로 처리됩니다.
  • role: "last_frame"은 반드시 첫 번째 프레임과 쌍을 이루어야 합니다.
  • type: "video_url"은 role: "reference_video"가 필요하며, type: "audio_url"은 role: "reference_audio"가 필요합니다. role: "reference_image"는 참조 이미지를 표시합니다.
  • 항목 제한: Seedance 2.0은 최대 16개의 content 항목(텍스트 1개, 이미지 9개, 비디오 3개, 오디오 3개, draft_task 1개)을 허용합니다. Seedance 2.5는 최대 51개(텍스트 1개, 이미지 30개, 비디오 10개, 오디오 10개, draft_task 1개)를 허용합니다.
  • image_url.url은 공개 이미지 URL 또는 asset://asset-YYYYMMDDHHMMSS-xxxxx와 같은 머티리얼 URI를 허용합니다. role은 해당 머티리얼이 첫 번째 프레임, 마지막 프레임 또는 참조 이미지인지 결정합니다.
  • 한 요청 내에서 첫 번째/마지막 프레임 입력과 참조 미디어를 혼합하지 마십시오.
  • REST 본문은 이 페이지에 있는 필드만 허용합니다. material_asset_id 및 material_asset_ids를 포함한 다른 최상위 필드는 400 UnsupportedParameter를 반환합니다. TokenLab 머티리얼 URI를 image_url.url에 넣으십시오.

매개변수 참고 사항

model은 seedance-2.0 또는 seedance-2.5와 같은 TokenLab 모델 ID를 허용합니다. 기존 클라이언트는 이미 사용 중인 Volcengine 모델 ID를 그대로 전송할 수 있습니다. 작업 조회(get-task) 응답은 전송한 model 값을 반환합니다. 인식되지 않는 값은 400 InvalidParameter를 반환합니다.

duration은 초 단위의 정수입니다. -1은 자동 지속 시간을 선택합니다. 기본값과 제한 사항은 모델마다 다릅니다:

매개변수Seedance 2.0Seedance 2.5
duration4–15 / -1 (기본값: 5)4–30 / -1 (기본값: -1)
resolution480p, 720p, 1080p (기본값: 720p)480p, 720p (기본값: 720p)
generate_audioboolean (기본값: false)boolean (기본값: true)
priority지원되지 않음integer: 0–9
seedinteger: -1–4294967295 (기본값: -1)지원되지 않음
execution_expires_after3600–259200 초 (기본값: 172800)3600–259200 초 (기본값: 172800)

Seedance 2.5의 경우, 첫 번째 프레임, 첫 번째/마지막 프레임, 비디오 확장 및 비디오-투-비디오 요청에는 ratio: "adaptive"가 필요합니다. 비디오-투-비디오는 duration: -1도 필요합니다. output_format은 Seedance 2.5에서만 mp4 또는 mov를 허용합니다.

  • ratio는 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 또는 adaptive(기본값: adaptive)를 허용합니다.
  • watermark와 return_last_frame은 불리언(기본값: false)입니다. safety_identifier는 최대 64자까지의 문자열입니다.
  • service_tier는 default만 허용하며, flex는 400 UnsupportedParameter를 반환합니다.
  • tools는 최대 하나의 항목인 {"type": "web_search"}만 허용합니다.
  • draft: true, frames, camera_fixed는 지원되지 않습니다. camera_fixed: false는 Seedance 2.0에서만 허용됩니다.
  • callback_url은 최대 2,048자까지의 공개 HTTP(S) 엔드포인트를 가리킬 수 있습니다.

콜백 전달

callback_url이 제공되면, TokenLab은 작업 상태가 변경될 때 HTTP POST를 보냅니다. 콜백 상태는 queued, running, succeeded, failed, expired입니다. JSON 본문은 작업 조회 응답과 일치합니다.

2xx 응답은 전달 성공을 의미합니다. succeeded 및 failed의 경우, 5초 이내에 전달되지 않으면 최대 3회까지 재시도합니다. 콜백에는 표준 JSON 콘텐츠 헤더만 포함되며 TokenLab 전용 전달 헤더는 없습니다. 리다이렉트는 따르지 않으며, 비공개 또는 예약된 네트워크 대상은 거부됩니다.

작업 ID를 저장하십시오. 콜백이 전달되지 않더라도 작업 조회 엔드포인트를 통해 결과를 검색할 수 있습니다.

이미지 준비

공개 HTTP(S) 이미지 URL 및 지원되는 데이터 URL은 제공된 대로 사용되며, 재사용 가능한 머티리얼로 자동 저장되지 않습니다. 명시적인 asset://asset-... 참조는 기존 TokenLab 머티리얼을 사용합니다. TokenLab은 생성 전에 소유권과 준비 상태를 확인합니다. 참조된 머티리얼이 아직 준비 중인 경우, 준비될 때까지 기다렸다가 다시 시도하십시오. 생성 실패 시 error.code와 error.message를 확인하십시오.

기존 머티리얼의 경우, 다른 시스템에서 반환된 원본 자산 ID 대신 공개 asset-YYYYMMDDHHMMSS-xxxxx ID를 사용하십시오. TokenLab은 생성 전에 머티리얼 소유권을 확인합니다.

생성 응답

{
  "id": "cgt-20260102030405-a1b2c"
}

생성 응답에는 작업 ID만 포함됩니다. 언제든지 상태와 결과를 검색할 수 있도록 저장해 두십시오.

중복 작업 방지

생성 요청 시 고유한 Idempotency-Key(1~255자, 줄 바꿈 없음)를 보내십시오. 응답이 도착하기 전에 연결이 끊기면 동일한 API 키, 멱등성 키(idempotency key) 및 요청 본문으로 재시도하십시오:

  • 원래 작업이 생성된 경우, TokenLab은 동일한 cgt-... ID를 반환하고 Idempotency-Replayed: true를 추가합니다.
  • 다른 본문으로 키를 재사용하면 idempotency_conflict 코드와 함께 409를 반환하며 두 번째 작업을 생성하지 않습니다.
  • 255자를 초과하거나 줄 바꿈이 포함된 키는 400 InvalidParameter를 반환합니다.

키는 JSON 응답 형태를 변경하지 않습니다. TokenLab은 X-Request-ID나 키가 없는 동일한 요청 본문으로부터 중복을 추론하지 않습니다.

예제

REST 생성

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

기존 머티리얼의 경우, 각 URI를 공식 content[] 항목에 넣고 역할을 선언하십시오:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

오류

REST 오류는 {"error": {"code", "message", "param", "type"}}를 사용합니다. 요청 문제는 InvalidParameter 또는 UnsupportedParameter와 함께 400을 반환하며, Bearer 키가 누락되면 401 AuthenticationError를 반환합니다. 잔액 부족(402) 또는 속도 제한(429)과 같은 비디오 생성 오류는 해당 HTTP 상태를 유지합니다.

동일한 작업은 POST /api/v3?Version=2024-01-01에서 CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks, DeleteContentsGenerationsTasks 액션으로도 사용할 수 있습니다. 새로운 통합은 위의 REST 경로를 사용해야 합니다.

다음 단계

작업이 최종 상태에 도달할 때까지 반환된 cgt-... ID를 사용하여 작업 조회 (Volc 호환)를 수행하십시오.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

멱등성 REST 작업 생성을 위한 클라이언트 생성 키로, 줄 바꿈 없는 1-255자입니다. 동일한 TokenLab API 자격 증명 하에서 동일한 JSON 본문과 함께 동일한 키를 재사용하면 원래의 cgt 작업 ID가 반환되며, 다른 본문과 함께 재사용하면 409 코드와 함께 idempotency_conflict가 반환됩니다. 너무 길거나 줄 바꿈이 포함된 키는 400을 반환합니다. 타임아웃 또는 연결 끊김 후 재시도할 때는 자격 증명, 키 및 요청 본문을 변경하지 마십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json