TokenLab
API 키 받기
문서API 레퍼런스통합

비디오 및 자료

비디오 생성

비디오 생성 작업을 시작합니다

POST
/v1/videos/generations

개요

비디오 생성에는 시간이 소요됩니다. 성공적인 생성 응답은 작업 ID와 poll_url을 반환하며, 해당 URL을 사용하여 진행 상황을 확인하고 결과를 가져올 수 있습니다.

작업 상태 확인

생성 응답에 포함된 poll_url을 호출하십시오. id와 task_id는 동일한 작업을 식별하며, GET /v1/tasks/{id}를 사용할 수도 있습니다.

오디오 및 미디어 입력

오디오 동작은 선택한 모델과 작업에 따라 다릅니다. 오디오 스위치가 없어도 영상에 소리가 포함될 수 있습니다. 생략과 false 지정은 다릅니다.

  • veo3.1과 veo3.1-fast는 Gemini API 계약에 따라 항상 오디오를 생성합니다. wan-2.6과 wan-2.7의 영상 생성도 오디오를 끌 수 없습니다. output_audio를 생략하거나 모델 상세에서 허용하면 true로 설정하세요.
  • hailuo-h3와 Grok 영상 모델은 오디오를 기본 생성합니다. 모델 상세에 없는 오디오 스위치를 추가하지 마세요.
  • Seedance 1.5/2.x와 viduq3-pro / viduq3-turbo는 오디오가 기본으로 켜지며 무음 출력도 지원합니다. PixVerse C1/V5.6/V6는 기본으로 꺼집니다. output_audio는 해당 필드를 명시한 작업에서만 사용하세요. Vidu는 계약에 선언된 불리언 audio도 허용합니다.
  • audio_url / audio_urls는 입력 또는 참조 오디오이며 출력 오디오 스위치가 아닙니다. 영상 편집, 동작 전이, 스타일 변환은 입력 음원을 유지할 수 있습니다. 원본 오디오 유지는 음소거가 아닙니다.

허용 값과 오디오별 가격은 모델 상세를 확인하세요. 지원되는 별칭 outputAudio, generate_audio, 불리언 audio를 output_audio와 함께 쓰면 값이 같아야 합니다. 같은 계열도 버전과 작업마다 제어가 다를 수 있습니다.

이미지, 비디오, 오디오에는 공개적으로 접근 가능한 https URL을 사용하십시오. 일부 모델은 인라인 data: URL도 허용하지만, 대용량 파일의 경우 URL을 사용하는 것이 더 안정적입니다.

요청 본문

modelstring기본값: veo3.1

비디오 모델 ID입니다. 현재 모델을 확인하려면 Models API를 사용하고, 텍스트-비디오, 이미지-비디오 및 기타 생성 모드에는 operation을 사용하십시오.

PixVerse

  • 모델: pixverse-c1, pixverse-v6, pixverse-v5.6
  • 작업: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • 오디오 선택기: output_audio, 기본값 false

TokenLab에서 위의 PixVerse 모델은 operation=video-extension을 허용하지 않습니다.

HappyHorse

  • 모델: happyhorse-1.0
  • 작업: text-to-video, image-to-video, reference-to-video, video-to-video
  • 오디오 선택기: output_audio를 전송하지 마십시오
promptstring

생성할 비디오에 대한 텍스트 설명입니다. 대부분의 공개 비디오 모델에서 필수입니다.

operationstring

생성 모드입니다. 지원되는 값에는 text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video, motion-control이 포함됩니다. 생략할 경우 TokenLab이 입력값으로부터 추론합니다. 명시적으로 전송하면 일치하지 않는 필드를 더 빠르게 감지할 수 있습니다.

image_urlstring

이미지-비디오 생성을 위한 시작 이미지의 공개 접근 가능한 URL입니다. Seedance 머티리얼 에셋의 경우, ACTIVE 상태인 TokenLab 머티리얼을 첫 번째 프레임으로 사용하기 위해 asset://asset-YYYYMMDDHHMMSS-xxxxx를 전달할 수도 있습니다. 모델 간 최상의 호환성을 위해 https URL을 포함한 image_url을 사용하는 것을 권장합니다.

