Runway Gen-4.5 API는 어떻게 사용하나요? 5분 만에 첫 영상 만들기

TL;DR

• Runway Gen-4.5는 Runway의 비디오 모델로, HiAPI에는 텍스트→비디오와 이미지→비디오 두 진입점이 있습니다. 모델 페이지를 열면 온라인에서 바로 체험할 수 있고, 신규 가입 시 200 크레딧을 지급합니다.
• 두 진입점 모두 초당 $0.1715입니다: 5초 $0.8575, 8초 $1.372, 10초 $1.715.
• 호출 방식: POST /v1/tasks로 제출하고 taskId로 결과를 조회하며, 완성 영상은 output[0].url에 있습니다.

Runway Gen-4.5로 할 수 있는 것

• 5·8·10초 세 가지 길이: 8초면 푸시인, 오빗, 느린 상승 샷을 한 번에 담기에 딱 좋습니다.
• 720p 고정: 가로 1280×720, 세로 720×1280, 해상도를 선택할 필요가 없습니다.
• 이미지→비디오는 5가지 화면비: 16:9, 9:16, 4:3, 3:4, 1:1로 같은 이미지로 여러 플랫폼용 버전을 만들 수 있습니다.
• 완성 영상에는 오디오 트랙이 없음: 화면은 모델에 맡기고 사운드는 편집할 때 일괄로 추가하세요.

She turns her head toward the camera and smiles, hair moves in a light breeze, slow push-in

이 프롬프트로 생성하기 → (인물 첫 프레임을 업로드하고 5초, 3:4 선택)

runway-gen-4.5/image-to-video, 3:4, 832×1104, 5초, $0.8575. 첫 프레임: .

그녀가 옆얼굴에서 카메라 쪽으로 고개를 돌려 미소 짓고, 머리카락이 살랑이며, 카메라가 얼굴 클로즈업까지 밀고 들어갑니다. 프롬프트에는 동작과 카메라 무빙만 적었고, 인물의 외형과 창가의 빛은 모두 첫 프레임에서 온 것입니다.

두 진입점 선택법

모델 ID	입력	길이	화면비	적합
runway-gen-4.5/text-to-video	프롬프트	5 / 8 / 10초 (9:16은 5 / 10만)	16:9, 9:16	소재가 없고 텍스트에서 시작
runway-gen-4.5/image-to-video	첫 프레임 1장 + 프롬프트	5 / 8 / 10초	16:9, 9:16, 4:3, 3:4, 1:1	주체가 원본 이미지와 일치해야 하거나 정사각형, 4:3, 3:4가 필요할 때

두 진입점은 동일 가격이며, 모두 초당 $0.1715입니다.

두 가지 시작 경로

브라우저에서 체험 (3단계)

1. 텍스트→비디오 또는 이미지→비디오 모델 페이지를 열고 로그인합니다.
2. 프롬프트를 작성하고, 이미지→비디오는 먼저 첫 프레임을 업로드합니다.
3. 5초와 화면비를 선택하고 실행을 클릭합니다.

API로 호출 (3단계)

1. 콘솔의 API Key 페이지에서 키를 생성해 환경 변수 HIAPI_KEY에 넣습니다.
2. POST https://api.hiapi.ai/v1/tasks로 제출하고 data.taskId를 받습니다.
3. GET /v1/tasks/{taskId}로 status가 success인지 확인하고 output[0].url을 다운로드합니다.

