튜토리얼

Kling 3.0 Turbo 텍스트→비디오 API 사용법? 파라미터, 코드, 오류

Kling 3.0 Turbo 텍스트→비디오의 4개 파라미터, curl 및 Python 예제, 초당 가격, 흔한 오류, 출시 전 주의사항.

Oct 18, 2026

TL;DR

Kling 3.0 Turbo 텍스트→비디오의 모델명은 kling-3.0-turbo/text-to-video이며, Kling 3.0의 고속 버전입니다.모델 페이지 열기에서 바로 온라인으로 체험할 수 있습니다.
초 단위 과금: 720p 초당 $0.13, 1080p 초당 $0.16. 길이는 3–15초 사이 임의의 정수이며, 5초 720p 한 편은 $0.65입니다.
파라미터는 단 4개: prompt, duration, aspect_ratio, resolution. 그 외 필드(seed, negative_prompt 등)를 추가로 전달하면 400이 반환됩니다.

먼저 한 편 보기

720p, 5초, 16:9:

aerial drone shot sweeping over a norwegian fjord waterfall, mist drifting,
camera gliding forward, smooth natural motion, stable cinematic camera
movement, consistent lighting across frames, cinematic composition, dramatic
directional lighting, rich cohesive color grade, ultra-detailed, premium
commercial finish

이 프롬프트로 생성하기 → (5초, 720p, 16:9)

kling-3.0-turbo/text-to-video, 5초.

파라미터 빠른 조회

필드	필수	값	설명
`prompt`	예	최대 2500자	화면, 피사체, 동작, 카메라 무빙; 따옴표 안의 대사는 립싱크 가능
`duration`	아니오	정수 3–15, 기본값 5	초 단위 과금, 1초 늘면 1초만큼 더 지불
`aspect_ratio`	아니오	`16:9`(기본) / `9:16` / `1:1`	가로, 세로, 정사각형
`resolution`	아니오	`720p`(기본) / `1080p`	초당 단가 결정

sound 필드는 없지만, 완성 영상에는 사운드가 기본 포함되며 끌 수 없습니다. 4K, 마지막 프레임, 참조 이미지도 없으므로, 이것들이 필요하면 Kling 3.0 표준판이나 Omni를 사용하세요.

curl: 첫 편 성공시키기

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/text-to-video",
    "input": {
      "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion, water droplets frozen mid-air",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'

반환에는 data.taskId만 있습니다. 5–10초마다 GET /v1/tasks/{taskId}를 폴링하고, status가 success가 되면 output[0].url에서 영상을 다운로드하세요.

Python: 제출, 폴링, 다운로드

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=900, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "kling-3.0-turbo/text-to-video", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(8)
    raise TimeoutError(task_id)

# 竖屏 3 秒 720p 试方向，$0.39
url = generate(
    prompt="A barista pours latte art in slow motion, close-up, warm cafe light",
    duration=3, aspect_ratio="9:16", resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

얼마인가

길이	720p($0.13/초)	1080p($0.16/초)
3초(최단)	$0.39	$0.48
5초	$0.65	$0.80
10초	$1.30	$1.60
15초(최장)	$1.95	$2.40

HiAPI 현재 가격, 2026년 10월 18일 확인.

실패 시 과금되지 않습니다. 전체 비교는 Kling 3.0 Turbo API 가격을 참고하세요.

마주치게 될 오류

전달한 것	반환
`prompt` 미전달	400, `missing required field "prompt"`
추가 필드 전달(예: `seed`, `negative_prompt`)	400, `additional properties ... not allowed`
`duration: 2`	400, `duration: minimum: got 2, want 3`
`duration: 99`	400, `duration: maximum: got 99, want 15`
`aspect_ratio: "4:3"`	400, `16:9`, `9:16`, `1:1`만 가능
`resolution: "480p"`	400, `720p`, `1080p`만 가능
Key 오류 또는 누락	401, `permission_denied`
잔액 부족	402, 먼저 충전 후 확인

파라미터 오류는 제출 시 동기적으로 반환되고; 생성 실패는 이후 폴링에서 status가 fail로 확인되며 오류는 data.error에 있습니다. 두 경로 모두 처리해야 합니다.

출시 전 주의사항

폴링 대신 콜백 사용: input과 같은 레벨에 "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}를 추가하면, 작업 종료 시 한 번만 알림이 오며 taskId로 중복 제거하세요.
Idempotency-Key 요청 헤더 포함: 타임아웃 재시도 시 같은 Key를 사용하면 작업은 하나만 생성되고 과금도 한 번만 됩니다.
결과는 즉시 다운로드: output[0].url에는 유효 기간이 있습니다.
15초를 넘으면 분할: 이전 편의 마지막 프레임을 kling-3.0-turbo/image-to-video에 첫 프레임으로 전달해 이어서 생성하세요.