목표: 한 번의 API 호출로 짧은 영상(텍스트→비디오)을 만들고, 작업 상태를 폴링해 산출물을 저장·배포하는 프로덕션용 스캐폴딩을 만든다.

1) 무엇을 선택할까? — 모델/플랫폼 한눈 비교

Veo 3.1 (Google, Gemini API/Vertex AI)
- 최신 영상 생성 모델. 8초 길이, 720p/1080p, 네이티브 오디오 포함, 텍스트/이미지 프롬프트 모두 지원. “프롬프트 충실도·사실감·오디오”가 강화됨. (Google AI for Developers)
- Gemini API와 Vertex AI에서 공식 문서/레퍼런스 제공. (Google AI for Developers)
Runway API (Gen-4, Gen-4 Turbo 등)
- REST API로 텍스트→비디오, 이미지→비디오, 비디오 업스케일 등 폭넓은 생성·편집 기능. 비동기 태스크 생성→상태 조회→결과 수령 구조. (Runway API)
- 브라우저 도구/워크플로우 강점 + 안정적 문서화. (Runway API)

결론 요약:
**짧고 고품질 “생성 그 자체”**는 Veo 3.1이 강하고, 편집/후반/워크플로우 통합은 Runway가 유리하다. 두 개를 역할 분담으로 병행하는 설계가 합리적이다.

2) 공통 아키텍처(운영 설계) — 실전에 필요한 것들

비동기 태스크 관리: 작업 생성 → job_id 저장 → 상태 폴링(Webhook/주기 폴링) → 완료 시 아웃풋 저장. (Runway는 폴링 구조가 기본) (Runway API)
스토리지/배포: 원본 MP4는 오브젝트 스토리지(GCS/S3)에 저장, 썸네일 생성 → CDN 배포.
프롬프트 버전관리: 프롬프트/시드/매개변수/모델 버전을 DB에 기록해 재현성 확보.
비용/제약 관리: 길이, 해상도, 큐 대기, 동시성 한도, 리트라이·백오프. (Gemini/Vertex AI 정책 문서 참고) (Google AI for Developers)
라이선스/안전 정책: 상업 이용·콘텐츠 정책 준수. (플랫폼 별 가이드 준수) (Google AI for Developers)

3) Veo 3.1 (Gemini API) — 최소 실행 코드

사전 준비

Google AI Studio 또는 GCP에서 API 키 발급

8초 720p/1080p 지원, 네이티브 오디오 가능. (세부 파라미터는 문서 참고) (Google AI for Developers)

A. Node.js (ESM)

npm i @google/generative-ai node-fetch

// veo31_text2video.js
import { GoogleGenerativeAI } from "@google/generative-ai";
import fs from "fs";

const API_KEY = process.env.GEMINI_API_KEY; // 환경변수로 관리
const genAI = new GoogleGenerativeAI(API_KEY);

// 모델 이름은 문서의 최신 “Veo 3.1” 변형을 확인해서 사용
const MODEL_NAME = "veo-3.1"; // 예시. 실제 사용 시 ai.google.dev 모델 목록 확인

async function main() {
  const model = genAI.getGenerativeModel({ model: MODEL_NAME });

  const prompt = `
  cinematic shot of a craftsman polishing a brushed aluminum panel,
  soft rim light, shallow depth of field, macro details, product beauty shot
  `;

  // 일부 SDK는 비디오 생성을 위해 전용 메서드/매개변수 사용. 문서 최신 예제를 반드시 참조.
  const res = await model.generateVideo({
    prompt,
    aspectRatio: "16:9",
    resolution: "1080p",
    durationSeconds: 8,
    audio: { enable: true }, // 네이티브 오디오
  });

  // 결과 객체에서 바이너리/URL을 받아 처리
  if (res?.video) {
    fs.writeFileSync("./out_veo31.mp4", Buffer.from(await res.video.arrayBuffer()));
    console.log("saved: out_veo31.mp4");
  } else if (res?.videoUrl) {
    console.log("video url:", res.videoUrl);
  } else {
    console.log("response:", res);
  }
}

main().catch(console.error);

