Runway API 텍스트 투 비디오: hiapi를 통해 Gen-4.5를 호출하는 개발자 가이드

관리형 텍스트 투 비디오 엔드포인트를 사용하는 이유

텍스트 투 비디오는 이미지 생성이나 편집 파이프라인의 대체물이 아닙니다. 그것은 서로 다른 기초 능력입니다. 이미지 모델은 정지 프레임을 주며, 당신은 그것을 자르거나 보정하거나 합성할 수 있습니다. 텍스트 투 비디오 호출은 움직임을 줍니다: 카메라 무빙, 피사체 동작, 그리고 시간에 따라 변하는 빛. 당신의 제품에 비디오 클립이 필요하다면 — 짧은 마케팅 장면, 앱 내 배경 루프, 어떤 장면의 미리보기 — 단 한 번의 '요청에서 클립까지' 호출이 종종 아이디어에서 소재까지 가장 빠른 경로입니다.

대가는 제어력입니다. 당신은 키프레임으로 움직임을 설정하는 대신 텍스트로 움직임을 묘사하므로, 모델이 스스로 해석해야 합니다. 이는 프롬프트 품질이 이미지 작업에서보다 더 중요해지고, 반복 루프가 일회성 시도보다 더 중요해진다는 뜻입니다.

hiapi를 통해 제공되는 관리형 엔드포인트는 이 기초 능력 주변의 인프라 작업을 없애줍니다: 일관된 인터페이스, 하나의 자격 증명 모델, 그리고 호출하는 비디오 모델들 사이에서 통일된 응답 구조를 얻습니다. 당신은 저장 파이프라인, 작업 폴링, 각종 SDK 대신 프롬프트와 제품 통합에 시간을 씁니다.

적합한 경우:

• 사용자 입력이나 템플릿에 따라 온디맨드로 생성되는 짧은 영상
• 전체 프로덕션 파이프라인에 투자하기 전의 빠른 콘셉트 탐색
• 배경 및 B-roll 소재 — 특정 생성이 약간 흠이 있어도 여전히 쓸 수 있는 경우

부적합한 경우: 프레임 단위의 정확한 연속성, 결정론적 출력 또는 장편 서사적 일관성이 필요한 모든 요구. 사용 가능한 결과마다 여러 후보 클립의 예산을 잡으세요.

runway-gen-4.5/text-to-video 엔드포인트의 구조

개념적으로 runway-gen-4.5/text-to-video로 가는 요청은 세 부분으로 구성됩니다: 프롬프트, 요청 수준 설정, 그리고 당신의 신원/인증. 창의적인 것은 첫 번째 부분뿐이며, 나머지 두 부분은 모델이 어떻게 실행되고 어떻게 과금되는지를 결정합니다.

당신이 보내는 것

• 프롬프트 문자열. 주요 창의적 입력 — 자연어로 피사체, 동작, 카메라, 조명, 분위기를 묘사합니다.
• 요청 수준 설정. 화면 비율, 길이, 그리고 엔드포인트가 노출하는 모든 생성 플래그. 이들은 출력의 컨테이너 형태를 결정하며, 내용은 아닙니다.
• 인증 헤더. 매 호출마다 함께 보내는 당신의 hiapi 키. 기밀로 취급하고 클라이언트 코드에 절대 공개하지 마세요.

당신이 받는 것

비디오 생성은 즉각적이지 않으므로, 엔드포인트 호출 방식에 따라 폴링해야 하는 작업 핸들을 받거나 미디어 URL로 해석되는 응답을 받을 수 있습니다. 어느 경우든, 당신이 받는 것은 생성된 클립에 대한 참조이지 인라인 원시 바이트가 아닙니다. 반환된 URL의 유효 기간 이후에도 소재를 계속 사용해야 한다면, 그것을 다운로드해 자신의 저장소에 영구 보관하세요.

유용한 사고 모델: 이 엔드포인트는 (prompt, settings)를 클립과 메타데이터로 매핑하는 함수입니다. 당신의 통합은 그것을 비동기적이고 재시도 가능하며 비결정론적으로 취급해야 합니다 — 같은 입력이 항상 같은 클립을 만들지는 않으며, 이는 예상된 동작이지 결함이 아닙니다.

요청 구성은 단순하고 지루하게 유지하세요. 요청 본문을 조립하고, 인증을 붙이고, 호출을 보내고, 응답을 { status, videoUrl, error }로 정규화하는 작은 내부 래퍼를 작성하세요. 이 가이드의 이후 모든 섹션은 이 래퍼가 이미 존재한다고 가정합니다.

움직임 속에서도 성립하는 영화적 프롬프트 작성

모호한 형용사는 움직임 속에서 무너집니다. "A beautiful cinematic shot of a city"는 모델에게 애니메이션할 어떤 것도 주지 않으므로, 그것은 다소 일반적이고 흐릿한 화면을 생성합니다. 해결책은 촬영감독에게 필요한 네 가지 요소를 명시하는 것입니다: 피사체, 카메라, 조명, 그리고 움직임.

