Kling 3.0 Turbo API: 대량 숏폼 비디오 자동화 아키텍처
대상 모델:
kling-3.0-turbo
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: Kling 3.0 Omni 심층 분석 · Kling V4 Flash API 가이드 · kling-3.0-turbo 레퍼런스 · kling-3.0-turbo 모델 가이드
1. 핵심 요약 및 개요 (TL;DR)
- 카탈로그부터: 기획 초안은 가끔
kling-3-turbo라고 씁니다. 그 문자열은 문서화된 공개 ID가 아닙니다. 2026-11-18에 공식 생성 레퍼런스와 모델 가이드 페이지(HTTP 200)를 확인한 결과, 고정model값은 **kling-3.0-turbo**입니다. 이 정확한 문자열을 보내세요. - 계약:
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을 사용합니다. 오리진은 하나만 골라 일관되게 쓰세요. - 문서화된 범위:
duration은 3–15초의 임의의 정수(기본값5)이며 5초와 10초만이 아닙니다.resolution은720p또는1080p(기본값720p)입니다.aspect_ratio(16:9,9:16,1:1)는 텍스트-비디오 요청에만 적용됩니다. - 이미지 입력은 첫 프레임만 지원됩니다.
reference_images를 보내면 첫 공개 URL만first_frame으로 사용됩니다. 이 연동은 끝 프레임을 지원하지 않으며 추가 이미지는 무시됩니다. base64는 보내지 마세요. - 버려야 할 미검증 주장: 5초 클립당
$0.11, "20초 미만" 지연, "30+ 동시성", 99.95% SLA, "60% 저렴" 같은 초안 숫자는 현재 API 문서가 아닙니다. 실시간 카탈로그나 모델 가이드 숫자만 인용하고, 바뀔 수 있는 표시 요율로 다루세요.
2. 공식 Turbo ID와 대량 처리 제약
model 필드에는 공개 모델 이름을 사용하세요. 초안 별칭, 마케팅 표시 이름, 관련 Omni ID로 바꾸지 마세요.
| 카탈로그 ID | 이 가이드에서의 역할 | 문서화된 작업 |
|---|---|---|
kling-3.0-turbo | 이 글의 핵심 ID | 텍스트-비디오와 첫 프레임 입력만 지원하는 이미지-비디오 |
kling-v3-omni | 자매 Omni ID. Omni 가이드 참고 | 공식 image_list / video_list / element_list 참조(첫·끝 프레임 포함) |
kling-v3 | 관련 비 Omni v3 ID | 별도의 생성 레퍼런스입니다. Turbo 필드가 그대로 적용된다고 가정하지 마세요 |
공식 Turbo 생성 페이지는 일부 마케팅 문구보다 범위가 좁습니다. 모델 가이드의 일반 설명은 추가 비디오 워크플로를 언급할 수 있지만, 이 ID의 API 레퍼런스가 문서화한 것은 텍스트-비디오와 첫 프레임 이미지-비디오뿐입니다. 자동화는 브로슈어가 아니라 레퍼런스에 맞추세요.
| 필드 | 문서화된 값 | 참고 |
|---|---|---|
prompt | 필수 문자열 | 이미지-비디오에서는 Turbo의 prompt 내용으로 전달 |
reference_images | 선택 문자열 배열 | 첫 이미지만 first_frame으로 사용되고 나머지는 무시 |
resolution | 720p(기본값), 1080p | Omni의 mode=std/pro 플래그가 아님 |
duration | 정수 3–15(기본값 5) | 5초와 10초만 나열한 초안은 불완전 |
aspect_ratio | 16:9(기본값), 9:16, 1:1 | 텍스트-비디오에만 적용 |
watermark | 불리언, 기본값 false | 공식 Kling 워터마크 켜기/끄기만. 사용자 정의 워터마크 객체는 불가 |
고빈도 숏폼 자동화는 이 계약 위의 오케스트레이션 문제입니다.
- 클립 하나, 작업 하나. 각 변형을 별도의 비동기 작업으로 제출하세요. 폴링을 시작하기 전에 작업 id(와 자신의 요청 id)를 저장하세요.
- 모든 대기에 한도를 두세요. 기한, 최소 5–10초와 지터가 있는 간격,
429시의Retry-After를 사용하세요. 상태 레퍼런스는 긴 비디오가 몇 분 걸릴 수 있다고 적습니다. 같은 id를 다시 조회하기 전에는 클라이언트 시간 초과를 실패로 보지 마세요. - 동시성 SLA를 만들어 내지 마세요. 공식 문서는 이 모델에 예약된 "30+ 동시" 할당량을 공개하지 않습니다.
429응답과 비동기 작업 속도 제한을 보세요. 배치 상태 조회는 작업 ID를 최대 100개까지 받습니다. - 이미지 작업을 정직하게 유지하세요. 컷에 끝 프레임, Omni 리스트, 모션 참조 비디오가 필요하면
reference_images에 의미를 과하게 싣지 말고kling-v3-omni로 전환하세요.