참고: 실제 메서드/필드는 SDK 버전에 따라 다를 수 있다. 공식 문서의 최신 샘플을 우선한다. (Google AI for Developers)

B. Python (requests 예시)

pip install requests

# veo31_text2video.py
import os, requests

API_KEY = os.getenv("GEMINI_API_KEY")
ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models/veo-3.1:generateVideo"  # 예시 엔드포인트

payload = {
    "prompt": {
        "text": "hyper-realistic shot of a workshop assembling stone panels, dramatic lighting, 24fps"
    },
    "aspectRatio": "16:9",
    "resolution": "1080p",
    "durationSeconds": 8,
    "audio": {"enable": True}
}

r = requests.post(
    f"{ENDPOINT}?key={API_KEY}",
    json=payload,
    timeout=120
)
r.raise_for_status()
data = r.json()

# 실제 응답 스펙에 따라 파일/URL 추출
video_url = data.get("videoUrl")
if video_url:
    print("video url:", video_url)
else:
    print(data)

Veo 3.1의 길이/해상도/오디오/참조 이미지 옵션 등은 문서 ‘모델 파라미터’ 섹션에서 최신 상태 확인. Vertex AI 경유 시 엔드포인트/요청 형식이 다르므로 해당 레퍼런스 참조. (Google AI for Developers)

4) Runway API — 태스크 생성/폴링/다운로드

사전 준비

Runway 개발자 포털에서 API 토큰 발급

텍스트→비디오: POST /v1/text_to_video (모델·파라미터는 문서 확인) (Runway API)

A. cURL로 개념 잡기

# 작업 생성
curl -X POST "https://api.runwayml.com/v1/text_to_video" \
  -H "Authorization: Bearer $RUNWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gen4_turbo",
    "promptText": "cinematic close-up of a craftsman applying stone veneer, particles, shallow focus",
    "ratio": "16:9",
    "duration": 8
  }'

응답 예시(요약): { "id": "task_123", "status": "queued" }

# 상태 폴링
curl -H "Authorization: Bearer $RUNWAY_API_KEY" \
"https://api.runwayml.com/v1/tasks/task_123"

완료시 응답에 결과 URL(또는 asset 목록)이 포함된다. 문서 기준으로 실제 필드명 확인. (Runway API)

B. Node.js(폴링 스캐폴딩)

npm i node-fetch

// runway_text2video.js
import fetch from "node-fetch";
const API = "https://api.runwayml.com/v1";
const KEY = process.env.RUNWAY_API_KEY;

async function createTask() {
  const res = await fetch(`${API}/text_to_video`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gen4_turbo",
      promptText: "macro shot of brushed aluminum machining, cinematic particles, 24fps",
      ratio: "16:9",
      duration: 8
    })
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

async function pollTask(id, max = 90, interval = 4000) {
  for (let i = 0; i < max; i++) {
    const r = await fetch(`${API}/tasks/${id}`, {
      headers: { "Authorization": `Bearer ${KEY}` }
    });
    if (!r.ok) throw new Error(await r.text());
    const data = await r.json();
    if (data.status === "succeeded") return data;
    if (data.status === "failed") throw new Error(JSON.stringify(data));
    await new Promise(res => setTimeout(res, interval));
  }
  throw new Error("timeout");
}

(async () => {
  const task = await createTask();
  console.log("created:", task.id, task.status);
  const done = await pollTask(task.id);
  console.log("done:", done);

  // 결과 URL 저장 로직 (예: S3/GCS 업로드) 추가
  // done.assets?.[0]?.url 같은 경로는 문서의 실제 필드 확인
})();

Runway는 태스크 기반이라 폴링/웹훅이 핵심. SDK(예: @runwayml/sdk) 가이드도 제공되니 필요 시 채택. (Runway API)

5) 품질·비용·길이 팩트 체크(요약)

