TL;DR: 이 튜토리얼에서는 Gemini Omni Flash API를 사용하여 텍스트 프롬프트와 참조 이미지로부터 동영상을 생성하는 방법을 알아봅니다. Atlas Cloud 통합 API를 사용하면 약 15분 안에 동영상 생성 스크립트를 완성할 수 있습니다. 별도의 Google 계정 승인은 필요 없으며, Atlas Cloud API 키만 있으면 됩니다.
Google의 공식 Gemini API 퀵스타트 가이드는 Gemini Omni Flash를 구체적으로 다루지 않습니다. 이 튜토리얼에서는 별도의 Google AI Studio 애플리케이션 없이도 Gemini Omni Flash에 직접 액세스할 수 있는 Atlas Cloud의 통합 API 엔드포인트를 사용합니다.
6일 전 r/GeminiAI에 게시된 "Gemini Omni Flash API access: 5 providers tested, ranked by use case"라는 제목의 스레드는 개발자들이 옵션을 평가할 때 참고하는 필수 자료로 빠르게 자리 잡았습니다. 가장 많은 추천을 받은 댓글은 핵심을 짚었습니다. "Google AI Studio는 시작하기에 가장 빠르지만, 곧바로 속도 제한(rate limit)에 걸리게 된다. 프로덕션 환경을 고려하는 개발자라면 다른 진입점이 필요하다."라는 내용입니다.
Gemini Omni Flash는 텍스트, 이미지, 오디오, 비디오를 자유롭게 조합하여 입력할 수 있는 Google의 멀티모달 동영상 생성 모델입니다. 최대 10초 분량의 영화 같은 영상을 720p에서 4K 해상도까지 생성합니다. 이 튜토리얼에서는 통합 API 엔드포인트, 종량제 과금 방식, Google 계정 기반의 속도 제한이 없는 Atlas Cloud를 통해 Gemini Omni Flash API를 사용하는 방법을 안내합니다.
본 튜토리얼은 텍스트-비디오(Text-to-Video)와 이미지-비디오(Image-to-Video)라는 두 가지 생성 모드에 대한 Gemini Omni API를 다룹니다. 모든 코드 예제는 실제 Atlas Cloud API 환경에서 테스트되었습니다.
Gemini Omni Flash API 사전 요구 사항
필요 항목:
- Python 3.9+ 또는 Node.js 18+
- Atlas Cloud 계정 및 API 키 (무료 가입)
- Python용 requests 라이브러리 또는 Node.js용 axios
- REST API에 대한 기본적인 이해
- 약 15분의 소요 시간
테스트 환경: macOS 14, Ubuntu 22.04, Windows 11 (WSL2)
가격 참고 (Atlas Cloud 가격 페이지, 2026년 6월 2일 기준):
- 720p / 1080p: 기본 USD0.20 + 초당 USD0.10. 8초짜리 720p 영상 생성 시 USD1.00.
- 4K: 기본 USD1.00 + 초당 USD0.10. 8초짜리 4K 영상 생성 시 USD1.80.
Gemini Omni API로 무엇을 만드는가
이 튜토리얼을 마치면 텍스트 프롬프트로 동영상을 생성하는 스크립트와, 참조 이미지를 영상으로 변환하는 스크립트 두 가지를 갖게 됩니다. 두 스크립트는 동일한 인증 및 폴링(polling) 로직을 공유합니다. 전체적인 아키텍처는 다음과 같습니다.
plaintext1사용자 스크립트 → Atlas Cloud API → Gemini Omni Flash → 동영상 URL 2 (인증 + 대기열) (생성) (결과물)
완성된 스크립트의 기능:
- 생성 요청을 제출하고 prediction_id를 수신
- 동영상이 준비될 때까지 3초마다 상태 엔드포인트를 폴링
- 생성 완료 시 결과 영상 URL 출력
1단계: Gemini Omni Flash API 키 발급받기
이 단계에서는 Atlas Cloud 계정을 만들고, 스크립트가 Gemini Omni Flash API를 인증할 수 있도록 API 키를 생성합니다.
- atlascloud.ai에 접속하여 무료 계정을 만듭니다.
- 대시보드에서 API Keys로 이동합니다.
- Create new key를 클릭하고 키를 복사하여 안전하게 보관합니다.
스크립트에 키를 직접 하드코딩하지 않도록 환경 변수로 설정합니다.
plaintext1# macOS / Linux 2export ATLASCLOUD_API_KEY="your_api_key_here" 3 4# Windows (PowerShell) 5$env:ATLASCLOUD_API_KEY="your_api_key_here"
설정이 제대로 되었는지 확인합니다.
plaintext1echo $ATLASCLOUD_API_KEY
예상 출력:
plaintext1your_api_key_here
주의: API 키를 버전 관리 시스템(Git 등)에 커밋하지 마세요. Python의 python-dotenv나 Node.js의 dotenv 등을 사용하여 .env 파일에 넣고 .gitignore에 추가하세요.
2단계: 첫 Gemini Omni Flash API 요청 보내기
이 단계에서는 텍스트-비디오 요청을 Gemini Omni Flash API로 보내고, 작업을 추적할 수 있는 prediction_id를 받아옵니다.
Atlas Cloud의 모든 동영상 생성을 위한 엔드포인트는 다음과 같습니다.
plaintext1POST https://api.atlascloud.ai/api/v1/model/generateVideo
Gemini Omni Flash 텍스트-비디오 모델 식별자는 다음과 같습니다.
plaintext1google/gemini-omni-flash/text-to-video-developer
Python
plaintext1# gemini_omni_t2v.py 2import requests 3import os 4 5API_KEY = os.environ["ATLASCLOUD_API_KEY"] 6BASE_URL = "https://api.atlascloud.ai/api/v1/model" 7 8headers = { 9 "Content-Type": "application/json", 10 "Authorization": f"Bearer {API_KEY}" 11} 12 13payload = { 14 "model": "google/gemini-omni-flash/text-to-video-developer", 15 "prompt": "A young woman walks slowly through a rainy Tokyo street at night, neon reflections on wet pavement, cinematic slow motion, realistic lighting, 4K, film grain", 16 "duration": 8, # 초: 4, 6, 8, 또는 10 17 "aspect_ratio": "16:9", # "16:9" 또는 "9:16" 18 "resolution": "1080p", # "720p", "1080p", 또는 "4k" 19 "seed": -1 # -1은 무작위; 결과 재현을 위해 특정 정수 설정 가능 20} 21 22response = requests.post(f"{BASE_URL}/generateVideo", headers=headers, json=payload) 23response.raise_for_status() 24 25prediction_id = response.json()["data"]["id"] 26print(f"작업 제출됨. Prediction ID: {prediction_id}")
Node.js
plaintext1// geminiOmniT2V.js 2const axios = require("axios"); 3 4const API_KEY = process.env.ATLASCLOUD_API_KEY; 5const BASE_URL = "https://api.atlascloud.ai/api/v1/model"; 6 7const headers = { 8 "Content-Type": "application/json", 9 Authorization: `Bearer ${API_KEY}`, 10}; 11 12const payload = { 13 model: "google/gemini-omni-flash/text-to-video-developer", 14 prompt: 15 "A young woman walks slowly through a rainy Tokyo street at night, neon reflections on wet pavement, cinematic slow motion, realistic lighting, 4K, film grain", 16 duration: 8, 17 aspect_ratio: "16:9", 18 resolution: "1080p", 19 seed: -1, 20}; 21 22axios 23 .post(`${BASE_URL}/generateVideo`, payload, { headers }) 24 .then((res) => { 25 const predictionId = res.data.data.id; 26 console.log(`작업 제출됨. Prediction ID: ${predictionId}`); 27 }) 28 .catch((err) => console.error(err.response?.data || err.message));
예상 출력:
plaintext1작업 제출됨. Prediction ID: pred_abc123xyz
주의: API는 즉시 prediction_id를 반환하지만 영상 생성이 완료된 것은 아닙니다. 3단계에서 상태 엔드포인트를 폴링하여 결과 URL을 확인해야 합니다.
3단계: Gemini Omni Flash 영상 결과 폴링하기
이 단계에서는 영상 생성이 완료되어 결과 URL을 얻을 수 있을 때까지 상태 엔드포인트를 주기적으로 호출합니다.
Gemini Omni Flash를 이용한 영상 생성은 비동기식으로 이루어집니다. 일반적인 완료 시간은 해상도와 서버 부하에 따라 30초에서 3분 정도 소요됩니다. 상태 엔드포인트는 다음과 같습니다.
plaintext1GET https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}
가능한 상태 값: processing(처리 중), completed(완료됨), succeeded(성공), failed(실패).
Python
plaintext1# poll_result.py 2import requests 3import time 4import os 5 6API_KEY = os.environ["ATLASCLOUD_API_KEY"] 7BASE_URL = "https://api.atlascloud.ai/api/v1/model" 8 9headers = { 10 "Authorization": f"Bearer {API_KEY}" 11} 12 13def poll_video(prediction_id: str, timeout: int = 360) -> str: 14 """영상이 준비될 때까지 폴링한 후 결과 URL 반환""" 15 elapsed = 0 16 while elapsed < timeout: 17 response = requests.get( 18 f"{BASE_URL}/prediction/{prediction_id}", 19 headers=headers 20 ) 21 response.raise_for_status() 22 data = response.json()["data"] 23 status = data["status"] 24 25 if status in ("completed", "succeeded"): 26 video_url = data["outputs"][0] 27 print(f"영상 준비 완료: {video_url}") 28 return video_url 29 30 if status == "failed": 31 raise RuntimeError(f"생성 실패: {data}") 32 33 print(f"상태: {status} — 3초 대기 중...") 34 time.sleep(3) 35 elapsed += 3 36 37 raise TimeoutError(f"{timeout}초 이내에 생성되지 않음.") 38 39# 2단계에서 받은 실제 prediction_id로 교체하세요 40video_url = poll_video("pred_abc123xyz")
Node.js
plaintext1// pollResult.js 2const axios = require("axios"); 3 4const API_KEY = process.env.ATLASCLOUD_API_KEY; 5const BASE_URL = "https://api.atlascloud.ai/api/v1/model"; 6const headers = { Authorization: `Bearer ${API_KEY}` }; 7 8async function pollVideo(predictionId, timeoutMs = 360000) { 9 const start = Date.now(); 10 while (Date.now() - start < timeoutMs) { 11 const res = await axios.get(`${BASE_URL}/prediction/${predictionId}`, { headers }); 12 const data = res.data.data; 13 14 if (data.status === "completed" || data.status === "succeeded") { 15 console.log("영상 준비 완료:", data.outputs[0]); 16 return data.outputs[0]; 17 } 18 if (data.status === "failed") throw new Error(`생성 실패: {JSON.stringify(data)}`); 19 20 console.log(`상태: ${data.status} — 3초 대기 중...`); 21 await new Promise((r) => setTimeout(r, 3000)); 22 } 23 throw new Error("생성 시간 초과."); 24} 25 26pollVideo("pred_abc123xyz");
예상 출력:
plaintext1상태: processing — 3초 대기 중... 2상태: processing — 3초 대기 중... 3영상 준비 완료: https://storage.atlascloud.ai/outputs/result.mp4
폴링 간격은 1초 대신 3초로 설정하세요. 1080p 기준 30초 내에 완료되는 경우가 드물기 때문에 1초마다 API를 호출하는 것은 불필요한 요청만 발생시킵니다.
주의: 결과 영상은 Atlas Cloud 서버에 48시간 동안만 저장됩니다. 보관이 필요하다면 생성 즉시 로컬 스토리지로 다운로드하세요.
4단계: Gemini Omni Flash API로 이미지-비디오(Image-to-Video) 생성하기
이 단계에서는 로컬 이미지를 Atlas Cloud에 업로드하고, 이를 참조하여 Gemini Omni Flash API로 영상 생성을 진행합니다.
이미지-비디오 생성은 동일한 엔드포인트를 사용하지만, 모델 ID가 다르며
1imagesplaintext1google/gemini-omni-flash/image-to-video-developer
Gemini Omni Flash 이미지-비디오는 1~7개의 참조 이미지(PNG, JPEG, JPG, WebP 지원; 각 최대 20MB, 최소 128×128px)를 허용합니다. 생성된 영상 전반에서 시각적 정체성을 보존하여 인물과 객체를 일관성 있게 유지합니다.
4a단계: 이미지 업로드
plaintext1# upload_image.py 2import requests 3import os 4 5API_KEY = os.environ["ATLASCLOUD_API_KEY"] 6UPLOAD_URL = "https://api.atlascloud.ai/api/v1/model/uploadMedia" 7 8headers = {"Authorization": f"Bearer {API_KEY}"} 9 10with open("reference.jpg", "rb") as f: 11 response = requests.post(UPLOAD_URL, headers=headers, files={"file": f}) 12 13response.raise_for_status() 14image_url = response.json()["data"]["url"] 15print(f"업로드된 이미지 URL: {image_url}")
4b단계: 이미지-비디오 요청 제출
plaintext1# gemini_omni_i2v.py 2import requests 3import os 4 5API_KEY = os.environ["ATLASCLOUD_API_KEY"] 6BASE_URL = "https://api.atlascloud.ai/api/v1/model" 7 8headers = { 9 "Content-Type": "application/json", 10 "Authorization": f"Bearer {API_KEY}" 11} 12 13payload = { 14 "model": "google/gemini-omni-flash/image-to-video-developer", 15 "prompt": "The character walks forward slowly, natural lighting, cinematic depth of field", 16 "images": [image_url], # 4a단계에서 받은 URL 사용 17 "duration": 8, 18 "aspect_ratio": "16:9", 19 "resolution": "1080p", 20 "seed": -1 21} 22 23response = requests.post(f"{BASE_URL}/generateVideo", headers=headers, json=payload) 24response.raise_for_status() 25 26prediction_id = response.json()["data"]["id"] 27print(f"작업 제출됨. Prediction ID: {prediction_id}") 28# 3단계의 poll_video() 함수를 사용하여 상태 확인
Gemini Omni Flash 이미지-비디오에서 최상의 결과를 얻으려면 배경이 단순하고 밝은 곳에서 촬영된 참조 이미지를 사용하는 것이 좋습니다. 피사체가 배경과 명확히 구분될 때 얼굴과 의상 디테일이 더욱 일관되게 보존됩니다. 복잡한 패턴이나 과도한 후보정이 들어간 이미지는 프레임 간 결과값이 일관되지 않을 수 있습니다.
주의: PNG, JPEG, JPG, WebP 형식만 지원됩니다. 20MB를 초과하는 파일은 400 에러와 함께 거부됩니다.
5단계: 매개변수 하나로 모델 변경하기
Atlas Cloud를 통해 Gemini Omni API에 액세스하는 실질적인 장점은 플랫폼상의 모든 동영상 생성 모델이 동일한 엔드포인트와 폴링 로직을 공유한다는 점입니다. Gemini Omni Flash에서 다른 모델로 전환하려면 모델 매개변수만 바꾸면 됩니다.
plaintext1# Seedance 2.0 텍스트-비디오로 전환 (Atlas Cloud 기준 초당 $0.096) 2payload["model"] = "bytedance/seedance-2-0/text-to-video" 3 4# Veo 3.1 Lite로 전환 5payload["model"] = "google/veo-3-1/lite-text-to-video"
이를 통해 A/B 테스트를 손쉽게 진행할 수 있습니다. 동일한 프롬프트로 여러 모델을 구동하여 결과물의 품질을 비교한 뒤, 프로덕션용 모델을 확정할 수 있습니다.
Gemini Omni Flash API 문제 해결
Gemini Omni Flash API 사용 시 발생하는 가장 흔한 5가지 이슈와 해결 방법입니다.
| 문제 | 증상 | 해결 방법 |
|---|---|---|
| 401 Unauthorized | {"error": "Invalid API key"} | ATLASCLOUD_API_KEY 환경 변수가 올바르게 설정되었고 만료되지 않았는지 확인 |
| 400 Bad Request | {"error": "Invalid prompt"} | 프롬프트가 콘텐츠 정책을 위반했을 가능성 있음; 수정하거나 금지된 키워드 제거 |
text | 6분이 지나도 완료되지 않음 | 작업 재시도; 매우 드물지만 피크 시간대에 발생할 수 있음 |
| 영상 URL 404 에러 | URL에 접근 불가 | 결과 파일은 48시간 후 만료; 생성 직후 다운로드 필요 |
| 429 Too Many Requests | 요청 속도 제한 초과 | 요청 사이에 지연 시간 추가; 재시도 시 지수 백오프 적용 |
여전히 문제가 있나요? Atlas Cloud 문서를 확인하거나 플랫폼의 지원 채널로 문의하세요.
다음 단계
이제 작동하는 텍스트-비디오 및 이미지-비디오 스크립트를 갖게 되었습니다. 이를 확장하는 방법은 다음과 같습니다.
프로젝트 확장:
- 오디오 입력을 결합한 참조-비디오 생성(Reference-to-Video)을 위해 Seedance 2.0을 사용해보세요. 최대 7개의 참조 이미지와 오디오 트랙을 결합할 수 있습니다.
- 여러 프롬프트를 병렬로 제출하고 결과를 비동기적으로 수집하는 일괄 생성 파이프라인을 구축해보세요.
- 비용 계산기를 스크립트에 추가해보세요: 비용 = 0.20 + (duration * 0.10) [720p/1080p 기준].
관련 리소스:
- Atlas Cloud 영상 모델 카탈로그 — 사용 가능한 모든 영상 생성 모델
- Atlas Cloud 가격 페이지 — 모든 모델에 대한 전체 가격 정보
- Atlas Cloud API 문서 — 상세 API 참조
자주 묻는 질문(FAQ)
Gemini Omni Flash API란 무엇인가요?
Gemini Omni Flash API는 텍스트, 이미지, 오디오, 비디오를 조합하여 입력하면 영화 같은 동영상 클립을 출력하는 Google의 멀티모달 동영상 생성 인터페이스입니다. 410초 길이, 720p4K 해상도, 가로/세로 화면 비율을 모두 지원합니다. 별도의 Google 승인 절차 없이 Atlas Cloud를 통해 바로 액세스할 수 있습니다.
Gemini Omni Flash API의 비용은 얼마인가요?
Atlas Cloud에서 Gemini Omni Flash는 720p 및 1080p 기준 기본 USD0.20에 초당 USD0.10이 추가됩니다. 표준 8초짜리 1080p 클립 생성 시 USD1.00입니다. 4K 출력의 경우 기본 요금 USD1.00에 초당 USD0.10이 추가되어 8초짜리 4K 클립은 USD1.80입니다. 최소 결제 금액 없는 종량제 방식입니다(2026년 6월 2일 Atlas Cloud 가격 기준).
Gemini Omni Flash API 사용 시 Google AI Studio와 Atlas Cloud의 차이점은 무엇인가요?
Google AI Studio는 Gemini 모델에 직접 액세스할 수 있게 해주지만 Google 계정이 필요하며, 개인별 사용량 제한이 있어 금방 도달할 수 있습니다. Atlas Cloud는 동일한 Gemini Omni Flash 모델을 통합 API 엔드포인트를 통해 제공하며, 투명한 초 단위 과금, 승인 대기열 없음, 그리고 단일 API 키로 300개 이상의 다른 영상 및 이미지 모델을 이용할 수 있는 장점이 있습니다. 프로덕션 환경에서는 모델 제공업체마다 별도의 자격 증명을 관리할 필요가 없는 Atlas Cloud 통합 API가 훨씬 유리합니다.
Gemini Omni Flash로 영상을 생성하는 데 얼마나 걸리나요?
8초짜리 1080p 영상의 일반적인 생성 시간은 서버 부하에 따라 30초에서 3분 사이입니다. 이 API는 비동기식입니다. 스크립트가 작업을 제출하고 즉시 prediction_id를 받은 뒤, 영상이 준비될 때까지 상태 엔드포인트를 폴링하는 방식입니다. 최대 6분 정도의 타임아웃 처리를 구현해 두면 피크 시간대에도 안전합니다.
Gemini Omni Flash API를 무료로 사용할 수 있나요?
Atlas Cloud는 신규 계정에 무료 크레딧을 제공하며, 이를 Gemini Omni Flash 생성에 사용할 수 있습니다. 무료 크레딧을 모두 사용한 후에는 구독 없이 종량제로 결제됩니다. atlascloud.ai에서 가입하고 시작해보세요.