피사체와 동작을 지목하기

화면에 무엇이 있는지, 그리고 그것이 클립 내내 무엇을 하는지 설명하세요. 시작점과 암시된 종료점을 제시하여 모델이 따라갈 움직임 궤적을 갖게 하세요.

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

카메라를 명확하게 지정하기

모델이 움직임으로 매핑할 수 있는 카메라 언어를 사용하세요: 느린 돌리 인, 고정 와이드, 핸드헬드 팔로우, 로우 앵글 트래킹, 느린 오른쪽 팬, 항공 하강. 클립당 하나의 카메라 무빙이 서로 충돌하는 세 개보다 안전합니다.

Static wide shot, camera at ground level, no zoom.

조명과 시간을 지정하기

조명은 인지되는 제작 수준의 대부분을 결정합니다. 광원과 질감을 제시하세요: 흐린 확산 일광, 렌즈 왼쪽에서 오는 강한 오후 햇살, 밤의 젖은 반사 속 실제 네온.

물리적으로 그럴듯한 움직임 묘사하기

짧은 클립에서 빠른 움직임은 잔상으로 뭉개집니다. 많은 빠른 사건보다 중간 속도의 단일하고 읽히는 동작을 선호하세요. 긴장감을 원한다면, 십여 가지 일이 동시에 일어나게 하는 대신 카메라 무빙과 조명에서 얻으세요.

한 단락으로 유지하기

한두세 문장의 촘촘한 단락이 불릿 형태의 사양 목록보다 낫습니다. 소망 목록이 아니라 촬영 묘사로 쓰세요. 스타일 형용사를 겹치지 말고, 한 가지 룩을 고르고 끝까지 유지하세요.

신뢰할 수 있는 템플릿:

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

어떤 설정도 바꾸기 전에, 먼저 프롬프트를 이 템플릿에 맞게 다시 쓰세요.

실행 가능한 요청, 단계별 설명

이 워크스루는 Node.js와 래퍼 함수를 가정하지만, 구조는 특정 언어에 의존하지 않습니다.

1단계: 촬영 묘사 작성

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

2단계: 요청 설정 선택

클립이 최종적으로 사용될 위치에 맞는 화면 비율과, 이야기를 전달할 수 있는 가장 짧은 길이를 선택하세요. 짧은 클립은 빨리 실패하고 탐색 비용도 더 낮습니다.

3단계: 호출 보내기

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

4단계: 클립 가져오기

응답이 작업 핸들을 담고 있다면, 종료 상태에 도달할 때까지 작은 백오프 간격으로 폴링하세요. 미디어 URL을 직접 담고 있다면 5단계로 건너뛰세요.

5단계: 소재 영구 저장

클립을 다운로드하고 자신의 키로 저장하세요. 반환된 URL은 임시 주소로 취급하세요.

6단계: 의사 결정 지점 기록

프롬프트, 설정, 생성된 소재를 함께 기록하세요. 바로 이 로그가 다음 섹션인 튜닝을 추측이 아닌 실행 가능한 것으로 만듭니다.

프롬프트를 바꾸지 않고 출력 튜닝하기

클립이 실망스러울 때 본능적인 반응은 프롬프트를 다시 쓰는 것입니다. 한 번은 참으세요. 프롬프트와 설정은 독립적인 변수이며, 둘 다 동시에 바꾸면 무엇이 핵심이었는지 판단하는 능력을 잃게 됩니다.

변수 격리하기

프롬프트는 고정하고 요청 수준 설정 하나만 바꾸세요 — 화면 비율, 길이 또는 특정 생성 플래그. 다시 실행하세요. 클립이 개선되면 문제는 창의적 층위가 아니라 구조적 층위에 있었던 것입니다. 개선되지 않으면 그 설정을 되돌리고 프롬프트를 수정하세요.

설정으로 구조적 문제 해결하기

• 구도가 배치 위치와 맞지 않나요? 화면 비율을 바꾸세요.
• 동작이 완료되기 전에 잘리나요? 길이를 늘리세요.
• 모든 것이 흔들리며 고정점이 없나요? 클립을 줄여 흔들릴 시간 자체를 줄이세요.

프롬프트 수정으로 내용 문제 해결하기

• 피사체가 잘못되었거나 없나요? 더 앞에서 지목하고 구체적으로 만드세요.
• 카메라가 떠도나요? 원하는 하나의 움직임을 제외한 모든 카메라 관련 단어를 삭제하세요.
• 밋밋하고 생기 없나요? 광원과 방향을 추가하세요.

작은 A/B 테스트하기

