비디오 생성 - TokenLab

개요

비디오 생성은 비동기 방식으로 동작합니다. 요청을 보내면 task_id 와 poll_url 을 받은 뒤, 최종 결과가 나올 때까지 상태를 주기적으로 조회하면 됩니다.

폴링 동작

가장 안정적인 상태 조회를 위해 생성 응답에서 반환된 정확한 poll_url 을 그대로 사용하세요. create 응답에 poll_url이 있으면 그 URL을 그대로 사용하세요. 그것이 /v1/tasks/{id}를 가리키면 고정 상태 조회의 canonical endpoint로 취급하세요.

모델 및 미디어 동작

오디오 출력은 모델에 따라 달라집니다. TokenLab에서 Veo 3 및 Seedance 요청은 output_audio를 생략하면 기본적으로 오디오가 켜진 것으로 처리됩니다. 모델이 오디오 제어를 지원하는 경우 output_audio로 명시적으로 전환하세요. 호환 별칭 outputAudio와 generate_audio도 허용되며, 둘 이상을 함께 보낼 때는 output_audio와 값이 같아야 합니다. 운영 환경에서는 이미지, 비디오, 오디오 입력에 공개 접근 가능한 https URL 을 사용하는 것이 좋습니다. 호환 모델은 여전히 data: URL 도 지원하지만, 큰 base64 페이로드는 재시도, 관측, 디버깅이 더 어렵습니다.

요청 본문

model

string

기본값:"veo3.1"

비디오 모델 ID입니다. veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6, kling-3.0-video 같은 제품 수준 논리 ID를 사용하고, text-to-video, image-to-video, reference-to-video 등은 operation으로 선택하세요. 비디오 생성 가이드와 Models API를 참조하세요.

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를 전송하지 마십시오

prompt

string

필수

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

operation

string

실행할 비디오 작업 유형입니다. 모델 세부정보은 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_url

string

image-to-video 흐름에 사용할 시작 이미지의 공개 URL 입니다. 모델 간 호환성을 가장 넓게 확보하려면 image_url 을 권장합니다.

image

string

data: URL 형식의 인라인 이미지입니다(예: data:image/jpeg;base64,...). 호환 모델은 지원하지만, 실제 운영에서는 image_url 이 더 안정적인 편입니다.

reference_images

array

reference-to-video 흐름에서 사용하는 참조 이미지 입력입니다. 허용 개수는 모델마다 다릅니다. seedance-2.0 및 seedance-2.0-fast 에서 TokenLab 는 현재 최대 9장의 참조 이미지와 추가로 최대 3개의 참조 비디오, 3개의 참조 오디오를 지원합니다. 모델 선택, 4K 경계, Mini 참고사항은 Seedance 2.0 비디오 모델 가이드를 참조하세요. 공개 https URL을 권장하며, 호환 모델은 data: URL도 지원합니다. grok-imagine-video의 reference-to-video는 최대 7개의 이미지 참조를 허용하며 duration은 최대 10초입니다. grok-imagine-video-1.5-preview는 image-to-video만 지원하고 참조 이미지를 받지 않습니다.

material_asset_id

string

소재 생성 또는 자동 이미지 준비에서 반환된 TokenLab Seedance 소재 ID입니다. 소재가 ACTIVE가 된 후 TokenLab 소재 라이브러리를 사용할 수 있는 Seedance 모델에서 사용하세요.

material_asset_ids

array

여러 TokenLab Seedance 소재 ID입니다. reference_images와 같은 Seedance 이미지 참조 한도를 공유하며, 선택한 모델은 TokenLab 소재 라이브러리를 사용할 수 있어야 합니다.

선택한 Seedance 모델이 TokenLab 소재 라이브러리를 사용할 수 있으면 TokenLab은 생성 전에 이미지 필드(image, image_url, image_urls, reference_images, start_image, end_image)를 재사용 가능한 소재로 준비합니다. 60초 안에 준비가 끝나지 않으면 API는 auto_material_asset_ids가 포함된 409 seedance_material_preparing을 반환합니다. 해당 소재가 ACTIVE가 된 후 다시 시도하세요. 선택한 모델이 소재 라이브러리를 사용할 수 없으면 일반 이미지 입력은 일반 이미지 경로로 처리되고, 명시적 소재 ID는 재시도 가능한 소재 가용성 오류로 안전하게 실패합니다.

reference_image_type

string

