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

申請プロセス

Grok Videos Generation API を使用するには、まず Ace Data Cloud コンソール にアクセスして API トークンを取得し、保管してください。 まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、コンソール で共通残高をチャージできます。
📘 完全なドキュメント:Grok Videos Generation API →

モデルの説明

model を通じて、以下の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」ボタンをクリックするとテストが行え、得られた結果は以下のようになります:
返された結果には複数のフィールドがあり、以下のように説明されます:
  • success:今回の動画生成リクエストが成功したかどうか。
  • task_id:今回の動画生成タスクの ID。
  • trace_id:今回のリクエストのトレース ID。問題を調査するために使用します。
  • data:生成された動画結果のリスト。
    • id:生成された動画の一意の識別子。
    • video_url:生成された動画のリンクアドレス。
    • state:動画生成タスクの状態。pending / succeeded / failed のいずれかです。
私たちは、結果の data の video_url リンクアドレスに基づいて生成された動画を取得するだけです。 対応する CURL コードは以下の通りです:
対応する Python コードは以下の通りです:

画像からの動画

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

参考画像によるガイド

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

非同期コールバック

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

タスク結果の確認

非同期コールバックを使用した場合や、タスクの状態を積極的に確認したい場合は、Grok Tasks API(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:動画生成に失敗したか、サービスに異常があります。