Kling 3.0 Omni API 심층 분석: 멀티샷 비디오 생성과 물리 일관성
대상 모델:
kling-v3-omni
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: Kling 3.0 Turbo 자동화 가이드 · Kling V4 Flash API 가이드 · kling-v3-omni 레퍼런스 · kling-v3-omni 모델 가이드
1. 핵심 요약 및 개요 (TL;DR)
- 카탈로그부터: 기획 초안은 가끔
kling-3-omni라고 씁니다. 그 문자열은 문서화된 공개 ID가 아닙니다. 2026-11-18에 공식 생성 레퍼런스와 모델 가이드 페이지(HTTP 200)를 확인한 결과, 고정model값은 **kling-v3-omni**입니다. 이 정확한 문자열을 보내세요. - 계약:
POST /v1/videos/generations에 비동기로 제출한 뒤GET /v1/videos/generations/{id}를completed또는failed까지 폴링합니다. 일반 작업은GET /v1/tasks/{id}로도 조회할 수 있습니다. 공식 예시는https://toapis.com(중국 본토는https://toapis.cn)입니다. 이 시리즈의 다른 가이드는https://api.toapis.com을 사용합니다. 오리진은 하나만 골라 일관되게 쓰세요. shots[]필드 없음: 멀티샷 연속성과 물리 일관성은 프롬프트와 참조 자산의 문제입니다. 공식 플레이스홀더<<<image_N>>>,<<<video_N>>>,<<<element_N>>>를metadata.image_list,video_list,metadata.element_list와 함께 사용하세요. 리스트 순서는 플레이스홀더 순서와 같아야 하며, 시스템은 플레이스홀더를 자동 삽입하거나 첫 프레임을 자동 추가하지 않습니다.- 미디어: 공개
http://또는https://URL만 보내세요. 로컬 파일은POST /v1/uploads/images로 업로드하고 반환된 URL을 사용하세요. base64는 보내지 마세요.audio와video_list는 상호 배타적입니다. - 버려야 할 미검증 주장:
$0.022/s같은 초안 단가, 99.95% SLA, 사용자 정의shots스키마는 현재 ToAPIs 문서가 아닙니다. 실시간 요율과 채널 지원은 계정에서 확인하세요.
2. 공식 Omni ID, 플레이스홀더, 일관성 워크플로
model 필드에는 공개 모델 이름을 사용하세요. 초안 별칭, URL 슬러그, 관련되지만 다른 카탈로그 ID로 바꾸지 마세요.
| 카탈로그 ID | 이 가이드에서의 역할 | 문서화된 작업 |
|---|---|---|
kling-v3-omni | 이 글의 핵심 ID | 텍스트-비디오와 공식 Omni 참조: image_list, video_list, element_list |
kling-3.0-turbo | 자매 숏폼 ID. Turbo 가이드 참고 | 텍스트-비디오와 첫 프레임 이미지-비디오만. Omni 참조 계약이 아님 |
kling-v3 | 관련 비 Omni v3 ID | 별도의 생성 레퍼런스입니다. 해당 문서가 말하지 않는 한 이 ID에 Omni 리스트나 플레이스홀더를 보내지 마세요 |
kling-v3-omni의 핵심 요청 필드:
| 필드 | 문서화된 값 | 참고 |
|---|---|---|
prompt | 필수 문자열 | 1부터 시작하는 플레이스홀더로 자산을 참조 |
mode | std(기본값) 또는 pro | std는 720P, pro는 1080P이며 같은 플래그가 과금 해상도를 결정 |
duration | 정수 3–15(기본값 5) | 5초 또는 10초로 제한되지 않음 |
aspect_ratio | 흔한 값 16:9(기본값), 9:16, 1:1 | 마케팅 매개변수 표가 더 짧으면 생성 레퍼런스를 우선 |
audio | 불리언, 기본값 false | true는 Sound로 과금되며 video_list와 함께 쓸 수 없음 |
video_list | 최대 1개 | Video로 과금. refer_type: base 또는 feature. keep_original_sound: yes 또는 no |
metadata.image_list | 공개 image_url | 선택 type은 first_frame 또는 end_frame. end_frame에는 first_frame이 필요 |
metadata.element_list | 주체 또는 역할 자산 | url과 선택적 type(예: image 또는 video), role |
watermark | 불리언 | 켜기/끄기만 |
client_business_id | 선택 문자열 | 중국어 Omni 레퍼런스에서 최상위 필드로 문서화됨(metadata에도 가능, 최상위 권장). 이후 GET /v1/videos/generations/{client_business_id}로 조회 가능 |
플레이스홀더 문법은 1부터 시작하며 리스트 순서와 맞춰야 합니다.
| 문법 | 참조 대상 |
|---|---|
<<<image_1>>> | metadata.image_list의 첫 항목 |
<<<video_1>>> | video_list의 첫 항목(중국어 레퍼런스 기준으로는 유일한 항목) |
<<<element_1>>> | metadata.element_list의 첫 항목 |
영어 생성 페이지는 리스트 문법으로 <<<video_2>>>를 예시합니다. 중국어 레퍼런스는 video_list를 1개로 제한합니다. 계정 레퍼런스가 나중에 달리 말하지 않는 한 두 번째 참조 비디오는 보내지 마세요.
문서화된 필드만으로도 멀티샷과 물리적으로 더 일관된 클립을 만들 수 있습니다.
- 첫·끝 프레임으로 구간을 고정하세요. 시작 스틸을
image_list에type: "first_frame"으로 넣고, 종료 스틸을type: "end_frame"으로 넣습니다. 프롬프트에서 둘 다 언급하고(<<<image_1>>>에서<<<image_2>>>로 전환) 그 사이의 움직임, 중력, 카메라 경로를 적으세요. element_list로 정체성을 고정하세요. 관련 작업에서 같은 주체 URL과 안정적인role(예:"subject")을 재사용해 카메라 설명만 바꿀 때 의상, 얼굴, 비율이 흔들리지 않게 합니다.refer_type: "feature"로 움직임을 빌리세요.<<<video_1>>>를 공개 모션 참조로 가리키고<<<element_1>>>가 그 움직임을 따르게 합니다. 원본 클립 자체를 편집할 때(배경 교체 등)는refer_type: "base"를 사용합니다.- 작업을 명시적으로 연결하세요. 상태 문서는 Omni 전용 마지막 프레임 API가 아닙니다. 다음 샷이 이전 테이크에서 시작해야 한다면 해당 테이크의 공개 스틸이나 다운로드를 호스팅해 다음
first_frame으로 보내세요. 각 작업 id는 저장해 두세요.