imagestring

데이터 URL 형식의 인라인 이미지입니다(예: data:image/jpeg;base64,...). 호환되는 모델에서 지원되지만, image_url이 공개 비디오 모델 전반에서 가장 폭넓은 호환성을 제공합니다.

reference_imagesarray

전용 참조 컨디셔닝을 지원하는 모델을 위한 참조 이미지 입력입니다. 지원되는 개수는 모델에 따라 다릅니다. seedance-2.0 및 seedance-2.0-fast의 경우, TokenLab은 현재 최대 9개의 참조 이미지와 최대 3개의 참조 비디오 및 3개의 참조 오디오를 지원합니다. 각 Seedance 참조는 https URL이거나 ACTIVE 상태인 TokenLab 머티리얼을 위한 asset://asset-YYYYMMDDHHMMSS-xxxxx URI일 수 있습니다. 모델 선택, 4K 경계 및 Mini 관련 참고 사항은 Seedance 2.0 비디오 모델 가이드를 참조하십시오. 머티리얼이 아닌 입력에는 공개 https URL을 권장하며, 호환되는 모델은 인라인 data: URL도 허용합니다. grok-imagine-video의 경우, reference-to-video는 최대 7개의 이미지 참조를 허용하며 duration은 10초로 제한됩니다. grok-imagine-video-1.5-preview는 이미지-비디오 전용이며 참조 이미지를 허용하지 않습니다.

material_asset_idstring

머티리얼 에셋 생성을 통해 반환된 TokenLab Seedance 머티리얼 에셋 ID입니다. 에셋이 ACTIVE 상태가 된 후 TokenLab 머티리얼 라이브러리를 사용할 수 있는 Seedance 모델과 함께 사용하십시오. 이 필드는 일반적인 참조 입력입니다. 첫 번째 프레임, 마지막 프레임 또는 참조 이미지 의미를 명시적으로 할당하려면 start_image, end_image 또는 reference_images에 asset://<material_asset_id>를 대신 입력하십시오.

material_asset_idsarray

여러 개의 TokenLab Seedance 머티리얼 에셋 ID입니다. reference_images와 동일한 Seedance 이미지 참조 제한을 공유하며, 선택된 모델이 TokenLab 머티리얼 라이브러리를 사용할 수 있어야 합니다.

일반 이미지 URL은 이미지 입력으로 전달되며, 재사용 가능한 머티리얼 에셋을 생성하지 않습니다. 머티리얼 API를 통해 재사용 가능한 에셋을 생성한 다음, 해당 TokenLab ID 또는 asset://asset-YYYYMMDDHHMMSS-xxxxx URI를 사용하십시오. 명시적 머티리얼 사용 시 409 seedance_material_preparing 오류가 반환되면, 반환된 inactive_asset_ids를 확인하고 해당 머티리얼이 ACTIVE 상태가 된 후 다시 시도하십시오.

reference_image_typestring

asset 참조와 style 참조를 구분하는 모델을 위한 선택적 참조 역할입니다.

kling_elementsarray

선택한 모델의 현재 공개 세부 정보에 이 필드가 명시된 경우에만 kling_elements를 사용하십시오. 이미지 입력과 13개의 요소를 제공하며, 각 요소는 name, 선택적 description, 24개의 element_input_urls를 포함해야 합니다. prompt 내에서 @name으로 참조하십시오. 요소 참조를 output_audio=true와 함께 사용하지 마십시오.

video_urlstring

소스 비디오의 공개 접근 가능한 URL입니다. 비디오 URL 기반의 video-to-video 흐름 및 motion-control에 필수적입니다. 일부 파생 흐름은 대신 task_id를 사용합니다.

video_urlsarray

멀티모달 참조 컨디셔닝을 지원하는 모델을 위한 추가 참조 비디오 입력입니다. 지원되는 개수는 모델에 따라 다릅니다. seedance-2.0 및 seedance-2.0-fast의 경우, TokenLab은 현재 최대 3개의 참조 비디오를 지원합니다.

