콘텐츠로 이동

Veo 모델 텍스트-투-비디오 API 문서

Veo는 Google이 개발한 고품질 텍스트-투-비디오 생성 모델입니다. 이 문서는 Google Veo 모델을 사용한 텍스트-투-비디오 생성의 전체 API 인터페이스 사양을 설명합니다.

지원 모델

현재 지원되는 모델:

모델 설명
veo-3.0-generate-001 Veo 3.0 텍스트-투-비디오 생성 모델
veo-3.0-fast-generate-001 Veo 3.0 고속 텍스트-투-비디오 생성 모델
veo-3.1-generate-preview Veo 3.1 텍스트-투-비디오 생성 모델 (프리뷰)
veo-3.1-fast-generate-preview Veo 3.1 고속 텍스트-투-비디오 생성 모델 (프리뷰)

개요

Veo 텍스트-투-비디오 기능은 비동기 작업 처리 메커니즘을 제공합니다:

  1. 작업 제출: 텍스트 프롬프트를 보내 비디오 생성 작업 생성
  2. 상태 조회: task ID로 생성 진행률/상태 조회
  3. 결과 획득: 작업 완료 후 생성 비디오 파일 획득

작업 상태 흐름

queued → in_progress → completed
                ↓
            failed
  • queued: 작업이 제출되어 처리 대기 중
  • in_progress: 작업이 처리 중
  • completed: 작업 성공 완료, 비디오 생성됨
  • failed: 작업 실패

API 목록

메서드 경로 설명
POST /v1/video/generations 비디오 생성 작업 제출 (표준 형식)
GET /v1/video/generations/{task_id} 작업 상태 조회 (표준 형식)
POST /v1/videos 비디오 생성 작업 제출
GET /v1/videos/{task_id} 작업 상태 조회
GET /v1/videos/{task_id}/content 비디오 콘텐츠 조회 (스트리밍 다운로드)

사용 예시

요청 본문

{
  "model": "veo-3.0-generate-001",
  "prompt": "A cat playing piano in a beautiful garden",
  "metadata": {
    "aspectRatio": "16:9",
    "durationSeconds": 8.0,
    "negativePrompt": "blurry, low quality",
    "personGeneration": "allow_all",
    "resolution": "1080p",
    "sampleCount": 1,
    "storageUri": "gs://your-bucket/path"
  }
}

요청 파라미터:

파라미터 유형 필수 설명
model string 예 모델 이름(예:) veo-3.0-generate-001
prompt string 예 생성할 비디오 콘텐츠를 설명하는 텍스트 프롬프트
metadata object 아니오 확장 파라미터 객체

metadata 파라미터:

파라미터 유형 필수 설명
aspectRatio string 아니오 비디오 종횡비, 옵션: "16:9", "9:16"
durationSeconds number 아니오 비디오 길이(초), 옵션: 4, 6, 8
negativePrompt string 아니오 비디오에서 원하지 않는 콘텐츠를 설명하는 네거티브 프롬프트
personGeneration string 아니오 인물 생성 전략, 옵션: "allow_all" (text-to-video), "allow_adult" (image-to-video)
resolution string 아니오 비디오 해상도(예:) "1080p", "720p"
sampleCount number 아니오 생성할 비디오 수, 기본값 1
storageUri string 아니오 생성 비디오 저장용 Google Cloud Storage URI

1. 비디오 생성 작업 제출

전체 요청:

curl -X POST "https://ssanai-workspace.atto-lab.cc/v1/video/generations" -H "Content-Type: application/json" -H "Authorization: Bearer API_KEY" -d @veoTest.json

엔드포인트:

POST /v1/video/generations

요청 헤더:

파라미터 유형 필수 설명
Content-Type string 예 application/json
Authorization string 예 Bearer API_KEY

응답 예시:

{
  "id": "TASK_ID",
  "task_id": "TASK_ID",
  "object": "video",
  "model": "veo-3.0-generate-001",
  "status": "",
  "progress": 0,
  "created_at": 1764616538
}

응답 필드 설명:

필드 유형 설명
task_id string 작업 ID (후속 작업 상태 조회용)
model string 비디오 생성에 사용된 모델

2. 작업 상태 조회

전체 표준 형식 엔드포인트

curl -X GET "https://ssanai-workspace.atto-lab.cc/v1/video/generations/TASK_ID" -H "Authorization: Bearer API_KEY"

엔드포인트:

GET /v1/video/generations/{task_id}

요청 헤더:

파라미터 유형 필수 설명
Authorization string 예 Bearer API_KEY

경로 파라미터:

파라미터 유형 필수 설명
task_id string 예 작업 ID

응답 예시 (처리 중):

{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "processing",
    "task_id": "TASK_ID",
    "url": ""
  }
}

응답 예시 (성공):

{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "TASK_ID",
    "url": "https://ssanai-workspace.atto-lab.cc/v1/videos/TASK_ID/content"
  }
}

반환된 URL에서 비디오를 다운로드할 수 있습니다.

응답 필드 설명:

필드 유형 설명
code string 응답 상태 코드, "success"는 성공을 의미
data object 작업 데이터 객체
data.task_id string 작업 ID
data.status string 작업 상태: queued, in_progress, succeeded, failed
data.format string 비디오 형식(예: "mp4")
data.url string 비디오 접근 URL (작업 성공 시)
data.error object 오류 정보 (작업 실패 시)
message string 오류 메시지

중요 안내

참고: [Google 책임 있는 AI 가이드라인]에 따라(https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/responsible-ai-and-usage-guidelines), Gemini 채널을 통한 일부 작업은 성공 응답을 반환하더라도 비디오 출력이 차단될 수 있습니다. 이 경우 필터링 상세 정보는 metadata.rai_media_filtered_count and metadata.rai_media_filtered_reasons 필드에서 아래 예시처럼 확인할 수 있습니다:

{
  "code": "success",
  "message": "",
  "data": {
    "bytes_base64_encoded": "",
    "error": null,
    "format": "mp4",
    "metadata": {
      "rai_media_filtered_count": 1,
      "rai_media_filtered_reasons": ["Sorry, we can't create videos with real people's names or likenesses. Please remove the celebrity reference and try again."]
    },
    "status": "succeeded",
    "task_id": "bW9kZWxzL3Zlby0zLjAtZmFzdC1nZW5lcmF0ZS0wMDEvb3BlcmF0aW9ucy9hd2IxZDhsNDVydGM",
    "url": "Sorry, we can't create videos with real people's names or likenesses. Please remove the celebrity reference and try again."
  }
}

관련 링크