TokenLab

미디어 가이드

Volcengine에서 Seedance 마이그레이션

Volcengine 요청 형식을 유지하면서 Seedance를 TokenLab으로 전환하세요

애플리케이션에서 이미 Volcengine Seedance API를 사용 중이라면, 해당 REST 경로, content[] 본문, 응답 필드, 콜백 및 PascalCase 머티리얼 Action을 그대로 유지할 수 있습니다. API 호스트를 변경하고 AK/SK 서명 방식을 TokenLab API 키로 교체하십시오.

변경 사항

변경 항목기존 Volcengine 클라이언트TokenLab
Base URL귀하의 Volcengine 엔드포인트https://api.tokenlab.sh/
인증AK/SK 요청 서명Authorization: Bearer <TOKENLAB_API_KEY>
작업 전송공식 /api/v3/contents/generations/tasks REST 경로유지됨
머티리얼/검증 ActionAction 및 Version 쿼리 매개변수유지됨
작업 본문Volcengine 스타일 content[]유지됨
머티리얼 본문GroupId 및 ProjectName과 같은 PascalCase 필드유지됨
비동기 결과Volcengine 작업 수명 주기폴링 및 선택적 콜백을 포함한 TokenLab cgt-... 작업 ID

AK/SK로만 서명된 요청은 401 AuthenticationError를 반환합니다. 모든 TokenLab 요청에는 반드시 Authorization: Bearer <TOKENLAB_API_KEY>가 포함되어야 합니다.

엔드포인트 선택

기존 클라이언트TokenLab 엔드포인트
Volcengine REST 작업 클라이언트/api/v3/contents/generations/tasks 및 해당 작업 경로
머티리얼 또는 검증 Action 클라이언트POST /?Action=...&Version=2024-01-01 또는 POST /api/v3?Action=...&Version=2024-01-01

비디오 작업의 경우 기존 REST 메서드, 경로 및 JSON 본문을 유지하십시오. 머티리얼 및 검증 요청은 계속해서 Action 및 Version 쿼리 매개변수를 사용합니다. Action 엔드포인트는 CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks 및 DeleteContentsGenerationsTasks 작업 Action도 허용하지만, 새로운 작업에는 REST 경로를 사용하십시오.

공식 작업 경로

메서드 및 경로목적
POST /api/v3/contents/generations/tasks비디오 작업 생성
GET /api/v3/contents/generations/tasks/{id}단일 작업 읽기
GET /api/v3/contents/generations/tasks작업 목록 조회
DELETE /api/v3/contents/generations/tasks/{id}대기 중인 작업 취소. 이미 시작된 작업은 409 task_not_cancellable을 반환함

REST 클라이언트는 다음의 동등한 참조를 사용할 수 있습니다:

요청 본문 규칙

  • content[]는 text, image_url, video_url, audio_url 및 draft_task 항목을 허용합니다.
  • image_url의 경우 role을 생략하거나 이미지-비디오 변환을 위해 first_frame을 사용하십시오. 첫 번째 프레임과 함께 last_frame을 사용하거나, 참조-비디오 변환을 위해 reference_image를 사용하십시오.
  • 선택된 Seedance 워크플로우가 해당 미디어 역할을 허용하는 경우 asset://asset-YYYYMMDDHHMMSS-xxxxx와 같은 공개 머티리얼 URI를 사용할 수 있습니다.
  • REST 본문은 model, content, ratio, duration, resolution, generate_audio, watermark, return_last_frame, seed, execution_expires_after, safety_identifier를 포함한 공식 필드만 허용합니다. 기본값은 모델에 따라 다릅니다: seedance-2.0 모델의 경우 generate_audio는 false이고 seedance-2.5는 true입니다. duration은 seedance-2.0 모델의 경우 5이고 seedance-2.5는 -1입니다. 이 REST 형식은 resolution 값으로 480p, 720p, 1080p(seedance-2.5의 경우 480p 및 720p)를 허용하지만, 통합 /v1/videos/generations API에서만 허용되는 4k는 허용하지 않습니다. seedance-2.5는 seed, frames, camera_fixed를 거부합니다.
  • callback_url은 공개 HTTP(S) 엔드포인트를 허용합니다. TokenLab은 queued, running, succeeded, failed, expired에 대해 동일한 쿼리-작업 본문을 전송합니다. succeeded 및 failed만 공식 동작을 따릅니다(5초 타임아웃 및 엔드포인트가 알림을 확인하지 않을 경우 재시도).

최소 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.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

반환된 cgt-... ID를 저장하십시오. status가 succeeded, failed, cancelled 또는 expired가 될 때까지 폴링하십시오. 생성 응답을 완료된 비디오로 간주하지 마십시오. callback_url을 제공하는 경우, 반복되는 succeeded 또는 failed 알림을 허용하고 복구 경로로서 폴링을 계속 유지하십시오.

v1 및 v3 유형 분리

이 엔드포인트에 /v1/tasks/{id} 응답 구조를 재사용하지 마십시오. 통합 v1 API는 pending, processing, completed, failed를 보고하며, Volc 호환 v3 API는 queued, running, succeeded, failed, cancelled, expired를 보고합니다. 공식 v3 응답은 duration을 JSON 문자열로 나타내며 실패하지 않은 작업에서는 error를 생략합니다.

생성 타임아웃 또는 연결 끊김 후 안전한 복구를 위해 REST 생성 요청에 고유한 Idempotency-Key를 추가하십시오. 동일한 키로 동일한 본문을 재시도하면 원래의 cgt-... ID가 반환되며, 동일한 키로 다른 본문을 보내면 409가 반환됩니다.

머티리얼 및 실인물 검증

동일한 Action 엔드포인트가 10가지 머티리얼 및 머티리얼 그룹 작업을 지원합니다. 정확한 PascalCase 본문, 필터, 페이징, 응답 엔벨로프 및 12시간 머티리얼 URL에 대해서는 머티리얼 Action (Volc 호환)을 참조하십시오.

실인물 머티리얼은 업로드 전에 두 가지 Action을 추가합니다:

  1. 시각적 검증 세션 생성
  2. 시각적 검증 결과 조회

두 번째 Action은 검증된 GroupId를 반환합니다. 해당 ID를 CreateAsset과 함께 사용하십시오. 클라이언트는 LivenessFace 그룹을 직접 생성할 수 없습니다.

마이그레이션 체크리스트

  1. API 호스트를 https://api.tokenlab.sh로 교체하십시오.
  2. AK/SK 서명을 TokenLab Bearer API 키로 교체하십시오.
  3. 공식 REST 작업 메서드, 경로 및 요청 본문 대소문자를 유지하십시오. Action 및 버전은 머티리얼 또는 검증 작업에만 사용하십시오.
  4. 관련 머티리얼 및 검증 요청 전반에 걸쳐 동일한 ProjectName을 유지하십시오.
  5. 해당 엔드포인트에서 반환된 TokenLab 작업, 그룹 및 에셋 ID를 저장하십시오.
  6. 프로덕션 트래픽을 이동하기 전에 생성, 폴링, 목록 조회 및 오류 응답을 각각 검증하십시오.

이 페이지의 내용