> ## 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 Flash 동영상 생성

> 텍스트 생성, 단일 시작 이미지, 이미지·동영상 참조, 편집 및 연장. 720p만 지원하며 생성 길이는 3–20초이며 24fps입니다.

> [!NOTE]
>
> 이 엔드포인트는 비동기로 처리됩니다. 제출 후 반환된 `task_id`를 사용하여 `GET /v1/tasks/{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-flash",
    "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-flash",
        "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-flash",
    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-flash`를 사용합니다. 입력 자료와 `omni_reference_task_type`에 따라 모드가 선택됩니다.

| 모드 | 입력 방법 |
| - | - |
| 텍스트로 동영상 생성 | 이미지, 동영상, 오디오 자료를 전달하지 않음 |
| 이미지로 동영상 생성 | `first_frame_image`, `image_with_roles`의 `first_frame` 또는 `image_urls`의 유일한 이미지로 첫 프레임 1장 지정 |
| 참조 기반 동영상 생성 | `video_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-flash`로 지정해야 합니다.

**prompt** `string`

생성하거나 편집할 내용을 설명합니다. 이미지 기반 생성에서만 생략할 수 있고 나머지는 필수입니다. 참조는 각 배열 순서대로 1부터 번호를 매겨 `@Image1` / `@Video1`로 지정합니다. 편집 입력 영상은 `@Video1`, 참조 이미지는 `@Image1`, `@Image2` 등입니다.

**duration** `integer`

`3`–`20`의 정수 초이며 일반 기본값은 `5`입니다. 편집에서 생략하면 입력 길이를 올림합니다. 연장에서는 추가 구간의 길이입니다. 명시적 `0`은 HTTP 400, `null`은 생략과 같습니다. 이 정수 길이로 과금하며 실제 결과는 약 1프레임 더 길 수 있습니다.

**seconds** `integer`

`duration`의 별칭으로 규칙이 같습니다. 둘 다 전달하면 각각 `3`–`20` 범위이며 값이 같아야 합니다. 그렇지 않으면 HTTP 400입니다.

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

`720p`만 지원하며 생략 시 기본값입니다. `1080p`는 HTTP 400입니다. `mode`로 등급을 선택할 수 없습니다.

**aspect\_ratio** `string`

텍스트 생성, 참조 생성, 편집은 `16:9`, `9:16`, `1:1`, `21:9`를 지원하며 `auto`는 참조 생성에서만 지원합니다. 이미지 생성에서는 `aspect_ratio` / `size`를 지정할 수 없습니다. 비어 있지 않은 값은 HTTP 400을 반환하며 빈 문자열은 생략으로 처리합니다. 다른 비율이 필요하면 첫 프레임을 미리 자르세요.

| 모드 | 기본 동작 |
| - | - |
| 텍스트로 동영상 생성 | `16:9` |
| 이미지로 동영상 생성 | `aspect_ratio` / `size` 지정 불가. 첫 프레임 비율을 따르며 변경하려면 미리 자르세요 |
| 참조 기반 동영상 생성 | `auto` |
| 동영상 편집 | 입력 동영상을 따름 |
| 동영상 연장 | 이 필드를 지원하지 않으며 원본 화면비를 유지 |

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

이미지 기반 생성은 첫 프레임 1장만 받으며 2장은 HTTP 400입니다. 참조 생성·편집에서는 참조 이미지로 최대 10장입니다. 이미지만 참조할 때는 `omni_reference_task_type: "reference"`를 명시하세요. 자료 URL은 공개 접근이 가능해야 합니다. 첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

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

각 항목에 `url`과 `role`을 지정합니다. 이미지 기반 생성은 `first_frame` 1장만, 참조 생성·편집은 `reference_image`를 사용합니다. 마지막·중간 프레임은 지원하지 않습니다. 참조 이미지 최대 10장, 참조 영상을 포함해 총 15개 자료까지입니다. 첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

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

이미지로 동영상 생성 시 첫 프레임 URL입니다. `image_with_roles`의 `first_frame` 또는 `image_urls`의 첫 번째 이미지로도 제공할 수 있습니다. 첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

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

참조 영상은 최대 5개, 합계 20초 이하입니다. 초과하면 자르지 않고 HTTP 400을 반환합니다. 편집·연장에서는 작업 유형을 명시하고 `video_url` 대신 영상 1개를 전달할 수도 있습니다.

참조 영상은 MP4 / MOV만 지원하며 너비와 높이가 모두 700–4553px 범위여야 합니다. 길이는 컨테이너가 아닌 비디오 스트림을 기준으로 각 영상 최소 3초, 합계 최대 20초입니다. 참조 영상 중 하나라도 3초 미만이면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

**video\_url** `string`

편집·연장 입력 영상 URL. `omni_reference_task_type: "edit"` 또는 `"extend"`를 명시하지 않으면 HTTP 400입니다. 편집 입력은 3–20초이며 3초 미만이나 20초 초과는 과금 없이 거절합니다.