asset 과 style 참조를 구분하는 모델에서 사용하는 선택 필드입니다.

kling_elements

array

Kling 3.0 요소 참조 정의입니다. kling-3.0-video의 이미지 조건 요청에서만 지원됩니다. 1-3개의 요소를 정의할 수 있으며 각 요소에는 name, 선택적 description, 2-4개의 이미지 URL이 들어 있는 element_input_urls가 필요합니다. prompt에서는 @name으로 요소를 참조합니다. kling_elements와 output_audio=true를 함께 사용하지 마세요. 요소 참조 요청에서는 output_audio를 생략하거나 false로 설정하세요.

video_url

string

원본 비디오의 공개 URL입니다. 비디오 URL 기반 video-to-video 흐름과 motion-control 에 필요하며, 일부 파생 흐름은 대신 task_id 를 사용합니다.

video_urls

array

멀티모달 참조 조건부 생성을 지원하는 모델용 추가 참조 비디오 입력입니다. 허용 개수는 모델마다 다릅니다. seedance-2.0 및 seedance-2.0-fast 에서 TokenLab 는 현재 최대 3개의 참조 비디오를 지원합니다.

audio_url

string

audio-to-video 를 지원하는 모델에서 사용하는 공개 오디오 URL 입니다.

audio_urls

array

멀티모달 참조 조건부 생성을 지원하는 모델용 추가 참조 오디오 입력입니다. 허용 개수는 모델마다 다릅니다. seedance-2.0 및 seedance-2.0-fast 에서 TokenLab 는 현재 최대 3개의 참조 오디오를 지원합니다.

task_id

string

일부 이어 만들기, 확장 또는 파생 흐름에서 사용하는 작업 식별자입니다.

extend_at

integer

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

extend_times

string

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

duration

integer

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

seconds

integer

duration의 호환 별칭입니다. seconds와 duration을 함께 보내면 값이 반드시 같아야 합니다. Seedance에서 seconds=-1은 duration=-1과 같은 자동 길이 의미입니다.

aspect_ratio

string

표준 화면비입니다. 예: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, 21:9. Seedance는 생략 시 기본값으로 adaptive를 사용합니다.

resolution

string

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

output_audio

boolean

모델별 표준 오디오 출력 토글입니다. Veo 3와 Seedance는 생략 시 true가 기본값입니다. kling-3.0-video는 요소 참조가 없는 요청에서 이 선택자를 받고, 생략 시 무음 출력이 기본값입니다. output_audio=true와 kling_elements를 함께 사용하지 마세요.

draft

boolean

Seedance 1.5 Pro Draft 워크플로 플래그입니다. Draft 작업을 지원하는 Seedance 모델에서 draft=true를 사용하십시오. draft_task_id와 함께 보내지 마세요.

draft_task_id

string

Seedance 1.5 Pro draft 승격 작업 ID입니다. 이전 draft 작업 ID를 보내 최종 비디오를 생성합니다. 일반 비디오 필드가 아닙니다.

ratio

string

aspect_ratio의 호환 별칭입니다. ratio와 aspect_ratio를 함께 보내면 값이 반드시 같아야 합니다.

generate_audio

boolean

output_audio의 호환 별칭입니다. generate_audio, output_audio, outputAudio가 함께 나타나면 모든 값이 같아야 합니다.

execution_expires_after

integer

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

priority

integer

호환 비디오 모델의 선택적 작업 우선순위이며 범위는 0부터 9까지입니다. priority를 service_tier=flex와 함께 사용하지 마세요.

safety_identifier

string

호환 비디오 모델의 선택적 최종 사용자 안전 식별자입니다. Seedance에서 생략하면 TokenLab은 제공된 user 값을 사용합니다.

service_tier

string

Seedance 2.0 모델에서는 default를 호환 no-op으로 허용합니다. flex는 선택한 모델이 지원할 때만 사용할 수 있습니다.

frames

integer

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

camera_fixed

boolean

호환 비디오 모델의 선택적 고정 카메라 선택자입니다. Seedance 2.0 모델은 이 필드를 지원하지 않습니다.

fps

integer

초당 프레임 수(1-120)입니다. FPS 제어를 공개적으로 지원하는 모델에서만 적용됩니다.

negative_prompt

string

생성 결과에서 피하고 싶은 요소입니다.

seed

integer

재현 가능한 생성을 위한 랜덤 시드입니다. Seedance는 생략 시 랜덤 시드로 -1을 사용합니다.

