Skip to main content

​
개요

VEO 3.1 Official은 Google Veo 3.1을 위한 APIYI의 공식 릴레이 채널입니다. Google AI Studio의 veo-3.1-generate-preview / veo-3.1-fast-generate-preview 비동기 엔드포인트로 투명하게 패스스루되며, 모델 ID, 응답 필드, 제약 조건이 업스트림과 동일합니다. 요청당 과금, Default 그룹에서 호출 가능 — 현재 이용 가능한 가장 낮은 진입 장벽의 공식 품질 Veo 3.1 채널입니다.
🎬 하이라이트: Google AI Studio로의 투명한 패스스루 + 네이티브 동기화 오디오 + 유연한 4 / 6 / 8초 길이 + 세 가지 해상도 단계(720p / 1080p / 4k) + $0.3부터의 요청당 과금 + Default 그룹 + 요청당 과금 또는 사용량 기반 Priority Tokens (전용 그룹은 필요하지 않으며, 순수 사용량 기반 과금은 지원되지 않습니다). 광고 숏폼, 이커머스 소재, 소셜 미디어 콘텐츠, 제품 데모처럼 공식급 품질이 필요하면서도 가장 간단한 온보딩이 필요한 용도에 적합합니다.
⚠️ CDN URL은 반환되지 않습니다 — MP4 stream을 직접 다운로드해야 합니다: 이 채널은 현재 배포 가능한 공개 / CDN URL을 반환하지 않습니다. status: "completed" 후에는 GET /v1/videos/{task_id}/content를 호출하여 MP4 binary를 가져온 다음 이를 직접 보유한 OSS / CDN에 저장한 뒤 최종 사용자에게 제공해야 합니다. 브라우저는 /content에 직접 접근할 수 없습니다(인증 헤더 필요). 아래 API 엔드포인트를 참고하십시오.

텍스트-투-비디오 API

POST /v1/videos, 텍스트만으로 비디오를 생성합니다 — JSON 요청 본문을 사용하는 가장 간단한 진입점입니다.

이미지-투-비디오 API

POST /v1/videos + input_reference의 multipart 업로드로 정지 이미지를 클립으로 애니메이션화합니다.

공식 vs 역방향

기존 VEO 3.1 (역방향 채널)과의 비교 의사결정 매트릭스입니다.

시각적 API 테스트

iCover 시각적 테스트 도구에서 이 엔드포인트를 직접 디버그할 수 있습니다 — 코드가 필요하지 않습니다.

비동기 작업 조회 / 다운로드

APIYI 콘솔에서 제출한 동영상 작업을 보고 동영상 링크를 다운로드할 수 있습니다 — API 외부의 조회 항목입니다.

​
왜 APIYI의 VEO 3.1 공식 채널인가요?

Google 공식 / Vertex AI 채널을 그대로 대체할 수 있으며, 온보딩 마찰, 안정성, 비용 측면에서 프로덕션 시나리오에 맞게 최적화되어 있습니다:

공식 패스스루 · 동일한 Model ID

Google AI Studio의 Veo 3.1 비동기 엔드포인트로 투명하게 패스스루됩니다. 모델 ID(veo-3.1-generate-preview / veo-3.1-fast-generate-preview)가 업스트림과 정확히 일치하며, 요청 및 응답 필드와 제약 조건도 일대일로 대응됩니다.

마찰 없는 온보딩 · 그룹 전환 불필요

호출은 Default 그룹에서 요청당 결제 또는 종량제 Priority Tokens로 동작합니다(순수 종량제는 지원되지 않습니다). 별도 그룹 전환이 필요 없습니다; 기존 요청당 결제 Tokens는 그대로 사용할 수 있습니다 — Veo 3.1을 위한 가장 마찰이 적은 공식 품질 채널입니다.

무제한 동시 실행 수 · 프로덕션 규모

투명한 프록시가 적용된 통합 계정 풀로, 배치 촬영, 광고 파이프라인, 대규모 생산을 선형적으로 확장할 수 있습니다. Google의 계정별 티어 상한이 없습니다.

