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

# Grok Videos Generation API 接続説明

> Grok API guide - Ace Data Cloud

本文では、Grok Videos Generation API の接続説明を紹介します。これは、入力テキストプロンプト、入力画像、およびオプションの参照画像を使用して Grok Imagine（xAI）動画を生成することができます。

## 申請プロセス

Grok Videos Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API トークンを取得し、保管してください。

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

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

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[Grok Videos Generation API →](https://platform.acedata.cloud/documents/grok-videos)

## モデル説明

本 API は、モデル名の接尾辞によって上流エンドポイントを選択します：`:reverse` は高速/標準エンドポイント（より安価）を使用し、`:official` は公式エンドポイント（画質が高く、出力秒数に基づいて課金）を使用します。合計で4つのモデルをサポートしています：

* `grok-imagine-video-1.5-fast:reverse`（デフォルト）：テキストから動画（`prompt` のみを送信）および画像から動画（`image_url` を送信）をサポートし、長さは6〜30秒、長さに応じて段階的に課金され、最も安価です。
* `grok-imagine-video:reverse`：テキストと画像からの動画をサポートし、長さは1〜15秒、出力秒数に基づいて課金されます。
* `grok-imagine-video:official`：公式エンドポイントで、テキストと画像からの動画をサポートし、長さは1〜15秒、出力秒数に基づいて課金され、画質が高いです。
* `grok-imagine-video-1.5:official`：公式エンドポイントで、**画像からの動画のみをサポート**し、**必ず** `image_url` を送信する必要があります。長さは1〜15秒、最高 `1080p` をサポートし、出力秒数に基づいて課金されます。

## 基本使用

まず、基本的な使用方法を理解します。入力プロンプト `prompt`、モデル `model` などのパラメータを入力することで、対応する動画を生成できます。

ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、すなわち JSON 形式を指定します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

また、リクエストボディを設定しています。これには以下が含まれます：

* `prompt`：生成したい動画内容を説明するテキストプロンプト。テキストから動画を生成する際は**必須**；`image_url` を送信する場合はオプションです。
* `model`：生成する動画のモデル。`grok-imagine-video-1.5-fast:reverse`（デフォルト）、`grok-imagine-video:reverse`、`grok-imagine-video:official` または `grok-imagine-video-1.5:official` のいずれかを選択できます。
* `image_url`：画像からの動画の入力画像リンク。`model` が `grok-imagine-video-1.5:official` の場合は**必須**です。
* `reference_image_urls`：動画のスタイルや内容を導くためのオプションの参照画像リンクの配列。
* `aspect_ratio`：生成する動画のアスペクト比。`1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` のいずれかを選択できます。
* `resolution`：出力解像度。`480p`（デフォルト）、`720p` または `1080p` のいずれかを選択できます。
* `duration`：生成する動画の長さ（秒）。`grok-imagine-video-1.5-fast:reverse` の値の範囲は6〜30、他のモデルの値の範囲は1〜15、デフォルトは6です。6秒または10秒の使用を推奨します。これらの標準長さは比較的安定しています。
* `callback_url`：非同期コールバックアドレス。設定後、API はすぐに `task_id` を返し、タスクが完了した際に結果をそのアドレスに POST します。
* `async`：オプション。`true` に設定すると、インターフェースはすぐに `task_id` を返し、`callback_url` を提供する必要がなくなります。その後、対応するタスククエリインターフェースを通じて結果をポーリングして取得します。

「Try」ボタンをクリックするとテストが行え、得られた結果は以下のようになります：

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `success`：今回の動画生成リクエストが成功したかどうか。
* `task_id`：今回の動画生成タスクの ID。
* `trace_id`：今回のリクエストのトレース ID。問題を調査するために使用します。
* `data`：生成された動画結果のリスト。
  * `id`：生成された動画の一意の識別子。
  * `video_url`：生成された動画のリンクアドレス。
  * `state`：動画生成タスクの状態。`pending` / `succeeded` / `failed` のいずれかです。

私たちは、結果の `data` の `video_url` リンクアドレスに基づいて生成された動画を取得するだけです。

対応する CURL コードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

対応する Python コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

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

## 画像からの動画

入力画像に基づいて動画を生成したい場合は、`image_url` を送信できます。`grok-imagine-video-1.5:official` を使用する際は、このフィールドを必ず提供する必要があります：

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## 参考画像によるガイド

1枚または複数の参考画像を使用して動画のスタイルや内容を導きたい場合は、`reference_image_urls` に画像リンクの配列を送信できます：

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## 非同期コールバック

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

```json theme={null}
{
  "prompt": "日差しの差し込む庭で蝶を追いかける子猫のシネマティックショット",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

即時に返される結果は以下の通りです：

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## タスク結果の確認

非同期コールバックを使用した場合や、タスクの状態を積極的に確認したい場合は、[Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks)（`POST https://api.acedata.cloud/grok/tasks`）を使用して`task_id`に基づいてタスクの最新の状態と結果を確認できます。

## 課金説明

本サービスの課金方式は`model`によって決まります：

* `grok-imagine-video-1.5-fast:reverse`：時間に応じた段階的課金で、解像度には関係ありません——`6–10`秒、`11–20`秒、`21–30`秒はそれぞれ異なる価格帯に対応します。
* `grok-imagine-video:reverse`：出力秒数に基づいて課金され、総額 = 単価 × `duration`。
* `grok-imagine-video:official`および`grok-imagine-video-1.5:official`：公式エンドポイントで、出力秒数に基づいて課金され、解像度が高いほど単価が高くなります；公式モデルは内容審査に失敗しても課金されます。

具体的な単価は価格ページに基づきます。失敗したリクエストは課金されず、無料枠も消費しません。

## エラー処理

リクエストに問題が発生した場合、APIは対応するエラーコードと説明を返します。一般的なものは以下の通りです：

* `400`：リクエストパラメータに誤りがある場合、例えば文生動画に`prompt`が欠けている、または`grok-imagine-video-1.5:official`に`image_url`が欠けている、または`duration`が範囲外（`grok-imagine-video-1.5-fast:reverse`は6–30、他のモデルは1–15）。
* `401`：認証失敗、トークンが無効またはAPIと一致しない。
* `403`：残高不足、またはプロンプトが内容審査に引っかかり拒否された。
* `429`：リクエストが頻繁すぎます。後で再試行してください。
* `500`：動画生成に失敗したか、サービスに異常があります。


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