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 엔드포인트를 사용합니다.
r/GeminiAI의 "Gemini Omni Flash API access: 5 providers tested, ranked by use case"라는 제목의 스레드가 6일 전 게시된 이후, 옵션을 평가하는 개발자들 사이에서 필수 참고 자료로 빠르게 자리 잡았습니다. 가장 많은 추천을 받은 댓글은 핵심을 정확히 짚었습니다. 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-06-02 기준):
- 720p / 1080p: 기본 USD0.20 + 초당 USD0.10. 8초짜리 720p 비디오 생성 시 USD1.00 비용 발생.
- 4K: 기본 USD1.00 + 초당 USD0.10. 8초짜리 4K 비디오 생성 시 USD1.80 비용 발생.
Gemini Omni API로 만드는 것
이 튜토리얼을 마치면 두 가지 스크립트를 얻게 됩니다. 하나는 텍스트 프롬프트로 비디오를 생성하는 것이고, 다른 하나는 참조 이미지를 애니메이션화하여 비디오로 만드는 것입니다. 두 스크립트 모두 동일한 인증 및 폴링 로직을 공유합니다. 아키텍처는 다음과 같습니다:
plaintext1사용자 스크립트 → Atlas Cloud API → Gemini Omni Flash → 비디오 URL 2 (인증 + 대기열) (생성) (출력)
완성된 스크립트의 기능:
- 생성 요청을 제출하고 prediction_id를 수신
- 비디오가 준비될 때까지 3초마다 상태 엔드포인트를 폴링
- 생성이 완료되면 출력 비디오 URL을 출력
1단계: Gemini Omni Flash API 키 발급받기
이 단계에서는 Atlas Cloud 계정을 만들고 API 키를 생성하여 스크립트가 Gemini Omni Flash 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 키를 버전 관리 시스템에 절대 커밋하지 마세요. python-dotenv나 Node.js용 dotenv를 사용하는 경우, .env 파일에 추가하고 ATLASCLOUD_API_KEY를 .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초로 설정하세요. 1초마다 폴링하는 것은 1080p 작업이 30초 이내에 완료되는 경우가 드물기 때문에 대기 시간을 의미 있게 단축하지 못하면서 불필요한 API 호출만 증가시킵니다.
주의: 출력된 비디오는 Atlas Cloud 서버에 48시간 동안 보관됩니다. 보관이 필요한 경우 생성 직후 파일을 직접 다운로드하세요.
4단계: Gemini Omni Flash API를 이용한 이미지-비디오 생성
이 단계에서는 로컬 이미지를 Atlas Cloud에 업로드하고 이를 Gemini Omni Flash API의 이미지-비디오(Image-to-Video) 생성을 위한 참조로 사용합니다.
이미지-비디오 생성은 동일한 엔드포인트를 사용하지만, 다른 모델 ID와 images 배열이 필요합니다. 모델 식별자는 다음과 같습니다:
plaintext1google/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"} | 프롬프트가 콘텐츠 정책을 위반했을 수 있습니다; 재작성하거나 제한된 콘텐츠를 제거하세요 |
processing 상태 고착 | 6분이 지나도 completed 상태가 안 됨 | 요청을 재시도하세요; 드물지만 부하가 높을 때 발생할 수 있습니다 |
| 비디오 URL 404 에러 | URL에 액세스할 수 없음 | 출력 파일은 48시간 후 만료됩니다; 생성 직후 다운로드하세요 |
| 429 Too Many Requests | 속도 제한 초과 | 요청 사이에 지연 시간을 추가하세요; 재시도 시 지수 백오프(exponential backoff)를 사용하세요 |
그래도 해결되지 않나요? Atlas Cloud 문서를 방문하거나 플랫폼의 지원 채널로 문의하세요.
다음 단계
이제 텍스트-비디오 및 이미지-비디오 스크립트가 작동하므로, 이를 확장하는 방법은 다음과 같습니다.
프로젝트 확장:
- 최대 7개의 참조 이미지와 오디오 트랙을 결합할 수 있는 Seedance 2.0을 사용하여 오디오 입력 기반의 참조-비디오 기능을 추가해 보세요.
- 여러 프롬프트를 병렬로 제출하고 비동기적으로 결과를 수집하는 배치 생성 파이프라인을 구축하세요.
- 스크립트에 비용 추정기를 추가하세요: 720p/1080p 기준 비용 = 0.20 + (duration * 0.10)
관련 리소스:
- Atlas Cloud 비디오 모델 카탈로그 — 사용 가능한 모든 비디오 생성 모델
- Atlas Cloud 가격 페이지 — 모든 모델에 대한 전체 가격 정보
- Atlas Cloud API 문서 — 전체 API 참조
자주 묻는 질문 (FAQ)
Gemini Omni Flash API란 무엇인가요?
Gemini Omni Flash API는 텍스트, 이미지, 오디오, 비디오를 조합하여 입력받고 시네마틱 비디오 클립을 출력하는 Google의 멀티모달 비디오 생성 인터페이스입니다. 4~10초의 길이, 720p에서 4K까지의 해상도, 가로 및 세로 화면 비율을 지원합니다. 별도의 Google 승인 절차 없이 Atlas Cloud를 통해 액세스할 수 있습니다.
Gemini Omni Flash API의 비용은 얼마인가요?
Atlas Cloud에서 Gemini Omni Flash는 720p 및 1080p 출력 기준 기본 USD0.20에 초당 USD0.10가 추가됩니다. 1080p의 표준 8초 클립 비용은 USD1.00입니다. 4K 출력의 경우 기본 수수료 USD1.00에 초당 USD0.10가 추가되어 8초짜리 4K 클립 비용은 USD1.80입니다. 모든 과금은 최소 사용 금액이 없는 종량제 방식입니다 (Atlas Cloud 가격 기준, 2026-06-02).
Gemini Omni Flash API 액세스를 위한 Google AI Studio와 Atlas Cloud의 차이점은 무엇인가요?
Google AI Studio는 Gemini 모델에 대한 직접적인 액세스를 제공하지만 Google 계정이 필요하며, 빠르게 소진될 수 있는 개인 사용량 할당량(quota)의 적용을 받습니다. 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에서 가입하여 시작해 보세요.
