> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 비디오 생성

> 명시적인 공개 작업, 비동기 폴링 및 모델별 미디어 입력으로 비디오를 생성합니다.

비디오 생성은 비동기입니다. `POST /v1/videos/generations`는 공개 작업 ID를 반환하며 일반적으로 `poll_url`을 포함합니다; 최종 비디오는 이후 상태 응답에서 나타납니다.

선택한 Seedance 모델이 TokenLab 소재 라이브러리를 사용할 수 있으면 이미지 URL과 지원되는 인라인 data URL이 생성 전에 재사용 가능한 TokenLab 소재로 준비됩니다. 준비가 60초를 넘으면 반환된 `auto_material_asset_ids`가 `ACTIVE`가 된 후 다시 시도하세요. 선택한 모델이 소재 라이브러리를 사용할 수 없으면 일반 이미지 입력은 일반 이미지 경로로 계속 처리됩니다.

## 모델 세부정보

생산 환경에서는 명시적인 `operation`을 사용하십시오. TokenLab은 입력에서 일부 작업을 유추할 수 있지만, 명시적인 작업 값은 검증, 지원 및 재시도를 더 명확하게 만듭니다.

| 작업                   | 필수 또는 일반 입력                                                      | 사용 사례                |
| -------------------- | ---------------------------------------------------------------- | -------------------- |
| `text-to-video`      | `prompt`                                                         | 텍스트만으로 생성            |
| `image-to-video`     | `image_url` 또는 호환 가능한 `image`                                    | 시작 이미지를 애니메이션화       |
| `reference-to-video` | `reference_images` 및 선택적 `video_urls` / `audio_urls` (지원되는 모델에서) | 정체성, 스타일 또는 자산 참조 유지 |
| `start-end-to-video` | `start_image`, `end_image`                                       | 첫 번째 및 마지막 프레임 제어    |
| `video-to-video`     | `video_url` 또는 모델별 `task_id`                                     | 기존 클립 변환 또는 업스케일     |
| `motion-control`     | `image_url` 및 `video_url`                                        | 주제에 모션 참조 적용         |
| `audio-to-video`     | `audio_url`                                                      | 오디오 조건 비디오 흐름        |
| `video-extension`    | `task_id`, `extend_at` 또는 모델별 확장 필드                              | 생성된 비디오 계속하기         |

## 모델 발견

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \\
  -H "Authorization: Bearer sk-your-api-key"
```

`model`에는 TokenLab에 표시되는 모델 ID를 사용하고, 기능 변형은 `operation`과 해당 미디어 입력으로 선택하세요. 예: `wan-2.7`, `happyhorse-1.0`, `viduq3`, `viduq3-mix`, `pixverse-v6`, `kling-3.0-video`, `veo3.1`, `seedance-2.0`. 작업별 접미사를 TokenLab 모델명으로 사용하지 마세요.

`reference_images`, `kling_elements`, `output_audio`, `duration`, `resolution`, 또는 `aspect_ratio`와 같은 전문 필드에 의존하기 전에 선택한 모델 세부정보를 읽으십시오.

## 요청 생성

```bash theme={null}
curl https://api.tokenlab.sh/v1/videos/generations \\
  -H "Authorization: Bearer sk-your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "veo3.1",
    "operation": "text-to-video",
    "prompt": "햇빛이 비치는 정원을 걷는 고양이의 차분한 영화 장면",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'
