Veo 모델 이미지-투-비디오 API 문서¶
Veo는 Google이 개발한 고품질 이미지-투-비디오 생성 모델입니다. 이 문서는 Google Veo 모델을 사용한 이미지-투-비디오 생성의 전체 API 인터페이스 사양을 설명합니다. 모든 비디오 생성 호출은 동일한 /v1/video/generations 엔드포인트를 사용하며, 사용 사례에 따라 파라미터가 달라집니다. 이미지 데이터는 base64 인코딩 문자열로 전달합니다.
지원 모델¶
현재 지원되는 모델:
| 모델 | 설명 |
|---|---|
| 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 이미지-투-비디오 기능은 비동기 작업 처리 메커니즘을 제공합니다:
- 작업 제출: 이미지와 텍스트 프롬프트를 보내 비디오 생성 작업 생성
- 상태 조회: task ID로 생성 진행률/상태 조회
- 결과 획득: 작업 완료 후 생성 비디오 파일 획득
작업 상태 흐름¶
- 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 | 비디오 콘텐츠 조회 (스트리밍 다운로드) |
사용 예시¶
1. 기본 이미지-투-비디오¶
가장 기본적인 이미지-투-비디오 생성은 단일 이미지를 첫 프레임으로 사용합니다.
요청 본문:
{
"model": "veo-3.1-generate-preview",
"prompt": "A cat playing piano in a beautiful garden",
"image": "<BASE64_ENCODED_IMAGE_DATA>",
"metadata": {}
}
2. 첫 프레임 + 마지막 프레임¶
image 필드의 이미지는 비디오의 첫 프레임을 지정합니다. metadata.lastFrame의 이미지는 마지막 프레임을 지정합니다. 이를 통해 생성 비디오의 시작과 끝 프레임을 모두 제어할 수 있습니다.
참고: 이 기능은 Veo 3.1 모델에서만 지원됩니다.
요청 본문:
{
"model": "veo-3.1-generate-preview",
"prompt": "A cat playing piano in a beautiful garden",
"image": "<BASE64_ENCODED_IMAGE_DATA>",
"metadata": {
"lastFrame": "<BASE64_ENCODED_IMAGE_DATA>"
}
}
3. 참조 이미지¶
이미지는 metadata.referenceImages 배열로 지정하며, 최대 3개 요소를 포함할 수 있습니다. 각 참조 이미지는 image(base64 인코딩 이미지 데이터)와 referenceType("asset" 또는 "style")을 포함하는 객체입니다.
참고: 이 기능은 veo-3.1-generate-preview에서만 지원됩니다.
요청 본문:
{
"model": "veo-3.1-generate-preview",
"prompt": "A cat playing piano in a beautiful garden",
"image": "<BASE64_ENCODED_IMAGE_DATA>",
"metadata": {
"referenceImages": [
{
"image": "<BASE64_ENCODED_IMAGE_DATA>",
"referenceType": "asset"
},
{
"image": "<BASE64_ENCODED_IMAGE_DATA>",
"referenceType": "style"
}
]
}
}
요청 파라미터:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| model | 문자열 | 예 | 모델 이름(예: veo-3.1-generate-preview) |
| prompt | 문자열 | 예 | 생성할 비디오 콘텐츠를 설명하는 텍스트 프롬프트 |
| image | 문자열 | 예 | 첫 프레임용 base64 인코딩 이미지 데이터 |
| metadata | 객체 | 아니오 | 확장 파라미터 객체 |
metadata 파라미터:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| aspectRatio | 문자열 | 아니오 | 비디오 종횡비, 옵션: "16:9", "9:16" |
| durationSeconds | 숫자 | 아니오 | 비디오 길이(초), 옵션: 4, 6, 8 |
| negativePrompt | 문자열 | 아니오 | 비디오에서 원하지 않는 콘텐츠를 설명하는 네거티브 프롬프트 |
| personGeneration | 문자열 | 아니오 | 인물 생성 전략, 옵션: "allow_all"(text-to-video), "allow_adult"(image-to-video) |
| resolution | 문자열 | 아니오 | 비디오 해상도(예: "1080p", "720p") |
| sampleCount | 숫자 | 아니오 | 생성할 비디오 수, 기본값 1 |
| storageUri | 문자열 | 아니오 | 생성 비디오 저장용 Google Cloud Storage URI |
| lastFrame | 문자열 | 아니오 | 마지막 프레임용 base64 인코딩 이미지 데이터 (Veo 3.1 모델 전용) |
| referenceImages | 배열 | 아니오 | 참조 이미지 배열(최대 3개, veo-3.1-generate-preview 전용) |
referenceImages 배열 요소:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| image | 문자열 | 예 | base64 인코딩 이미지 데이터 |
| referenceType | 문자열 | 예 | 참조 유형, 옵션: "asset" 또는 "style" |
1. 비디오 생성 작업 제출¶
전체 요청:¶
curl -X POST "https://ssanai-workspace.atto-lab.cc/v1/video/generations" -H "Content-Type: application/json" -H "Authorization: Bearer API_KEY" -d @veoImageToVideoTest.json
엔드포인트:¶
요청 헤더:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| Content-Type | 문자열 | 예 | application/json |
| Authorization | 문자열 | 예 | Bearer API_KEY |
응답 예시:¶
응답 필드 설명:¶
| 필드 | 유형 | 설명 |
|---|---|---|
| task_id | 문자열 | 작업 ID (후속 작업 상태 조회용) |
2. 작업 상태 조회¶
전체 표준 형식 엔드포인트¶
curl -X GET "https://ssanai-workspace.atto-lab.cc/v1/video/generations/TASK_ID" -H "Authorization: Bearer API_KEY"
엔드포인트:¶
요청 헤더:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| Authorization | 문자열 | 예 | Bearer API_KEY |
경로 파라미터:¶
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| task_id | 문자열 | 예 | 작업 ID |
응답 예시 (처리 중):¶
{
"code": "success",
"message": "",
"data": {
"bytes_base64_encoded": "",
"error": null,
"format": "mp4",
"metadata": null,
"status": "processing",
"task_id": "TASK_ID",
"url": ""
}
}
응답 예시 (성공):¶
{
"code": "success",
"message": "",
"data": {
"bytes_base64_encoded": "",
"error": null,
"format": "mp4",
"metadata": null,
"status": "succeeded",
"task_id": "TASK_ID",
"url": "https://ssanai-workspace.atto-lab.cc/v1/videos/TASK_ID/content"
}
}
참고: AI 서비스 제공자에 따라 비디오는 bytes_base64_encoded 필드의 base64 데이터(Vertex) 또는 url 필드의 콘텐츠 URL(Gemini)로 반환됩니다.
응답 예시 (실패):¶
{
"code": "success",
"message": "",
"data": {
"bytes_base64_encoded": "",
"error": null,
"format": "mp4",
"metadata": null,
"status": "failed",
"task_id": "TASK_ID",
"url": "Reference to video does not support this mix of reference images."
}
}
작업이 실패하면 url 필드에는 비디오 URL 대신 오류 메시지가 포함됩니다.
응답 필드 설명:¶
| 필드 | 유형 | 설명 |
|---|---|---|
| code | 문자열 | 응답 상태 코드 ("success"는 성공) |
| data | 객체 | 작업 데이터 객체 |
| data.task_id | 문자열 | 작업 ID |
| data.status | 문자열 | 작업 상태: queued, in_progress, succeeded, failed |
| data.format | 문자열 | 비디오 형식(예: "mp4") |
| data.url | 문자열 | 비디오 접근 URL(성공 시) 또는 오류 메시지(실패 시) |
| data.bytes_base64_encoded | 문자열 | base64 인코딩 비디오 데이터(제공 시) |
| data.error | 객체 | 오류 정보 (작업 실패 시) |
| message | 문자열 | 오류 메시지 |
중요 안내¶
참고: Google 책임 있는 AI 가이드라인에 따라, Gemini 채널의 일부 작업은 성공 응답을 반환하더라도 비디오 출력이 차단될 수 있습니다. 이 경우 필터링 상세 정보는 metadata.rai_media_filtered_count 및 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."
}
}