curl: 첫 번째 영상

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway-gen-4.5/text-to-video",
    "input": {
      "prompt": "A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

5초, 16:9, $0.8575. 완성 영상은 다음과 같습니다:

A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting

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

runway-gen-4.5/text-to-video, 16:9, 1280×720, 5초, $0.8575.

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(model, timeout_s=900, **inp):
    # 같은 작업을 재시도할 때 같은 Idempotency-Key를 사용해 중복 청구를 방지
    r = requests.post(API, json={"model": model, "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"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 이미지→비디오: 같은 이미지로 1:1 버전, 8초 ($1.372)
url = generate(
    "runway-gen-4.5/image-to-video",
    prompt="The scene slowly comes alive: clouds drift, light shifts across the mountain lake, gentle forward camera move",
    image_urls=["https://당신의 이미지 호스팅/lake.jpg"],
    duration=8, aspect_ratio="1:1",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

파라미터 표

필드	필수	값	설명
prompt	예	1–1000자	주체, 동작, 카메라를 작성; 이미지→비디오는 동작과 카메라만 작성
duration	아니오	5 (기본값) / 8 / 10	텍스트→비디오 9:16은 5 / 10만
aspect_ratio	아니오	텍스트→비디오: 16:9 (기본값) 9:16; 이미지→비디오: 16:9 (기본값) 9:16 4:3 3:4 1:1	이미지→비디오 첫 프레임은 화면비에 맞춰 중앙 크롭
image_urls	이미지→비디오 필수	1장만, jpeg/png/webp, ≤10MB	첫 프레임; 텍스트→비디오는 이 필드를 받지 않음

resolution, seed, negative_prompt는 없고, 마지막 프레임도 없습니다.

만나게 될 오류

제출 시 파라미터가 잘못되면 API가 바로 400을 반환하며, 작업을 생성하지 않고 비용도 청구하지 않습니다:

• duration: value must be one of 5, 10: 텍스트→비디오에서 9:16을 선택하고 8초를 전달했습니다.
• duration: value must be one of 5, 8, 10: 길이는 이 세 가지뿐입니다.
• image_urls: maxItems: got 2, want 1: 이미지→비디오는 첫 프레임 1장만 받으며 마지막 프레임은 지원하지 않습니다.
• image_urls: missing required field "image_urls": 이미지→비디오에서 첫 프레임을 전달하지 않았습니다.
• prompt: maxLength: got 3,000, want 1,000: 프롬프트는 최대 1000자입니다.
• additional properties 'negative_prompt', 'cfg_scale' not allowed: 이 두 필드는 Runway Gen-4.5에 존재하지 않습니다.

출시 전 주의사항

• 폴링 대신 콜백 사용: 요청 최상위(즉 input과 같은 레벨)에 "callback": {"url": "https://당신의 도메인/hiapi/callback"}를 추가하고 taskId로 중복을 제거하세요.
• 즉시 전송: output[0].url은 약 7일 후 만료되므로 받는 즉시自己的 스토리지에 저장하세요.
• duration과 aspect_ratio를 명시적으로 작성: 세로형 텍스트→비디오는 8초를 피해야 하므로 코드에 고정하는 것이 가장 안정적입니다.
• 재시도 시 멱등 키 사용: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 작업이 한 번만 생성됩니다.

자주 묻는 질문

1080p나 4K로 만들 수 있나요?

아니요, 출력은 720p로 고정됩니다. 1080p가 필요하면 Kling 2.5 Turbo를 사용할 수 있으며, Runway Gen-4.5와 Kling 2.5 Turbo 비교를 참고하세요.

완성 영상에 소리가 있나요?

아니요, 출력에는 화면만 있습니다. 배경 음악, 효과음, 내레이션은 편집할 때 추가하세요.

이미지→비디오에 마지막 프레임을 추가할 수 있나요?

아니요, image_urls는 1장만 받습니다. 마지막 프레임으로 결말을 제어하려면 Kling 2.5 Turbo 이미지→비디오를 사용하세요.

첫 프레임 비율과 화면비가 다르면 어떻게 되나요?

첫 프레임은 선택한 화면비에 맞춰 중앙 크롭되므로 주체를 중앙에 두는 것이 가장 안정적입니다.

가격 상세는 Runway Gen-4.5 API 가격을, 더 많은 사례는 Runway Gen-4.5 프롬프트 모음을 참고하세요. 먼저 결과를 보고 싶다면 위의 등대 프롬프트를 복사해 모델 페이지에서 첫 번째 영상을 생성하세요.