Kling 3.0 API: 텍스트 투 비디오 요청 코드와 실측 클립

Kling 3.0 텍스트 투 비디오 작업은 https://api.omniakey.com/v1/media/tasks로 보내는 POST 한 번입니다. model id는 kling-3.0, operation은 text_to_video이며 duration(5, 10, 15초)과 mode(std 또는 pro) 두 가지가 필수 파라미터입니다. 응답에는 작업 id가 들어오며, 성공할 때까지 폴링한 뒤 MP4를 내려받습니다. 2026년 10월 29일에는 5초 standard 모드 클립을 1280×720으로 2개 만들어 파일과 프레임을 측정했습니다.

Kling 3.0 요청에 필요한 것

본문에 들어가는 필드는 7개입니다. 이 중 duration과 mode는 Kling에서 필수이며 클립 길이와 화질 등급을 정합니다.

모델 페이지의 자체 샘플은 duration 6과 resolution 720p를 보내지만 둘 다 여기서는 유효하지 않습니다. 이 페이지는 5, 10, 15초만 받고 별도의 resolution 필드는 없다고 명시합니다(모델 페이지, 2026년 10월 29일 확인). FAQ에서는 standard 출력을 720P, pro를 1080P로 매핑합니다.

오디오는 기본으로 포함되며 페이지에 켜고 끄는 옵션이 없습니다(2026년 10월 29일 확인). aspect_ratio는 텍스트 투 비디오에 적용되고, 이미지 투 비디오는 첫 프레임에서 화면 비율을 가져가므로 명시적 비율은 거부됩니다. 이번 두 실행은 std, 5초, 16:9였고 pro 모드, 10초와 15초, 9:16과 1:1, 이미지 투 비디오, 마지막 프레임은 범위 밖이었습니다.

결과는 프롬프트 문장이 좌우합니다. 장면, 동작, 카메라를 어떻게 적을지는 Kling 3.0 프롬프트 가이드에서 다룹니다.

요청 코드

Python 파일 하나로 본문 전송, 작업 폴링, MP4 다운로드를 처리합니다. 키는 환경 변수 OMNIAKEY_API_KEY에서 읽고, 생성 요청에는 무작위 Idempotency-Key를 붙이며, 폴링 간격은 5초로 최대 180회입니다. 본문은 다음 절의 두 클립과 같습니다. model kling-3.0, type video, operation text_to_video, duration 5, mode std, 화면 비율 16:9입니다.

import json
import os
import time
import urllib.error
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def poll(url, attempts=5):
    for attempt in range(attempts):
        try:
            return request("GET", url)
        except urllib.error.HTTPError as err:
            if err.code < 500 or attempt == attempts - 1:
                raise
        except urllib.error.URLError:
            if attempt == attempts - 1:
                raise
        time.sleep(5 * (attempt + 1))

def text_to_video(prompt, out_path, duration=5, mode="std", aspect_ratio="16:9"):
    body = {
        "model": "kling-3.0",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": prompt},
        "parameters": {"duration": duration, "mode": mode, "aspect_ratio": aspect_ratio},
    }
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    print("task", task, flush=True)
    for _ in range(180):
        time.sleep(5)
        state = poll(f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # 서명된 링크는 수명이 짧으므로 바로 내려받습니다
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=300) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

if __name__ == "__main__":
    task = text_to_video(
        "A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on "
        "the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.",
        "paper-boat.mp4",
    )
    print("done", task)

각 폴링은 작업 URL에 보내는 GET입니다. 반복문은 progress.percent가 아니라 status를 보는데, 렌더링 중에는 이 값이 0에 머물 수 있기 때문입니다. status가 queued나 processing이 아니면 멈추고, succeeded면 assets[0].url에서 내려받으며 그 밖의 상태는 작업 자체의 오류 메시지를 냅니다. 자산 링크는 만료되므로 다운로드는 즉시 해야 하고, 만료됐다면 작업을 다시 조회해 새 링크를 받습니다. 연결이 끊기거나 서버 오류(5xx)가 난 폴링은 최대 5회 재시도하며 매번 조금 더 기다립니다.

2026년 10월 29일 같은 설정으로 이 파일을 한 번 더 실행했습니다. 첫 시도는 폴링 중 연결이 끊겼고, 그래서 지금의 폴링에는 재시도가 들어 있습니다. 두 번째 실행이 반환한 작업은 task_PNB1kPopriUyfcHsXhVWY2hBOEoSUIqM이고 MP4는 5.04초, 1280×720, 스테레오 AAC 트랙으로 측정됐습니다. 생성부터 다운로드까지 807초가 걸렸고 아래 두 클립은 82.2초와 110.7초였으니 대기 시간을 넉넉히 잡아야 합니다.

직접 만든 클립 두 개

두 요청 모두 2026년 10월 29일에 위 본문으로 나갔습니다. paper boat 작업은 task_cbOtsBxO75cml3nOmVUu9YG3PkYXW2ja, teapot 작업은 task_M2Ub1EoCaCUa1FjOZDdWDOuEOS9nRjnt입니다. 프롬프트는 적힌 그대로 전송했습니다.

종이배

A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.

티팟

A ceramic teapot sits on a wooden table by a window. Steam rises in slow curls. Soft morning light moves across the table. The camera pushes in slowly. No people, no text.

파일 측정 결과

클립 도구로 2026년 10월 29일에 각 다운로드를 측정했습니다.

