블로그

튜토리얼

HiAPI API로 kling-3.0/motion-control 사용하는 방법: curl 및 Python 예제

Nov 12, 2026
커버 이미지: 따뜻한 차콜색 바탕 위로 넓은 호박색 광선 띠가 대각선으로 지나가고, 가장자리는 깔끔하며 아래쪽에는 어두운 기하학적 도형이 약간 장식되어 있습니다.
이 페이지에서

kling-3.0/motion-control의 용도와 선택 시점

모션 제어는 영상 생성의 한 능력으로, 참조 영상을 모델에 넘기면 텍스트 프롬프트로 동작을 설명하는 대신 모델이 출력의 움직임, 리듬, 구도를 구동합니다. HiAPI API에서 kling-3.0/motion-control을 사용할 때 참조 영상은 주요 입력입니다. 참조 영상은 물체가 어떻게 움직이는지 고정하고, 나머지 파라미터는 그 움직임을 중심으로 생성되는 내용을 형성합니다.

움직임 자체가 난제일 때 이 모델을 선택해야 합니다. 적합한 대표적 상황은 다음과 같습니다:

  • 짧은 영상이 있고, 다른 내용으로 그 카메라 무브먼트나 주체 동작을 재현하고 싶을 때.
  • 텍스트 프롬프트에 운을 맡기는 텍스트-투-비디오 결과가 아니라 예측 가능한 움직임이 필요할 때.
  • 여러 번의 생성에 재사용할 수 있는 자산으로 움직임을 다루는 파이프라인을 구축 중이므로, 한 문장 설명이 아니라 입력으로 제공해야 할 때.

텍스트-투-비디오만 필요하고 모션 참조가 없다면 모션 제어는 업로드 단계와 더 엄격한 입력 제약만 추가할 뿐 이득이 없습니다. 마찬가지로 참조 영상이 길거나 구도가 불안정하면 더 많은 재시도를 예상해야 합니다. 이 가이드의 나머지 부분은 모션 제어가 적합한 도구라고 판단했으며 안정적이고 재현 가능한 통합 방식을 원한다고 가정합니다.

사전 조건 및 엔드포인트 설정

처음 호출하기 전에 세 가지를 준비하세요.

1. API 키

HiAPI.ai 계정 콘솔에서 키를 생성하고 소스 코드에 넣지 말고 환경 변수에 저장하세요:

export HIAPI_API_KEY="your_api_key_here"

모든 요청에 베어러 토큰으로 전송합니다: Authorization: Bearer $HIAPI_API_KEY.

2. 기본 URL 규칙

모든 HiAPI 호출은 동일한 기본 URL과 버전이 포함된 경로 접두사를 공유합니다. 기본 URL을 설정에 두어 환경을 전환할 때 호출 지점을 수정하지 않도록 하세요:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. 모델 식별자

모델은 요청의 model 필드로 요청별 선택하며, 정확한 식별자 kling-3.0/motion-control을 사용해야 합니다. 여러 곳에 하드코딩하지 말고 상수로 전달하여 향후 모델 교체 시 한 줄만 수정하면 되도록 하세요.

또한 API가 참조 영상을 가져올 수 있는 호스팅 위치가 필요합니다. 일반적으로 서명된 제한 시간 URL을 사용하며, 사용자 정의 헤더나 쿠키 없이 접근 가능해야 합니다.

이 세 가지가 준비되면 남은 작업은 요청 구조와 작업 생명주기입니다.

참조 영상과 모션 파라미터 제공

모션 제어 요청은 개념적으로 두 부분으로 나뉩니다: 모션 소스(참조 영상)와 생성 설정(모델이 무엇을 출력해야 하는지).

참조 영상

참조 영상은 JSON 페이로드에 원시 바이트로 전달하지 않고 요청 본문에 URL 형태로 넣습니다. 두 가지 실용 규칙:

  • 작업이 대기하고 처리되는 동안 항상 유효한 URL을 사용하세요. 서명된 URL이 일찍 만료되는 것은 작업이 제출 몇 분 후 실패하는 흔한 원인입니다.
  • 영상을 짧고 화면이 안정적으로 유지하세요. 너무 길거나 흔들림이 심하거나 잦은 편집이 있는 참조 소재는 모델에 모호한 모션 신호를 제공합니다.

