Kuaishou

Kling 3.0

kling-3.0-omni/reference-to-video

통합 멀티모달 비디오 생성 시리즈로, 텍스트-비디오, 이미지-비디오, 레퍼런스-비디오, 비디오 내 편집을 지원하며 네이티브 립싱크와 다국어 오디오를 갖춤

kling-3.0-omni/image-to-video kling-3.0-omni/reference-to-video kling-3.0-omni/text-to-video kling-3.0-omni/transformation kling-3.0/image-to-video kling-3.0/motion-control kling-3.0/text-to-video

kling-3.0-omni/reference-to-video 사용해 보기

입력

Subjects

작품 갤러리

모든 작품 보기

출력

video

파라미터를 입력하고 생성하면 결과가 여기에 표시됩니다.

가격

kling-3.0-omni/reference-to-video per second

사양	720P	1080P	4K
Sound Off · Without Reference Videos	$0.100	$0.129	$0.479
Sound On · Without Reference Videos	$0.129	$0.1645	$0.479
Sound Off · With Reference Videos	$0.143	$0.193	$0.479
Sound On · With Reference Videos	$0.143	$0.193	$0.479

포지셔닝 소개

kling-3.0-omni/reference-to-video는 Kling 3.0 Omni 시리즈에서 참조 이미지 기반 비디오 생성을 위한 라인으로, 1~7장의 참조 이미지(또는 최대 7개의 재사용 가능한 주체 요소와 결합)를 시각적 앵커로 삼아 텍스트 프롬프트와 함께 3~15초의 비디오를 생성할 수 있습니다. 720p, 1080p, 4k 해상도와 16:9, 9:16, 1:1 화면비를 지원하며, 네이티브 오디오와 스마트 멀티샷을 활성화할 수 있습니다. 캐릭터나 사물의 컷 간 일관성을 유지해야 하거나 마케팅 및 소셜 미디어 비디오를 대량으로 제작해야 하는 개발자에게 적합합니다.

핵심 하이라이트

다중 참조 이미지와 주체 요소의 이중 앵커링——1~7장의 참조 이미지를 전달하거나, 2~4장의 이미지를 포함한 최대 7개의 주체 요소를 정의하고 프롬프트에서 @name으로 참조할 수 있습니다.
참조 비디오 선택적 오버레이——3~15.5초의 참조 비디오 1개를 추가하여 동작과 구도를 제약할 수 있으며, 이 경우 참조 이미지와 주체의 합계 상한이 4개로 축소됩니다.
세로 화면부터 4K까지 아우르는 해상도와 화면비——출력은 720p, 1080p, 4k 중 선택 가능하며, 16:9, 9:16, 1:1 화면비를 지원하여 가로형 화면과 숏폼 세로형 배포에 모두 대응합니다.
네이티브 오디오와 멀티샷 조합 가능——기본적으로 꺼져 있는 네이티브 오디오와 스마트 멀티샷을 동시에 켜서 사운드가 포함된 멀티샷 클립을 한 번에 생성할 수 있습니다. 참조 비디오를 사용할 때는 두 기능을 사용할 수 없습니다.

기능 설명

다중 주체 일관성 생성: elements를 통해 주체 이름, 설명, 동일 주체의 2~4장 이미지를 정의하고 프롬프트에서 @name으로 호출하여, 같은 캐릭터나 사물이 여러 컷에서 동일한 외형을 유지하도록 합니다.

참조 비디오 제약: MP4/MOV 참조 비디오 1개(최대 200MB, 3~15.5초)를 전달하여 동작과 리듬을 유도하며, 기존 소재를 기반으로 스타일화하거나 재촬영식으로 생성하는 데 적합합니다.

해상도와 화면비 제어: 배포 채널에 따라 720p, 1080p 또는 4k 출력을 선택하고 16:9, 9:16, 1:1 화면비를 설정하여 후반 크롭과 트랜스코딩을 줄입니다.