```

프로덕션 미디어 입력에는 인라인 `data:` URL보다 공개 `https` URL을 권장합니다. 임시 URL을 사용하는 경우 TokenLab이 작업 생성을 완료할 때까지 유효하게 유지하세요.

## 입력 및 모델별 필드

* Veo 3 계열 요청은 `output_audio`가 생략될 경우 기본적으로 오디오가 켜집니다. 모델이 토글을 지원하고 사용자 경험이 사운드에 의존하는 경우 명시적으로 설정하십시오.
* `kling_elements`는 `kling-3.0-video` 이미지 조건 요청을 위한 것입니다. 각 요소를 `prompt`에서 `@name`으로 참조하십시오; `output_audio=true`와 결합하지 마십시오.
* Seedance 2.0 패밀리의 4K 출력, Fast/Mini 해상도 제한, 멀티모달 참조 입력을 사용하기 전에 [Seedance 2.0 비디오 모델 가이드](/ko/guides/seedance-2-video)를 읽으세요.
* `grok-imagine-video`의 경우, video-to-video는 공개 `.mp4` `video_url`을 사용합니다; 모델별 제한 사항인 `duration` 및 `resolution`은 모델 계약에서 제공되어야 합니다.

## PixVerse 및 HappyHorse

| 모델                           | 작업                                                                            | 입력                                                                          | 해상도                     | 지속 시간                                              | 오디오 선택기                     |
| ---------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------- | --------------------------- |
| `pixverse-c1`, `pixverse-v6` | `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video` | `prompt`; `image_url`; `start_image` + `end_image`; `reference_images`      | 360p, 540p, 720p, 1080p | 1초에서 15초 사이의 정수                                    | `output_audio`, 기본값 `false` |
| `pixverse-v5.6`              | `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video` | C1 및 V6와 동일한 필드                                                             | 360p, 540p, 720p, 1080p | 5초, 8초 또는 10초; 1080p는 5초 또는 8초 지원                  | `output_audio`, 기본값 `false` |
| `happyhorse-1.0`             | `text-to-video`, `image-to-video`, `reference-to-video`, `video-to-video`     | `prompt`; `image_url`; `reference_images`; `video_url` + `reference_images` | 720p, 1080p             | 생성 작업의 경우 3초에서 15초; video-to-video 출력은 최대 15초로 제한됨 | `output_audio`를 전송하지 마십시오   |

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

```bash theme={null}
curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pixverse-v6",
    "operation": "image-to-video",
    "prompt": "A slow camera move through a neon-lit street",
    "image_url": "https://example.com/start.jpg",
    "resolution": "1080p",
    "duration": 5,
    "output_audio": true
  }'
```

## 결과 폴링

반환된 `poll_url`을 먼저 사용하십시오. 고정 엔드포인트가 필요한 경우, 생성 응답에서 동일한 `id` / `task_id`로 `GET /v1/tasks/{id}`를 사용하십시오.

완료된 비디오 작업은 모델 및 출력 수에 따라 `video_url`, `video` 또는 `videos`를 반환할 수 있습니다. `billing_transaction_id`는 작업 식별자가 아닌 청구 식별자로 취급하십시오.

## 일반적인 함정

* 오래된 비디오 상태 경로를 하드코딩하지 마십시오; `poll_url`을 선호하십시오.
* 모델 계약이 허용하지 않는 한 첫 번째 프레임 필드를 전용 참조 이미지 흐름과 결합하지 마십시오.
* `duration`이 입력 참조 비디오 길이를 설명한다고 가정하지 마십시오; 일반적으로 생성된 출력 길이를 제어합니다.
* 타임아웃 후 작업이 이미 생성되었는지 확인하지 않고 생성 요청을 재시도하지 마십시오.

## API 참조

| 주제          | 참조                                                      |
| ----------- | ------------------------------------------------------- |
| 비디오 생성      | [비디오 생성](/ko/api-reference/video/create-video)          |
| 비디오 상태 가져오기 | [비디오 상태 가져오기](/ko/api-reference/video/get-video-status) |
| 작업 상태 가져오기  | [작업 상태 가져오기](/ko/api-reference/tasks/get-task-status)   |
| 작업 취소       | [작업 취소](/ko/api-reference/tasks/cancel-task)            |
| 청구 및 가격 책정  | [청구 및 가격 책정](/ko/guides/billing)                        |

## OpenAI 스타일 및 Volc 호환 비디오 API

모델 전반의 TokenLab 통합 비디오 API에는 `/v1/videos/generations`를 사용하세요. 기존 Seedance 2.0 통합이 Volc 스타일 `content[]` 또는 Action 요청을 이미 사용한다면 `/api/v3` 아래의 Seedance 호환 엔드포인트를 사용할 수 있습니다. 두 방식 모두 TokenLab Bearer API Key와 비동기 폴링을 사용하지만 요청과 응답 형식은 다릅니다.