Gemini Videos Generation API 연동 안내

본 문서에서는 텍스트 프롬프트(및 선택적 참조 이미지)를 입력하여 Google Gemini(omni-flash) 비디오를 생성할 수 있는 Gemini Videos Generation API의 연동 안내를 소개합니다.

신청 절차

Gemini Videos Generation API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 받아 예비용으로 보관하세요.

아직 로그인하거나 등록하지 않았다면, 자동으로 로그인 페이지로 이동하여 등록과 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스마다 별도로 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: Gemini Videos Generation API →

기본 사용

먼저 기본 사용 방식을 알아보겠습니다. 프롬프트 prompt, 모델 model 및 종횡비 aspect_ratio를 입력하면 해당 비디오를 생성할 수 있습니다. 여기에서 Request Headers를 설정한 것을 볼 수 있으며, 다음을 포함합니다:

accept: 수신하려는 응답 결과의 형식으로, 여기에서는 JSON 형식인 application/json으로 작성합니다.
authorization: API 호출 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.

또한 Request Body를 설정하며, 다음을 포함합니다:

prompt: 생성하려는 비디오 콘텐츠를 설명하는 텍스트 프롬프트로, 필수입니다.
model: 비디오를 생성하는 모델로, 현재는 omni-flash만 지원하며 기본값도 omni-flash입니다.
aspect_ratio: 생성 비디오의 종횡비로, 16:9(가로 화면) 또는 9:16(세로 화면)을 선택할 수 있으며 기본값은 16:9입니다.
resolution: 선택 가능한 출력 해상도로, 720p 또는 1080p를 선택할 수 있으며 기본값은 720p입니다.
image_urls: 비디오 생성을 유도하는 데 사용되는 선택 가능한 참조 이미지 링크 배열로, 비어 있는 항목은 무시됩니다. video_urls를 사용하여 비디오 편집을 할 때는 이 파라미터가 필수입니다(최소 한 장).
video_urls: 비디오 편집 / 비디오 참조에 사용되는 선택 가능한 참조 비디오 링크 배열(최대 1개)로, 제공 시 반드시 최소 한 장의 image_urls도 함께 제공해야 합니다.
callback_url: 비동기 콜백 주소로, 설정 후 API는 즉시 task_id를 반환하며 작업 완료 시 결과를 해당 주소로 POST합니다.
async: 선택 사항으로, true로 설정하면 인터페이스가 즉시 task_id를 반환하며 callback_url을 제공할 필요가 없고, 이후 해당 작업 조회 인터페이스를 통해 폴링하여 결과를 가져옵니다.

「Try」 버튼을 클릭하면 테스트할 수 있으며, 얻는 결과는 다음과 유사합니다:

{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

반환 결과에는 여러 필드가 있으며, 다음과 같이 소개합니다:

success: 이번 비디오 생성 요청의 성공 여부입니다.
task_id: 이번 비디오 생성 작업의 ID입니다.
trace_id: 이번 요청의 추적 ID로, 문제를 조사하는 데 사용됩니다.
data: 생성된 비디오 결과 목록입니다.
- id: 생성 비디오의 고유 식별자입니다.
- video_url: 생성 비디오의 링크 주소입니다(state가 pending일 때는 null).
- state: 비디오 생성 작업의 상태로, pending / succeeded / failed 중 하나입니다.
- aspect_ratio: 해당 비디오의 종횡비로, 요청 파라미터와 일치합니다.
- prompt: 해당 비디오 생성에 사용된 프롬프트입니다.

동기 반환 시 최상위 수준에는 started_at, finished_at, elapsed(소요 시간, 초) 및 cost(이번 차감 금액, 단위 Credit) 등의 필드도 함께 포함됩니다. 결과에서 data의 video_url 링크 주소에 따라 생성된 비디오를 가져오기만 하면 됩니다. 해당 CURL 코드는 다음과 같습니다:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

해당 Python 코드는 다음과 같습니다:

import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

이미지로 비디오 생성

참조 이미지를 기반으로 비디오를 생성하려면, image_urls에 하나 이상의 이미지 링크를 전달하여 비디오 생성을 유도할 수 있습니다:

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

비디오 편집 / 참조 비디오(입력 비디오, 생성 비디오)

「한 편의 비디오를 직접 입력하고, 새로운 비디오 한 편을 생성」하는 것을 지원합니다: video_urls에 참조 비디오 링크 하나(최대 1개)를 전달하고, 동시에 image_urls에 최소 한 장의 참조 이미지를 제공한 뒤(업스트림의 필수 요구 사항), prompt로 원하는 편집 효과(스타일 변경, 장면 교체, 요소 추가 및 삭제 등)를 설명합니다. 아래는 완전한 실제 예시입니다——햇살 가득한 해변 비디오 한 편을 눈이 펑펑 내리는 겨울 장면으로 바꾸면서, 동시에 해변, 야자수 및 작은 배의 배치를 유지합니다. 비디오 편집은 시간이 비교적 오래 걸리므로(이 예시에서는 약 6.5분), async: true로 비동기 제출합니다:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

제출 후 API는 즉시 task_id를 반환합니다:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

이후 해당 task_id를 id로 사용하여 Gemini Tasks API를 폴링하면, 작업 완료 후 생성된 새 비디오를 받을 수 있습니다(이는 본 예시의 실제 반환 결과입니다):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

더 고화질의 결과가 필요한 경우 resolution을 1080p로 설정할 수 있습니다(나머지 매개변수는 변경하지 않음).

안내: 예시의 입력 / 출력 미디어 링크는 모두 실제 생성 결과입니다. 플랫폼에서 생성된 비디오 및 이미지 링크에는 보관 기간이 있으며, 만료 후에는 무효화됩니다. 결과를 받은 후 즉시 다운로드하여 자체 스토리지에 저장하세요.

주의: 참조 비디오는 최대 1개까지 가능합니다. 또한 video_urls를 제공할 때는 최소 한 장의 image_urls를 반드시 제공해야 하며, 그렇지 않으면 다음과 같은 매개변수 오류가 반환됩니다:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

비동기 콜백

비디오 생성에는 일정한 처리 시간이 필요합니다. 긴 연결을 유지하며 대기하고 싶지 않은 경우 callback_url을 전달할 수 있습니다. 이때 API는 즉시 task_id를 반환하고, 작업이 완료되면 최종 결과를 해당 주소로 POST합니다:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

즉시 반환되는 결과는 다음과 같습니다:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

작업 결과 조회

비동기 콜백을 사용했거나 작업 상태를 직접 조회하려는 경우, Gemini Tasks API(POST https://api.acedata.cloud/gemini/tasks)를 통해 task_id를 기준으로 작업의 최신 상태와 결과를 조회할 수 있습니다. 요청 본문에는 비디오 생성 시 반환된 task_id를 id로 전달합니다:

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

작업 완료 후 반환되는 결과는 다음과 유사하며, response.data의 구조는 동기 생성 시와 동일합니다(생성 중일 때 state는 pending이고 video_url은 null입니다):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

오류 처리

요청에 문제가 발생하면 API는 해당 오류 코드와 설명을 반환합니다. 일반적인 경우는 다음과 같습니다:

400: 요청 매개변수가 잘못되었습니다. 예를 들어 prompt가 누락되었거나 aspect_ratio 값이 유효하지 않습니다.
401: 인증에 실패했습니다. token이 유효하지 않거나 API와 일치하지 않습니다.
403: 잔액이 부족하거나 프롬프트가 콘텐츠 심사에 걸려 거부되었습니다.
500: 서버 내부 오류 또는 업스트림 생성 실패입니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Gemini Videos Generation API 연동 안내

신청 절차

기본 사용

이미지로 비디오 생성

비디오 편집 / 참조 비디오(입력 비디오, 생성 비디오)

비동기 콜백

작업 결과 조회

오류 처리

​신청 절차

​기본 사용

​이미지로 비디오 생성

​비디오 편집 / 참조 비디오(입력 비디오, 생성 비디오)

​비동기 콜백

​작업 결과 조회

​오류 처리

신청 절차

기본 사용

이미지로 비디오 생성

비디오 편집 / 참조 비디오(입력 비디오, 생성 비디오)

비동기 콜백

작업 결과 조회

오류 처리