Kling AI 텍스트-투-비디오은(는) 무엇을 하나요?
개요
텍스트 프롬프트를 사용하여 /v1/videos/text2video 엔드포인트로 비디오를 생성합니다. v1부터 v2.6까지의 모델, 표준/전문가 모드, 카메라 제어, 네거티브 프롬프트, 그리고 네이티브 오디오(v2.6 이상)를 지원합니다.
엔드포인트: POST https://api.klingai.com/v1/videos/text2video
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
model_name | string | 예 | 모델 버전 (모델 카탈로그 참조) |
prompt | string | 예 | 비디오 설명, 최대 2500자 |
negative_prompt | string | 아니오 | 생성에서 제외할 내용 |
duration | string | 예 | "5" 또는 "10" 초 |
aspect_ratio | string | 아니오 | "16:9" (기본값), "9:16", "1:1" 등 |
mode | string | 아니오 | "standard" (기본값) 또는 "professional" |
cfg_scale | float | 아니오 | 프롬프트 준수 정도 (0.0-1.0, 기본값 0.5) |
camera_control | object | 아니오 | 카메라 움직임 설정 |
callback_url | string | 아니오 | 완료 알림을 위한 웹훅 URL |
전체 예제 — Python
import jwt, time, os, requests
BASE = "https://api.klingai.com/v1"
def get_headers():
ak, sk = os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{"iss": ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5},
sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}
)
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# 텍스트-투-비디오 작업 생성
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "황금 시간의 산호초 위를 드론으로 촬영한 항공 샷, "
"맑은 물속을 헤엄치는 열대어, "
"수면을 뚫고 들어오는 태양 광선, 시네마틱 4K",
"negative_prompt": "blurry, low quality, distorted, watermark",
"duration": "5",
"aspect_ratio": "16:9",
"mode": "professional",
"cfg_scale": 0.5,
})
task = response.json()
task_id = task["data"]["task_id"]
# 완료될 때까지 폴링
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/text2video/{task_id}", headers=get_headers()
).json()
status = result["data"]["task_status"]
if status == "succeed":
video = result["data"]["task_result"]["videos"][0]
print(f"비디오 URL: {video['url']}")
print(f"길이: {video['duration']}초")
break
elif status == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
# else: submitted/processing — 계속 폴링
카메라 제어 사용하기
# 카메라 움직임 유형: pan, tilt, zoom, roll
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "일출의 절벽 위 중세 성, 안개 낀 계곡",
"duration": "5",
"mode": "standard",
"camera_control": {
"type": "simple",
"config": {
"horizontal": 5, # 오른쪽으로 패닝 (음수는 왼쪽), 범위 -10 ~ 10
"vertical": 0, # 틸트 (음수는 아래, 양수는 위)
"zoom": 3, # 확대 (양수) 또는 축소 (음수)
"roll": 0, # 회전
"pan": 0, # 좌/우 돌리
"tilt": -2, # 위/아래 돌리
}
},
})
규칙: type: "simple"의 경우 config에서 하나의 필드만 0이 아닌 값을 가질 수 있습니다.
네이티브 오디오 사용하기 (v2.6 전용)
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "어두운 클럽에서 연주하는 재즈 밴드, 색소폰 솔로, "
"박수치는 관객, 따뜻한 호박색 조명",
"duration": "10",
"mode": "professional",
"motion_has_audio": True, # 동기화된 오디오 생성
})
프롬프트 엔지니어링 팁
| 기법 | 예시 |
|---|---|
| 장면 + 동작 + 스타일 | "벚꽃 사이를 걷는 사무라이, 시네마틱 슬로우 모션" |
| 조명 단서 | "황금 시간", "네온 조명", "흐린 확산광" |
| 카메라 언어 | "클로즈업", "와이드 설립 샷", "트래킹 샷" |
| 네거티브 프롬프트 | "blurry, watermark, text overlay, distorted faces" |
| 재질/질감 | "브러시드 스틸", "핸드 페인팅 수채화", "포토리얼리스틱" |
비용 참조
| 길이 | 표준 | 전문가 |
|---|---|---|
| 5초 | 10 크레딧 | 35 크레딧 |
| 10초 | 20 크레딧 | 70 크레딧 |
오류 처리
| 오류 | 원인 | 해결책 |
|---|---|---|
400 잘못된 프롬프트 | 비어 있거나 2500자 초과 | 프롬프트 길이 확인 |
400 잘못된 모델 | 지원되지 않는 model_name | 카탈로그에서 유효한 모델 ID 사용 |
402 크레딧 부족 | 크레딧이 충분하지 않음 | 계정 충전 |
task_status: failed | 콘텐츠 정책 위반 또는 복잡성 | 프롬프트 단순화, 제한된 콘텐츠 제거 |
전제 조건
- 승인된 브리프, 권리가 명확하거나 합성된 참고 자료, 승인된 워크스페이스 및 예산, 콘텐츠 정책 검토, 게시 및 삭제를 위한 명명된 소유자가 필요합니다.
지침
- 승인된 브리프를 바탕으로 샌드박스 초안을 생성합니다. 프롬프트나 업로드에 개인, 보호된 자료 또는 확인되지 않은 주장을 포함하지 마십시오.
- 제출 전에 요청된 길이, 스타일, 대상, 크레딧 예산, 콘텐츠 정책 상태 및 초안 전용 설정을 확인하십시오.
- 정책, 권리 및 품질을 위해 워터마크가 있는 카나리 렌더링 하나를 검토합니다. 정책이나 귀속 문제가 발생하면 중단하고 게시하지 말고 초안을 삭제합니다.
- 소유자 승인 후에만 게시하고 편집된 제작 영수증을 보관합니다. 승인된 보존 기간이 지나면 임시 자산을 제거합니다.
출력
브리프 ID, 승인된 소스 분류, 모드/모드, 길이, 크레딧 예상, 정책 및 권리 검토 결과, 초안 대상, 승인자, 보존/제거 참조 및 작업 ID가 포함된 렌더 영수증을 생성합니다. 프롬프트 텍스트, 신원 및 자격 증명은 제외합니다.
예시
brief=synthetic-product-demo; source=rights-cleared; mode=standard; duration=5s; policy=pass; destination=draft-only; approval=pending; cleanup=24h는 안전한 카나리 요청입니다.