그림 1: 공개 URL만 담긴 image_list, video_list, element_list를 POST /v1/videos/generations에 제출하고, 같은 작업 id를 폴링한 뒤 status가 completed일 때만 result.data[0].url을 읽습니다.
Omni 리스트가 필요 없는 고빈도 숏폼 초안은 kling-3.0-turbo를 사용하세요. 다른 Kling 생성 계약은 Kling V4 Flash 가이드를 참고하세요.
3. 프로덕션 구현: cURL과 Python
이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn을 안내합니다. 환경마다 오리진은 하나만 고정하세요. 경로, 모델 ID, Bearer 헤더는 같습니다.
1단계: 첫·끝 프레임 작업을 cURL로 제출
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
"mode": "std",
"duration": 5,
"aspect_ratio": "16:9",
"metadata": {
"image_list": [
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"}
]
}
}'
텍스트 전용 작업은 metadata와 플레이스홀더를 생략합니다. 주체와 모션 참조 작업은 refer_type: "feature"인 video_list와 metadata.element_list를 사용하고 audio: true를 설정하지 마세요.
2단계: Python 헬퍼와 폴러
아래 스니펫은 문서화된 작업 상태 경로와 queued / in_progress / completed / failed 상태를 따릅니다. 배포 전에 계정 API 레퍼런스에서 id, result.data[0].url, 응답 엔벨로프를 확인하세요.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_ID = "kling-v3-omni"
DURATION_RANGE = range(3, 16)
def dispatch_omni(
prompt: str,
*,
model: str = DOCUMENTED_ID,
mode: str = "std",
duration: int = 5,
aspect_ratio: str = "16:9",
audio: bool = False,
image_list: list[dict] | None = None,
element_list: list[dict] | None = None,
video_list: list[dict] | None = None,
client_business_id: str | None = None,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-v3-omni; kling-3-omni is not a documented public ID")
if mode not in {"std", "pro"}:
raise ValueError("mode must be std or pro")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
if audio and video_list:
raise ValueError("audio and video_list are mutually exclusive")
if video_list and len(video_list) > 1:
raise ValueError("video_list is documented as at most one clip")
types = [item.get("type") for item in (image_list or [])]
if "end_frame" in types and "first_frame" not in types:
raise ValueError("end_frame requires first_frame")
payload = {
"model": model,
"prompt": prompt,
"mode": mode,
"duration": duration,
"aspect_ratio": aspect_ratio,
}
if audio:
payload["audio"] = True
if video_list:
payload["video_list"] = video_list
metadata = {}
if image_list:
metadata["image_list"] = image_list
if element_list:
metadata["element_list"] = element_list
if metadata:
payload["metadata"] = metadata
if client_business_id:
payload["client_business_id"] = client_business_id
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_omni(
"Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
image_list=[
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"},
],
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
프롬프트 템플릿 버전을 작업 기록 옆에 저장해 플레이스홀더나 리스트 순서 변경과 문구 변경을 구분하세요. expires_at 전에 파일을 다운로드하세요. 상태 레퍼런스는 30일 보관 기간을 문서화합니다.
4. 오류 처리 및 상태 매트릭스
아래 범주는 진단 출발점이며 ToAPIs의 정확한 오류 코드를 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 요청 오류와 status: failed 이유(content_policy_rejected, insufficient_user_balance, generation_timeout 등)는 오류 레퍼런스를 보세요.
| HTTP 또는 작업 상태 | 흔한 범주 | 권장 조치 |
|---|---|---|
400 | 잘못된 필드, 플레이스홀더/리스트 불일치, audio와 video_list 동시 사용, first_frame 없는 end_frame | kling-v3-omni인지, 플레이스홀더 순서가 각 리스트와 맞는지, 미디어가 공개 URL인지, 상호 배타 필드를 함께 쓰지 않았는지 확인 |
401 | 없거나 잘못된 API 키 | ToAPIs 대시보드에서 키를 교체하고 Authorization: Bearer 헤더를 확인 |
429 | 속도 또는 동시성 제한 | Retry-After가 있으면 따르고, 지터와 함께 백오프하며, 안전할 때만 재시도 |
5xx 또는 클라이언트 시간 초과 | 게이트웨이 또는 업스트림의 일시 문제 | 다시 제출하기 전에 기존 작업 id를 조회 |
status: queued 또는 in_progress | 오류가 아님 | 기다렸다가 다시 폴링하고 두 번째 작업을 만들지 말 것 |
status: failed | 생성이 성공하지 않음 | error.code와 error.message(있으면 error.reason)를 읽고, 수정하지 않은 정책 거부 페이로드를 재시도하지 말 것 |
5. 요금과 FinOps ROI
공식 중국어 Omni 레퍼런스는 과금 맵을 공개합니다. 먼저 SKU 계열을 고른 뒤 계정이 실제로 제시하는 금액을 읽으세요.
| 요청 형태 | 과금 규격 |
|---|---|
mode=std, audio=false, video_list 없음 | 720P |
mode=pro, audio=false, video_list 없음 | 1080P |
mode=std, audio=true | 720P+Sound |
mode=pro, audio=true | 1080P+Sound |
mode=std, video_list 있음 | 720P+Video |
mode=pro, video_list 있음 | 1080P+Video |
2026-11-18에 가져온 kling-v3-omni 모델 가이드는 가격 참고값으로 12 크레딧 / 초를 보여 주며, 최종 청구는 현재 계정 견적을 따른다고 명시했습니다. 해당 페이지는 Omni의 초당 달러 요율을 공개하지 않았고 Sound나 Video를 별도 달러 수치로 나누지도 않았습니다. 크레딧을 직접 통화로 환산하지 말고, 기획 초안의 $0.022/s 같은 요율도 재사용하지 마세요.
- 문서화된 더 저렴한 모드로 먼저 초안을 만드세요.
std(720P)와 5초 정도의 중간 duration으로 반복하고, 버전 관리된 프롬프트 템플릿을 유지하며, 참조 리스트는 한 번에 하나만 바꾸세요. - 표시 가격은 채널 보장이 아닙니다. 샷 리스트를 예측하기 전에
GET /v1/models?type=video와 계정의 실시간 견적으로 ID, SKU, 가용성을 확인하세요. - 프롬프트 계층에서 지출을 통제하세요. 클라이언트가 시간 초과해도 상태를 확인하기 전에 다시 제출하지 마세요. 공식 벤더 계약은 약정이나 선불 하한을 두는 경우가 많고, ToAPIs 과금은 보통 사용량 기준입니다. 유효 조건은 계정에서 확인하세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: kling-v3-omni를 보내고 kling-3-omni는 보내지 마세요. 문서화된 shots[]는 없습니다. duration은 3–15초이고 mode가 720P 또는 1080P를 선택합니다. audio와 video_list는 함께 쓸 수 없습니다. generations 상태 경로를 폴링하고 작업 id를 저장하세요.
7. 액션 체크리스트
- ToAPIs 개발자 포털에서 키를 만드세요.
-
GET /v1/models?type=video로 키에kling-v3-omni가 보이는지 확인하세요.kling-3-omni는 보내지 마세요. - 첫·끝 프레임
image_list,mode: "std",duration: 5로 위 cURL을 스모크 테스트하세요. - 제한된 기한 안에
GET /v1/videos/generations/{id}를 폴링하고expires_at전에 결과를 다운로드하세요. - 다음: 고빈도 숏폼 초안은 Kling 3.0 Turbo 자동화 가이드, 실시간 카탈로그는 kling-v3-omni 모델 가이드, 다른 Kling 계약은 Kling V4 Flash 가이드.







