> ## 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)

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを促され、完了後に現在のページへ自動的に戻ります。

**1 つの 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`：受け取りたいレスポンス結果の形式です。ここでは `application/json`、つまり 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` を使用して動画編集を行う場合、このパラメータは必須です（少なくとも 1 枚）。
* `video_urls`：任意の参照動画リンク配列（最大 1 つ）です。**動画編集 / 動画参照**に使用されます。指定する場合は、少なくとも 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` に 1 つまたは複数の画像リンクを渡して、動画生成のガイドに使用できます：

```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"
  ]
}
```

## 動画編集 / 参照動画（動画を入力して動画を生成）

「1 本の動画を入力し、新しい動画を生成する」ことに直接対応しています：`video_urls` に参照動画リンクを 1 つ（最大 1 つ）渡し、**同時に** `image_urls` に少なくとも 1 枚の参照画像を指定し（上流の必須要件）、その後 `prompt` で希望する編集効果（スタイル変更、シーン変更、要素の追加・削除など）を説明します。

以下は完全な実例です——日差しのあるビーチ動画を雪が降りしきる冬のシーンに変更しながら、ビーチ、ヤシの木、小舟のレイアウトを維持します。動画編集には比較的長い時間がかかるため（この例では約 6.5 分）、`async: true` を使用して非同期で送信します：

```json theme={null}
{
  "prompt": "この晴れた熱帯のビーチを、大雪が降る曇り空の雪深い冬のシーンに変えてください。同じビーチ、ヤシの木、ボートのレイアウトを維持してください。",
  "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": "この晴れた熱帯のビーチを、大雪が降る曇り空の雪深い冬のシーンに変えてください。同じビーチ、ヤシの木、ボートのレイアウトを維持してください。"
    }
  ],
  "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` を指定する場合は、少なくとも 1 枚の `image_urls` を指定する必要があります。そうしない場合、以下のパラメータエラーが返されます：

```json theme={null}
{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "video_urls が指定されている場合、image_urls（少なくとも1枚の参照画像）が必要です。"
  }
}
```

## 非同期コールバック

動画生成には一定の処理時間が必要です。長時間接続を維持して待機したくない場合は、`callback_url` を渡すことができます。この場合、API は直ちに `task_id` を返し、タスク完了後に最終結果をそのアドレスへ POST します：

```json theme={null}
{
  "prompt": "日差しの差し込む庭で、子猫が蝶を追いかける映画のようなショット",
  "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": "日の出の雪山の上を流れる雲のタイムラプス",
    "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": "日の出の雪山の上を流れる雲のタイムラプス"
      }
    ],
    "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.