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

# Kling V4 동영상 생성

> 텍스트·이미지·참조 자료 기반 동영상 생성, 동영상 편집 및 연장을 지원합니다. 720p / 1080p로 3–30초를 생성하며 항상 스테레오 오디오를 포함합니다.

> [!NOTE]
>
> 이 엔드포인트는 비동기로 처리됩니다. 제출 후 반환된 `task_id`를 사용하여 `GET /v1/videos/generations/{task_id}`로 작업 상태와 결과를 조회하세요.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v4",
    "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "kling-v4",
        "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kling-v4",
    prompt: "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    duration: 5,
    resolution: "720p",
    aspect_ratio: "9:16"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

## 모드 선택

다섯 가지 모드 모두 동일한 모델 이름 `kling-v4`를 사용합니다. 입력 자료와 `omni_reference_task_type`에 따라 모드가 선택됩니다.

| 모드 | 입력 방법 |
| - | - |
| 텍스트로 동영상 생성 | 이미지, 동영상, 오디오 자료를 전달하지 않음 |
| 이미지로 동영상 생성 | 첫 프레임 필수, 마지막 프레임과 최대 8개의 중간 프레임 추가 가능 |
| 참조 기반 동영상 생성 | `video_urls`, `audio_urls` 또는 `image_with_roles`의 `reference_image` 전달. `omni_reference_task_type: "reference"`를 명시적으로 설정할 수도 있음 |
| 동영상 편집 | `omni_reference_task_type: "edit"` 설정 및 입력 동영상 제공 |
| 동영상 연장 | `omni_reference_task_type: "extend"` 설정 및 입력 동영상 제공 |

`omni_reference_task_type`의 기본값은 `auto`이며 생략한 것과 같습니다. `reference`를 명시하면 `image_urls`의 이미지를 참조 이미지로 처리합니다.

> [!WARNING]
>
> `edit` 또는 `extend`를 지정하지 않고 `video_url`만 전달하면 HTTP 400을 반환합니다. 동영상을 참조 자료로 사용하려면 `video_urls`를 사용하세요.

## 요청 헤더

**Authorization** `string` *required*

Bearer 인증: `Bearer <token>`. `<token>`은 APIMart API Key입니다.

## 요청 매개변수

**model** `string` *required*

`kling-v4`로 지정해야 합니다.

**prompt** `string`

생성하거나 편집할 내용에 대한 설명입니다. 이미지로 동영상을 생성할 때는 생략 가능하며, 나머지 모드에서는 필수입니다.

참조 기반 생성에서는 `@Image1`, `@Video1`, `@Audio1`으로 자료를 참조합니다. 각 자료 유형의 배열 순서에 따라 1부터 번호를 매깁니다. 동영상 편집에서 입력 동영상은 `@Video1`, 참조 이미지는 `@Image1`, `@Image2` 등입니다.

**duration** `integer`

생성할 길이(초)로 `3`–`30`을 지원하며, 기본값은 `5`입니다.

* 동영상 편집: 생략하면 출력 길이는 입력 동영상을 따릅니다.
* 동영상 연장: 새로 생성할 구간의 길이입니다. 원본과 새 구간을 연결한 전체 동영상을 반환합니다.

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

출력 해상도로 `720p`와 `1080p`를 지원합니다. 해상도는 이 필드로 선택하세요. V4는 `mode`를 지원하지 않습니다.

**aspect\_ratio** `string`

`16:9`, `9:16`, `1:1`, `21:9`를 지원하며, 참조 기반 생성에서는 `auto`도 지원합니다.

| 모드 | 기본 동작 |
| - | - |
| 텍스트로 동영상 생성 | `16:9` |
| 이미지로 동영상 생성 | 첫 프레임을 따름 |
| 참조 기반 동영상 생성 | `auto` |
| 동영상 편집 | 입력 동영상을 따름 |
| 동영상 연장 | 이 필드를 지원하지 않으며 원본 화면비를 유지 |

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

이미지 URL 목록으로, 모드에 따라 용도가 달라집니다.

* 이미지로 동영상 생성: 첫 번째 이미지는 첫 프레임, 두 번째는 마지막 프레임이며 최대 2장입니다.
* 참조 기반 생성 및 동영상 편집: 최대 10장의 참조 이미지입니다. 참조 이미지만으로 생성하려면 `omni_reference_task_type: "reference"`를 명시적으로 설정하세요.

자료 URL은 공개적으로 접근 가능해야 합니다.

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

역할이 지정된 이미지 목록입니다. 각 항목은 `url`과 `role`을 포함합니다.

