可灵 3.0 API 사용법? 텍스트→비디오, 이미지→비디오 중국어 튜토리얼

TL;DR

• 可灵 3.0(Kling 3.0)은 콰이쇼우가 만든 비디오 모델로, HiAPI에서 텍스트→비디오 kling-3.0/text-to-video와 이미지→비디오 kling-3.0/image-to-video 두 가지 엔드포인트를 제공합니다. 한 편당 3–15초, 최대 4K, 네이티브 사운드 지원.모델 페이지 열기에서 바로 온라인 생성할 수 있고, 신규 가입 시 200 크레딧을 드립니다.
• 초 단위 과금: 720p 초당 $0.10, 사운드 켜면 $0.143; 1080p $0.129, 사운드 켜면 $0.193; 4K $0.479. 5초 720p는 $0.50입니다.
• API는 두 단계: POST /v1/tasks로 제출하고, taskId로 결과를 조회합니다. 아래 curl과 Python은 복사해서 바로 실행할 수 있습니다.

먼저 결과 보기

텍스트→비디오: 영어 프롬프트 한 개, 요청 한 번.

A lone red fox sprints across a windswept snowy ridge at golden hour, powder snow kicking up behind each stride, then leaps over a frozen creek in a graceful arc. Cinematic, dramatic side lighting, ultra-detailed fur, shallow depth of field, smooth motion.

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

kling-3.0/text-to-video 모델 페이지 예시, 5초. 720p 사운드 끄면 $0.50, 1080p 사운드 켜면 $0.965.

이미지→비디오: 아래 등대 이미지를 첫 프레임으로 사용합니다.

The waves surge and crash against the rocks, the lighthouse beam sweeps slowly across the stormy night sky, rain streaks through the wind. Smooth cinematic motion, synchronized ambient sound of waves and storm.

이 프롬프트로 생성 →(첫 프레임 이미지를 업로드, 5초)

kling-3.0/image-to-video 모델 페이지 예시, 5초. 720p 사운드 켜면 $0.715.

可灵 3.0, Omni, Turbo 중 어떻게 고를까?

HiAPI에서 可灵 3.0은 세 라인이 있고, 모델 이름과 가격 및 파라미터가 다릅니다:

