Kling V4 동영상 생성

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

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())

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());

POST

videos

generations

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

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())

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());

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

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

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())

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의 이미지를 참조 이미지로 처리합니다.

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

요청 헤더

string

필수

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

요청 매개변수

string

필수

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

string

생성하거나 편집할 내용에 대한 설명입니다. 이미지로 동영상을 생성할 때는 생략 가능하며, 나머지 모드에서는 필수입니다.참조 기반 생성에서는 @Image1, @Video1, @Audio1으로 자료를 참조합니다. 각 자료 유형의 배열 순서에 따라 1부터 번호를 매깁니다. 동영상 편집에서 입력 동영상은 @Video1, 참조 이미지는 @Image1, @Image2 등입니다.

integer

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

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

string

기본값:"720p"

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

string

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

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

string[]

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

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

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

object[]

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

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

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

string

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

string

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

string[]

참조 기반 생성에 사용할 참조 동영상 목록입니다. 최대 5개 클립이며 총 최대 30초를 사용합니다.동영상 편집 또는 연장에서는 video_url 대신 정확히 1개의 동영상 URL을 전달할 수도 있습니다. omni_reference_task_type: "edit" 또는 "extend"를 지정해야 합니다.

string

편집 또는 연장할 입력 동영상 URL입니다. omni_reference_task_type: "edit" 또는 "extend"를 함께 지정해야 합니다.편집용 입력 동영상은 최소 3초여야 합니다. 3초 미만이면 HTTP 400을 반환하며, 30초를 초과하면 처음 30초를 사용합니다.

string[]

참조 기반 생성에 사용할 참조 오디오 목록입니다. 최대 3개 클립, 각각 5–30초입니다.참조 기반 생성에서 참조 이미지, 동영상, 오디오는 합계 최대 15개 자료입니다.

string

기본값:"auto"

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

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

string

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

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

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

요청 예제

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

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

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

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

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

{
  "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장입니다.

참조 기반 동영상 생성

{
  "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초여야 합니다.

동영상 편집

{
  "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"로 새 오디오를 생성할 수 있습니다.

동영상 연장

{
  "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로 바꾸세요.

curl --request GET \
  --url 'https://api.apimart.ai/v1/videos/generations/<task_id>' \
  --header 'Authorization: Bearer <token>'

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

요금

초 단위로 요금이 부과됩니다. 단가는 모델 요금을 확인하세요. 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 사용

개요

모델

텍스트 시리즈

이미지 시리즈

비디오 시리즈

오디오 시리즈

모더레이션 시리즈

업로드 관리

작업 관리

계정 관리

Kling V4 동영상 생성

모드 선택

요청 헤더

요청 매개변수

요청 예제

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

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

참조 기반 동영상 생성

동영상 편집

동영상 연장

작업 조회

요금

지원하지 않는 매개변수

자주 발생하는 오류

​모드 선택

​요청 헤더

​요청 매개변수

​요청 예제

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

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

​참조 기반 동영상 생성

​동영상 편집

​동영상 연장

​작업 조회

​요금

​지원하지 않는 매개변수

​자주 발생하는 오류

모드 선택

요청 헤더

요청 매개변수

요청 예제

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

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

참조 기반 동영상 생성

동영상 편집

동영상 연장

작업 조회

요금

지원하지 않는 매개변수

자주 발생하는 오류