본문으로 건너뛰기
API 레퍼런스

Kling 텍스트→비디오

Kling 3.0 모델로 프롬프트에서 클립을 생성하며 사운드, 멀티샷, Omni 참조 기반 영상 생성을 사용하세요.

Markdown 보기
01

개요

지원되는 모델로 텍스트를 비디오로 변환하는 엔드포인트를 사용하세요. 반환된 Task ID로 상태를 조회하거나, 아래에 문서화된 전달을 위해 callback_url을 제공하세요.

빠른 시작

  1. API 키를 만들고 RUNAPI_API_KEY로 설정합니다.
  2. 지원되는 모델을 선택하고 해당 모델의 스키마와 일치하는 본문으로 POST 요청을 전송합니다.
  3. 반환된 작업 ID를 저장한 후, 터미널 상태가 될 때까지 폴링하거나 아래에 문서화된 콜백을 처리하세요.

엔드포인트

POST /api/v1/kling/text_to_video
Base URL
https://runapi.ai
API 버전
v1
인증
Authorization: Bearer YOUR_API_TOKEN
02

지원 모델

현재 가격, 속도 제한 및 상업적 이용 세부 정보는 모델 페이지를 여십시오.

03

요청 스키마

JSON 본문

필드와 허용 값은 선택된 모델에 따라 다릅니다. 제공된 경우 callback_url은 아래에 문서화된 Task 전달을 수신합니다.

kling-3.0필드 15개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

cfg_scalenumber
선택

가이던스 스케일 (0-1).

duration_secondsinteger
선택

기간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
enable_soundboolean
선택

사운드 생성을 활성화합니다.

기본값: false
first_frame_image_urlstring
선택

첫 번째 프레임 이미지 URL.

kling_elementsarray
선택

이미지, 비디오 또는 오디오 자료가 포함된 요소 참조.

last_frame_image_urlstring
선택

단일 샷 모드의 마지막 프레임 이미지 URL.

modelstring
필수

모델 슬러그.

multi_promptarray
선택

사용자 지정 다중 샷 모드에서 필수: 1–6개 샷, 비어 있지 않은 각 프롬프트는 500자 이하(각 @element 참조는 37자로 계산), 각 duration_seconds는 1–12이며 합계는 duration_seconds와 같아야 합니다.

multi_shotsboolean
선택

멀티 샷 생성을 활성화합니다.

negative_promptstring
선택

네거티브 프롬프트.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p, 4k 기본값: 1080p
promptstring
선택

동영상 설명. 단일 샷과 자동 스토리보드에서 필수입니다.

shot_typestring
선택

다중 샷 스토리보드 방식: custom 또는 automatic. multi_shots가 true일 때만 custom이 기본값입니다.

허용 값: custom, automatic
kling-o1필드 11개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

기간(초).

허용 값: 5 기본값: 5
enable_soundboolean
선택

사운드 생성은 비활성 상태로 유지해야 합니다.

기본값: false
modestring
선택

생성 모드.

허용 값: std, pro 기본값: std
modelstring
필수

모델 슬러그.

preserve_reference_video_audioboolean
선택

참조 비디오의 원본 오디오를 보존합니다.

기본값: false
promptstring
필수

비디오 설명; 번호가 매겨진 마커로 참조 미디어를 지정하세요.

범위: 1 - 2500
reference_image_urlsarray
선택

순서 있는 공개 HTTP(S) JPG, JPEG 또는 PNG 참조 이미지 URL.

항목 범위: 1 - 7
reference_video_typestring
선택

비디오를 기본 편집 또는 기능 참조로 사용하세요.

허용 값: base, feature 기본값: base
reference_video_urlstring
선택

공개 HTTP(S) MP4 또는 MOV 참조 비디오 URL.

kling-v2.1-master-text-to-video필드 8개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

cfg_scalenumber
선택

가이던스 스케일 (0-1).

duration_secondsinteger
선택

기간(초).

허용 값: 5, 10 기본값: 5
enable_soundboolean
선택

사운드 생성을 활성화합니다.

modelstring
필수

모델 슬러그.

negative_promptstring
선택

네거티브 프롬프트.

promptstring
선택

비디오 설명.

kling-v2.5-turbo-text-to-video-pro필드 8개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

cfg_scalenumber
선택

가이던스 스케일 (0-1).

duration_secondsinteger
선택

기간(초).

허용 값: 5, 10 기본값: 5
enable_soundboolean
선택

사운드 생성을 활성화합니다.

modelstring
필수

모델 슬러그.

negative_promptstring
선택

네거티브 프롬프트.

promptstring
선택

비디오 설명.

kling-v2.6필드 7개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

기간(초).

허용 값: 5, 10 기본값: 5
enable_soundboolean
선택

사운드 생성을 활성화합니다. pro 모드가 필요합니다.