| `role` | 용도 |
| - | - |
| `first_frame` | 이미지로 동영상 생성 시 첫 프레임, 정확히 1장 필수 |
| `last_frame` | 이미지로 동영상 생성 시 마지막 프레임 또는 연장 시 목표 마지막 프레임 |
| `keyframe` | 이미지로 동영상 생성 시 중간 프레임. `middle_frame`도 허용하며 배열 순서대로 사용, 최대 8장 |
| `reference_image` | 참조 기반 생성에 사용할 참조 이미지 |

이미지로 동영상을 생성할 때 첫 프레임, 마지막 프레임, 중간 프레임은 합계 최대 10장입니다.

**first\_frame\_image** `string`

이미지로 동영상 생성 시 첫 프레임 URL입니다. `image_with_roles`의 `first_frame` 또는 `image_urls`의 첫 번째 이미지로도 제공할 수 있습니다.

**last\_frame\_image** `string`

이미지로 동영상 생성 시 마지막 프레임 URL 또는 동영상 연장 시 목표 마지막 프레임 URL입니다.

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

참조 기반 생성에 사용할 참조 동영상 목록입니다. 최대 5개 클립이며 총 최대 30초를 사용합니다.

동영상 편집 또는 연장에서는 `video_url` 대신 정확히 1개의 동영상 URL을 전달할 수도 있습니다. `omni_reference_task_type: "edit"` 또는 `"extend"`를 지정해야 합니다.

**video\_url** `string`

편집 또는 연장할 입력 동영상 URL입니다. `omni_reference_task_type: "edit"` 또는 `"extend"`를 함께 지정해야 합니다.

편집용 입력 동영상은 최소 3초여야 합니다. 3초 미만이면 HTTP 400을 반환하며, 30초를 초과하면 처음 30초를 사용합니다.

**audio\_urls** `string[]`

참조 기반 생성에 사용할 참조 오디오 목록입니다. 최대 3개 클립, 각각 5–30초입니다.

참조 기반 생성에서 참조 이미지, 동영상, 오디오는 합계 최대 15개 자료입니다.

**omni\_reference\_task\_type** `string` (default: auto)

`auto`, `reference`, `edit`, `extend`를 지원합니다.

* `auto`: 자료에 따라 텍스트·이미지·참조 기반 생성을 자동 선택하며, 필드를 생략한 것과 같습니다.
* `reference`: 참조 기반 생성이며 `image_urls`의 이미지를 참조 이미지로 처리합니다.
* `edit`: 동영상 편집으로, 입력 동영상이 필요합니다.
* `extend`: 동영상 연장으로, 입력 동영상이 필요합니다.

**audio\_setting** `string`

`origin`(입력 동영상의 원본 오디오 유지)과 `auto`(새 오디오 생성)를 지원합니다. 동영상 편집 또는 참조 동영상이 포함된 참조 기반 생성에서만 사용합니다.

* 동영상 편집: 기본적으로 원본 오디오를 유지하며, `auto`를 설정하면 새 오디오를 생성합니다.
* 참조 동영상이 포함된 참조 기반 생성: 기본적으로 새 오디오를 생성하며, `origin`은 참조 동영상의 오디오를 유지합니다.
* 동영상 연장: 이 필드는 지원하지 않습니다. 원본 오디오를 유지하고 새 구간에는 오디오를 자동 생성합니다.

V4는 항상 스테레오 오디오가 포함된 동영상을 출력하며, 소리와 영상을 함께 생성합니다.

## 요청 예제

아래 자료 URL은 예시입니다. 실제로 공개 접근 가능한 URL로 바꾸세요.

### 이미지로 동영상 생성: 첫 프레임과 마지막 프레임

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera slowly moves closer",
  "image_urls": ["https://example.com/start.png", "https://example.com/end.png"]
}
```

첫 번째 이미지는 첫 프레임, 두 번째는 마지막 프레임입니다. 이미지로 동영상 생성 시 `prompt`는 생략할 수 있습니다.

### 이미지로 동영상 생성: 첫 프레임, 중간 프레임, 마지막 프레임

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "A girl walks from the window to the door, then looks back and smiles",
  "image_with_roles": [
    {"url": "https://example.com/1.png", "role": "first_frame"},
    {"url": "https://example.com/2.png", "role": "keyframe"},
    {"url": "https://example.com/3.png", "role": "keyframe"},
    {"url": "https://example.com/4.png", "role": "last_frame"}
  ],
  "duration": 10
}
```

중간 프레임은 배열 순서대로 사용합니다. 첫 프레임은 정확히 1장이어야 하며, 첫 프레임·마지막 프레임·중간 프레임의 합계는 최대 10장입니다.