요청당 과금 · Google보다 60% 이상 저렴

veo-3.1-fast-generate-preview $0.3/req, veo-3.1-generate-preview $1.2/req — 4/6/8초 및 720p/1080p/4k 전 구간 동일합니다. Google의 공식 8초 1080p와 비교하면 62–68% 절감됩니다, 충전 보너스를 더해 추가 절감할 수 있으며; 실패한 작업은 과금되지 않습니다.

전 세계 무마찰 접근

해외 서버나 프록시가 필요 없습니다 — 중국 본토 데이터 센터, 가정용 네트워크 또는 해외 노드에서 api.apiyi.com에 직접 연결할 수 있습니다. Google AI Studio / Vertex AI 해외 접속 설정은 완전히 건너뛸 수 있습니다.

전문 지원 · 엔터프라이즈 온보딩

저희 팀은 동영상 생성 분야에 깊은 전문성을 보유하고 있습니다: prompt engineering, 해상도 선택, 배치 생산, 후처리까지 지원합니다. 엔터프라이즈 고객을 위한 PoC부터 프로덕션까지의 완전한 기술 지원을 제공합니다.

​
주요 기능

네이티브 동기화 오디오

Veo 3.1은 동기화된 오디오가 포함된 동영상(주변음, 대사, 음악)을 기본적으로 출력합니다. 별도의 오디오 후반 작업이 필요하지 않습니다 — prompt에 오디오 의도를 설명하십시오.

유연한 4 / 6 / 8초 길이

seconds 문자열 enum: "4" / "6" / "8". 요청별 과금이며, 길이는 가격에 영향을 주지 않습니다. 1080p / 4k 등급에는 "8"이 필요합니다.

세 가지 해상도 등급

720p / 1080p / 4k, 요청별 요금이 동일합니다. 가로(16:9)와 세로(9:16)를 자유롭게 전환할 수 있습니다.

정확한 지시 준수

Veo 3.1은 카메라 움직임, 객체 물리, 캐릭터 표정 충실도에서 동급을 선도합니다. 풍부한 카메라 언어 키워드 지원(push/pull/pan/dolly, 로우/하이 앵글).

이미지-투-비디오(input_reference)

정적 콘텐츠를 애니메이션으로 만들기 위한 시각적 기준으로 이미지 1장을 업로드합니다. 이미지-투-비디오를 참조하십시오.

비동기 작업 모델

제출하면 즉시 task_id이 반환됩니다. 상태를 별도로 조회하고 최종 동영상을 다운로드하십시오 — 일괄 관리 및 실패 시 재개 흐름에 적합합니다.

OpenAI 호환 프로토콜

base_url=https://api.apiyi.com/v1 + Bearer 인증을 사용합니다. 원시 HTTP 또는 OpenAI SDK의 저수준 client.post()를 통해 작동합니다.

실패는 무료입니다

비동기 모드에서는 실패한 생성, 콘텐츠 정책 거부, 매개변수 오류는 과금되지 않습니다. 오직 status=completed 작업만 과금됩니다.

​
가격

APIYI는 요청당 과금 방식을 사용합니다. 지원되는 지속 시간/해상도 조합 내에서는 정액 요금이며, 더 길거나 더 높은 해상도 출력에 대한 추가 요금은 없습니다. ai.google.dev/gemini-api/docs/pricing의 공개 요율에 따르면, Google의 공식 Veo 3.1은 초당 과금하며, 아래 할인율은 8초 동영상을 기준으로 계산되었습니다.
과금 참고:
  • 지속 시간(4/6/8초), 해상도(720p/1080p/4k), 또는 input_reference 제공 여부와 무관하게, 모델명 기준으로 요청당 과금됩니다 — 4K를 선택해도 720p와 요금은 동일합니다
  • 비동기 모드에서는 생성 실패 / 콘텐츠 정책 거부 / 용량 오류가 모두 과금되지 않습니다
  • Top-Up Promotions의 충전 보너스 단계는 실효 비용을 추가로 낮춥니다
  • 4K 렌더링은 4–6배 더 느리고 파일은 약 10배 더 큽니다 — 일상 사용에는 1080p를 기본값으로 사용하십시오
  • Google의 공식 4K 요금은 $0.30/초(빠름) / $0.60/초(표준)이며, 즉 8초에 $2.40 / $4.80입니다(출처: ai.google.dev/gemini-api/docs/pricing)