기본값: false
modestring
선택

생성 모드.

허용 값: std, pro 기본값: std
modelstring
필수

모델 슬러그.

promptstring
필수

비디오 설명.

범위: 1 - 2500
kling-v3-omni필드 7개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

기간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
enable_soundboolean
선택

동기화된 사운드 생성을 활성화합니다.

기본값: false
modelstring
필수

모델 슬러그.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p, 4k 기본값: 720p
promptstring
필수

비디오 설명.

범위: 1 - 2500
kling-v3-omni-reference필드 8개
aspect_ratiostring
필수

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

출력 지속 시간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
enable_soundboolean
선택

동기화된 사운드 생성을 활성화합니다.

기본값: false
modelstring
필수

모델 슬러그.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p, 4k 기본값: 720p
promptstring
필수

비디오 설명.

범위: 1 - 2500
reference_image_urlsarray
필수

순서 있는 참조 이미지 URL.

항목 범위: 1 - 7
kling-v3-turbo-text-to-video필드 6개
aspect_ratiostring
선택

출력 화면 비율.

허용 값: 16:9, 9:16, 1:1 기본값: 16:9
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

기간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
modelstring
필수

모델 슬러그.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p 기본값: 720p
promptstring
필수

비디오 설명.

범위: 1 - 2500

조건부 규칙

이 요구 사항은 나열된 모든 조건이 일치할 때 적용됩니다.

  1. 다음의 경우 model = kling-3.0
    필수
    허용되지 않음
    reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
  2. 다음의 경우 model = kling-o1
    필수
    허용되지 않음
    output_resolution, negative_prompt, cfg_scale, multi_shots, multi_prompt, first_frame_image_url, last_frame_image_url, kling_elements
  3. 다음의 경우 model = kling-v2.1-master-text-to-video
    필수
    허용되지 않음
    mode, reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
  4. 다음의 경우 model = kling-v2.5-turbo-text-to-video-pro
    필수
    허용되지 않음
    mode, reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
  5. 다음의 경우 model = kling-v2.6
    필수
    허용되지 않음
    output_resolution, negative_prompt, cfg_scale, multi_shots, multi_prompt, first_frame_image_url, last_frame_image_url, kling_elements, reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
  6. 다음의 경우 mode = std, model = kling-v2.6
    필수
    허용되지 않음
  7. 다음의 경우 mode absent, model = kling-v2.6
    필수
    허용되지 않음
  8. 다음의 경우 model = kling-v3-omni
    필수
    허용되지 않음
    negative_prompt, cfg_scale, multi_shots, multi_prompt, first_frame_image_url, last_frame_image_url, kling_elements, reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
  9. 다음의 경우 model = kling-v3-turbo-text-to-video
    필수
    허용되지 않음
    enable_sound, negative_prompt, cfg_scale, multi_shots, multi_prompt, first_frame_image_url, last_frame_image_url, kling_elements, reference_image_urls, reference_video_url, reference_video_type, preserve_reference_video_audio
04

수락 만들기

HTTP 202

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

폴링 처리 중

HTTP 200

GET /api/v1/kling/text_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

폴링 완료

HTTP 200

GET /api/v1/kling/text_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

폴링 실패

HTTP 200

GET /api/v1/kling/text_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

고객 콜백: 완료됨

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

고객 콜백: 실패함

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

오류

HTTP 401

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
11

오류

HTTP 401

GET /api/v1/kling/text_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
12

오류

HTTP 400

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 오류 메시지.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 유효성 검사 요약입니다.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "공개 요청 필드를 키로 하는 유효성 검사 메시지로, 각 필드에 대해 사람이 읽을 수 있는 문자열 배열이 포함됩니다.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

응답 예시

JSON 
{
  "error": "model must be one of: kling-3.0, kling-o1, kling-v2.1-master-text-to-video, kling-v2.5-turbo-text-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-omni-reference, kling-v3-turbo-text-to-video"
}
13

오류

HTTP 402

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Insufficient balance"
}
14

오류

HTTP 429

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "API key credit limit exceeded"
}
15

오류

HTTP 409

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

오류

HTTP 429

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

오류

HTTP 503

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

오류

HTTP 504

POST /api/v1/kling/text_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request timed out"
}
19

오류

HTTP 404

GET /api/v1/kling/text_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

생성된 코드 샘플

cURL을 직접 사용하거나 해당 언어의 SDK를 설치하세요. 각 샘플은 이 레퍼런스에 표시된 유효성 검사된 요청을 제출합니다.

설치

Shell 
pip install runapi-kling
PYTHON 
import os
from runapi.kling import KlingClient

client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_video.create(
  model="kling-v3-turbo-text-to-video",
  prompt="A paper kite flying above a quiet coastal town at sunrise",
  duration_seconds=5,
  aspect_ratio="16:9",
  output_resolution="720p"
)