### 참조 기반 동영상 생성

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The girl in @Image1 runs along the beach with the camera movement from @Video1 and background music from @Audio1",
  "image_with_roles": [
    {"url": "https://example.com/girl.png", "role": "reference_image"}
  ],
  "video_urls": ["https://example.com/camera.mp4"],
  "audio_urls": ["https://example.com/bgm.mp3"],
  "aspect_ratio": "auto",
  "duration": 5
}
```

참조 이미지는 최대 10장, 동영상은 5개, 오디오는 3개이며 합계 최대 15개 자료입니다. 참조 동영상은 총 최대 30초를 사용하며, 각 참조 오디오는 5–30초여야 합니다.

### 동영상 편집

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "Change the scene to a snowy winter night",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4",
  "image_urls": ["https://example.com/style.png"]
}
```

입력 동영상은 최소 3초여야 하며, 30초를 초과하면 처음 30초를 사용합니다. `duration`과 `aspect_ratio`를 생략하면 출력 길이와 화면비가 입력 동영상을 따릅니다. 기본적으로 원본 오디오를 유지하며, `audio_setting: "auto"`로 새 오디오를 생성할 수 있습니다.

### 동영상 연장

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera continues moving forward as the sky grows darker",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 5
}
```

입력 동영상의 마지막 프레임부터 연장합니다. 원본과 새 구간을 연결한 전체 동영상을 반환하며, 새 구간의 길이에 대해서만 요금이 부과됩니다.

`last_frame_image` 또는 `image_with_roles`의 `last_frame`으로 목표 마지막 프레임을 제공할 수 있습니다. 연장은 `aspect_ratio`와 `audio_setting`을 지원하지 않습니다.

## 작업 조회

다음 요청의 작업 ID를 제출 응답으로 받은 ID로 바꾸세요.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/videos/generations/<task_id>' \
  --header 'Authorization: Bearer <token>'
```

예상 생성 시간: 3초 길이의 720p 동영상은 약 3분, 15초 길이의 동영상은 약 3.5분입니다.

## 요금

초 단위로 요금이 부과됩니다. 단가는 [모델 요금](https://apimart.ai/pricing)을 확인하세요. `720p`와 `1080p`의 단가는 다릅니다.

동영상 편집과 참조 동영상이 포함된 참조 기반 생성에는 동영상 입력용 단가를 적용합니다. 나머지 모드에는 일반 생성 단가를 적용합니다.

| 모드 | 과금 대상 초 |
| - | - |
| 텍스트로 동영상 생성, 이미지로 동영상 생성, 이미지 또는 오디오만 사용하는 참조 기반 생성 | 출력 초 |
| 동영상 연장 | 새 구간의 초 |
| 동영상 편집, 참조 동영상이 포함된 참조 기반 생성 | 출력 초 + max(출력 초, 입력 동영상 초) |

입력 동영상 초는 각 클립 길이를 합산한 뒤 초 단위로 올림하고 최대 30초로 제한합니다. 예를 들어 3.04초 동영상을 `duration` 없이 편집하면 4초가 출력되고, 4 + 4 = 8초가 과금됩니다.

동영상 편집과 참조 동영상이 포함된 참조 기반 생성은 제출 시 입력 동영상의 길이를 확인합니다. 확인에 실패하면 HTTP 400을 반환하며 과금하지 않습니다. 생성 실패 시 전액 환불됩니다.

## 지원하지 않는 매개변수

다음 매개변수 또는 값은 HTTP 400을 반환합니다.

* `mode`: V4에는 `std`, `pro`, `4k` 등급이 없습니다. `resolution`을 사용하세요.
* `negative_prompt`, `watermark: true`, `audio: false`.
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`.
* `camera_control`, `voice_list`.

## 자주 발생하는 오류

| 오류 | 해결 방법 |
| - | - |
| `video_url needs omni_reference_task_type edit ... or extend` | `video_url` 사용 시 `edit` 또는 `extend`를 명시하고, 참조 동영상에는 `video_urls` 사용 |
| `image-to-video requires exactly 1 first frame` | 첫 프레임을 정확히 1장 제공. 마지막 프레임이나 중간 프레임만으로는 불가 |
| `first frame, last frame and keyframes together are at most 10 images` | 첫 프레임·마지막 프레임·중간 프레임 합계를 10장 이하로 축소 |
| `reference images, videos and audios together are at most 15 files` | 참조 자료 합계를 15개 이하로 축소 |
| `video edit requires an input video of at least 3 seconds` | 최소 3초 길이의 입력 동영상 사용 |
| `Failed to probe the input video duration` | URL 접근 가능 여부와 유효한 동영상 파일인지 확인 |
| `has no std/pro/4k mode` | `mode`를 제거하고 `resolution` 사용 |
| `Could not download the input from ... (HTTP 403)` | 핫링크 방지 없이 공개 접근 가능한 자료 URL 사용 |


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