비디오 생성은 비동기 작업입니다. POST 로 제출하면 즉시 작업 id 가 돌아오고,
결과는 GET /v1/videos/generations/{id} 로 폴링합니다.
본문
modelstring필수- VIDEO 카테고리 모델 ID (예:
everyais/veo-3-1-generate-001) promptstring필수- 1~4000자
durationinteger선택- 공통 입력 범위 1~120초. 생략 기본값과 지원 길이는 모델별로 다릅니다(아래 표 참고)
pricingVariantstring선택- 해상도/오디오 변형 키.
GET /v1/models의pricing.variants[].key값을 그대로 씁니다 userstring선택- 최종 사용자 식별자
extra_body.googleobject선택negativePrompt(≤4000자) ·seed·enhancePrompt
모델별 길이·해상도 조합
GET /v1/models의 capabilities.video_generation, limits.supported_durations, pricing.variants[].key를 확인하세요. 필드 생략은 지원 미확인입니다. 미지원 값·조합은 400이며 지원값으로 자동 보정하지 않습니다.
| 모델·경로 | 지원값과 조합 |
|---|---|
| Veo 3 / 3.1 | duration은 4·6·8초. 생략하면 8초입니다. 1080p·4k는 8초만 지원합니다 |
| Veo 3.1 Lite | 4·6·8초이며 4k는 미지원입니다 |
| Veo 2 | duration은 5·6·7·8초, 생략하면 8초입니다 |
| Gemini Developer API의 Veo 3 | 오디오 없는 variant는 미지원입니다. Vertex 경로의 지원 여부와 다를 수 있으므로 공개 variant만 사용하세요 |
| Omni | duration을 생략하세요. 명시하면 400입니다. 공급자가 실제 길이를 결정하며 완료 응답의 durationSeconds로 확인합니다. 현재 720p와 오디오 포함 variant만 지원합니다 |
Omni는 extra_body.google의 negativePrompt·seed·enhancePrompt를 지원하지 않으며 명시하면 400입니다. Omni의 pricingVariant는 16:9·9:16 비율만 지원합니다.
GET /v1/videos/generations/{id}
작업 상태·결과 폴링. POST 응답의 id 를 이 경로에 넣습니다.
⚠️
/v1/outputs/{requestId}로는 조회되지 않습니다. 비디오 작업 id 와 요청 id 는 별도 공간이라 그쪽으로 폴링하면 항상 404 입니다.
진행 중일 때는 Retry-After: 5 헤더가 붙습니다 — 5초 간격 폴링을 권장합니다.
status 값은 4가지입니다.
| status | 의미 |
|---|---|
processing | 제출·프로바이더 처리·정산 진행 중 |
completed | 완료 — durationSeconds 와 data 포함 |
failed | 실패 또는 타임아웃 — error 포함 |
cancelled | 취소됨 |
{
"id": "cm...",
"object": "video.generation.job",
"created": 1709884800,
"model": "everyais/veo-3-1-generate-001",
"status": "completed",
"durationSeconds": 8,
"data": [{ "url": "https://..." }]
}드물게 프로바이더 호출 결과를 확정하지 못한 경우 processing 과 함께
outcome_unknown: true 가 내려오고, 운영자 확인이 필요하면 requires_manual_review: true 가 추가됩니다.
작업이 없거나·만료(24시간)됐거나·다른 API 키의 것이면 404 job_not_found 입니다.
과금
총 비용 = durationSeconds × 초당 단가 입니다. pricingVariant 를 지정하면 해당 변형 단가가 우선 적용됩니다.
예를 들어 everyais/veo-3-1-generate-001 은 720p-with-audio · 1080p-with-audio · 4k-with-audio
변형을 제공합니다. 정확한 키와 단가는 GET /v1/models 응답의 pricing 필드에서 확인하세요.