• 종이배 — 크기: 1280×720; 프레임 레이트: 24.0 fps; 길이: 5.04초; 오디오: AAC, 2채널, 44.1 kHz; 평균 레벨: −50.9 dB; 최대 레벨: −34.0 dB; 컷: 없음
• 티팟 — 크기: 1280×720; 프레임 레이트: 24.0 fps; 길이: 5.04초; 오디오: AAC, 2채널, 44.1 kHz; 평균 레벨: −54.3 dB; 최대 레벨: −35.9 dB; 컷: 없음
• 코드 실행 클립 — 크기: 1280×720; 프레임 레이트: 24.0 fps; 길이: 5.04초; 오디오: AAC, 2채널, 44.1 kHz; 평균 레벨: −48.4 dB; 최대 레벨: −20.0 dB; 컷: 없음

처음 두 클립은 아주 조용합니다. 평균 레벨이 −50.9 dB와 −54.3 dB이고 피크는 −34.0 dB와 −35.9 dB입니다. 코드 실행 클립은 더 크며 평균 −48.4 dB, 피크 −20.0 dB입니다. 측정한 것은 레벨뿐이고 트랙의 내용은 확인 범위 밖이었습니다. 장면 전환 검출은 세 클립 모두에서 강한 컷도 약한 컷도 찾지 못했으므로 각 클립은 하나의 숏으로 재생됩니다.

프레임에서 보이는 것

두 클립 모두 프롬프트를 따랐고, 티팟 클립에는 작은 움직임이 하나 더 있습니다.

종이배 클립에서 배는 5.04초 내내 화면 중앙 근처에 머물고 젖은 거리가 뒤로 흘러가므로 카메라가 배를 따라가는 숏으로 읽힙니다. 가로등의 따뜻한 반사는 마지막 프레임까지 자갈길에 남아 있습니다(2026년 10월 29일 프레임 확인). 따라가기를 끊는 컷은 없습니다.

티팟 클립에서는 김이 천천히 말려 올라가며 사라지고 아침 빛이 나무 테이블 위를 지나갑니다. 마지막 프레임의 티팟은 처음보다 크고 오른쪽 아래로 더 이동해 있어, 느린 푸시인에 옆으로 밀리는 움직임이 더해진 것으로 보입니다. 프롬프트가 요청한 것은 느린 푸시인이었고 이 옆 이동은 프롬프트에 없던 동작입니다(2026년 10월 29일 프레임 확인).

오류와 제한

duration이 5, 10, 15를 벗어나면 HTTP 400 model_price_error가 돌아오고 작업은 생성되지 않습니다(비디오 API 문서, 2026년 10월 29일 확인). 허용된 세 값 중 하나를 정수 초로 보내야 합니다.

Idempotency-Key 없이 생성 요청을 보내면 400 missing_idempotency_key가 돌아옵니다. 키는 최대 255자입니다. 같은 키에 같은 본문이면 기존 작업이 HTTP 200으로 돌아오고 새로 과금되지 않으며, 같은 키에 본문이 바뀌면 409 idempotency_key_reused가 됩니다(미디어 API 개요, 2026년 10월 29일 확인).

2026년 10월 29일, Python urllib의 기본 User-Agent로 POST를 보내면 Cloudflare에서 HTTP 403과 본문 error code: 1010이 돌아왔습니다. 자체 User-Agent 헤더를 붙이자 API에 도달했습니다. 생성 요청과 다운로드 요청 모두에 User-Agent를 설정해야 합니다.

출력 링크는 수명이 짧습니다. assets[].url을 저장하지 말고 작업을 다시 폴링해 새 URL을 받아야 합니다(비디오 API 문서, 2026년 10월 29일 확인). 작업 기록은 생성 후 24시간 보관됩니다(미디어 API 개요, 2026년 10월 29일 확인).

Kling 3.0은 초 단위가 아니라 생성 건당 과금입니다(비디오 API 문서, 2026년 10월 29일 확인). 현재 요금은 OmniaKey 가격 페이지에서 확인할 수 있습니다.

자주 묻는 질문

kling-3.0은 어떤 길이를 지원합니까?

5, 10, 15초입니다. 다른 값은 HTTP 400 model_price_error를 반환하고 작업을 만들지 않습니다(비디오 API 문서, 2026년 10월 29일 확인).

std와 pro는 무엇이 다릅니까?

모델 페이지는 둘을 Standard와 Pro로 표시하고 standard 출력은 720P, pro는 1080P로 매핑합니다(2026년 10월 29일 확인). std만 실행했기 때문에 두 모드의 차이를 측정하지는 못했습니다.

클립에 소리가 들어 있습니까?

모든 클립에 44.1 kHz, 2채널 AAC 트랙이 들어 있습니다. 처음 두 클립은 아주 조용해서 평균 레벨이 −50.9 dB와 −54.3 dB이고, 코드 실행 클립은 평균 −48.4 dB, 피크 −20.0 dB입니다. 레벨만 측정했고 트랙의 내용은 식별하지 않았습니다.

이미지에서 클립을 시작할 수 있습니까?

모델 페이지에는 첫 프레임과 선택적 마지막 프레임을 쓰는 이미지 투 비디오가 있습니다(2026년 10월 29일 확인). 첫 프레임이 화면 비율을 정하며 그 operation에서는 명시적 비율이 거부됩니다.

클립 생성에는 얼마나 걸립니까?

2026년 10월 29일 두 번의 실행에서 종이배는 110.7초, 티팟은 82.2초에 끝났습니다. 둘 다 16:9의 5초 std 클립이었습니다.

Kling 3.0 모델 페이지에서 시작해 같은 본문에 자신의 프롬프트를 넣어 보내면 됩니다.