> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini Videos Generation API 연동 안내

> Gemini AI API guide - Ace Data Cloud

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

## 신청 절차

Gemini Videos Generation API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 받아 예비용으로 보관하세요.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 등록하지 않았다면, 자동으로 로그인 페이지로 이동하여 등록과 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다.

**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스마다 별도로 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

## 기본 사용

먼저 기본 사용 방식을 알아보겠습니다. 프롬프트 `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」 버튼을 클릭하면 테스트할 수 있으며, 얻는 결과는 다음과 유사합니다:

```json theme={null}
{
  "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 코드는 다음과 같습니다:

```shell theme={null}
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 코드는 다음과 같습니다:

```python theme={null}
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`에 하나 이상의 이미지 링크를 전달하여 비디오 생성을 유도할 수 있습니다:

```json theme={null}
{
  "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`로 비동기 제출합니다:

```json theme={null}
{
  "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`를 반환합니다:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

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

```json theme={null}
{
  "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`를 반드시 제공해야 하며, 그렇지 않으면 다음과 같은 매개변수 오류가 반환됩니다:

```json theme={null}
{
  "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합니다:

```json theme={null}
{
  "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"
}
```

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

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

## 작업 결과 조회

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

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

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

```json theme={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`: 서버 내부 오류 또는 업스트림 생성 실패입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.