모델	엔드포인트	720p / 초	1080p / 초	4K / 초	적합
可灵 3.0 kling-3.0/*	텍스트→비디오, 이미지→비디오(첫 프레임 또는 첫/마지막 프레임)	$0.10, 사운드 켜면 $0.143	$0.129, 사운드 켜면 $0.193	$0.479	사운드 있는 완성본, 멀티 숏 단편
可灵 3.0 Omni kling-3.0-omni/*	텍스트→비디오, 이미지→비디오, 레퍼런스→비디오, 비디오 리라이팅	$0.10, 사운드 켜면 $0.129	$0.129, 사운드 켜면 $0.1645	$0.479	인물/상품 고정, 레퍼런스 비디오의 카메라 무브 따라 하기
可灵 3.0 Turbo kling-3.0-turbo/*	텍스트→비디오, 이미지→비디오	$0.13	$0.16	—	사운드 구분 없이 해상도만으로 과금

텍스트→비디오와 이미지→비디오만 필요하면 kling-3.0을 선택하세요; 레퍼런스 이미지로 주체를 고정하거나 레퍼런스 비디오, 기존 비디오 리라이팅이 필요하면 可灵 3.0 Omni 중국어 튜토리얼을 참고하세요.

두 가지 시작 방법

온라인 체험(코딩 없이)

1. 可灵 3.0 텍스트→비디오 모델 페이지를 열고 회원가입 또는 로그인합니다.
2. 프롬프트를 붙여넣고 길이, 해상도, 화면비를 선택한 뒤 사운드 여부를 결정합니다.
3. 생성을 클릭하고, 완성되면 바로 다운로드합니다.

API 호출

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks로 작업을 제출하면 taskId가 반환됩니다.
3. GET /v1/tasks/{taskId}로 상태를 조회하고, status가 success이면 output[0].url에서 비디오를 다운로드합니다.

curl: 첫 번째 비디오

5초 720p 사운드 끔, $0.50:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/text-to-video",
    "input": {
      "prompt": "金色夕阳下，一只红狐在风雪覆盖的山脊上疾奔，雪粉飞扬，电影级侧光，平滑跟拍",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "sound": false
    }
  }'

반환:

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

결과 조회:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

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

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

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(model, timeout_s=900, **params):
    body = {"model": model, "input": params}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 竖屏、带声音的口播短视频
url = generate(
    "kling-3.0/text-to-video",
    prompt="竖屏短视频：一位博主拿着新耳机对着镜头介绍，手势自然，室内自然光，口型和说话声同步",
    duration=6, resolution="1080p", aspect_ratio="9:16", sound=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

이 6초 1080p 사운드 켜면 $1.158입니다.

이미지→비디오: 첫 프레임 한 장, 또는 첫/마지막 두 프레임

모델 이름을 kling-3.0/image-to-video로 바꾸고 이미지를 image_urls에 넣습니다: 1장이면 첫 프레임, 2장이면 [첫 프레임, 마지막 프레임].

{
  "model": "kling-3.0/image-to-video",
  "input": {
    "image_urls": [
      "https://your-cdn.example.com/start.jpg",
      "https://your-cdn.example.com/end.jpg"
    ],
    "prompt": "镜头缓慢推进，两个画面之间平滑过渡",
    "duration": 5,
    "resolution": "720p",
    "sound": false
  }
}

• 이미지는 JPEG / PNG / WebP를 지원하며 SVG는 지원하지 않습니다.
• 이미지→비디오에는 aspect_ratio가 없고, 화면비는 첫 프레임을 따릅니다.
• 프롬프트는 선택 사항이며, 「이후 어떻게 움직일지」를 작성하고 전체 이미지를 다시 설명할 필요는 없습니다.

파라미터 한눈에 보기

파라미터	값	설명
prompt	문자열	텍스트→비디오 필수, 이미지→비디오 선택
image_urls	1–2장	이미지→비디오 전용; 1장이면 첫 프레임, 2장이면 첫/마지막 프레임
duration	3–15 정수, 기본 5	단위 초
resolution	720p / 1080p / 4K, 기본 1080p	생략하면 1080p로 과금
aspect_ratio	16:9 / 9:16 / 1:1, 기본 16:9	텍스트→비디오 전용
sound	기본 false	켜면 대사, 효과음, 환경음 생성

비용 계산

길이	720p	720p 사운드 켬	1080p	1080p 사운드 켬	4K
3초	$0.30	$0.429	$0.387	$0.579	$1.437
5초	$0.50	$0.715	$0.645	$0.965	$2.395
10초	$1.00	$1.43	$1.29	$1.93	$4.79
15초	$1.50	$2.145	$1.935	$2.895	$7.185

resolution 기본값은 1080p이므로, 프롬프트를 조정할 때 720p를 명시하면 20% 이상 절약할 수 있습니다. 더 많은 가격 비교는 可灵 3.0 API 가격을 참고하세요.

출시 전 유의사항

• 폴링 대신 콜백 사용: 요청 최상위(input과 동일 레벨)에 "callback": {"url": "https://你的域名/hiapi/callback"}를 추가하고 taskId로 중복을 제거하세요.
• 즉시 이전 저장: output[0].url은 임시 링크이므로 받은 즉시 자체 스토리지에 저장하세요.
• 재시도 시 멱등 키 사용: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 재시도해도 작업이 한 번만 생성됩니다.
• 실패 시 자동 환불: 성공적으로 생성된 비디오에만 과금합니다.

자주 묻는 질문

프롬프트에 중국어를 쓸 수 있나요?

네. 중국어, 영어 모두 가능하며 대사 내용도 프롬프트에 직접 작성할 수 있습니다.

사운드는 별도로 과금되나요?

sound: true이면 단가가 높아집니다: 720p는 초당 $0.10에서 $0.143으로, 1080p는 $0.129에서 $0.193으로. 화면만 필요하면 기본값 false를 유지하세요.

한 편의 최대 길이는?

3–15초입니다. 더 긴 영상은 구간별로 생성한 뒤 편집하세요.

可灵 3.0과 Seedance 2.5 중 어떻게 고를까?

可灵 3.0은 단가가 낮고 4K를 지원합니다; Seedance 2.5는 한 편 최대 30초입니다. 비교는 可灵 3.0과 Seedance 2.5의 차이를 참고하세요.

바로 쓸 수 있는 작성법은 可灵 3.0 프롬프트 가이드를 참고하세요; 위의 붉은 여우 프롬프트를 복사해 모델 페이지에서 생성하기도 할 수 있습니다.