Grok Imagine视频API初心者向けチュートリアル
出典: Elser AI
GrokビデオAPIは、開発者がテキストプロンプトに基づいてビデオを生成することを可能にし、サポートされているワークフローでは、開始画像やその他の参照を使用することもできます。同期テキスト応答とは異なり、ビデオ生成は非同期です。最初のリクエストでタスクIDが返され、アプリケーションは結果が準備できるまでポーリングする必要があります。
このチュートリアルでは、アーキテクチャを説明し、最小限のPythonサンプルを提供します。コードを書く前に視覚的な品質を評価したい場合は、Elser AIのGrok Imagineワークスペースでプロンプトをテストし、成功したレンズ仕様をAPIに移行できます。
ご必要なものは何ですか
- xAI 開発者アカウント1つ；
- 安全に保存されたAPIキー；
- Python 3.10 以降のバージョン；
requestsパッケージ；- 動画ファイルの永続ストレージが完了しました；
- 予算とリトライ戦略。
APIキーをソースコードにハードコードしたり、ブラウザ側のJavaScriptで公開したりしないでください。
API ワークフローの仕組み
/v1/videos/generationsに生成リクエストを送信してください。request_idを受け取ります。/v1/videos/{request_id}をポーリングします。- ステータスが
doneになるか、端末障害が発生した場合に停止します。 - 生成されたURLは一時的なものですので、返却された動画は速やかにダウンロードしてください。
- メタデータ、プロンプト、モデル、設定、コストを保存し、監査と再現性に使用します。
最小テキスト動画変換例
import os
import time
from pathlib import Path
import requests
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "grok-imagine-video-1.5",
"prompt": (
マットブラックの製品ボックスが反射する表面上で開かれている。
柔らかなコーラル色の照明が、カメラ作動時に製品を照らします
ゆっくりと近づく。高級スタジオ照明、リアルな動き、文字なし。
),
"duration": 6,
"resolution": "720p",
}
create = requests.post(
f"{BASE_URL}/videos/generations"
headers=HEADERS,
json=負荷,
timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]
deadline = time.time() + 15 * 60
while time.time() < deadline:
status_response = requests.get(
f"{BASE_URL}/videos/{request_id}"
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=60、
)
status_response.raise_for_status()
result = status_response.json()
結果が["状態"] == "完了":
video_url = 結果["動画"]["url"]
video_response = requests.get(video_url, timeout=180)
video_response.raise_for_status()
Path("output.mp4").write_bytes(video_response.content)
print("output.mp4 を保存しました")
中断
もし結果が["状態"] {"expired", "failed", "cancelled"} の中で：
raise RuntimeError(f"生成終了、状態：{result['status']}")
time.sleep(5)
else:
タイムアウトエラー（「ビデオ生成が期限までに完了しませんでした」）を引き起こす
デプロイ前に、xAIの現在のAPIアーキテクチャを確認してください。モデル名、サポートされるパラメータ、応答ステータスは変更される可能性があります。
画像から動画へ
xAIのドキュメントでは、公開画像URLまたはbase64データURIを使用した画像主導の生成をサポートしています。概念的には、リクエストに画像オブジェクトが追加されます。
payload = { "model": "grok-imagine-video-1.5", "prompt": ( 主体、服装、背景を保持する。 主体が窓の方を向き、同時にカメラがゆっくりと前進する。 ), "画像": {"url": "https://example.com/source-image.png"}, "duration": 6, "resolution": "720p", }
入力がプライベートな場合は、短期間有効な署名付きURLを使用してください。APIの要件を満たすためだけに、顧客のメディアコンテンツを公開してはなりません。
## 本番環境のエラー処理
本番環境のクライアントは以下を処理すべき：
- 認証に失敗しました；
- 検証エラー；
- 審査拒否；
- レート制限；
- ネットワークタイムアウト；
- 期限切れの職位や結果リンク；
- 重複送信；
- 一部のストレージ障害；
- アカウントの予算が尽きました。
リトライ可能なエラーに対しては、ジッターを伴う指数バックオフ戦略を使用してください。検証や審査の失敗を無制限にリトライしないでください。冪等キーを追加するか、独自のタスク記録を維持して、ネットワークのリトライによって予期しない動画の重複が発生しないようにしてください。
## コスト管理
xAIは生成された秒数に基づいて動画の価格を設定し、料金はモデルと解像度によって異なります。メディア入力にも費用が発生する場合があります。各ジョブのモデル、解像度、時間、および返される使用データが保存されます。
役立つ安全対策には以下が含まれます：
- 各リクエストの最大時間；
- 各ユーザーの1日あたりの支出上限；
- 低解像度ドラフトモード；
- 高解像度再レンダリングの前に承認を得る必要があります。
- 自動リトライ回数制限；
- 異常生成量アラート；
- 各承認済みセグメントのコストレポート。
## キューと並行設計
動画タスクはキューに入る必要があります。ワーカーノードがリクエストを送信し、責任を持ってポーリングし、完了したファイルを永続化オブジェクトストレージに転送します。アプリケーションデータベースは以下を追跡する必要があります：
- 内部ポジションID；
- xAI リクエスト ID；
- ユーザーとプロジェクト；
- プロンプトと入力の引用；
- 状態と進捗；
- タイムスタンプ；
- モデルと設定；
- 出力ストレージURL；
- コストと審査結果。
現在のアカウントレベルのレート制限を遵守してください。過度の並列操作によりレート制限やコストの制御不能が発生しても、何の利益もありません。
## 安全性とプライバシー
ユーザーがアップロードした画像に対する権限と、識別可能な人物の許可を検証します。非自発的な親密画像、詐欺的ななりすまし、搾取、または違法コンテンツを作成しようとする明らかな試みをシステムが拒否するようにします。サービスに必要なメディアとログのみを保持し、明確な削除ポリシーを公開します。
提供者のウォーターマークやソース識別子を削除してはならない。高い拡散性、政治、医療、金融、または身分に敏感な内容については、人間による審査を含める必要がある。
## API統合前のノーコード評価
クリエイティブ仕様が検証された後、APIプロジェクトはより容易に実施できます。[Elser AI上のGrok Imagine Video](https://www.elser.ai/ja/m/grok)を使用して、プロンプト、参照画像の適合性、アスペクト比、およびショットの受入基準をテストします。チームが使用可能なショットを確実に記述できるようになったら、繰り返し部分を自動化できます。
## 起動チェックリスト
- API キーはキーマネージャーに保存されています。
- 現在のモデルとパラメータは xAI ドキュメントに基づいて検証済みです。
- キュー、タイムアウト、リトライ、および冪等性ロジックはテスト済みです。
- 一時的なURLから転送された出力。
- 各ユーザーおよびグローバル消費制限が有効になっています。
- 審査失敗の処理、盲目的な再試行は行わない。
- ソースの権利と同意が確認されました。
- ログから機密メディアと資格情報を除外します。
- 透かしとAI開示ルールは文書化されています。