Veo 3.1
- 8초, 720p/1080p, 오디오, 텍스트/이미지 프롬프트, 제어 옵션(참조 이미지/스타트·엔드 프레임 등) 지원. (Google AI for Developers)
- 최근 수직(9:16) 지원·가격 인하 보도. 실제 청구는 콘솔/문서 기준 확인. (The Verge)
Runway
- 텍스트→비디오 외에도 이미지→비디오, 비디오 업스케일/편집 등 다수 엔드포인트. REST 인증 + 폴링 구조가 표준. (Runway API)

길이·해상도·요금은 수시 업데이트된다. 공식 문서/콘솔에서 현재 값을 항상 확인할 것. (Google AI for Developers)

6) 운영 팁 (실무 기준 체크리스트)

큐·동시성 제어: 초당/동시 요청 제한을 고려해 작업 큐와 레이트 리미터 적용. (Runway API)
리트라이 전략: 지수 백오프 + 멱등 키(Idempotency)로 중복 생성 방지. (Gemini/Vertex 정책 권고) (Google AI for Developers)
메타데이터 관리: 프롬프트/시드/모델/버전/파라미터/원본 이미지 해시까지 저장(재현성·A/B 테스트).
아카이브 정책: 원본·파생물·썸네일·캡션(자막) 분리 저장, 만료·정책 준수.

7) 언제 무엇을 쓰나 — 실전 선택 가이드

브랜딩 캠페인용 짧은 하이엔드 샷 → Veo 3.1 우선 검토. (프롬프트 충실도·오디오·시네마틱) (Google AI for Developers)
다양한 편집/업스케일/후반 워크플로우 → Runway API 중심. (여러 엔드포인트·협업) (Runway API)
혼합 전략: Veo로 생성 → Runway로 보정/트리밍/업스케일.

8) 마무리 — 바로 붙여 쓸 수 있는 “프로덕션 템플릿”

엔드포인트 래퍼: VideoJobService(create/poll/cancel), StorageService(upload/getURL), DB(jobs/prompts).
워크플로우: /jobs(POST 생성) → /jobs/:id(GET 상태) → 완료 시 웹훅으로 프런트에 알림.
옵스: 로깅·메트릭(성공률, 평균 대기/생성시간, 비용/초), 알람(Slack/Email).

이 글의 코드를 바로 리포지토리에 옮겨 .env(키), 스토리지 업로드 로직만 채우면 MVP가 돌아간다. 모델·요금·제약은 변동성이 크다. 항상 공식 문서의 최신 내용을 재확인하는 걸 전제로 운영하자. (Google AI for Developers)

참고 자료(공식·주요 문서)

Veo 3.1 개요·가이드(8초/720p·1080p·오디오, 모델 파라미터) (Google AI for Developers)
Veo 3.1 출시 공지(유료 미리보기, Gemini API/Vertex AI) (구글 개발자 블로그)
Gemini API 모델·레퍼런스(최신 엔드포인트/SDK) (Google AI for Developers)
Vertex AI Veo 비디오 생성 API 레퍼런스 (Google Cloud Documentation)
Runway API 레퍼런스/가이드(텍스트→비디오, 태스크/폴링) (Runway API)
Runway Gen-4 소개(모델 특성·워크플로우) (Runway)

🎓 AI 영상 자동화 용어 도움말

용어 설명