​
그룹 설정

VEO 3.1 Official은 Default 그룹(1x)에서 작동하며, 전용 그룹 전환이 필요하지 않습니다. Token의 과금 모드는 Pay-per-request 또는 Pay-as-you-go Priority여야 합니다. 순수 Pay-as-you-go는 지원되지 않습니다(필요한 경우 콘솔에서 Token 모드를 전환하십시오).
온보딩 마찰 비교: Sora 2 Official(전용 Sora2Official 그룹 + Pay-as-you-go Priority만 필요)과 비교하면, VEO 3.1 Official은 Default 그룹에서 실행되며 Pay-per-request와 Pay-as-you-go Priority를 모두 지원합니다. 기존 Pay-per-request Token을 그대로 넣고 base_url만 변경하는 “제로 설정” 온보딩에 이상적입니다.

​
기술 사양

1080p / 4k 해상도에서는 seconds가 "8"여야 합니다 — "4" 또는 "6"는 상위 계층에서 거부됩니다. 720p에서는 세 가지 지속 시간이 모두 지원됩니다.

​
API 엔드포인트

⚠️ MP4 바이너리 다운로드만 가능 — CDN URL은 반환되지 않습니다이 채널은 현재 응답에 CDN / public URL을 출력하지 않습니다 — 동영상 파일은 GET /v1/videos/{task_id}/content을 통해 MP4 바이너리 stream으로만 가져올 수 있습니다(Authorization: Bearer 헤더 필요).의미:
  • 응답에 video_url / data.url / 기타 직접 배포 가능한 링크는 반환되지 않습니다
  • 프런트엔드는 엔드포인트 URL을 <video> 태그에 직접 넣을 수 없습니다 — auth header 없이 보내는 브라우저 요청은 401이 됩니다
  • status: "completed" 즉시, MP4를 다운로드하여 자체 OSS / CDN에 저장한 뒤 최종 사용자에게 URL을 제공하십시오
  • 동영상 보존 정책은 공식 문서에 명시되어 있지 않습니다 — 동영상을 가져오기 위해 원격 task_id에 장기적으로 의존하지 마십시오
엔드포인트 선택: 기본 api.apiyi.com; 백업 게이트웨이 vip.apiyi.com / b.apiyi.com는 동일한 동작을 합니다.

​
핵심 매개변수

⚡ 전체 매개변수 참조: model / prompt / seconds / size / metadata.* 유형, 기본값, 제약 조건이 모두 포함된 전체 표는 Text-to-Video - 매개변수 참조로 이동하십시오. 이 섹션에서는 함정이 가장 많은 3개 매개변수만 설명합니다.

​
seconds (비디오 길이)

길이 필드의 이름은 **seconds**이며(duration이 아니라), 반드시 문자열이어야 합니다("4" / "6" / "8"). 숫자를 전달하면 다음이 반환됩니다:
흔한 함정: 필드 이름을 duration로 지정하면 조용히 무시됩니다. duration는 이 채널에서 인식되지 않으므로 → 버려지고 → 길이는 기본값 4초로 되돌아갑니다:
  • 720p(및 4초를 허용하는 다른 단계)에서는: 오류는 없지만 4초만 받습니다(이것이 정확히 “8초를 보냈는데 4초를 받는” 사례입니다)
  • 1080p / 4k에서는 4초가 허용되지 않으므로 Resolution 1080p requires duration seconds to be 8 seconds, but got 4 오류가 발생합니다
올바른 사용법: 값이 "8"인 seconds 필드를 전달하십시오(문자열).
매개변수 우선순위: metadata.durationSeconds > seconds > 8

​
metadata.resolution (해상도 단계)

매개변수 우선순위: metadata.resolution > size > 720p

​
⚠️ generateAudio를 전달하지 마십시오

