Runway ML API은(는) 무엇을 하나요?
개요
Runway의 Gen-3 Alpha Turbo 모델은 텍스트 프롬프트나 이미지로부터 고품질 비디오를 생성합니다. REST API는 비동기 작업 패턴을 따릅니다. 작업 생성 → 완료 폴링 → 결과 다운로드 단계로 구성됩니다. 시네마틱 클립 제작, 이미지 애니메이션, 자동화된 비디오 콘텐츠 파이프라인 구축에 사용하세요.
설정
pip install requests python-dotenv
export RUNWAY_API_KEY="your_api_key_here"
기본 URL: https://api.dev.runwayml.com/v1
API 문서: https://docs.runwayml.com
핵심 개념
- 작업: 비동기 비디오 생성 작업입니다. 즉시
task_id를 반환합니다. - Gen-3 Alpha Turbo: 가장 빠른 Gen-3 모델입니다. 프로덕션 파이프라인에 최적입니다.
- 이미지-투-비디오 (
gen3a_turbo): 정적 이미지에 움직임을 부여합니다. - 텍스트-투-비디오: 텍스트 프롬프트만으로 비디오를 생성합니다.
- 길이: 5초 또는 10초.
- 비율:
1280:720(가로),720:1280(세로),1104:832,832:1104,960:960(정사각형).
사용 방법
1단계: 클라이언트 설정
import os
import time
import requests
API_KEY = os.environ["RUNWAY_API_KEY"]
BASE_URL = "https://api.dev.runwayml.com/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-Runway-Version": "2024-11-06"
}
2단계: 텍스트-투-비디오 생성
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""텍스트-투-비디오 작업을 제출하고 task_id를 반환합니다."""
payload = {
"model": "gen3a_turbo",
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = text_to_video(
prompt_text="황금 시간대 안개 낀 산골짜기 위를 나는 드론 샷, 시네마틱, 슬로우 모션",
duration=5,
ratio="1280:720"
)
print(f"작업 제출됨: {task_id}")
3단계: 이미지-투-비디오 생성
import base64
from pathlib import Path
def image_to_video(
image_path: str,
prompt_text: str = "",
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""이미지를 비디오로 애니메이션합니다. image_path는 로컬 파일 또는 URL일 수 있습니다."""
if image_path.startswith("http"):
prompt_image = image_path
else:
# 로컬 파일을 데이터 URI로 인코딩
img_bytes = Path(image_path).read_bytes()
ext = Path(image_path).suffix.lstrip(".").lower()
mime = {"jpg": "image/jpeg", "jpeg": "image/jpeg", "png": "image/png", "webp": "image/webp"}.get(ext, "image/png")
b64 = base64.b64encode(img_bytes).decode()
prompt_image = f"data:{mime};base64,{b64}"
payload = {
"model": "gen3a_turbo",
"promptImage": prompt_image,
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = image_to_video(
image_path="product_shot.png",
prompt_text="제품이 천천히 회전하고, 반짝이는 입자가 주위를 떠다니며, 고급스러운 느낌",
duration=5,
ratio="1280:720"
)
print(f"작업 제출됨: {task_id}")
4단계: 작업 상태 폴링
def get_task(task_id: str) -> dict:
r = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
r.raise_for_status()
return r.json()
def wait_for_task(task_id: str, poll_interval: int = 5, timeout: int = 600) -> list[str]:
"""작업이 완료될 때까지 폴링하고 출력 비디오 URL 목록을 반환합니다."""
start = time.time()
while True:
task = get_task(task_id)
status = task["status"]
progress = task.get("progress", 0)
print(f"[{int(time.time()-start)}s] 상태: {status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # 비디오 URL 목록
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"작업 {status}: {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"{timeout}초 후에도 작업이 완료되지 않았습니다.")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"비디오 준비 완료: {output_urls}")
5단계: 결과 다운로드
def download_video(url: str, output_path: str = "output.mp4") -> str:
r = requests.get(url, stream=True)
r.raise_for_status()
with open(output_path, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
size_mb = os.path.getsize(output_path) / 1024 / 1024
print(f"저장됨: {output_path} ({size_mb:.1f} MB)")
return output_path
download_video(output_urls[0], "mountain_valley.mp4")
전체 파이프라인 예제
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""한 번에 수행: 텍스트로 비디오를 생성하고 다운로드합니다."""
print(f"생성 중: {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# 제품 광고 클립 생성
generate_and_download(
prompt="흰색 책상 위의 세련된 스마트폰 클로즈업, 화면이 켜지고, 부드러운 카메라 후퇴",
output_path="product_ad.mp4",
duration=5,
ratio="1280:720"
)
파라미터 참조
| 파라미터 | 값 | 설명 |
|---|---|---|
model | gen3a_turbo | Gen-3 Alpha Turbo 사용 (가장 빠름) |
duration | 5, 10 | 비디오 길이 (초) |
ratio | 1280:720, 720:1280, 1104:832, 832:1104, 960:960 | 해상도 종횡비 |
seed | 정수 | 결정론적 출력을 위한 재현성 시드 |
promptText | 문자열 | 원하는 비디오를 설명하는 텍스트 프롬프트 |
promptImage | URL 또는 데이터 URI | 이미지-투-비디오의 시작 이미지 |
가이드라인
- Runway 작업은 길이와 부하에 따라 30~120초가 소요됩니다.
- 출력 URL은 일정 시간 후 만료됩니다. 생성 후 즉시 비디오를 다운로드하세요.
- 프롬프트를 설명적이고 시네마틱하게 작성하세요: 카메라 움직임, 조명, 분위기를 포함하세요.
- 프롬프트를 반복할 때 동일한 결과를 재현하려면
seed를 사용하세요. - 일괄 생성 시 작업을 병렬로 큐에 추가하되, 속도 제한을 준수하세요 (HTTP 429 확인 후
Retry-After헤더 값에 따라 재시도). - API 키는 환경 변수에 저장하고, 하드코딩하지 마세요.
- 최신 모델 이름과 엔드포인트는 빠르게 변경될 수 있으므로 https://docs.runwayml.com을 확인하세요.