작업 생성 (Volc 호환)

​

개요

​

인증 및 엔드포인트

• 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"은 반드시 첫 번째 프레임과 쌍을 이루어야 합니다.
• role: "reference_image", reference_video, reference_audio는 참조용으로 사용됩니다.
• image_url.url은 공개 이미지 URL 또는 asset://asset-YYYYMMDDHHMMSS-xxxxx와 같은 머티리얼 URI를 허용합니다. role은 해당 머티리얼이 첫 번째 프레임, 마지막 프레임 또는 참조 이미지인지 결정합니다.
• 첫 번째/마지막 프레임 입력과 참조 미디어를 하나의 요청에 혼합하지 마십시오.
• 요청 본문은 이 형식에서 지원하는 필드만 허용합니다. 최상위 material_asset_id, material_asset_ids, priority는 거부됩니다. 대신 image_url.url 내부에 TokenLab 머티리얼 URI를 넣으십시오.

​

매개변수 참고 사항

• ratio는 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 또는 adaptive를 허용합니다.
• duration은 모델이 지원하는 자동 지속 시간 값을 포함한 비디오 길이(초 단위)입니다.
• resolution은 480p, 720p 또는 1080p를 허용합니다.
• generate_audio의 기본값은 false입니다. 동기화된 오디오가 필요한 경우 true로 설정하십시오.
• watermark, return_last_frame, seed, execution_expires_after, safety_identifier는 선택한 모델에서 유효한 경우 허용됩니다.
• callback_url은 공개 HTTP(S) 엔드포인트를 가리킬 수 있습니다.

​

콜백 전달

​

이미지 준비

​

생성 응답

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

​

중복 작업 방지

• 원래 작업이 생성된 경우, TokenLab은 동일한 cgt-... ID를 반환하고 Idempotency-Replayed: true를 추가합니다.
• 원래 요청이 여전히 등록 중인 경우, TokenLab은 Retry-After와 함께 409 IdempotencyRequestInProgress를 반환합니다. 해당 지연 시간 이후에 동일한 키와 본문으로 재시도하십시오.
• 다른 본문으로 키를 재사용하면 409 IdempotencyConflict가 반환되며 두 번째 작업은 생성되지 않습니다.

​

예시

​

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": "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"
  }'

[
  {
    "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"}
  }
]

​

다음 단계