Veo 3 / 3.1은 오디오를 기본적으로 인식하지만, generateAudio 매개변수는 전달하면 안 됩니다. 업스트림은 INVALID_ARGUMENT로 거부합니다. 오디오를 제어하려면 의도를 prompt에 작성하십시오:
“해 질 무렵의 해안 등대; 파도, 멀리서 들리는 바닷새, 낮은 바람 소리, 영화 같은 분위기”

​
모범 사례

1

필요에 따라 모델을 선택합니다

  • Iteration / batch previews → veo-3.1-fast-generate-preview ($0.3/request)
  • Final delivery / 4K → veo-3.1-generate-preview ($1.2/request)
  • 같은 prompt + seed로 둘 다 실행한 뒤 눈으로 보고 선택합니다
2

먼저 4초로 검증합니다

새 prompt마다 카메라 방향과 스타일을 검증하기 위해 seconds: "4"부터 시작합니다(60–90초 렌더링, $0.3). 느낌이 고정되면 8초 또는 1080p로 확장합니다.
3

비동기 폴링을 사용하고 동기 대기는 사용하지 않습니다

공식 릴레이는 async-only입니다: 제출하고 task_id를 받기 위해 POST한 뒤 GET /v1/videos/{task_id}를 8–10초마다 폴링하여 status: "completed"가 될 때까지 기다린 다음 /content에서 다운로드합니다. webhooks는 없으며 폴링만 사용합니다.
4

티어별로 클라이언트 타임아웃을 설정합니다

  • 720p / 1080p: 3분 하드 타임아웃
  • 4K: 10분 하드 타임아웃
  • POST 제출 (multipart): 최소 30초
5

완료되면 즉시 다운로드합니다

status가 completed로 바뀌면, 자체 OSS / CDN으로 즉시 다운로드하십시오 — 원격 task_id에 장기적으로 의존하지 마십시오. /content 엔드포인트는 status가 바뀐 직후 가끔 400을 반환합니다; 4초 후 다시 시도하십시오(샘플 클라이언트에 이 동작이 기본 내장되어 있습니다).
6

오디오 의도를 prompt에 인코딩합니다

generateAudio을 전달하지 마십시오(INVALID_ARGUMENT가 반환됩니다). 주변음, 대사, BGM은 prompt에: “파도, 먼 바닷새, 낮은 바람 소리”처럼 설명하십시오.
7

자체 측에서 요청 제한을 적용합니다

동시 실행 수 상한은 공개 문서에 없습니다; 실제로는 동시에 10개 제출을 해도 모두 성공적으로 대기열에 들어갔습니다. 프로덕션 측 진행 중 요청 수를 10 이하로 제한할 것을 권장합니다, 429 / 5xx에는 지수 백오프로 대응합니다.

​
오류 코드 및 재시도

권장 클라이언트 설정:
  • POST 제출 제한 시간: 30초(multipart 업로드는 더 필요할 수 있습니다)
  • 폴링 간격: 8~10초; 최대 대기 시간 720p/1080p 3분, 4K 10분
  • 5xx 및 failed에 대해 지수 백오프 재시도(1~2회 권장)
  • /content를 4초 간격으로 3~5회 재시도

​
FAQ

