미디어 가이드
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 경로 | 유지됨 |
| 머티리얼/검증 Action | Action 및 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/generationsAPI에서만 허용되는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을 추가합니다:
두 번째 Action은 검증된 GroupId를 반환합니다. 해당 ID를 CreateAsset과 함께 사용하십시오. 클라이언트는 LivenessFace 그룹을 직접 생성할 수 없습니다.
마이그레이션 체크리스트
- API 호스트를
https://api.tokenlab.sh로 교체하십시오. - AK/SK 서명을 TokenLab Bearer API 키로 교체하십시오.
- 공식 REST 작업 메서드, 경로 및 요청 본문 대소문자를 유지하십시오. Action 및 버전은 머티리얼 또는 검증 작업에만 사용하십시오.
- 관련 머티리얼 및 검증 요청 전반에 걸쳐 동일한
ProjectName을 유지하십시오. - 해당 엔드포인트에서 반환된 TokenLab 작업, 그룹 및 에셋 ID를 저장하십시오.
- 프로덕션 트래픽을 이동하기 전에 생성, 폴링, 목록 조회 및 오류 응답을 각각 검증하십시오.