편집 영상은 MP4 / MOV만 지원하며 너비와 높이가 모두 700–4553px 범위여야 합니다. 3–20초 제한은 컨테이너가 아닌 비디오 스트림 길이를 기준으로 합니다. 형식, 너비, 높이 또는 편집 입력 길이가 조건에 맞지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

연장 입력에는 편집 모드의 높이 범위와 최소 3초 제한이 적용되지 않습니다. 예를 들어 480p, 2초 영상도 연장할 수 있습니다.

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

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

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

**audio\_setting** `string`

참조 영상이 있는 참조 생성에 사용합니다. `origin`은 첫 참조 영상의 원음을 유지하고 `auto`는 오디오를 새로 생성하며 기본값은 `auto`입니다. `origin`에는 참조 영상이 필요하고 첫 참조 영상에 오디오 트랙이 없으면 출력에도 없습니다. 편집은 원음을 유지하지 않고 오디오를 새로 생성하므로 편집 요청에서 이 파라미터를 생략하세요. 연장에서는 지원하지 않습니다.

## 출력 크기와 프레임 레이트

출력은 `720p` 등급이며 실제 픽셀 크기는 비율에 따라 달라집니다. 프레임 레이트는 24fps입니다. 실제 길이는 `duration`보다 약 1프레임 길 수 있으며 3초 요청은 약 3.04초가 됩니다.

| 비율 / 모드 | 실제 픽셀 |
| - | - |
| `16:9` | 1280×720 |
| `9:16` | 720×1280 |
| `1:1` | 960×960 |
| `21:9` | 1464×628 |
| 이미지 생성 | 첫 프레임 비율을 따르며 총 약 0.92MP. 예: 1:2.5 첫 프레임은 604×1516 출력 |

## 요청 예제

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

### 이미지 기반 생성: 첫 프레임 1장

```json theme={null}
{
  "model": "kling-v4-flash",
  "image_urls": [
    "https://example.com/start.png"
  ]
}
```

첫 프레임 1장만 제공하며 `prompt`는 생략할 수 있습니다. 마지막·중간 프레임 또는 두 번째 이미지는 지원하지 않습니다.

`aspect_ratio` / `size` 지정 불가. 첫 프레임 비율을 따르며 변경하려면 미리 자르세요.

첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

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

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

참조 이미지 최대 10장, 참조 영상 최대 5개로 총 15개 자료까지입니다. 참조 영상 합계는 20초 이하이며 참조 오디오는 지원하지 않습니다. 첫 참조 영상의 원음을 유지하려면 `audio_setting: "origin"`을 추가하세요. `origin` 사용 시 첫 참조 영상에 오디오 트랙이 없으면 출력에도 오디오 트랙이 없습니다.

첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

참조 영상은 MP4 / MOV만 지원하며 너비와 높이가 모두 700–4553px 범위여야 합니다. 길이는 컨테이너가 아닌 비디오 스트림을 기준으로 각 영상 최소 3초, 합계 최대 20초입니다. 참조 영상 중 하나라도 3초 미만이면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

### 동영상 편집

```json theme={null}
{
  "model": "kling-v4-flash",
  "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–20초여야 합니다. `duration`을 생략하면 입력 길이를 올림하고 `aspect_ratio`를 생략하면 입력 비율을 따릅니다. 편집은 원음을 유지하지 않고 오디오를 새로 생성합니다. 요청에서 `audio_setting`을 생략하세요.

첫 프레임과 참조 이미지는 너비와 높이가 모두 300px 이상이고 너비:높이 비율이 2:5–5:2여야 합니다. 조건을 충족하지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

편집 영상은 MP4 / MOV만 지원하며 너비와 높이가 모두 700–4553px 범위여야 합니다. 3–20초 제한은 컨테이너가 아닌 비디오 스트림 길이를 기준으로 합니다. 형식, 너비, 높이 또는 편집 입력 길이가 조건에 맞지 않으면 제출 시 HTTP 400을 반환하며 과금하지 않습니다.

### 동영상 연장

```json theme={null}
{
  "model": "kling-v4-flash",
  "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
}
```

입력 영상의 마지막 프레임에서 3–20초의 새 구간을 생성하고 새 구간만 반환합니다. 원본 영상은 포함되지 않으며 새 구간 길이로 과금합니다. 이미지, 목표 마지막 프레임, `aspect_ratio`, `audio_setting`은 지원하지 않으며 원본 비율을 유지합니다.

연장 입력에는 편집 모드의 높이 범위와 최소 3초 제한이 적용되지 않습니다. 예를 들어 480p, 2초 영상도 연장할 수 있습니다.

## 작업 조회

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

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

[작업 조회 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 사용하세요. `task_id`를 저장하고 `completed` 또는 `failed`까지 조회합니다. 720p 3초 영상은 실측 약 1–4분이었으며 참고치입니다. 정해진 시간이 지났다는 이유만으로 실패로 판단하지 마세요.

## 요금

초 단위로 과금합니다. 단가는 [모델 가격](https://apimart.ai/pricing)을 확인하세요. 일반 생성과 영상 입력은 서로 다른 단가를 사용합니다.

| 모드 | 과금 대상 초 |
| - | - |
| 텍스트 생성, 이미지 생성, 이미지만 참조하는 생성 | 출력 초; `kling-v4-flash@720P` |
| 영상 연장 | 추가 구간 초; `kling-v4-flash@720P` |
| 영상 편집, 참조 영상이 있는 생성 | 출력 초 + max(출력 초, 입력 영상 초); `kling-v4-flash@720P-input` |

입력 영상 초는 컨테이너가 아닌 각 비디오 스트림 길이를 합산한 뒤 올림합니다. 3.04초 영상을 `duration: 3`으로 편집하면 3 + 4 = 7초로 과금합니다. 편집 및 영상을 포함한 참조 생성은 제출 시 형식, 너비, 높이, 비디오 스트림 길이를 확인합니다. 확인 실패, MP4 / MOV 외 형식, 700–4553px 범위를 벗어난 너비 또는 높이, 합계 20초 초과 또는 편집 입력 3초 미만이면 HTTP 400을 반환하며 과금하지 않습니다. 각 참조 영상은 비디오 스트림 길이로 판단하며, 3초 미만이면 제출 시 HTTP 400을 반환하고 과금하지 않습니다.

실패 작업은 전액 환불하며 플랫폼이 시간 초과로 판정한 작업도 포함됩니다. 클라이언트 조회를 중단해도 작업은 취소되지 않습니다. 이후 성공하면 정상 과금합니다.

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

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

* `resolution: "1080p"`
* `last_frame_image`, `role: "last_frame"`, `role: "keyframe"`
* `audio_urls`, `audio_url`
* `mode`, `negative_prompt`, `watermark: true`, `audio: false`
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`
* `camera_control`, `voice_list`