네이티브 오디오와 스마트 멀티샷: audio를 켜면 사운드가 동시에 생성되며, prefer_multi_shots를 켜면 모델이 프롬프트에 따라 멀티샷을 자동으로 분할합니다. 두 기능 모두 참조 비디오를 사용하지 않을 때 사용할 수 있습니다.

길이와 프롬프트 길이 조정 가능: 출력 길이는 서사 필요에 따라 3~15초로 설정할 수 있으며, 프롬프트 상한은 3072자로 주체, 동작, 샷 연출을 설명하기에 충분합니다.

적용 시나리오

브랜드 마케팅 팀: 참조 이미지 + 상품 판매 포인트 프롬프트——상품의 다각도 참조 이미지로 외형을 고정하고, 화면비와 해상도 규격을 갖춘 숏폼을 제작하여 피드 광고와 공식 웹사이트 배포에 바로 활용합니다.
소셜 미디어 운영: 캐릭터 요소 + 세로형 스크립트——고정 캐릭터 요소를 정의한 뒤 9:16 숏폼을 대량 생성하여 캐릭터 설정을 일관되게 유지하며 일일 콘텐츠 제작에 사용합니다.
영상 애니메이션 사전 제작: 참조 비디오 + 스토리보드 프롬프트——참조 비디오로 동작 리듬을 제약하고 멀티샷 프리비주얼 클립을 출력하여 감독이 샷 설계와 편집 포인트를 확인하도록 합니다.
이커머스 콘텐츠 팀: 상품 이미지 모음에서 비디오로 변환——상품 참조 이미지를 업로드하고 1:1 또는 16:9 화면비를 설정하여 상세 페이지와 상품 대표 이미지 영역에 사용할 전시용 비디오를 생성합니다.

제한 사항 및 선택 가이드

참조 이미지와 주체 요소의 합계는 7개를 초과할 수 없으며, 참조 비디오를 추가하면 4개로 축소되고 이때 네이티브 오디오와 스마트 멀티샷은 사용할 수 없습니다. 1회 길이 상한은 15초이므로 긴 서사는 구간별로 생성한 뒤 이어 붙여야 합니다. 참조 이미지는 JPG/PNG, 장당 최대 50MB, 최단 변 최소 300px이어야 하며, 참조 비디오는 MP4/MOV, 3~15.5초로 제한됩니다. 단일 이미지 구동이나 순수 텍스트 생성만 필요하다면 동일 시리즈의 image-to-video 또는 text-to-video 라인을 선택할 수 있으며, 동작 제어에 특별한 요구가 있을 때는 motion-control을 검토할 수 있습니다.

새소식

변경 이력 보기 →

새 모델 신규 모델: Kling 3.0 Omni(커링 O3), POST /v1/tasks로 호출. kling-3.0-omn… Oct 12, 2026

자주 묻는 질문

모든 질문 보기 →

Kling 3.0 Image-to-Video는 이미지를 업로드해야 하나요?

네. 현재 kling-3.0/image-to-video는 이미지-투-비디오 방식이며, 입력 이미지가 주체와 시작 구도를 담당하고 Prompt가 동작, 카메라, 환경 변화를 담당합니다.
Kling 3.0 Image-to-Video는 어떤 길이와 해상도를 지원하나요?

현재 HiAPI 요청 계약은 3–15s를 지원하며, 출력 해상도는 720p, 1080p, 4K입니다. 선택 가능한 값은 페이지 매개변수 패널과 API 문서를 기준으로 합니다.
Kling 3.0 Image-to-Video는 어떻게 과금되나요?

작업은 출력 길이와 선택한 등급에 따라 과금됩니다. 페이지에는 전역 금액 단위에 따라 실시간 가격이 표시되며, 최종 청구는 성공한 작업 기록을 기준으로 합니다.
이미지-투-비디오에서 피사체 안정성을 어떻게 높이나요?

