API로 Kling AI 숏폼 영상 사용하기: kling-3.0-omni 텍스트-투-비디오 엔드투엔드 워크플로

숏폼은 수량 게임입니다. 피드는 매일 게시하는 계정에 보상을 주지만, 매일 손으로 촬영하고 편집하고 한 클립의 사운드 디자인까지 할 수 있는 사람은 없습니다. kling-3.0-omni/text-to-video는 단 한 번의 API 호출로 완전한 숏폼 체크리스트를 커버하는 몇 안 되는 모델입니다. 세로형 9:16 출력, 시네마틱 모션, 멀티 숏 시퀀스, 네이티브 동기화 오디오까지 지원하므로 전체 파이프라인을 "프롬프트 하나 작성, 태스크 하나 폴링, 바로 게시 가능한 .mp4 하나 다운로드"로 단순화할 수 있습니다.

이 가이드는 hiapi API에서 전체 워크플로를 엔드투엔드로 다룹니다. 비동기 태스크 제출, 피드 스크롤을 멈추게 할 프롬프트 설계, 네이티브 오디오 활성화, 멀티 숏 내러티브로 확장, 그리고 대량 변형 생성까지. 아래 삽입된 각 클립은 라이브 API에서 나온 실제, 편집되지 않은 첫 출력물입니다. 이 글을 위해 생성되었으며, 옆에 정확한 프롬프트와 설정이 표시되어 있습니다.

사용할 도구

kling-3.0-omni/text-to-video(콰이쇼우의 Kling 3.0 Omni, 텍스트-투-비디오 엔드포인트)는 hiapi의 비동기 태스크 인터페이스에서 실행됩니다. 과금은 출력 초 단위로 계산되며 해상도와 네이티브 오디오 활성화 여부에 따라 달라집니다. 다음 요율은 이 글 작성 시점의 hiapi 요금 페이지에서 가져왔습니다:

티어	초당 가격	5초 클립	10초 클립
720p	$0.10	$0.50	$1.00
720p + 오디오	$0.143	$0.72	$1.43
1080p	$0.129	$0.65	$1.29
1080p + 오디오	$0.193	$0.97	$1.93
4K	$0.479	$2.40	$4.79

피드용 세로형 영상에는 720p가 정직한 선택입니다. TikTok과 Reels는 어차피 모든 것을 다시 압축하며, 프롬프트를 반복하기에 가장 저렴한 방법이기 때문입니다. 1080p/4K는 다른 포맷으로 편집할 클립에 남겨두세요.

이 글에서 실제로 검증한 입력 스키마: prompt(문자열), duration(정수 초 — 5초와 10초를 실행했습니다), resolution(720p / 1080p / 4K), aspect_ratio(세로형은 9:16), 그리고 sound(불리언, 기본값 꺼짐). 이를 기반으로 구축하기 전에 알아두면 좋은 동작 하나: sound를 생략하면 반환되는 .mp4에 오디오 트랙이 전혀 없습니다 — 무음 트랙이 아니라 트랙 자체가 없습니다. 다운스트림 편집 파이프라인이 모든 파일에 오디오 스트림이 있을 것이라 기대한다면, 항상 sound: true를 설정하거나 트랙 없는 파일을 명시적으로 처리하세요.

제출 → 폴링 → 다운로드: 태스크 수명 주기

모든 것은 POST /v1/tasks를 통해 이루어집니다. 태스크를 제출하고 즉시 태스크 ID를 받은 뒤 완료될 때까지 폴링하고 출력을 다운로드합니다. 5초 720p 클립은 보통 몇 분 안에 렌더링됩니다.

curl로 제출:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/text-to-video",
    "input": {
      "prompt": "Vertical short-form video. A barista in a sunlit specialty coffee bar pours a perfect rosetta latte art in one smooth motion, steam rising, morning light through the window, shallow depth of field, crisp photoreal detail, subtle slow push-in.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

응답은 즉시 반환됩니다:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWZYC1VKGV2CCSBK6AY9862H"}, "message": "success"}

그런 다음 GET /v1/tasks/{taskId}를 status가 success(또는 fail)가 될 때까지 폴링하고 output[0].url을 다운로드합니다. 아래는 완전한 Python 헬퍼 스크립트입니다. 이 가이드의 모든 클립을 생성할 때 사용한 실제 패턴입니다:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "kling-3.0-omni/text-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    return json.loads(out)["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(8)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=120)