audio_urlstring

선택한 모델에서 지원하는 오디오 기반 또는 참조 오디오 작업을 위한 공개 오디오 URL입니다.

audio_urlsarray

멀티모달 참조 컨디셔닝을 지원하는 모델을 위한 추가 참조 오디오 입력입니다. 지원되는 개수는 모델에 따라 다릅니다. seedance-2.0 및 seedance-2.0-fast의 경우, TokenLab은 현재 최대 3개의 참조 오디오를 지원합니다.

task_idstring

일부 연속, 확장 또는 파생 흐름에서 사용되는 작업 식별자입니다.

extend_atinteger

일부 video-extension 흐름에서 사용되는 모델별 확장 시작 오프셋입니다.

extend_timesstring

일부 video-extension 흐름에서 사용되는 모델별 확장 승수 또는 반복 횟수입니다.

durationinteger

생성된 출력 비디오의 길이(초 단위)입니다. Seedance 1.5/2.0 모델의 경우, 이 필드를 생략하면 5가 사용됩니다. -1을 보내면 모델이 지원하는 길이 범위 내에서 선택하며, 작업이 완료될 때까지 비용은 보수적으로 추정됩니다.

secondsinteger

duration에 대한 호환성 별칭입니다. seconds와 duration을 모두 보낼 경우, 값은 동일해야 합니다. Seedance의 경우 seconds=-1은 duration=-1과 동일한 자동 길이 의미를 갖습니다.

aspect_ratiostring