공식(이 페이지): Google AI Studio의 업스트림 엔드포인트로 투명하게 패스스루합니다. 모델 ID는 Google 업스트림(veo-3.1-generate-preview / veo-3.1-fast-generate-preview)과 일치하며, 요청당 $0.3 / $1.2이고 비동기 엔드포인트만 지원합니다.Reverse(기존 VEO 3.1): Google Flow에 대한 리버스 엔지니어링 기반 접근입니다. 모델 ID는 veo-3.1-fast / veo-3.1 / -fl 시리즈이며, 요청당 $0.15부터로 더 저렴하고, 스트리밍 동기와 비동기 모드를 모두 지원하며, 프레임-투-동영상(첫/마지막 프레임)도 지원합니다.전체 공식 vs Reverse 결정 매트릭스를 보십시오. 두 채널은 공존하며, 비즈니스 요구에 맞게 선택하면 됩니다.
요청 필드는 seconds입니다(string "4" / "6" / "8"). 이를 duration로 이름 붙이면 인식되지 않으며 — 조용히 무시되고 length는 기본 4초로 되돌아갑니다. 이것이 “8초를 보냈는데 4초만 나왔다”의 근본 원인입니다.왜 문자열이어야 하느냐면: 백엔드 Go struct가 이 필드(내부 이름 duration)를 string로 선언하므로, 숫자는 디코더 계층에서 parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string로 거부됩니다(그 오류의 duration는 백엔드 내부 필드 이름이며 — 요청은 여전히 seconds를 보냅니다). 기억하십시오: seconds를 보내고, 값은 따옴표로 감싸십시오: "4" / "6" / "8".
Veo 3 / 3.1은 기본적으로 오디오를 지원하는 동영상 모델이지만, generateAudio 매개변수는 전달하면 안 됩니다(업스트림이 INVALID_ARGUMENT를 반환합니다). 사운드를 제어하려면, 의도를 prompt에 적으십시오:
“해질녘 해안 등대; 파도, 먼 바다새 소리, 낮은 바람 소리, 영화 같은 분위기”
  • 동일한 매개변수에서는 렌더링 시간이 대체로 비슷합니다(측정값 720p 8초: fast 83초, standard 78초). fast는 더 빠른 것이 아니라 더 저렴합니다($0.3 vs $1.2)
  • 기본값은 veo-3.1-fast-generate-preview입니다
  • 최종 납품이나 디테일 충실도 / 물리 일관성이 중요할 때는 veo-3.1-generate-preview로 전환합니다
  • 프로덕션에서 A/B 테스트를 할 때는: 같은 prompt + seed로 둘 다 실행하고, 눈으로 선택합니다
대부분의 경우 권장하지 않습니다:
  • 요청당 요금이 같아 보여 매력적이지만
  • 렌더링은 4–6배 더 느립니다(720p 80초 → 4K 350초)
  • 파일은 약 10배 더 큽니다(720p 4MB → 4K 40MB) — 대역폭과 저장 비용이 두 배로 듭니다
  • 1080p는 대부분의 재생 시나리오에서 시각적으로 충분합니다
4K가 필요한 경우: veo-3.1-generate-preview를 사용하고, seconds="8"를 설정하며(필수), 클라이언트 타임아웃은 10분 이상으로 하고, 백그라운드 비동기 작업으로 실행합니다.
  • webhook은 없습니다. GET /v1/videos/{task_id}만 폴링하십시오
  • 권장 폴링 간격: 8초(측정상 충분하며 요청 제한에 걸리지 않습니다)
  • 측정 시간: 720p / 1080p 60–115초, 4K 5–6분
  • 클라이언트 타임아웃: 720p/1080p는 3분, 4K는 10분
status가 completed로 바뀐 직후에는, /v1/videos/{task_id}/content 호출이 업스트림 CDN 동기화 지연 때문에 가끔 400을 반환합니다. 4초 기다린 뒤 한 번 재시도하면 보통 해결됩니다(샘플 클라이언트는 4초 간격으로 3–5회 재시도합니다).
현재는 불가능합니다. 이 채널은 응답에 CDN / 공개 URL을 반환하지 않습니다 — video_url / data.url / 그 밖의 직접 배포 가능한 링크도 없습니다.동영상을 가져오는 유일한 방법: status: "completed" 후 GET /v1/videos/{task_id}/content를 호출해 MP4 이진 스트림을 가져옵니다(Authorization: Bearer 헤더 필요).표준 프로덕션 패턴:
  1. 백엔드가 작업 완료 즉시 MP4를 내려받아 자체 OSS / CDN에 업로드합니다
  2. 최종 사용자에게는 CDN URL을 제공합니다
  3. 프런트엔드 <video> 태그는 /content를 직접 가리키면 안 됩니다 — 브라우저는 auth header를 포함할 수 없어 요청이 401이 됩니다