프로덕션 환경에서 중요한 운영 세부 사항: 받은 output[0].url은 기한부 서명 링크(만료 시간 포함)입니다. 태스크가 성공하면 즉시 바이트를 다운로드하여 자체 버킷이나 CDN에 저장하세요 — 원본 태스크 URL을 데이터베이스나 CMS에 저장하지 마세요.

3초 훅을 위한 프롬프트 설계

숏폼의 성패는 화면의 첫 1초에 달려 있습니다. 세로형 훅에서 일관되게 효과가 있는 프롬프트 패턴: 하나의 피사체, 하나의 연속적이고 만족스러운 동작, 명확히 서술된 조명, 그리고 카메라 언어로 표현된 카메라 움직임. 다음은 위 curl 예제의 정확한 프롬프트와 그것이 생성한 클립입니다:

Vertical short-form video. A barista in a sunlit specialty coffee bar pours a
perfect rosetta latte art in one smooth motion, steam rising, morning light
through the window, shallow depth of field, crisp photoreal detail, subtle
slow push-in.

실제 출력 — kling-3.0-omni/text-to-video, 5초 @ 720p, 9:16, 오디오 없음. 첫 결과물, 편집되지 않음.

각 요소의 역할:

• "Vertical short-form video"(세로형 숏폼 영상)를 맨 앞에 두면 픽셀 비율뿐 아니라 구도 결정까지 고정됩니다 — 모델이 휴대폰 화면에 맞춰 구도를 잡습니다.
• 하나의 연속 동작("pours ... in one smooth motion", 즉 "한 번의 매끄러운 동작으로 따르다")은 모델에게 무작위 컷을 끼워 넣지 않고 렌더링할 하나의 아크를 제공합니다.
• "Subtle slow push-in"(미묘한 느린 푸시인)은 진짜 카메라 지시입니다. 모호한 감정 단어("dynamic" "engaging")는 모델이 즉흥적으로 만들게 하지만, 카메라 용어는 모델을 궤도에 유지시킵니다.
• 조명은 한 문장을 차지해야 합니다("morning light through the window", 즉 "창문을 통해 들어오는 아침 빛") — 조명이 "AI 클립"과 "실제 세트 촬영"을 가르는 차이입니다.

네이티브 오디오: sound: true 설정하고 사운드스케이프 서술하기

Kling 3.0 Omni의 대표 기능은 네이티브 동기화 오디오입니다. 모델이 화면과 일치하는 사운드트랙을 렌더링하며, 음식, ASMR, 거리 콘텐츠에서는 이것이 리텐션의 상당 부분을 차지합니다. 두 가지를 동시에 해야 합니다: 입력에서 "sound": true를 설정하고(오디오 요율로 과금, 720p 기준 $0.143/초), 화면을 묘사하듯 프롬프트에서 오디오를 묘사해야 합니다:

Vertical short-form video. Close-up of a street food vendor's wok at night:
diced garlic and chili hit sizzling oil with a burst of steam, flames lick up
the wok's edge as the vendor tosses noodles in rhythmic flips, neon signs
glowing bokeh in the background. Handheld feel, appetizing, high energy.
Native audio: loud sizzle, wok clangs, distant street chatter.

실제 출력 — kling-3.0-omni/text-to-video, 5초 @ 720p, 9:16, sound: true. 볼륨을 켜세요: 지글거리는 소리와 웍 부딪히는 소리는 모두 모델이 생성하고 팬을 던지는 동작과 동기화된 것입니다.

"Native audio:" 접미사 패턴 — 쉼표로 구분된 두세 개의 핵심 사운드 짧은 목록 — 은 "with realistic sound effects"(사실적인 음향 효과 포함) 같은 산문식 묘사보다 확실히 우수합니다. 사운드를 명명하면 모델이 그것을 일치하는 시각적 사건과 동기화합니다.

ffprobe로 실제 출력에서 과금 경계를 검증했습니다: sound를 설정하지 않고 제출한 클립은 H.264 비디오 스트림만 포함하고, sound: true 클립은 추가 AAC 오디오 트랙을 가집니다. 오디오를 요청한 클립에만 오디오 프리미엄을 지불합니다.

단일 프롬프트로 멀티 숏 내러티브 구현

Omni의 또 다른 차별화 기능은 멀티 숏 시퀀스입니다. 세 개의 독립 클립을 이어 붙이는 대신 한 번의 생성에서 명시적인 컷을 작성할 수 있습니다. 프롬프트에서 숏에 번호를 매기고 전체 시퀀스에 공유 색보정을 부여하여 우연이 아닌 편집처럼 보이게 하세요:

Vertical short-form video, three-shot sequence. Shot 1: a young woman in a
yellow rain jacket steps out of a subway exit into light rain, opens a clear
umbrella. Shot 2: close-up of her boots splashing through a neon-reflecting
puddle in slow motion. Shot 3: she stops at a food cart, smiles as warm steam
drifts past, city lights bokeh behind. Cohesive teal-and-amber grade,
cinematic handheld energy. Native audio: soft rain, city ambience, distant
traffic hum.

실제 출력 — kling-3.0-omni/text-to-video, 10초 @ 720p, 9:16, sound: true. 세 개의 스크립트된 숏, 한 번의 생성: $1.43.

대략 숏당 3초로 예산을 잡으세요 — 10초 길이는 3박자 이야기에 적합합니다. 반복되는 앵커(노란 우비)는 컷 간에 정체성을 일관되게 유지하는 핵심입니다. 모든 멀티 숏 프롬프트에 눈에 띄는 시각적 상수를 부여하세요. 그렇지 않으면 피사체가 숏 사이에서 변합니다.

대량 제작: 하나의 템플릿, 다양한 변형

규모가 커지면 경제성이 흥미로워집니다. 일주일치 데일리 게시물은 변수 슬롯이 있는 프롬프트 템플릿 하나와 동시 제출로 해결됩니다 — 태스크는 병렬로 렌더링되므로 배치가 대략 한 클립 정도의 시간에 완료됩니다. 라테 훅 템플릿을 가져와 피사체를 교체했습니다:

Vertical short-form video. A ceramic bowl of matcha being whisked into a vivid
green froth with a bamboo whisk, in a sunlit specialty tea bar, steam rising,
morning light through the window, shallow depth of field, crisp photoreal
detail, subtle slow push-in.

실제 출력 — 라테 클립과 같은 템플릿, 변수 하나만 변경. 5초 @ 720p, 9:16: $0.50.

푸시인, 창문 빛, 얕은 심도는 그대로 유지됩니다 — 이것이 바로 원하는 시각적 일관성을 가진 계정입니다. 코드에서 배치는 기다리기 전에 먼저 제출하는 것입니다:

TEMPLATE = ("Vertical short-form video. {subject}, in a sunlit specialty {venue}, "
            "steam rising, morning light through the window, shallow depth of field, "
            "crisp photoreal detail, subtle slow push-in.")

VARIANTS = [
    {"subject": "A barista pouring a perfect rosetta latte art in one smooth motion", "venue": "coffee bar"},
    {"subject": "A ceramic bowl of matcha being whisked into a vivid green froth with a bamboo whisk", "venue": "tea bar"},
    {"subject": "A croissant being pulled apart to reveal steaming, glossy layers", "venue": "bakery"},
]

task_ids = [submit({
    "prompt": TEMPLATE.format(**v),
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
}) for v in VARIANTS]          # all rendering in parallel

clips = [wait(tid) for tid in task_ids]

720p 기준 비용 계획: 월 30개의 5초 무음 훅 클립은 $15; 같은 월에 네이티브 오디오를 더하면 $21.45입니다. 공격적인 일정 — 매일 10초 오디오 클립 — 도 월 $42.90에 불과하며, 비디오 편집자의 한 시간보다 저렴합니다. 결과가 돌아오는 대로 폴링하고, 특정 태스크의 fail 상태는 전체 배치가 아닌 해당 변형만 재시도하도록 처리하세요.

이 글의 모든 내용은 영상 생성에 총 $3.15를 사용했습니다: 네 개의 클립, 25초 분량, 모두 첫 결과물입니다.

다음 단계

이제 전체 루프를 갖추었습니다: 9:16 태스크 제출, 폴링, .mp4 가져오기, 템플릿으로 확장. 다음 단계를 위한 몇 가지 팁:

• hiapi 문서에서 API 키와 전체 엔드포인트 참조를 확인하세요 — 위의 태스크 수명 주기는 플랫폼의 모든 비디오 모델에 동일합니다.
• 대규모 배치 예산을 잡기 전에 요금 페이지에서 모든 티어의 현재 초당 요율을 확인하세요.
• 이 사용 사례에 모델을 선택할 때, Short-Form Video with seedance-2.0-mini에서 동일한 숏폼 워크플로를 예산 모델로 실행했습니다 — Kling과 비교할 가격/품질 기준선으로 사용하세요.

자신의 피사체로 $0.50짜리 시험 클립부터 시작하고, 피드에서 검증된 프롬프트 요소를 유지한 뒤 kling-3.0-omni/text-to-video 모델 페이지에서 템플릿을 배치 태스크로 전환하세요.