종횡비입니다(예: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Seedance는 생략 시 adaptive를 기본값으로 사용합니다.

resolutionstring

모델에 따른 출력 해상도입니다. Seedance는 720p를 기본값으로 사용합니다. seedance-2.0은 480p, 720p, 1080p, 4k를 지원하며, seedance-2.0-fast 및 seedance-2.0-mini는 480p와 720p로 제한됩니다.

output_audioboolean

이를 선언하는 작업을 위한 오디오 출력 선택기입니다. 생략 시 모델 기본값을 따르며, false는 허용되는 경우에만 무음 출력을 요청합니다. 위의 오디오 동작 및 선택한 모델 세부 정보를 참조하십시오.

draftboolean

Seedance 1.5 Pro 초안 모드를 활성화합니다. draft_task_id와 함께 보내지 마십시오.

draft_task_idstring

Seedance 1.5 Pro 초안 승격 작업 ID입니다. 최종 비디오를 생성하려면 이전 초안 작업 ID를 보내십시오. 이는 일반적인 비디오 필드가 아닙니다.

ratiostring

aspect_ratio에 대한 호환성 별칭입니다. ratio와 aspect_ratio를 모두 보낼 경우, 값은 동일해야 합니다.

generate_audioboolean

output_audio에 대한 호환성 별칭입니다. generate_audio, output_audio, outputAudio가 함께 나타날 경우 모든 값은 일치해야 합니다.

execution_expires_afterinteger

호환되는 비디오 모델을 위한 선택적 실행 만료 시간(초 단위)입니다. Seedance는 생략 시 172800초를 기본값으로 사용합니다.

priorityinteger

호환되는 비디오 모델을 위한 0에서 9 사이의 선택적 작업 우선순위입니다. priority를 service_tier=flex와 함께 사용하지 마십시오.

safety_identifierstring

호환되는 비디오 모델을 위한 선택적 최종 사용자 안전 식별자입니다. Seedance의 경우 생략 시 TokenLab은 제공된 user 값을 사용합니다.

service_tierstring

default는 Seedance 2.0 모델에 대해 호환성 no-op으로 허용됩니다. flex는 선택한 모델이 지원하는 경우에만 허용됩니다.

framesinteger

호환되는 비디오 모델을 위한 선택적 프레임 수입니다. Seedance 2.0 모델 및 Seedance 1.5 Pro는 이 필드를 지원하지 않습니다.

camera_fixedboolean

호환되는 비디오 모델을 위한 선택적 고정 카메라 선택기입니다. Seedance 2.0 모델은 이 필드를 지원하지 않습니다.

fpsinteger

FPS 제어를 노출하는 모델을 위한 초당 프레임 수(1-120)입니다.

negative_promptstring

생성된 비디오에서 제외할 요소입니다.

seedinteger

재현 가능한 생성을 위한 무작위 시드입니다. Seedance는 생략 시 무작위 시드를 위해 -1을 사용합니다.

cfg_scalenumber

CFG 스타일 제어를 노출하는 모델을 위한 프롬프트 준수 강도(0-20)입니다.

motion_strengthnumber

이를 노출하는 모델을 위한 움직임 강도(0-1)입니다.

start_imagestring

start-end-to-video에서 첫 번째 프레임을 위한 URL 또는 호환되는 이미지 입력입니다.

end_imagestring

start-end-to-video에서 마지막 프레임을 위한 URL 또는 호환되는 이미지 입력입니다.

sizestring

호환되는 비디오 모델을 위한 모델별 크기 계층입니다.

watermarkboolean

이를 노출하는 모델을 위한 선택적 워터마크 토글입니다. Seedance는 생략 시 false를 기본값으로 사용합니다.

effect_typestring

특수 편집 흐름을 위한 모델별 효과 선택기입니다.

userstring

최종 사용자를 위한 고유 식별자입니다. Seedance의 경우, TokenLab은 해당 필드가 생략되면 이 값을 safety_identifier로도 사용합니다.

호환되는 필드 이름

  • 기본 필드는 snake_case를 사용합니다: aspect_ratio, output_audio, reference_images, reference_image_type.
  • 호환성을 위해 TokenLab은 ratio, generate_audio, outputAudio, seconds, referenceImages, referenceImageType도 허용합니다.
  • 기본 필드와 해당 별칭이 모두 전송된 경우, 값은 일치해야 합니다.
  • operation이 생략되면 TokenLab이 입력값으로부터 추론합니다.

미디어 입력

  • image_url, reference_images, video_url, audio_url에는 인라인 base64보다 공개적으로 접근 가능한 https URL을 우선 사용하십시오.
  • 동일한 요청 내에서 인라인 base64와 원격 URL을 혼용하지 마십시오.
  • 작업 처리가 시작될 때까지 원격 미디어 URL이 유효하도록 유지하십시오.

Seedance 매개변수

Seedance 1.5/2.0 모델의 경우, 통합 엔드포인트는 TokenLab 필드 이름을 따르며 호환되는 별칭인 seconds, ratio, generate_audio를 허용합니다. 생략된 Seedance 선택기는 다음 기본값을 사용합니다: duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0, seed=-1.

duration=-1 또는 seconds=-1을 설정하면 Seedance가 모델 지원 범위 내에서 출력 길이를 선택합니다. TokenLab은 작업 완료 전까지 비용을 보수적으로 추정하며, 작업 완료 후 실제 사용량에 따라 정산합니다. service_tier=default는 Seedance 2.0에 대해 호환성 no-op으로 허용됩니다. service_tier=flex, frames, camera_fixed는 선택한 모델이 지원하지 않는 경우 거부됩니다.

Seedance 예시

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

응답

결과, 오류, 타임스탬프 및 모델을 설명하는 필드는 작업에 대해 사용 가능한 경우 반환됩니다.

idstring

표준 비동기 작업 식별자입니다. 두 값이 모두 존재할 경우 task_id와 동일한 식별자로 취급하십시오.

task_idstring

폴링을 위한 표준 비동기 작업 식별자입니다. 비동기 상태 엔드포인트에서 사용하는 것과 동일한 작업 식별자입니다.

poll_urlstring

이 작업을 위한 권장 폴링 URL입니다. 상태 확인 시 이 정확한 경로를 사용하십시오.

billing_transaction_idstring

정산이 이미 완료된 경우의 TokenLab 결제 트랜잭션 ID입니다. 이는 대시보드/회계 트랜잭션 식별자이며 비동기 id / task_id와는 별개입니다.

statusstring

작업 상태: pending, processing, completed, failed.

createdinteger

작업이 생성된 Unix 타임스탬프입니다.

modelstring

사용된 모델입니다.

video_urlstring

결과를 즉시 사용할 수 있는 경우의 직접 비디오 URL입니다.

videoobject

사용 가능한 경우 url, duration, width, height를 포함하는 단일 비디오 결과입니다.

videosarray

작업이 하나 이상의 출력을 반환할 때의 다중 비디오 결과입니다.

errorstring | object

작업 실패 시의 오류 메시지 또는 구조화된 오류 객체입니다.

요청

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

응답

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

이미지-비디오 (Image to Video)

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

Kling 3.0 요소

선택한 모델의 현재 공개 세부 정보에 이 필드가 명시된 경우에만 kling_elements를 사용하십시오. 이미지 입력과 13개의 요소를 제공하며, 각 요소는 name, 선택적 description, 24개의 element_input_urls를 포함해야 합니다. prompt 내에서 @name으로 참조하십시오. 요소 참조를 output_audio=true와 함께 사용하지 마십시오.

참조-비디오 (Reference to Video)

모델이 전용 참조 컨디셔닝을 지원하는 경우 operation=reference-to-video를 사용하십시오. TokenLab 요청에서 이미지 참조는 reference_images를 사용하고, 멀티모달 참조 비디오 및 오디오는 video_urls와 audio_urls를 사용합니다. seedance-2.0 및 seedance-2.0-fast의 경우, TokenLab은 현재 최대 9개의 참조 이미지와 최대 3개의 참조 비디오 및 3개의 참조 오디오를 지원합니다. 모델 선택, 4K 경계 및 Mini 관련 참고 사항은 Seedance 2.0 비디오 모델 가이드를 참조하십시오. duration은 생성된 출력 길이만 제어하며, 참조 비디오 입력 길이에 대한 별도의 제한을 설정하지 않습니다. grok-imagine-video의 경우, reference-to-video는 최대 7개의 이미지 참조(reference_images 또는 image_urls)를 허용하며 duration은 10초로 제한됩니다. 참조 이미지를 image_url / image 첫 프레임 입력과 함께 사용하지 마십시오. grok-imagine-video-1.5-preview는 이미지-비디오 전용입니다.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

키프레임 제어

첫 번째 프레임과 마지막 프레임을 제어하려면 start_image와 end_image를 사용하십시오:

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

비디오-비디오 (Video to Video)

grok-imagine-video 비디오-비디오의 경우, video_url에 공개 HTTPS .mp4 URL을 보내고 편집 prompt를 함께 전송하십시오. 이 작업에서는 resolution, duration, aspect_ratio를 생략하십시오.

모델이 기존 비디오를 기본 입력으로 허용하는 경우 operation=video-to-video를 사용하십시오.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

모션 제어 (Motion Control)

모델이 피사체 이미지와 모션 참조 비디오를 모두 기대하는 경우 operation=motion-control을 사용하십시오. TokenLab은 공개 image_url + video_url 요청 형태를 해당 모델의 모션 제어 요청 형식으로 매핑합니다.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject identity stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

모델 탐색

공개 비디오 인벤토리와 지원되는 작업은 시간이 지남에 따라 변경됩니다. 모델별 흐름을 구현하기 전에 Models API를 사용하여 현재 지원 여부를 확인하십시오:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

모델별 작업이나 필드에 의존하기 전에 모델 세부 정보 응답을 읽어보십시오. audio-to-video 및 video-extension과 같은 작업은 모델별로 다르므로, 이 페이지의 정적 예시에 의존하지 말고 현재 가용성을 확인하십시오.

인증

BearerAuth
AuthorizationBearer <token>

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

위치: header

헤더

X-TokenLab-Delivery-Policy?string

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

허용 값

  • "auto"
  • "verified"
  • "official"

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

음악 생성 상태 조회

이전

작업 생성 (Volc 호환)

다음