피사체가 선명하고 가림이 적으며 구도가 완전한 입력 이미지를 사용하세요. Prompt에는 주요 동작과 카메라를 먼저 설명한 다음 반드시 유지해야 할 외형, 재질, 배경 관계를 나열하세요. 첫 테스트는 짧은 길이로 진행하는 것이 좋습니다.

생성 작업 제출

POST https://api.hiapi.ai/v1/tasks

헤더

Authorizationstring필수

계정 API 키. 모든 요청에 필수입니다. 예: Bearer YOUR_HIAPI_API_KEY. API 키 받기

Content-Typestring선택

요청 본문은 항상 JSON으로 파싱됩니다. 전송 시 application/json(charset 포함 가능)만 허용되며, 다른 값은 415를 반환합니다. 예: application/json.

Idempotency-Keystring선택

멱등 키. 최대 255바이트. 같은 계정에서 같은 키의 재시도는 태스크를 한 번만 생성하며, 재전송 시 최초의 taskId를 반환합니다.

멱등 키

네트워크 타임아웃이나 클라이언트 자동 재시도 시 같은 키로는 태스크를 한 번만 생성하고 이중 과금되지 않습니다(범위 = API 키의 계정). 업무 고유 식별자(예: "order-42")를 키로 사용할 것을 권장합니다. 같은 키 재전송 시 최초 taskId를 반환하며, 키는 첫 제출 후 24시간 뒤 만료됩니다. 자세한 시나리오 표는 통합 비동기 API 소개 페이지를 참고하세요.

본문

modelstring필수

현재 고정 값: kling-3.0-omni/reference-to-video

routestring선택

현재 고정 값: default

inputobject필수

kling-3.0-omni/reference-to-video 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.

audioboolean선택기본값: false

비디오 생성 시 화면과 일치하는 네이티브 오디오를 동시에 생성할지 여부이며, 불리언 값이고 기본값은 false입니다. 참조 비디오(video_urls)를 제공할 경우 사용할 수 없습니다.

promptstring필수minLength 1maxLength 3072

생성하고자 하는 비디오 내용을 설명합니다. elements의 주체를 사용하려면 프롬프트에서 @name 형식으로 해당 이름을 참조할 수 있습니다.

durationinteger선택기본값: 5min 3max 15

출력 비디오 길이(초)이며, 정수이고 값 범위는 3-15, 기본값은 5입니다.

elementsarray선택maxItems 7

재사용 가능한 주체 목록으로 최대 7개입니다. 각 요소는 이름, 간단한 설명, 2-4장의 이미지를 포함하며, 프롬프트에서 @name으로 참조할 수 있습니다.

Array [ object ]

배열 항목

namestring필수minLength 1

주체의 고유 이름으로, 프롬프트에서 @name 형식으로 참조하는 데 사용되며 이름에는 공백이 포함될 수 없습니다.

descriptionstring필수minLength 1

해당 주체에 대한 간단한 설명 텍스트로, 모델이 해당 주체를 인식하고 재현하는 데 도움을 줍니다.

element_input_urlsarray필수minItems 2maxItems 4

동일 주체의 참조 이미지 배열로, 2-4장을 제공해야 하며 JPG/PNG 형식을 지원합니다.

Array [ string ]

image_urlsarray필수minItems 1maxItems 7

참조 이미지 배열로, 1-7장을 제공할 수 있습니다. 참조 비디오를 추가한 경우 최대 4장이며, 참조 이미지와 주체(elements)를 합쳐 7장을 초과할 수 없습니다(참조 비디오 포함 시 합계 4장을 초과할 수 없음). JPG/PNG를 지원하며, 단일 파일은 50MB를 초과할 수 없고 변 길이는 최소 300 px입니다.

Array [ string ]

resolutionstring선택기본값: "720p"

출력 비디오 해상도이며, 문자열이고 기본값은 720p입니다.

옵션:720p1080p4k

video_urlsarray선택minItems 1maxItems 1