cfg_scale

number

프롬프트 반영 강도(0-20)입니다. 해당 제어를 노출하는 모델에서만 사용됩니다.

motion_strength

number

움직임 강도(0-1)입니다. 해당 제어를 노출하는 모델에서만 사용됩니다.

start_image

string

start-end-to-video 에서 사용할 첫 프레임 이미지 URL 또는 호환 입력입니다.

end_image

string

start-end-to-video 에서 사용할 마지막 프레임 이미지 URL 또는 호환 입력입니다.

size

string

호환 비디오 모델의 모델별 크기 단계입니다.

watermark

boolean

해당 기능을 공개하는 모델의 선택적 워터마크 토글입니다. Seedance는 생략 시 기본값으로 false를 사용합니다.

effect_type

string

일부 편집/효과 흐름에서 사용하는 모델별 효과 선택자입니다.

user

string

최종 사용자의 고유 식별자입니다. 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이 제공된 입력에서 추론합니다. 프로덕션 트래픽에서는 여전히 명시적 operation 지정을 권장합니다.

미디어 입력 권장 사항

image_url, reference_images, video_url, audio_url 에는 공개 접근 가능한 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은 작업 완료 전 비용을 보수적으로 추정하고, 완료된 작업 usage를 사용할 수 있으면 실제 결과에 따라 정산합니다. 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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

응답

string

표준 비동기 작업 식별자입니다. id와 task_id가 함께 있으면 같은 작업 ID로 취급하세요.

task_id

string

상태 조회에 사용할 고유 작업 식별자입니다.

poll_url

string

이 작업에 권장되는 상태 조회 URL 입니다. 상태 확인 시 이 경로를 그대로 사용하세요.

billing_transaction_id

string

정산이 이미 완료된 경우 반환되는 TokenLab 청구 거래 ID입니다. dashboard / 정산에 사용하는 거래 식별자이며 비동기 id / task_id 와는 별개입니다.

status

string

초기 상태: pending.

created

integer

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

model

string

사용된 모델입니다.

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

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

이미지에서 비디오로

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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,
        "aspect_ratio": "16:9"
    }
)

Kling 3.0 Elements

요소 참조가 필요할 때 kling_elements를 kling-3.0-video와 함께 사용하세요. 이미지 조건 요청(image_url, image_urls, start_image, end_image)을 제공하고 프롬프트에서 각 요소를 @name으로 참조합니다. kling_elements와 output_audio=true를 함께 사용하지 마세요. 요소 참조 요청에서는 output_audio를 생략하거나 false로 설정하세요.

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

참조 이미지 기반 비디오

모델이 전용 참조 조건부 생성을 지원하면 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는 image-to-video만 지원합니다.

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",
        "prompt": "Smooth transition from day to night",
        "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"
    }
)

비디오에서 비디오로

grok-imagine-video의 video-to-video에는 공개 HTTPS .mp4 URL을 video_url로 보내세요. TokenLab은 이를 xAI REST video.url 본문으로 변환합니다. resolution은 480p 또는 720p로 설정할 수 있으며, 이 편집 흐름은 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.",
        "resolution": "720p"
    }
)

모션 컨트롤

모델이 피사체 이미지와 모션 참조 비디오를 모두 필요로 한다면 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 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" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

모델 상세 응답의 tokenlab.capabilities, tokenlab.supported_operations, GET /v1/models, GET /v1/models/{model} 를 확인하세요. audio-to-video 와 video-extension 같은 작업은 모델별 기능입니다. 이 페이지의 정적 예시에 의존하지 말고 그곳에서 현재 지원 여부를 확인하세요.

​개요

​폴링 동작

​모델 및 미디어 동작

​요청 본문

​호환성 참고

​미디어 입력 권장 사항

​Seedance 파라미터

​Seedance 예시

​응답

​이미지에서 비디오로

​Kling 3.0 Elements

​참조 이미지 기반 비디오

​시작/종료 프레임 제어

​비디오에서 비디오로

​모션 컨트롤

​모델 탐색

개요

폴링 동작

모델 및 미디어 동작

요청 본문

호환성 참고

미디어 입력 권장 사항

Seedance 파라미터

Seedance 예시

응답

이미지에서 비디오로

Kling 3.0 Elements

참조 이미지 기반 비디오

시작/종료 프레임 제어

비디오에서 비디오로

모션 컨트롤

모델 탐색