Kling 3.0 API 사용법: 키, 요청, 폴링, 프레임, 멀티샷
Kling 3.0 API 단계별 사용법: 키 만들기, 동영상 작업 보내기, 동영상 URL 폴링, 첫 프레임과 마지막 프레임으로 시작하기, 멀티샷 클립 만들기.
Markdown으로 읽기Kling 3.0 API를 쓰려면 API 키를 만들고, 모델 ID kling-3-0과 프롬프트가 담긴 JSON 본문 하나를 POST한 뒤, 반환된 작업을 동영상 URL이 준비될 때까지 폴링하면 됩니다. 엔드포인트 하나로 텍스트로 동영상 생성, 첫 프레임과 마지막 프레임 동영상, 멀티샷 클립, 엘리먼트 참조를 모두 처리하며, 어떤 방식이 될지는 본문의 필드가 정합니다.
이 가이드는 동작하는 코드와 함께 각 단계를 설명한 뒤, 프레임, 멀티샷 클립, 엘리먼트, 그리고 과금 전에 거부되는 요청을 다룹니다.
첫 요청 전에 무엇이 필요한가요?
- API 키. API 키 페이지에서 만들고 서버에 보관하세요. 브라우저 코드에는 절대 넣지 마세요.
- 크레딧. 결제 페이지에서 잔액을 충전하세요. 크레딧은 만료되지 않으며, 실패한 작업은 과금되지 않습니다.
- 모델 ID
kling-3-0.
export SEEDROUTER_API_KEY="your-key"Kling 3.0 요청은 어떻게 보내나요?
작업을 /v1/videos/generations에 POST하세요:
curl https://api.seedrouter.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3-0",
"prompt": "A red paper boat drifting on a calm pond at sunrise, soft mist on the water, slow push-in, no text, no logos.",
"mode": "std",
"duration": 5,
"aspect_ratio": "16:9"
}'응답은 동영상이 아니라 작업입니다:
{"id": "task_...", "model": "kling-3-0", "status": "processing", "created_at": 1789689600}model과 prompt를 제외한 모든 필드에는 기본값이 있습니다:
| 필드 | 기본값 | 값 |
|---|---|---|
mode | pro | std(720p), pro(1080p), 4K |
duration | 5 | 3~15초 |
aspect_ratio | 16:9 | 16:9, 9:16, 1:1 |
sound | false | true이면 네이티브 오디오를 생성 |
스키마는 엄격합니다. 알 수 없는 필드는 작업이 생성되기 전에 HTTP 400으로 거부되므로, 오타 때문에 설정이 조용히 무시된 채 유료 클립이 만들어지는 일은 없습니다.
동영상은 어떻게 받나요?
status가 completed 또는 failed가 될 때까지 10~20초마다 GET /v1/tasks/{id}를 폴링하세요. 테스트에서 3초 std 클립은 약 2분, 사운드가 있는 5초 pro 클립은 약 2분 반 만에 끝났습니다.
import os
import time
import requests
API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
task = requests.post(
f"{API}/videos/generations",
headers=HEADERS,
json={
"model": "kling-3-0",
"prompt": "A red paper boat drifting on a calm pond at sunrise, slow push-in, no text, no logos.",
"mode": "std",
"duration": 5,
},
timeout=60,
)
task.raise_for_status()
task_id = task.json()["id"]
while True:
result = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=60).json()
if result["status"] in ("completed", "failed"):
break
time.sleep(15)
if result["status"] == "completed":
print(result["output"]["video_url"])
else:
print(result["error"])완료된 작업은 다음과 같습니다:
{
"id": "task_...",
"model": "kling-3-0",
"status": "completed",
"output": {"video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4"}
}std는 1280 × 720, pro는 1920 × 1080으로 반환되었고 둘 다 MP4(H.264)입니다. sound를 켜면 파일에 스테레오 오디오 트랙이 담깁니다. 호스팅된 링크는 영구적이지 않으니 파일을 자체 스토리지에 다운로드하세요. 폴링 중 네트워크 타임아웃이 났다고 생성이 실패한 것은 아니므로, 새 작업을 제출하지 말고 작업 ID를 보관해 다시 확인하세요.
첫 프레임과 마지막 프레임으로 시작하려면?
image_urls에 이미지 URL을 한두 개 넣으세요. 첫 번째 이미지로 클립이 시작되고, 두 번째 이미지에서 끝납니다. 이미지가 없으면 프롬프트만으로 클립을 만듭니다.
{
"model": "kling-3-0",
"prompt": "The camera glides from the empty street to the lit shop window",
"image_urls": ["https://example.com/start.png", "https://example.com/end.png"],
"mode": "pro",
"duration": 6
}이미지는 공개 HTTP(S) URL이어야 하며 JPG 또는 PNG여야 합니다. Base64 데이터는 거부되니 먼저 파일을 자체 스토리지에 업로드하세요.
멀티샷 클립은 어떻게 만드나요?
multi_shots를 true로 설정하고 multi_prompt에 각 샷을 설명하세요. 샷은 최대 5개, 각 112초입니다. 샷 길이를 모두 더하면 315초여야 하며, 그 합계가 과금되는 클립 길이입니다. duration은 사용되지 않습니다.
{
"model": "kling-3-0",
"mode": "pro",
"sound": true,
"multi_shots": true,
"multi_prompt": [
{"prompt": "Wide shot of a small open kitchen, a chef tosses vegetables in a wok, flames rising, warm light.", "duration": 3},
{"prompt": "Close-up of the wok, vegetables flipping through the flames, oil sizzling, steam drifting.", "duration": 3}
]
}테스트에서 이 요청으로 만들어진 클립입니다. 와이드 샷에서 클로즈업으로 전환되는 6초 동영상 하나입니다:
Kling 3.0, pro(1080p), 멀티샷 3 + 3초, 사운드 포함.
인물이나 제품을 일관되게 유지하려면?
kling_elements에 추가하세요. name, 짧은 description, 피사체 이미지 URL 2~4개를 넣으며, 요청당 엘리먼트는 최대 3개입니다. 프롬프트에서 엘리먼트를 이름으로 언급하세요.
{
"model": "kling-3-0",
"prompt": "@hero slowly turns toward the camera in soft window light",
"kling_elements": [
{
"name": "hero",
"description": "a young woman with short black hair and a yellow raincoat",
"element_input_urls": ["https://example.com/hero-front.png", "https://example.com/hero-side.png"]
}
]
}과금 전에 거부되는 요청은 무엇인가요?
다음 요청은 제출 시점에 HTTP 400으로 반환되며, 작업이 생성되지 않고 과금도 되지 않습니다:
| 요청 | 이유 |
|---|---|
| 샷 길이의 합이 3초 미만이거나 15초를 넘는 멀티샷 클립 | Kling 3.0은 3~15초 클립을 만듭니다 |
description이 없는 엘리먼트 | 모든 엘리먼트에 필요합니다 |
image_urls 2개 초과, 샷 5개 초과, 엘리먼트 3개 초과 | 모델의 제한을 벗어납니다 |
소문자로 쓴 mode: "4k" | 값은 4K입니다 |
| Base64 이미지, 또는 위 표에 없는 필드 | 미디어는 URL로 넣으며, 스키마는 엄격합니다 |
접수된 뒤 실패한 작업(예: 모델의 콘텐츠 정책에 걸린 경우)은 error 코드와 함께 status: "failed"를 반환하며 과금되지 않습니다. 코드 목록은 오류 카탈로그에 있습니다.
Kling 자체 API와는 무엇이 다른가요?
Kling의 개발자 API는 자체 필드 이름을 쓰며, 레거시 버전과 현재 버전도 서로 다릅니다.[1][2] 연동을 옮기는 중이라면 필드를 다음과 같이 매핑하세요:
| SeedRouter | Kling 레거시 API |
|---|---|
model: "kling-3-0" | model_name: "kling-v3" |
sound: true / false | sound: "on" / "off" |
duration: 5(정수) | duration: "5"(문자열) |
mode: "4K" | mode: "4k" |
image_urls: [first, last] | image와 image_tail |
multi_shots + multi_prompt: [{prompt, duration}] | multi_shot + shot_type: "customize" + multi_prompt: [{index, prompt, duration}] |
kling_elements: [{name, description, element_input_urls}] | 미리 만들어 둔 element_list: [{element_id}] |
SeedRouter는 결과를 폴링하는 작업으로 전달하며, callback_url은 제공하지 않습니다.
코딩 에이전트가 대신 실행할 수 있나요?
네. Kling 3.0 페이지에는 Claude Code, Codex 또는 Cursor용 프롬프트가 준비되어 있습니다. 이 프롬프트는 환경 변수에서 키를 읽고, 요청과 그 비용을 보여 준 뒤 승인을 기다렸다가, 제출하고 폴링해 클립을 다운로드합니다. 같은 페이지의 Playground는 코드가 보낼 본문과 똑같은 본문을 보냅니다.
Kling 3.0 API 관련 질문
Kling 3.0 공식 API가 있나요?
네. Kling은 자체 키, 유닛 기반 과금, 요청 형식을 갖춘 개발자 API를 공개하고 있습니다.[1][3] SeedRouter는 다른 모델과 공유하는 키 하나, 잔액 하나로 Kling 3.0을 호출하는 별도의 방법입니다.
Kling 3.0 API 가격은 얼마인가요?
동영상 초 단위로, 모드와 사운드 사용 여부에 따라 과금됩니다. 클립별 비용은 Kling 3.0 API 가격 가이드에서 계산해 두었고, 현재 요율은 모델 페이지에서 볼 수 있습니다.
작업을 취소할 수 있나요?
아니요. 접수된 작업은 완료되거나 실패할 때까지 실행됩니다. 실패한 작업은 과금되지 않습니다.