시드 프롬프트를 고정하고 세 가지 변형을 생성하되, 각각은 한 절만 바꾸세요. 기억이 아니라 나란히 비교하세요. 비결정론은单个 나쁜 클립이 증거가 아님을 뜻합니다. 어떤 절이 해롭다고 단정하기 전에 두세 번의 실행에서 패턴을 찾으세요.

이미 유지하고 있는 로그에 결론을 적으세요. 십수 번의 반복을 거치면, 이것은 당신의 제품에 특화된 프롬프트와 설정 매뉴얼이 되어 어떤 일반 프롬프트 목록보다 큰 가치를 갖습니다.

흔한 실패 디버깅

첫 주의 실패 대부분은 네 가지 범주로 귀결됩니다. 각 범주의 조사 경로는 다릅니다.

요청 거부 또는 차단

정책 정보가 담긴 비2xx 응답은 프롬프트나 설정이 수용되지 않았음을 의미합니다. 무작정 재시도하지 말고 오류 응답 본문을 읽으세요. 문제가 된 묘사를 다시 쓰고, 실명한 실제 인물이나 브랜드를 제거한 뒤 다시 보내세요. 거부된 프롬프트를 있는 그대로 기록하세요 — 반복되는 거부는 대개 프롬프트 템플릿의 특정 습관으로 추적됩니다.

타임아웃

비디오 생성은 느립니다. HTTP 클라이언트가 엔드포인트가 응답하기 전에 타임아웃되면, 작업은 여전히 실행 중일 수 있고 과금됩니다. 생성 호출의 클라이언트 타임아웃을 늘리고, 요청을 매달아 두지 말고 폴링을 백그라운드 작업자로 옮기세요.

빈 클립 또는 사용 불가 클립

응답은 성공했으나 클립에 식별 가능한 피사체가 없는 경우는 대개 프롬프트가 지나치게 추상적이었음을 의미합니다. 피사체-카메라-조명-움직임 템플릿에 비추어 다시 읽으세요. 네 가지 중 하나가 빠졌다면 그것이 수정 지점입니다.

인증 및 구성 오류

401과 403은 프롬프트 문제가 아니라 키 문제입니다. 키가 로컬 셸이 아니라 런타임 환경에 존재하는지 확인하고, 헤더 형식을 확인하세요. 이런 실패는 일찍 발견할수록 비용이 적고, 프로덕션에서 발견할수록 비쌉니다.

일반 규칙 하나: 무언가를 바꾸기 전에 오류를 분류하세요. 프롬프트류 오류, 설정류 오류, 인프라류 오류는 서로 다른 수정 방식을 요구하며, 섞이면 생성 예산을 낭비합니다.

비용, 지연, 프로덕션 보호 장치

출시 전에 실패 시 엔드포인트의 동작을 먼저 정하세요. 비디오 생성은 대부분의 제품에서 가장 비싸고 느린 호출이기 때문입니다.

호출 단위가 아닌 클립 단위로 예산 잡기

비디오 과금은 보통 출력 길이에 연동되므로, 긴 클립이 짧은 클립보다 비쌉니다. API 호출 횟수를 세는 대신, 완성된 클립 단위로 예산을 잡으세요 — 재시도와 거부된 후보 포함. 사용자별 및 세션별 생성 상한을 두세요. 현재 요율은 가격 패널을 참조하고, 비즈니스 로직에 하드코딩하지 마세요.

지연을 고려한 설계

사용자 대상 요청이 생성에 블로킹되게 절대 두지 마세요. 작업을 시작하고 즉시 핸들을 반환하며, 폴링, 웹훅 또는 알림을 통해 클립을 전달하세요. UI에 진행 상황을 표시해 느린 렌더링이 멈춘 것이 아니라 진행 중인 작업으로 읽히게 하세요. 프롬프트와 설정으로 생성된 클립을 캐시해 중복 재생성을 피하세요.

생성 전 검증

호출 전의 저렴한 검사가 호출 후의 비싼 처리를 아낍니다:

• 래퍼에서 프롬프트의 최소 및 최대 길이를 강제하기
• 피사체나 동작이 빠진 프롬프트 거부하기
• 렌더링 대상에 맞춰 화면 비율 검증하기
• 사용자가 자신의 할당량 내에 있는지 확인하기

입구와 출구 모두 검수하기

보내기 전에 프롬프트에 텍스트 검사를 하세요. 표시하기 전에 반환된 클립에 가벼운 검사를 하세요. 둘 다 한 번의 지원 사고보다 저렴합니다.

폴백 유지

생성이 실패하거나 너무 오래 걸리면, 오류 대신 정적 커버 프레임이나 플레이스홀더 클립을 제공하세요. 기능은 중단이 아니라 저하되어야 합니다.

하나의 엔드포인트, 하나의 래퍼, 하나의 로그로 시작하고, 제품이 실제로 어디서 실패하는지 알게 되면 보호 장치를 점진적으로 추가하세요. 그리고 가격 패널은 항상 비용의 단일 진실 공급원이 되게 하세요.