미리보기 문서

Veo 4 모델 API를 제품 워크플로에 통합하세요

이 개발자 가이드는 Veo 4 API의 계획된 요청 흐름을 보여줍니다. 비디오 작업 생성, 상태 확인, 웹훅 수신, 공개 출시 전 크레딧 예산까지 포함합니다.

API Keys 열기 가격 보기

통합 흐름

네 단계로 API 연결

백엔드 통합을 준비할 때 이 흐름을 사용하세요. 키는 서버에 보관하고, 작업은 비동기로 제출한 뒤 완료 후 결과 URL을 저장합니다.

API key 생성

Dashboard > API Keys를 열어 서버용 키를 준비하세요. 브라우저 클라이언트는 키를 노출하지 말고 백엔드를 호출해야 합니다.

비디오 작업 제출

prompt, mode, aspect ratio, quality, 선택적 webhook URL을 포함해 text-to-video 또는 image-to-video 요청을 보냅니다.

진행 상황 추적

task_id로 task endpoint를 폴링해 succeeded 또는 failed가 될 때까지 확인합니다. 프로덕션에서는 Webhook으로 폴링을 줄일 수 있습니다.

에셋 저장

작업 성공 후 video_url과 thumbnail_url을 CMS, 편집기, 자동화 파이프라인 또는 사용자 프로젝트에 저장합니다.

미리보기 계약

계획된 REST 인터페이스

아래 예시는 팀이 지금 클라이언트를 설계할 수 있도록 구체적으로 작성되었습니다. 출시 발표 전까지는 초안 계약으로 다뤄주세요.

Base URL

서버에서 HTTPS로 호출하세요. 최종 출시 시 버전 도메인이나 지역 엔드포인트가 추가될 수 있습니다.

https://veo4api.net/api/video/veo4

인증

모든 요청은 Bearer token을 사용합니다. API keys는 서버 secrets에 보관하고 공개 frontend bundle에는 넣지 마세요.

Authorization: Bearer YOUR_API_KEY

POSThttps://veo4api.net/api/video/veo4/generate변경 가능

새 비동기 Veo 4 비디오 작업을 생성합니다. 응답은 즉시 task_id를 반환하고 렌더링은 백그라운드에서 계속됩니다.

필드	타입	필수	설명
`prompt`	string	예	생성 클립에 대한 자연어 지시입니다. 피사체, 카메라 움직임, 스타일, 제약을 포함하세요.
`image_urls`	string[]	아니오	image-to-video 작업에 사용할 공개 접근 가능한 원본 이미지입니다. 현재 proxy는 image_urls와 호환 이미지 URL alias를 받습니다.
`aspect_ratio`	string	아니오	계획 값은 16:9, 9:16, 1:1입니다.
`extend_task_id`	string	아니오	비디오 확장 워크플로를 요청할 때 사용할 기존 완료 비디오의 선택적 task_id입니다.
`seeds`	number	아니오	더 재현 가능한 출력을 위한 선택적 숫자 seed입니다. 현재 허용 범위는 10000-99999입니다.
`watermark`	string	아니오	비디오 생성 backend로 전달되는 선택적 watermark 라벨입니다.
`enableTranslation`	boolean	아니오	생성 전 prompt 번역 여부를 제어하는 선택적 boolean입니다. 기본값은 true입니다.
`public`	boolean	아니오	결과가 공개 showcase 영역에 표시될 수 있는지 나타내는 선택적 boolean입니다.

cURL

curl -X POST "https://veo4api.net/api/video/veo4/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic dolly shot of a glass greenhouse during sunrise",
    "aspect_ratio": "16:9",
    "watermark": "veo4api",
    "enableTranslation": true
  }'

JavaScript

const response = await fetch("https://veo4api.net/api/video/veo4/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Animate this product photo into a smooth studio orbit shot",
    image_urls: ["https://cdn.example.com/input/product.png"],
    aspect_ratio: "1:1",
    seeds: 12345,
    public: false
  })
});

const data = await response.json();
console.log(data.task_id);

Queued 응답

{
  "task_id": "veo4_task_01j9example",
  "status": "queued",
  "model": "veo-4",
  "credits_estimated": 180,
  "created_at": "2026-05-17T08:00:00Z"
}

완료 작업 응답

{
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "progress": 100,
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "thumbnail_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.jpg",
  "completed_at": "2026-05-17T08:03:42Z"
}

// Poll the task with:
// GET https://veo4api.net/api/video/veo4/status?task_id={task_id}

비동기 전달

웹훅으로 완료 이벤트 받기

Webhook 전달은 공개 API contract의 계획 기능입니다. 활성화 전까지는 status endpoint를 폴링하고, 향후 webhook_url 필드를 처리할 수 있도록 백엔드를 준비하세요.

서명 정책

Webhook 서명 세부사항은 아직 최종이 아닙니다. 향후 signature header 검증, task_id 저장, 중복 이벤트 무시를 준비하세요.

Webhook payload 예시

{
  "event": "video.succeeded",
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "model": "veo-4",
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "credits_charged": 180,
  "created_at": "2026-05-17T08:00:00Z",
  "completed_at": "2026-05-17T08:03:42Z"
}

신뢰성

작업 상태와 오류 처리

명확한 작업 상태와 재시도 가능한 실패를 기준으로 클라이언트를 설계하세요. 생성은 비동기이므로 200 응답은 작업이 접수되었다는 뜻입니다.

상태	의미
`queued`	요청이 접수되어 용량을 기다리는 중입니다.
`processing`	모델이 비디오를 렌더링하거나 후처리 중입니다.
`succeeded`	비디오가 준비되었고 결과 URL을 사용할 수 있습니다.
`failed`	생성에 실패했습니다. 오류를 보여주고 prompt 수정 또는 재시도를 허용하세요.
`canceled`	완료 전에 작업이 취소되었습니다.

코드	권장 처리
`400`	재시도 전 prompt length, image_urls, aspect_ratio, seeds, public visibility를 검증하세요.
`401`	API key가 없거나 만료되었거나 유효하지 않습니다. 새 키 생성을 안내하세요.
`402`	크레딧이 부족합니다. Billing으로 보내거나 품질을 낮춰 재시도하세요.
`409`	작업 요청 충돌입니다. 플랫폼이 conflict를 반환하면 새 작업 대신 기존 작업을 조회하세요.
`429`	Rate limit입니다. exponential backoff를 적용하고 과도한 polling을 피하세요.
`500`	일시적인 플랫폼 또는 모델 오류입니다. 나중에 재시도하고 원래 작업 기록을 유지하세요.

크레딧 계획

계획된 크레딧 비용

현재 가격 표시는 Veo 4 용량 계획을 위해 이 숫자를 사용합니다. 출시 전에는 최종 청구 약속이 아닙니다.

표준 비디오 작업

180

표준 Veo 4 비디오 생성 1회당 예상 크레딧입니다.

HD 비디오 작업

240

HD Veo 4 비디오 생성 1회당 예상 크레딧입니다.

용량 계획 용도로만 사용하세요. 실제 API 제한, 품질 티어, 청구 방식은 조정될 수 있습니다.