## 자주 발생하는 오류

| 오류 | 해결 방법 |
| - | - |
| `kling-v4-flash only supports resolution 720p (got: 1080p)` | `1080p` 대신 `720p`를 사용하세요. |
| `kling-v4-flash duration must be between 3 and 20 seconds` | `duration` / `seconds`는 3–20의 정수이며 0은 허용하지 않습니다. |
| `kling-v4-flash image-to-video follows the first frame's aspect ratio; remove aspect_ratio / size` | 이미지 생성에서 `aspect_ratio` / `size`를 제거하세요. 비율은 첫 프레임을 따르므로 변경하려면 미리 자르세요. |
| `kling-v4-flash first frame: image width and height must be at least 300px` | 첫 프레임과 참조 이미지의 너비와 높이가 모두 300px 이상이어야 합니다. |
| `kling-v4-flash first frame: image aspect ratio (width:height) must be between 2:5 and 5:2` | 이미지 너비:높이 비율을 2:5–5:2로 조정하세요. |
| `kling-v4-flash input video #1: unsupported video format webm/mkv (supported: mp4/mov)` | 편집 또는 참조 영상은 MP4 / MOV를 사용하세요. WebM / MKV는 지원하지 않습니다. |
| `kling-v4-flash input video #1: video height must be between 700 and 4553px` | 편집 및 참조 영상 너비와 높이가 모두 700–4553px 범위여야 합니다. 이 범위는 연장 입력에 적용되지 않습니다. |
| `kling-v4-flash input video #1: video width must be between 700 and 4553px` | 편집 및 참조 영상의 너비와 높이가 모두 700–4553px 범위여야 합니다. 세로 영상의 너비도 최소 700px여야 합니다. |
| `kling-v4-flash reference video #1 must be at least 3 seconds` | 각 참조 영상의 비디오 스트림 길이는 최소 3초여야 합니다. 3초 미만이면 제출 시 HTTP 400을 반환하며 과금하지 않습니다. |
| `kling-v4-flash only supports aspect_ratio 16:9, 9:16, 1:1 or 21:9 (got: auto)` | `auto`는 참조 생성에서만 지원합니다. 이미지 생성에서는 비율 필드를 생략하세요. |
| `kling-v4-flash image-to-video only takes a first frame; last frame and keyframes are not supported` | 첫 프레임 1장만 남기고 마지막·중간 프레임이나 두 번째 이미지를 제거하세요. |
| `kling-v4-flash reference-to-video does not take reference audios` | `audio_urls` / `audio_url`을 제거하세요. |
| `kling-v4-flash video extend takes no images` | 연장 요청에서 이미지와 목표 마지막 프레임을 제거하세요. |
| `kling-v4-flash input videos must be at most 20 seconds in total` | 참조 영상 합계 또는 편집 입력은 20초 이하여야 하며 자동으로 자르지 않습니다. |
| `video edit requires an input video of at least 3 seconds` | 비디오 스트림 길이가 최소 3초인 편집 입력을 사용하세요. 컨테이너 길이를 기준으로 판단하지 않습니다. |
| `video_url needs omni_reference_task_type edit ... or extend` | `edit` / `extend`를 명시하고 참조 영상은 `video_urls`에 넣으세요. |
| `Failed to probe the input video duration` | 입력 URL의 접근 가능 여부와 유효한 영상인지 확인하세요. |
| `duration (3) and seconds (5) are aliases and must match` | 별칭 하나만 보내거나 두 값을 같은 3–20 범위 값으로 맞추세요. |


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