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

# Kling v4 동영상 생성

> 하나의 kling-4.0 모델로 텍스트, 참조 미디어, 처음/중간/마지막 키프레임을 사용한 동영상 생성

세 입력 모드는 모두 `kling-4.0` 을 사용합니다. 전달한 미디어에 따라 생성 경로를 선택합니다. 비동기 API 이므로 제출 후 플랫폼 작업 ID 로 결과를 조회합니다.

> [!NOTE]
>
> 플랫폼 API 키를 사용합니다. 중국 본토에서는 `https://toapis.com` 을 `https://toapis.cn` 으로 바꿀 수 있습니다. 사용 가능 여부는 배포된 채널 설정과 계정 권한에 따라 달라집니다.

## 입력 모드

| 모드 | 요청 내용 |
| - | - |
| 텍스트 동영상 | 프롬프트와 출력 사양만 전달하고 미디어는 생략합니다. |
| 참조 미디어 | `image_urls` / `video_urls` 또는 reference 역할의 미디어를 사용합니다. 이미지와 동영상을 함께 사용할 수 있습니다. |
| 키프레임 | `image_with_roles` 에 `first_frame`, `keyframe`, `last_frame` 을 명시합니다. 참조 이미지나 동영상을 함께 전달하지 않습니다. |

## 요청 매개변수

**Authorization** `string` *required*

`Bearer YOUR_API_KEY` 로 인증합니다.

**model** `string` *required*

항상 `kling-4.0`. 모드에 따라 모델 ID 를 바꾸지 않습니다.

**prompt** `string` *required*

필수, 공백만 입력할 수 없으며 최대 8000 Unicode 문자. 주제, 동작, 카메라 및 미디어 관계를 설명합니다.

**duration** `integer` (default: 5)

3-30 초의 정수. 기본값은 5.

**resolution** `string` (default: 720p)

`720p` 또는 `1080p`. 기본값은 `720p`. 이 필드로 해상도를 선택합니다.

**aspect\_ratio** `string`

`auto`, `16:9`, `9:16`, `1:1`, `21:9`. 생략하면 업스트림 기본값을 유지합니다. 자동 비율은 `auto` 를 명시할 수 있습니다.

**image\_urls** `string[]`

참조 이미지 URL 배열, 최대 10 장. 위치로 첫/마지막 프레임을 추론하지 않습니다. reference 이미지 역할과 합산하므로 같은 미디어를 중복 전달하지 않습니다.

**video\_urls** `string[]`

참조 동영상 URL 배열. `video_with_roles` 와 합쳐 최대 5 개.

**image\_with\_roles** `object[]`

각 객체는 `url` 과 `role` 을 가집니다. `reference` / `reference_image` 는 참조 이미지. `first_frame`, `keyframe`, `last_frame` 은 처음, 중간, 마지막 프레임입니다.

**video\_with\_roles** `object[]`

각 객체는 `url` 과 `role` 을 가집니다. `reference` / `reference_video` 를 지원합니다.

**metadata** `object`

불리언 `keep_original_sound` 로 참조 동영상 원음을 보존합니다. 예: `{"keep_original_sound": true}`. 참조 동영상에만 사용합니다. 키프레임 모드에서는 false 여도 이 키를 전달할 수 없습니다.

**client\_business\_id** `string`

선택적 고객 업무 ID. 작업과 함께 저장되며 같은 조회 API 에서 사용할 수 있습니다.

## 미디어 규칙과 검증

* 공개 접근 가능한 HTTP(S) URL 을 사용하고 사용자 이름이나 암호를 넣지 않습니다. 로컬 파일은 [이미지 업로드](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 또는 [동영상 업로드](https://docs.toapis.com/docs/ko/api-reference/uploads/videos.md)로 URL 을 얻습니다. 로컬 경로나 base64 를 보내지 않습니다.
* 참조 모드는 이미지 10 장과 동영상 5 개까지 지원합니다. 일반 배열과 명시적 reference 역할은 합산하므로 같은 미디어를 중복 제출하지 않습니다.
* 키프레임은 최소 1 장. 처음과 마지막은 각각 최대 1 장, 중간은 최대 8 장. 총합은 `min(duration + 1, 10)` 이하입니다. 3 초는 4 장, 5 초는 6 장, 9-30 초는 10 장까지.
* 중간 프레임은 배열의 `keyframe` 순서입니다. 처음과 마지막은 역할로 정하고 일반 이미지 위치로 추론하지 않습니다. 첫 프레임만, 마지막만 또는 중간만 있어도 키프레임 모드입니다.
* 키프레임과 참조 미디어는 함께 사용할 수 없습니다. 기존 Kling `mode`, `audio`, `video_list` 또는 Omni 참조 구조를 사용하지 않습니다. `audio_with_roles`, `metadata.elements`, `metadata.voices` 는 지원하지 않습니다.
* 잘못된 사양, 역할, URL, 개수 또는 모드 조합은 거부됩니다. 오류를 수정한 뒤 다시 제출합니다. 파일 크기, 코덱, 입력 동영상 길이 상한은 이 페이지에서 보장하지 않으며 업로드 서비스와 업스트림 요구 사항도 충족해야 합니다.

## 요청 예제

### 텍스트 동영상

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "석양 아래 해안에 부딪히는 파도, 천천히 전진하는 카메라",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 참조 미디어

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "참조 이미지 인물 외형을 유지하고 참조 동영상 카메라 움직임을 사용",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/motion.mp4"
  ],
  "metadata": {
    "keep_original_sound": true
  }
}
```

### 키프레임

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "첫 프레임에서 중간 장면을 거쳐 마지막 프레임으로 부드럽게 전환",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/middle-1.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/middle-2.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/last.png",
      "role": "last_frame"
    }
  ]
}
```

### 작업 제출

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "석양 아래 해안에 부딪히는 파도, 천천히 전진하는 카메라",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0",
  "status": "queued",
  "created_at": 1792713600
}
```

## 작업 조회와 과금

응답의 `id` 는 플랫폼 작업 ID 입니다. 공급자 task\_id 대신 아래 API 로 조회합니다. 상태는 `queued`, `in_progress`, `completed`, `failed`. [동영상 작업 상태](https://docs.toapis.com/docs/ko/api-reference/tasks/video-status.md)와 [작업 Webhook](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md)을 참조하세요.

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

기본값은 5 초 / 720p 이며 명시적으로 사양을 지정할 수 있습니다. 고정 가격이나 기존 Sound 과금과의 동일성을 보장하지 않습니다. 실제 과금은 계정 견적 및 작업 usage / billing 을 따릅니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.