작업 생성 (Volc 호환)

개요Copy Anchor Link

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

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

인증 및 엔드포인트Copy Anchor Link

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

콘텐츠 규칙Copy Anchor Link

• type: "text"는 프롬프트 텍스트입니다.
• role이 없거나 role: "first_frame"인 type: "image_url"은 첫 번째 프레임으로 처리됩니다.
• role: "last_frame"은 반드시 첫 번째 프레임과 쌍을 이루어야 합니다.
• role: "reference_image", reference_video, reference_audio는 참조용으로 사용됩니다.
• image_url.url은 공개 이미지 URL 또는 asset://asset-YYYYMMDDHHMMSS-xxxxx와 같은 머티리얼 URI를 허용합니다. role은 해당 머티리얼이 첫 번째 프레임, 마지막 프레임 또는 참조 이미지인지 결정합니다.
• 첫 번째/마지막 프레임 입력과 참조 미디어를 하나의 요청에 혼합하지 마십시오.
• 최상위 material_asset_id와 material_asset_ids는 허용되지 않습니다. TokenLab 소재 URI는 image_url.url에 넣으세요. priority는 Seedance 2.5에서만 지원합니다.

매개변수 참고 사항Copy Anchor Link

duration은 정수 초 단위이며 -1은 자동 길이를 지정합니다. 기본값과 제한은 모델에 따라 다릅니다.

Seedance 2.5의 첫 프레임, 첫/마지막 프레임, 비디오 확장 및 비디오 간 생성 요청은 ratio: "adaptive"가 필요합니다. 비디오 간 생성에는 duration: -1도 필요합니다. output_format의 mp4와 mov는 Seedance 2.5에서만 지원합니다.

• ratio는 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 또는 adaptive를 허용합니다.
• watermark, return_last_frame, seed, execution_expires_after, safety_identifier는 선택한 모델에서 유효한 경우 허용됩니다.
• callback_url은 공개 HTTP(S) 엔드포인트를 가리킬 수 있습니다.

콜백 전달Copy Anchor Link

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

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

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

이미지 준비Copy Anchor Link

공개 HTTP(S) 이미지 URL과 지원하는 data URL은 입력한 형태로 사용되며 재사용 가능한 소재로 자동 저장되지 않습니다. 명시적인 asset://asset-... 참조는 기존 TokenLab 소재를 사용하며 생성 전에 소유권과 준비 상태를 확인합니다. 소재가 준비 중이면 완료 후 다시 시도하세요. 생성 요청이 실패하면 error.code와 error.message를 확인하세요.

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

생성 응답Copy Anchor Link

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

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

중복 작업 방지Copy Anchor Link

생성 요청 시 고유한 Idempotency-Key를 전송하십시오. 응답이 도착하기 전에 연결이 끊기면 동일한 API 키, 멱등성 키(idempotency key) 및 요청 본문으로 재시도하십시오.

• 원래 작업이 생성된 경우, TokenLab은 동일한 cgt-... ID를 반환하고 Idempotency-Replayed: true를 추가합니다.
• 원래 요청이 아직 등록 중이면 409 IdempotencyRequestInProgress가 반환됩니다. 나중에 같은 키와 본문으로 다시 시도하세요.
• 다른 본문으로 키를 재사용하면 409 IdempotencyConflict가 반환되며 두 번째 작업은 생성되지 않습니다.

멱등성은 공식 v3 REST 생성 경로에 적용됩니다. 이는 JSON 응답 형태를 변경하지 않으며, X-Request-ID나 키가 없는 동일한 요청 본문으로부터 추론되지 않습니다.

예시Copy Anchor Link

REST 생성Copy Anchor Link

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": "doubao-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"}
  }
]

다음 단계Copy Anchor Link

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

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "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"}