장편 AI 비디오 연속성: Kling Video O1 팁과 워크플로
대상 모델:
kling-video-o1
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: Kling 3.0 Omni 멀티샷 가이드 · Kling 3.0 Turbo 자동화 가이드 · Wan 3.0 Video API 빠른 시작 · Wan 3.0 Prime 대 Wan 2.6 Flash · kling-video-o1 레퍼런스 · kling-video-o1 모델 가이드
1. TL;DR 및 성능 개요
- 먼저 카탈로그를 확인하세요: 기획 초안은 가끔
kling-3-omni라고 씁니다. 이 문자열은 Kling Video O1의 문서화된 공개 ID가 아니며kling-v3-omni를 대신하지도 않습니다. 2026-11-20에 공식 O1 생성 레퍼런스와 모델 가이드(HTTP 200)를 확인한 결과, 고정model값은kling-video-o1이었습니다. - 한 작업이 장편이 아닙니다: 문서화된
duration은 3–10초 정수(기본값5)입니다. 자기회귀 메모리 버퍼,previous_task_id,tail_frame_url, “마지막 8프레임”, “6회 = 30초” 같은 초안 주장은 공개 계약에 없습니다. 더 긴 작품은 문서화된 요청을 연결하고 파일은 직접 이어 붙이세요. - 연속성은 참조 문제입니다: 공식 플레이스홀더
<<<image_N>>>,<<<video_N>>>,<<<element_N>>>를metadata.image_list,video_list,metadata.element_list와 함께 사용하세요. 리스트 순서는 플레이스홀더 순서와 같아야 합니다. 시스템이 플레이스홀더를 자동 삽입하거나 첫 프레임을 자동 추가하지 않습니다. - 계약:
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을 사용합니다. 오리진을 하나 정해 일관되게 쓰세요. - 버려야 할 미검증 주장:
$0.030/s,$0.038/s같은 초안 단가와 SLA·지연 수치는 현재 ToAPIs 문서가 아닙니다. 계정 카탈로그에서 실시간 요금을 확인하세요.
2. 공식 O1 ID와 문서화된 연속성 도구
model 필드에는 공개 모델 이름을 사용하세요. 초안 별칭, URL 슬러그, 관련되지만 다른 카탈로그 ID로 바꾸지 마세요.
| 카탈로그 ID | 이 가이드에서의 역할 | 문서화된 작업 |
|---|---|---|
kling-video-o1 | 이 글의 주 ID | 텍스트-투-비디오와 공식 Omni 참조: image_list, video_list, element_list |
kling-v3-omni | 관련 Omni ID. Day 17 멀티샷 가이드 참고 | 별도의 문서화된 Omni 계약. 플레이스홀더 스타일은 비슷하지만 모델 문자열과 길이 구간이 다름 |
kling-3.0-turbo | 짧은 형식의 자매 ID. Turbo 가이드 참고 | 텍스트-투-비디오와 첫 프레임 이미지-투-비디오만 지원. Omni 참조 계약이 아님 |
kling-video-o1의 핵심 요청 필드:
| 필드 | 문서화된 값 | 참고 |
|---|---|---|
prompt | 필수 문자열 | 1부터 시작하는 플레이스홀더로 자산을 참조 |
mode | std(기본값) 또는 pro | std는 720P, pro는 1080P. 같은 플래그가 과금 해상도도 결정 |
duration | 3–10 정수(기본값 5) | kling-v3-omni(3–15)보다 좁음. 더 짧은 플레이그라운드 미리보기보다 이 생성 레퍼런스를 우선 |
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 | 선택 문자열 | 중국어 O1 레퍼런스에서 최상위 필드로 문서화됨(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개로 제한하고 미디어 규칙을 추가합니다. 공개 MP4 또는 MOV, 최소 3초, 해상도 720px–2160px, 프레임레이트 24–60fps, 크기 최대 200MB입니다. 계정 레퍼런스가 나중에 달리 말하지 않는 한 두 번째 참조 영상을 보내지 마세요.
그 계약 안에 남는 실용적인 장편 워크플로는 다음과 같습니다.
- 3–10초 비트로 스토리보드를 나눕니다. 비트마다 프롬프트 하나를 씁니다. 시작·끝 스틸을
type: "first_frame"과type: "end_frame"으로 고정하고 프롬프트에서도 둘 다 언급하세요(Transition from <<<image_1>>> to <<<image_2>>>). element_list로 정체성을 고정하세요. 관련 작업에서 같은 주체 URL과 안정적인role(예:"subject")을 재사용해 카메라 설명만 바꿀 때 의상, 얼굴, 비율이 흔들리지 않게 합니다.refer_type: "feature"로 동작을 빌리거나refer_type: "base"로 이전 테이크를 편집하세요.<<<video_1>>>을 공개 동작 참조로 두고<<<element_1>>>이 그 동작을 따르게 합니다. 소스 클립 자체를 편집할 때는base를 씁니다.refer_type이base일 때 중국어 레퍼런스는 첫·끝 프레임을 금지하고, 소스는 3–10초이며 출력 길이는 업로드 영상을 따른다고 합니다.audio=true도 함께 켜지 마세요.- 작업을 명시적으로 연결한 뒤 직접 스티칭하세요. 상태 문서는 O1 전용 마지막 프레임 API나 “이 작업을 이어 가기” API가 아닙니다.
completed이후result.data[0].url을 다운로드하고(상태 페이로드에last_frame_url이 있으면 사용), 공개 스틸이나 클립으로 호스팅한 다음 다음 요청의first_frame또는video_url로 보내세요. 파일은 자체 편집기나 ffmpeg 파이프라인에서 이어 붙입니다. 각 작업 id와 버전 있는 프롬프트 템플릿을 저장하세요.

그림 1: 문서화된 O1 작업은 매번 세그먼트 하나를 반환합니다. 완료 결과의 스틸이나 클립을 공개 호스팅하고, 다음 요청에서 첫 프레임 또는 참조 영상으로 보낸 뒤 파일은 직접 이어 붙이세요.
Day 17 모델에서 비슷한 Omni 리스트가 필요하면 kling-v3-omni(길이 3–15초)를 쓰세요. Omni 리스트가 필요 없는 대량 짧은 초안에는 kling-3.0-turbo를 쓰세요. 다른 제품군에서 더 긴 단일 요청 창이 필요하면 Wan 3.0 빠른 시작(문서상 2–30초, 또는 스마트 길이 -1)을 보세요.
3. 프로덕션 구현: cURL과 Python
이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn을 지정합니다. 환경마다 오리진은 하나만 유지하세요. 경로, 모델 ID, Bearer 헤더는 같습니다.
1단계: 첫·끝 프레임 비트를 cURL로 제출
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "kling-video-o1",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping the same subject, lighting, and camera height as the streets empty at dusk",
"mode": "std",
"duration": 8,
"aspect_ratio": "16:9",
"client_business_id": "o1-episode-01-beat-03",
"metadata": {
"image_list": [
{"image_url": "https://example.com/beat-03-start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/beat-03-end.jpg", "type": "end_frame"}
],
"element_list": [
{"url": "https://example.com/character.jpg", "type": "image", "role": "subject"}
]
}
}'
주체 리스트가 실제로 참여하려면 프롬프트에도 <<<element_1>>>를 적으세요. 폴링 전에 반환된 id(또는 client_business_id)를 저장하세요.
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-video-o1"
DURATION_RANGE = range(3, 11)
def dispatch_o1(
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-video-o1; kling-3-omni and kling-v3-omni are not this model's 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 10")
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")
if video_list:
refer = video_list[0].get("refer_type", "base")
if refer == "base" and ("first_frame" in types or "end_frame" in types):
raise ValueError("refer_type=base cannot be combined with first_frame or end_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_o1(
"Keep <<<element_1>>> in frame while the camera moves from <<<image_1>>> to <<<image_2>>>",
duration=8,
image_list=[
{"image_url": "https://example.com/beat-03-start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/beat-03-end.jpg", "type": "end_frame"},
],
element_list=[
{"url": "https://example.com/character.jpg", "type": "image", "role": "subject"},
],
client_business_id="o1-episode-01-beat-03",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
파일을 받은 뒤 마지막 스틸(다음 비트가 base 편집이면 클립 자체)을 공개 URL에 올리고 다음 dispatch_o1을 시작하세요. 문서화된 서버 측 스티칭도, 이전 task_id를 O1에 가리키는 필드도 없습니다. 프롬프트 템플릿 버전을 작업 기록 옆에 저장하세요. 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, 또는 base와 첫·끝 프레임 혼용 | kling-video-o1, 플레이스홀더 순서와 각 리스트 일치, 공개 URL, 상호 배타 필드 미결합을 확인 |
401 | API 키 누락 또는 무효 | ToAPIs 대시보드에서 키를 교체하고 Authorization: Bearer 헤더를 확인 |
429 | 속도 또는 동시성 제한 | Retry-After가 있으면 준수. 지터와 함께 백오프. 안전할 때만 재시도 |
5xx 또는 클라이언트 타임아웃 | 게이트웨이 또는 업스트림 일시 문제 | 다시 제출하기 전에 기존 작업 id(또는 client_business_id)를 조회 |
status: queued 또는 in_progress | 오류가 아님 | 기다렸다가 다시 폴링. 같은 슬롯에 두 번째 비트를 만들지 말 것 |
status: failed | 생성이 성공하지 않음 | error.code와 error.message(있으면 error.reason)를 읽으세요. 정책 거부 페이로드를 그대로 재시도하지 마세요 |
5. 가격 및 FinOps
공식 영어 O1 레퍼런스가 공개하는 것은 과금 맵이지 달러 표가 아닙니다. SKU 계열을 고른 뒤 계정이 실제로 제시하는 금액을 읽으세요.
| 요청 형태 | 과금 명세 |
|---|---|
mode=std, audio=false, video_list 없음 | 720P(std) |
mode=pro, audio=false, video_list 없음 | 1080P(pro) |
audio=true | Sound로 과금(video_list와 함께 쓸 수 없음) |
요청에 video_list 포함 | Video로 과금 |
2026-11-20에 가져온 kling-video-o1 모델 가이드는 가격 참고로 12 credits / 초를 보여 주었고, 최종 과금은 현재 계정 견적을 따른다고 밝혔습니다. 그 페이지는 USD 초당 요금을 공개하지 않았고 Sound나 Video를 별도의 달러·크레딧 숫자로 나누지도 않았습니다. 크레딧을 직접 통화로 환산하지 말고, $0.030/s나 $0.038/s 같은 기획 초안 단가도 재사용하지 마세요.
- 먼저
std에서 초안을 잡으세요. 720P와 중간 길이(예: 5초)로 반복하고, 버전 있는 프롬프트와 스틸 패키지를 유지하며, 참조 리스트는 한 번에 하나만 바꾼 뒤mode나 10초로 올리세요. - 장편 비용은 성공한 세그먼트의 합에, 실제로 다시 제출한 실패 재시도를 더한 값입니다. 클라이언트 타임아웃은 비트가 실패했다는 증거가 아닙니다. 중복 제출 전에 id를 조회하세요.
- 표시 가격은 채널 보장이 아닙니다. 에피소드를 예측하기 전에
GET /v1/models?type=video와 계정의 실시간 견적으로 ID, SKU, 가용성을 확인하세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: kling-video-o1을 보내고 kling-3-omni나 kling-v3-omni는 보내지 마세요. 문서화된 previous_task_id나 tail_frame_url은 없습니다. 길이는 3–10초입니다. audio와 video_list는 함께 쓸 수 없습니다. 공개 스틸이나 클립은 직접 연결하고 모든 작업 id를 저장하세요.
7. 실행 체크리스트
- ToAPIs 개발자 포털에서 키를 만드세요.
-
GET /v1/models?type=video로 키에kling-video-o1이 보이는지 확인하세요.kling-3-omni는 보내지 마세요. - 첫·끝 프레임
image_list,mode: "std",duration: 5로 cURL 스니펫을 스모크 테스트하세요. - 기한이 있는 상태에서
GET /v1/videos/generations/{id}를 폴링하고,expires_at전에 결과를 받은 뒤 다음 비트의 공개 스틸이나 클립은 직접 호스팅하세요. - 다음 단계: Day 17 Omni ID가 필요하면 Kling 3.0 Omni 멀티샷 가이드, 실시간 카탈로그는 kling-video-o1 모델 가이드, 한 요청이 10초를 넘어야 하면 Wan 3.0 빠른 시작.