업스트림이 CDN URL을 노출하면 이 페이지도 업데이트됩니다.
보관 기간은 공식적으로 문서화되어 있지 않습니다. 강력히 권장하는 방법은 완료 즉시 내려받아 로컬에 저장하는 것입니다 — 원격 task_id에 장기적으로 의존하지 마십시오; /content는 만료 후 결국 404가 됩니다.
progress 필드는 거칠게 표시되어 있습니다 — 0 / 50 / 100 사이에서만 점프합니다. 백분율 진행률 표시줄에는 사용하지 마십시오. 대신 스피너를 사용하거나, “경과 / 예상”을 직접 계산하십시오.
아닙니다. status=completed 작업만 과금됩니다. failed / 취소됨 / content-policy 거부 / 매개변수 오류는 모두 무료입니다. 실제 동영상 출력이 없으면 과금도 없습니다.
바이트 단위로는 동일하지 않습니다. 측정 결과: 같은 prompt + 같은 seed(88888) + 같은 매개변수로 fast를 두 번 실행했더니 — 파일 크기는 9.81 MB 대 9.25 MB였고, md5도 완전히 달랐으며, 렌더링 시간도 달랐습니다.하지만 seed는 장식이 아닙니다: 같은 seed의 출력은 서로 가까이 묶입니다(5회 테스트, 그룹 내 파일 크기 편차는 6%에 불과함). 다른 seed는 체계적으로 이동합니다(그룹 간 편차 +36.8%). 시사점:
  • “안정적인 느낌”을 원하면 → seed를 고정하십시오
  • “변형을 탐색”하고 싶다면 → prompt를 만지작거리는 대신 seed를 바꾸십시오
  • “정확한 재생”을 원한다면 → 불가능하니 mp4를 저장하십시오
현재 둘 다 지원되지 않습니다. Image-to-video는 이미지 1장만 허용하며, 필드명은 input_reference로 고정되어 있고, 파일 또는 Base64로만 가능하며 원격 URL은 지원하지 않습니다.Google upstream Veo 3.1은 다중 참고 / 첫-마지막 프레임 / 동영상 확장을 지원하지만, 이 채널은 지원하지 않습니다. 첫/마지막 프레임이 필요하면 VEO 3.1 (Reverse) -fl 시리즈를 사용하십시오.
측정상 10개의 동시 제출이 모두 성공적으로 대기열에 들어갔고 거부는 없었습니다. 정확한 상한은 공개되어 있지 않습니다. 프로덕션에서는 진행 중 요청 수를 10 이하로 제한하고, 429 / 5xx에는 지수 백오프를 적용하는 것을 권장합니다.
  • 보이는 워터마크는 없습니다
  • 하지만 MP4 메타데이터에는 Google C2PA Content Credentials(발급 주체: Google C2PA Media Services, 형식 urn:c2pa:...)가 포함됩니다. 최종 사용자는 이를 볼 수 없지만; C2PA 도구(예: Adobe Content Authenticity)는 “Veo로 생성됨”을 검증할 수 있습니다
  • 재배포 시나리오에서는 유의하십시오. 보통 재생에는 영향을 주지 않습니다
부분적으로 가능합니다. 인터페이스는 OpenAI 관례(Bearer 인증 + /v1/...)를 따르지만, OpenAI 공식 SDK는 videos.create 메서드를 노출하지 않습니다(/v1/videos는 사용자 정의 경로입니다). OpenAI SDK의 저수준 client.post() 또는 raw HTTP를 사용하십시오. raw HTTP가 가장 간단합니다 — Text-to-Video Playground의 코드 예제를 보십시오.

​
관련 문서

VEO 3.1 Official은 APIYI의 안정적인 공식 릴레이 서비스입니다. Google AI Studio로의 투명한 패스스루이며, 모델 ID, 응답 필드, 제약 조건이 Google 상류와 정확히 일치합니다. 또한 이 채널은 Default 그룹에서 요청당 과금으로 동작합니다. 이용 가능한 공식 품질 채널 중 가장 진입 장벽이 낮습니다. 콘솔 지원 패널에 피드백을 남겨 주십시오.