그림 1: 각 숏폼 변형을 POST /v1/videos/generations에 제출하고, 제한된 루프로 같은 작업 id를 폴링한 뒤 status가 completed일 때만 result.data[0].url을 읽습니다.
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-3.0-turbo",
"prompt": "A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9",
"watermark": false
}'
이미지-비디오 작업은 "reference_images": ["https://example.com/first-frame.png"]를 추가하고, aspect_ratio나 두 번째 이미지를 끝 프레임으로 의존하지 마세요.
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-3.0-turbo"
DURATION_RANGE = range(3, 16)
def dispatch_turbo(
prompt: str,
*,
model: str = DOCUMENTED_ID,
resolution: str = "720p",
duration: int = 5,
aspect_ratio: str = "16:9",
reference_images: list[str] | None = None,
watermark: bool = False,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-3.0-turbo; kling-3-turbo is not a documented public ID")
if resolution not in {"720p", "1080p"}:
raise ValueError("resolution must be 720p or 1080p")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
payload = {
"model": model,
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"watermark": watermark,
}
if reference_images:
payload["reference_images"] = reference_images[:1]
else:
payload["aspect_ratio"] = aspect_ratio
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")
def dispatch_batch(prompts: list[str], **kwargs) -> list[str]:
"""Submit every prompt first, then poll. A failed submit must not hide already-issued ids."""
task_ids = []
for prompt in prompts:
task_ids.append(dispatch_turbo(prompt, **kwargs))
return task_ids
if __name__ == "__main__":
variants = [
"A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"The same shoe on a wet evening street, slower tracking shot, warm storefront light",
]
ids = dispatch_batch(variants, resolution="720p", duration=5)
for task_id in ids:
print("Task:", task_id)
print("Video:", poll_task(task_id))
프롬프트 템플릿 버전을 각 작업 기록 옆에 저장해 해상도나 duration 변경과 문구 변경을 구분하세요. 각 파일은 expires_at 전에 다운로드하세요. 상태 레퍼런스는 30일 보관 기간을 문서화합니다.
4. 오류 처리 및 상태 매트릭스
아래 범주는 진단 출발점이며 ToAPIs의 정확한 오류 코드를 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 요청 오류와 status: failed 이유(content_policy_rejected, insufficient_user_balance, generation_timeout 등)는 오류 레퍼런스를 보세요.
| HTTP 또는 작업 상태 | 흔한 범주 | 권장 조치 |
|---|---|---|
400 | 잘못된 필드, 지원되지 않는 duration 또는 resolution, 이 연동이 받지 않는 미디어 유형 | kling-3.0-turbo인지, duration이 3–15인지, resolution이 720p 또는 1080p인지, 이미지가 있다면 공개 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
2026-11-18에 가져온 kling-3.0-turbo 모델 가이드는 다음 표시 비교 요율을 보여 주며, 가격은 바뀔 수 있고 최종 청구는 현재 계정 가격, duration, resolution, 화면비, 제출 매개변수를 따른다고 명시했습니다.
| 규격 | ToAPIs 표시 요율(2026-11-18) | 같은 페이지의 공식 표시 요율 |
|---|---|---|
720p | $0.08 / 초 | $0.1143 / 초 |
1080p | $0.1 / 초 | $0.1429 / 초 |
저장소의 모델 가이드 설정도 같은 ToAPIs 표시 숫자와 720p 초당 16 크레딧, 1080p 초당 20 크레딧 행을 나열합니다. 모두 스냅샷으로 보고 계약으로 보지 마세요. "클립 1000개에 $380" 같은 초안 산술은 재사용하지 마세요.
- 먼저
720p로 초안을 만드세요. duration은 보수적으로 유지하고(문서 기본값은 5초), 프롬프트 템플릿을 버전 관리하며, 한 번에 변수 하나만 바꾸세요. - 표시 가격은 채널 보장이 아닙니다. 배치 비용을 예측하기 전에
GET /v1/models?type=video와 계정의 실시간 견적으로 ID와 가용성을 확인하세요. - 오케스트레이션 계층에서 지출을 통제하세요. 모든 작업 id를 저장하고, 클라이언트 시간 초과 후에는 상태를 확인하기 전에 다시 제출하지 말며,
expires_at전에 결과를 다운로드하세요. 공식 벤더 계약은 약정이나 선불 하한을 두는 경우가 많고, ToAPIs 과금은 보통 사용량 기준입니다. 유효 조건은 계정에서 확인하세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: kling-3.0-turbo를 보내고 kling-3-turbo는 보내지 마세요. duration은 3–15초입니다. 이미지 입력은 첫 프레임만입니다. 문서화된 Turbo 오디오나 Omni 리스트 계약은 없습니다. generations 상태 경로를 폴링하고 모든 작업 id를 저장하며 SLA를 만들어 내지 마세요.
7. 액션 체크리스트
- ToAPIs 개발자 포털에서 키를 만드세요.
-
GET /v1/models?type=video로 키에kling-3.0-turbo가 보이는지 확인하세요.kling-3-turbo는 보내지 마세요. -
resolution: "720p",duration: 5,aspect_ratio: "16:9"로 위 cURL을 스모크 테스트하세요. - 제한된 기한 안에
GET /v1/videos/generations/{id}를 폴링하고expires_at전에 결과를 다운로드하세요. - 다음: 공식 Omni 참조나 끝 프레임이 필요하면 Kling 3.0 Omni 심층 분석, 실시간 카탈로그는 kling-3.0-turbo 모델 가이드, 다른 Kling 계약은 Kling V4 Flash 가이드.







