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

비디오 및 자료

비디오 생성

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

POST
/v1/videos/generations

개요

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

폴링 동작

가장 안정적인 상태 조회를 위해 생성 응답에서 반환된 정확한 poll_url 을 그대로 사용하세요.

create 응답에 poll_url이 있으면 그 URL을 그대로 사용하세요. 그것이 /v1/tasks/{id}를 가리키면 고정 상태 조회의 canonical endpoint로 취급하세요.

모델 및 미디어 동작

오디오 동작은 선택한 모델과 작업에 따라 다릅니다. 오디오 스위치가 없어도 영상에 소리가 포함될 수 있습니다. 생략과 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 도 지원하지만, 큰 base64 페이로드는 재시도, 관측, 디버깅이 더 어렵습니다.

요청 본문

modelstring기본값: 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를 전송하지 마십시오
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

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

imagestring

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

reference_imagesarray

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_idstring

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

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가 명시된 경우만 사용하세요. 이미지 입력과 1–3개 요소를 제공하세요. 각 요소는 name, 선택적 description, 2–4개 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 워크플로 플래그입니다. Draft 작업을 지원하는 Seedance 모델에서 draft=true를 사용하십시오. draft_task_id와 함께 보내지 마세요.

draft_task_idstring

Seedance 1.5 Pro draft 승격 작업 ID입니다. 이전 draft 작업 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

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

framesinteger

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

camera_fixedboolean

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

fpsinteger

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

negative_promptstring

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

seedinteger

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

cfg_scalenumber

프롬프트 반영 강도(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에서 safety_identifier를 생략하면 TokenLab이 이 값을 사용합니다.

호환성 참고

  • 표준 공개 필드는 계속 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.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

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

task_idstring

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

poll_urlstring

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

billing_transaction_idstring

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

statusstring

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

createdinteger

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

modelstring

사용된 모델입니다.

videoobject

사용 가능한 경우 url, duration, width, 및 height를 포함한 단일 비디오 페이로드.

videosarray

생성 작업이 여러 출력을 반환할 때의 다중 비디오 페이로드.

errorstring | object

오류 메시지(실패한 경우).

요청

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

이미지에서 비디오로

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,
        "resolution": "768p"
    }
)

Kling 3.0 요소

선택한 모델의 현재 공개 상세에 kling_elements가 명시된 경우만 사용하세요. 이미지 입력과 1–3개 요소를 제공하세요. 각 요소는 name, 선택적 description, 2–4개 element_input_urls를 포함하며 prompt에서 @name으로 참조합니다. output_audio=true와 함께 사용할 수 없습니다.

참조 이미지 기반 비디오

모델이 전용 참조 조건부 생성을 지원하면 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",
        "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로, 편집 지시를 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."
    }
)

모션 컨트롤

모델이 피사체 이미지와 모션 참조 비디오를 모두 필요로 한다면 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"

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

모델 상세 응답의 tokenlab.capabilities, tokenlab.supported_operations 를 확인하세요. 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 호환)

다음