Veo 3.1	구글이 만든 최신 인공지능 영상 생성 모델. 텍스트(문장)만 입력하면 실제 같은 8초짜리 영상(720p~1080p)을 자동으로 만들어 준다. “AI가 감독한 짧은 영상”이라고 생각하면 쉽다.
Gemini API	구글이 개발자에게 제공하는 AI 인터페이스. Veo 3.1도 여기 안에 포함되어 있어서, 코드를 통해 영상이나 이미지를 자동으로 만들 수 있다.
Vertex AI	구글 클라우드(GCP)에서 제공하는 기업용 AI 플랫폼. Gemini/Veo 같은 모델을 더 안전하고 확장성 있게 쓸 수 있다.
Runway	‘Runway ML’이라는 AI 영상 제작 도구. 웹에서 쓰기 쉽고, 편집·효과·색보정 같은 후반작업 기능까지 제공한다. Gen-4, Gen-4 Turbo 모델로 유명하다.
API (Application Programming Interface)	프로그램끼리 연결되는 창구. 개발자가 “이 명령을 보내면 결과를 돌려줘”라고 요청할 수 있게 만든 표준 통로다.
REST API	인터넷을 통해 데이터를 주고받는 가장 보편적인 API 방식. HTTP(웹 요청)으로 작동한다.
엔드포인트(Endpoint)	API가 연결되는 실제 주소(URL). 예: https://api.runwayml.com/v1/text_to_video
API 키(API Key)	특정 사용자를 인증하기 위한 비밀열쇠. “내가 이 API를 사용할 권한이 있다”는 증명서 같은 역할.
프롬프트(Prompt)	AI에게 주는 명령문. “석공이 돌판을 다듬는 장면, 시네마틱하게”처럼 구체적인 문장일수록 좋은 결과를 얻는다.
텍스트-투-비디오(Text-to-Video)	텍스트로 설명한 장면을 영상으로 바꿔주는 기술.
이미지-투-비디오(Image-to-Video)	사진을 기반으로 이어지는 영상을 생성하는 기술.
비동기(Asynchronous)	요청을 보내고 기다리지 않고 다른 일을 먼저 처리하는 방식. AI 영상 생성은 시간이 걸리기 때문에 이런 구조를 쓴다.
폴링(Polling)	일정 간격으로 “끝났니?” 하고 계속 물어보는 방식. 영상 생성 완료 여부를 확인할 때 사용한다.
웹훅(Webhook)	작업이 완료되면 서버가 자동으로 알림을 보내주는 구조. 폴링 대신 효율적이다.
S3 / GCS	생성된 영상을 저장하기 위한 클라우드 저장소. S3는 아마존, GCS는 구글의 서비스다.
CDN (Content Delivery Network)	영상이나 이미지를 전세계 어디서나 빠르게 보여주기 위한 분산 서버망.
SDK (Software Development Kit)	API를 더 쉽게 쓰기 위한 도구 모음(라이브러리). Node.js나 Python용으로 제공된다.
Node.js / Python	API를 제어하는 대표적인 프로그래밍 언어 환경. 자동화 스크립트나 서버를 만들 때 주로 쓴다.
JSON	데이터 교환 형식. API 요청과 응답 대부분이 이 형식으로 주고받는다. 예: { "prompt": "a sunset" }
Fast GPU / Relax Mode	Midjourney처럼 GPU 사용시간이 제한된 경우, 빠르게 처리(Fast)하거나 느리지만 무제한(Relax)으로 생성할 수 있는 모드 구분.
Aspect Ratio (화면비율)	영상의 가로:세로 비율. 예: 16:9(가로형), 9:16(세로형).
Resolution (해상도)	영상의 선명도 단위. 720p, 1080p처럼 숫자가 높을수록 고화질.
Duration (길이)	생성될 영상의 시간 길이(초 단위).
Prompt Adherence (프롬프트 충실도)	입력한 문장을 얼마나 정확히 반영하느냐의 정도. Veo 3.1의 개선 포인트 중 하나.
비디오 Job(Task)	영상 생성 하나를 의미하는 단위. Runway API는 job ID를 발급하고 완료될 때까지 추적한다.
Idempotency(멱등성)	같은 요청을 여러 번 보내도 결과가 중복되지 않도록 하는 원리. 시스템 안정성 확보용.
백오프(Back-off)	실패 시 잠시 대기 후 재시도하는 기법. 서버 과부하 방지용.
메타데이터(Metadata)	영상의 부가 정보(프롬프트, 모델 버전, 해상도 등). 추후 재생성이나 기록 보관에 사용한다.
상업적 이용(License)	생성된 영상·이미지를 상업용으로 쓸 수 있는지에 대한 권한. 플랫폼 약관에서 확인 필요.

필요하면 이 표를 Notion/블로그 하단 도움말 섹션으로 넣을 수 있게 마크다운 포맷 그대로 export해드릴 수도 있어요.
원하시나요?

저작자표시 (새창열림)

My Coding World

Veo 3.1 · Runway API로 “텍스트 → 영상” 자동화 파이프라인 구축하기 (실전 코드 포함)