소재가 비공개 스토리지에 있다면 업로드 시점이 아니라 제출 시점에 충분히 긴 유효 기간의 서명 URL을 생성하세요.

모션 및 출력 파라미터

일반적으로 참조 영상과 함께 설정하는 파라미터:

  • 참조 모션이 구동할 대상 콘텐츠를 설명하는 텍스트 프롬프트.
  • 생성 영상이 표시 위치에 맞도록 출력 종횡비와 길이 설정.
  • 모델이 노출하는 모션 강도 또는 충실도 설정으로, 참조에 충실한 정도와 프롬프트 자유도 사이를 조절.

이 파라미터는 함수 인자에 흩어 놓지 말고 클라이언트의 작고 명시적인 설정 객체로 두세요. 그러면 무엇이 제출되었는지 정확히 기록할 수 있으며, 이는 이 모델에서 가장 유용한 디버깅 자료입니다.

마지막으로 제출 전에 검증하세요: 참조 URL이 미디어 콘텐츠 유형을 반환하는지, 프롬프트가 비어 있지 않은지, 모든 수치 설정이 문서 범위 내인지. 로컬 검사는 몇 밀리초면 되지만 거부된 비동기 작업은 왕복 한 번과 혼란의 대가를 치릅니다.

비동기 작업: 제출, 폴링 및 결과 읽기

모션 제어는 제출 응답에서 영상을 반환하지 않고 추적해야 할 작업을 반환합니다. 처음부터 이 생명주기를 중심으로 클라이언트를 구축하세요.

1단계 — 제출

모델 엔드포인트에 작업을 POST합니다. 성공적인 제출은 작업 식별자를 반환합니다. 즉시 해당 ID를 영속화하세요. 이는 작업을 조작하는 유일한 핸들이며 폴링과 지원 요청에 사용됩니다.

2단계 — 폴링

해당 ID로 작업 상태를 GET합니다. 상태 필드는 다음 세 가지 중 하나를 알려줍니다:

  • 대기 중 또는 큐에 있음: 수락되었지만 아직 시작되지 않음. 계속 기다립니다.
  • 처리 중 또는 실행 중: 진행 중. 계속 기다리되 백오프를 사용합니다.
  • 종료 상태: 성공 또는 실패. 폴링을 중지합니다.

폴링 루프는 출력 필드 존재 여부만 확인하지 말고 종료 상태를 명시적으로 검사해야 합니다. 실패한 작업에는 결과가 없으므로 "결과 없음"을 "아직 실행 중"으로 처리하면 무한 루프에 빠집니다.

3단계 — 결과 읽기

성공 시 응답에는 출력 위치가 포함되며, 일반적으로 생성된 영상의 URL입니다. 임시 URL 뒤의 생성 자산을 영구적으로 사용 가능한 것으로 간주하지 말고 자체 스토리지로 즉시 다운로드하세요.

폴링 규범

프로덕션 환경에서 안정성을 유지하는 두 가지 규칙:

  1. 엔드포인트를 마구 두드리지 말고 폴링 간 백오프를 적용하세요(1~2초에서 시작해 증가).
  2. 총 대기 시간을 제한하고 시간 초과를 작업 스레드가 영구적으로 차단되지 않도록 재시도 가능한 오류로 노출하세요.

각 실행마다 작업 ID, 제출된 파라미터, 최종 상태를 기록하세요. 문제가 발생하면 이 로그가 다른 사람에게 묻기 전에 대부분의 질문에 답할 수 있습니다.

실행 가능한 curl 요청

다음은 셸의 전체 흐름입니다. 작업을 제출하고 작업 ID를 추출한 다음 종료 상태에 도달할 때까지 폴링합니다.

#!/usr/bin/env bash
set -euo pipefail

BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"

# 1) 작업 제출
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "prompt": "종이배가 비 내리는 도시 거리를 떠내려가고 있다, 시네마틱",
    "reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
    "duration": 5,
    "aspect_ratio": "16:9"
  }')

echo "$SUBMIT"

TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"

# 2) 종료 상태까지 폴링
while true; do
  STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
  echo "status: $STATUS"

  case "$STATUS" in
    succeeded) echo "$STATUS_JSON"; break ;;
    failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
  esac

  sleep 3
done