선택적 참조 비디오 배열로, MP4 또는 MOV를 지원하며, 단일 파일은 200MB를 초과할 수 없고 길이는 3-15.5초, 너비와 높이는 700-4553 px, 프레임 레이트는 24-60 fps입니다. 참조 비디오를 추가한 후에는 네이티브 오디오와 스마트 멀티 샷을 지원하지 않습니다.

Array [ string ]

aspect_ratiostring선택기본값: "16:9"

출력 비디오의 화면 비율이며, 문자열이고 기본값은 16:9입니다.

옵션:16:99:161:1

prefer_multi_shotsboolean선택기본값: false

모델이 프롬프트에 따라 여러 샷을 자동으로 계획하도록 할지 여부이며, 불리언 값이고 기본값은 false입니다. 참조 비디오를 추가한 후에는 사용할 수 없습니다.

callbackobject선택

종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.

콜백(Webhook)

생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.

urlstring필수

callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.

whenstring선택기본값: "final"

현재는 final만 지원(success / fail 모두 알림).

옵션:final

storagestring선택기본값: "temp"

산출물 저장 등급: temp(기본·약 7일) 또는 persistent(장기 보관·용량 과금). 잔액 부족이나 저장 한도 초과 시 자동으로 temp로 강등됩니다. 실제 적용된 등급은 태스크 상세 응답에서 확인할 수 있습니다.

옵션:temppersistent

요청 예시

# 비동기 태스크 제출. 성공 시 즉시 taskId 반환(생성 완료 대기 없음)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "image_urls": "…",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "prefer_multi_shots": false
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "kling-3.0-omni/reference-to-video",
    input: {
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "image_urls": "…",
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "prefer_multi_shots": false
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "kling-3.0-omni/reference-to-video",
        "input": {
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "image_urls": "…",
          "resolution": "720p",
          "aspect_ratio": "16:9",
          "prefer_multi_shots": False
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

작업 상세 조회

GET https://api.hiapi.ai/v1/tasks/:id

응답 필드

taskIdstring필수

태스크 ID. 접두사는 항상 tk-hiapi-.

modelstring필수

확인된 전체 모델명. route 파라미터로 제출한 태스크는 base@route(예: gpt-image-2/text-to-image@ext)를 반환하며, 그 외에는 제출 시의 모델명과 동일합니다.

routestring선택

route 파라미터를 명시해 제출한 태스크에만 나타나며, 제출한 값을 그대로 반환합니다.

statusstring필수

태스크 상태.

상태 값

queued 대기 중, 아직 시작되지 않음. handling 처리 중. archiving 처리 완료, 산출물 준비 중. success 종료: 완료. 산출물 사용 가능(output 반환). fail 종료: 실패(error 반환). 제출 후 status로 판단합니다: success와 fail이 종료 상태이며 나머지는 비종료입니다. 1~3초 간격으로 종료까지 폴링하세요. 성공 시 output[].url에서 산출물을 다운로드하고 expireAt 전에 옮기세요. 장기 보관이 필요하면 생성 시 storage: "persistent"를 사용하세요.

creatednumber필수

태스크 생성 시각(Unix 초).

completednumber필수

종료 상태가 된 Unix 초. 비종료 상태에서는 0.

outputarray선택

status == success일 때만 나타납니다. 산출물 목록 — 항상 배열이며, 하나의 태스크에서 여러 type을 동시에 반환할 수 있습니다(예: video + first_frame).

Array [ object ]

배열 항목

urlstring필수

산출물 URL. 바로 다운로드할 수 있습니다.

typestring필수

현재 가능한 값: video, image, audio, first_frame, last_frame, thumbnail. 이후 확장될 수 있습니다.

expireAtnumber필수

산출물 접근 가능 기한(Unix 초). 만료 전에 다운로드하거나 이전하세요.

errorobject선택

status == fail일 때만 나타납니다.

codestring필수

비즈니스 오류 코드.

messagestring필수

오류 설명.

응답 예시

성공

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

처리 중(비종료)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

실패

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}