API 레퍼런스

비디오 생성

요약

텍스트 프롬프트에서 비디오를 생성하는 비동기 API입니다.

Google Veo 등 최신 비디오 생성 모델을 사용하여 고품질 영상을 만들 수 있습니다. 비디오 생성은 작업 제출 → 상태 폴링 → 다운로드의 3단계로 진행됩니다.

공식 레퍼런스: Google Veo (Vertex AI)

참고

비디오 생성은 일반적으로 30~120초가 소요됩니다. 폴링 간격은 10초를 권장합니다.

operation_id에 슬래시가 포함될 수 있습니다 — 전체 문자열을 그대로 전달하세요
폴링 및 다운로드 URL에 ?model=<모델명>을 반드시 추가하세요 (예: ?model=veo-3.1-fast-generate-preview). 없으면 400 에러가 반환됩니다.

엔드포인트

Method	Path	설명
POST	`/v1/gateway/video/generation/`	비디오 생성 작업 시작
GET	`/v1/gateway/video/generation/{operation_id}/`	작업 상태 폴링
GET	`/v1/gateway/video/generation/{operation_id}/download/`	완성된 비디오 다운로드

1. 비디오 생성 시작

POST

/v1/gateway/video/generation/

비동기 비디오 생성 작업을 시작합니다.

파라미터

model

string

required

비디오 모델 이름 (예: veo-3.1-fast-generate-preview, fal-ai/kling-video/v3).

prompt

string

required

생성할 비디오에 대한 텍스트 설명.

parameters

object

모델별 파라미터 (종횡비, 길이 등).

input_urls

array

입력 이미지/비디오 URL (이미지-투-비디오 모델용).

응답


json
{
  "operation_id": "models/veo-3.1-fast-generate-preview/operations/u15jum6vbdpc",
  "status": "processing"
}

2. 상태 폴링

GET

/v1/gateway/video/generation/{operation_id}/

Query Parameter

model

string

required

비디오 생성 시 사용한 모델 이름 (예: veo-3.1-fast-generate-preview). 이 파라미터가 없으면 400 에러가 반환됩니다.

Google Veo — video_uri가 상대 경로(다운로드 엔드포인트)로 반환됩니다:


json
{
  "operation_id": "models/veo-3.1-fast-generate-preview/operations/u15jum6vbdpc",
  "status": "completed",
  "video_uri": "/v1/gateway/video/generation/models/veo-3.1-fast-generate-preview/operations/u15jum6vbdpc/download/?model=veo-3.1-fast-generate-preview",
  "duration_seconds": null
}

Fal/Replicate 제공업체 — video_uri가 직접 다운로드 가능한 CDN URL로 반환됩니다:


json
{
  "operation_id": "xai/grok-imagine-video::5e94b562-ee6c-47be-973c-6546e70b7175",
  "status": "completed",
  "video_uri": "https://v3b.fal.media/files/.../video.mp4",
  "duration_seconds": null
}

Status	의미
`processing`	작업 진행 중
`completed`	비디오 준비 완료
`failed`	생성 실패

3. 비디오 다운로드

GET

/v1/gateway/video/generation/{operation_id}/download/

Query Parameter

model

string

required

비디오 생성 시 사용한 모델 이름 (예: veo-3.1-fast-generate-preview). 이 파라미터가 없으면 400 에러가 반환됩니다.

video/mp4 바이트를 직접 스트리밍합니다.

전체 흐름 (Python)


python
import time
import httpx

API_KEY = "YOUR_API_KEY"
BASE = "https://factchat-cloud.mindlogic.ai/v1/gateway"
client = httpx.Client(headers={"Authorization": f"Bearer {API_KEY}"}, timeout=120.0)

# 1. 시작
resp = client.post(f"{BASE}/video/generation/", json={
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "A serene mountain lake at sunrise",
})
operation_id = resp.json()["operation_id"]

# 2. 폴링
while True:
    status = client.get(f"{BASE}/video/generation/{operation_id}/", params={"model": "veo-3.1-fast-generate-preview"}).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(10)

# 3. 다운로드
resp = client.get(f"{BASE}/video/generation/{operation_id}/download/", params={"model": "veo-3.1-fast-generate-preview"})
with open("output.mp4", "wb") as f:
    f.write(resp.content)

사용 가능한 모델

모델	제공업체	크레딧/비디오	주요 파라미터
`veo-3.1-fast-generate-preview`	Google	600	`duration_seconds` (4/6/8), `aspect_ratio` (16:9, 9:16)
`veo-3.1-generate-preview`	Google	1,600	`duration_seconds` (4/6/8), `aspect_ratio` (16:9, 9:16)
`kwaivgi/kling-v2.5-turbo-pro`	Kling (Replicate)	350	`duration` (5/10), `aspect_ratio`
`xai/grok-imagine-video`	xAI (Fal)	300	`duration` (1–15초), `resolution` (480p/720p), `aspect_ratio`
`bytedance/seedance-1-pro`	ByteDance (Replicate)	60	`duration` (2–12초), `resolution` (480p/720p/1080p), `aspect_ratio`
`pixverse/pixverse-v5`	PixVerse (Replicate)	300	`duration` (5/8), `quality` (360p–1080p), `aspect_ratio`
`minimax/hailuo-02`	MiniMax (Replicate)	270	`duration` (6초 고정), `resolution` (768p/1080p)

모든 모델은 텍스트-투-비디오와 이미지-투-비디오(1개 입력 이미지, input_urls 사용)를 모두 지원합니다.

테넌트에 따라 일부 모델이 활성화되지 않을 수 있습니다. 활성화되지 않은 모델을 사용하면 403 에러가 반환됩니다 — 관리자에게 문의하세요.

마지막 수정 날짜: Mar 05, 2026

/images/generate

에러