이 스크립트를 각색할 때 두 가지 설명. 첫째, 모델 식별자와 엔드포인트 경로를 변수에 저장해 스크립트 가독성을 유지하세요. 둘째, 위 파싱은 jq 없이 Python만 사용하는데 Python이 거의 어디에나 있기 때문입니다. jq를 선호하면 교체해도 됩니다. 어느 쪽이든 핵심 동작은 같습니다: 제출 응답에서 작업 ID를 추출하고 종료 상태 값을 볼 때까지 상태를 폴링합니다.

동일한 요청(Python 버전)

아래 Python 클라이언트는 curl 흐름과 대응하지만 폴링 루프가 더 견고합니다: 준지수 백오프, 전체 시간 초과, 각 종료 상태의 명시적 처리.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"

HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

TERMINAL = {"succeeded", "failed", "cancelled"}


def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "reference_video_url": reference_video_url,
        "duration": duration,
        "aspect_ratio": "16:9",
    }
    r = requests.post(
        f"{BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["id"]


def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/videos/generations/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in TERMINAL:
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = submit_job(
        prompt="종이배가 비 내리는 도시 거리를 떠내려가고 있다, 시네마틱",
        reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
    )
    print("submitted:", task_id)
    result = wait_for_job(task_id)

    if result["status"] == "succeeded":
        print("output:", result.get("output"))
    else:
        print("job did not succeed:", result)

각색할 때 유지할 가치가 있는 부분: 종료 상태 집합, 상한이 있는 백오프, 분리된 제출 및 대기 함수. 실제 서비스에서는 두 프로세스로 분리합니다 — 요청 핸들러에서 제출하고 작업 ID를 저장한 뒤 워커가 폴링 — 느린 작업이 HTTP 응답을 차단하지 않도록.

흔한 장애 지점과 디버깅 방법

kling-3.0/motion-control의 대부분 통합 문제는 몇 가지 범주에 속합니다. 순서대로 확인하세요.

인증 및 모델 오류

401은 거의 항상 베어러 토큰이 없거나 잘렸거나 잘못된 환경에서 가져온 것을 의미합니다. 모델을 찾을 수 없음 오류는 model 문자열이 정확히 일치하지 않음을 의미합니다 — 슬래시로 구분된 식별자이므로 잘못된 문자 순서나 여분 공백은 설정에서 조용히 실패하고 API에서 크게 오류가 납니다.

참조 영상 사용 불가

작업이 수락되었지만 몇 분 후 참조 URL을 가져오지 못해 실패합니다. 빈도순 원인: 서명 URL이 처리 전에 만료됨; URL이 서비스가 보내지 않는 인증 헤더를 요구함; URL이 영상이 아닌 HTML(로그인 페이지 또는 오류 페이지)을 반환함. 네트워크 외부에서 일반 curl로 URL을 테스트하고 콘텐츠 유형을 확인하세요.

파라미터 형식 오류 또는 범위 초과

길이와 종횡비 설정이 문서 범위를 벗어나면 제출 시 거부되는데 이는 좋은 일입니다 — 즉시 오류를 받습니다. 발견을 위해 왕복할 필요 없도록 로컬에서 미리 검증하세요.

폴링 결함

두 가지 전형적 문제: 루프가 failed를 확인하지 않고 출력 필드만 검사하여 무한 루프에 빠짐; 그리고 sleep 없는 타이트 루프로 폴링하여 스스로 속도 제한에 걸림. 명시적 종료 상태 검사와 백오프를 추가하고 오류 보고서에 항상 작업 ID를 첨부하여 작업을 재구축하지 말고 조회하세요.

결과 URL 만료

영상은 생성했지만 임시 출력 URL만 저장했습니다. 작업 성공 후 즉시 출력을 자체 스토리지로 다운로드하세요. 반환된 URL은 영구 저장소가 아니라 가져오기 핸들로 취급하세요.

각 디버깅 세션을 시작할 때 정확한 요청 본문과 원시 응답 JSON을 먼저 기록하세요. 위의 거의 모든 문제는 이 두 자료에서 확인할 수 있습니다. 더 깊이 나아갈 준비가 되면 HiAPI.ai 문서의 다른 비디오 모델과 엔드포인트 참조를 확인하고 동일한 "먼저 제출 후 폴링" 클라이언트 형태를 유지하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기