Grok画像から動画APIの使い方【ステップバイステップガイド】

要約

Grok画像-動画APIは、grok-imagine-videoモデルを使用して、静止画像を動画クリップにアニメーション化します。画像のURL、プロンプト、およびオプション設定をhttps://api.x.ai/v1/videos/generationsにPOSTします。APIはすぐにrequest_idを返します。その後、statusが"done"になるまでGET /v1/videos/{request_id}をポーリングします。動画の長さは1秒から15秒です。料金は480p出力で1秒あたり0.05ドルから始まります。

はじめに

2026年1月28日、xAIはgrok-imagine-videoモデルを公開APIアクセス向けにローンチしました。その最初の1ヶ月で、このモデルは12億本の動画を生成し、Artificial Analysisのテキスト-動画リーダーボードで第1位を獲得しました。画像-動画機能はその主力機能の1つです。APIに写真と説明的なプロンプトを渡すと、その写真が短い動画クリップにアニメーション化され、MP4としてダウンロードできます。

ジョブを送信し、完了をポーリングするこの非同期フローは、多くの開発者が見過ごすテストの課題をもたらします。最初のPOSTが200を返しただけでは統合は完了しません。実際のネットワーク条件下でポーリングループが"processing"、"done"、および"failed"の状態を正しく処理することを確認して初めて完了します。

Apidogのテストシナリオは、この問題を直接解決します。チェーンされたシーケンスを構築できます。つまり、/v1/videos/generationsにPOSTし、request_idを抽出し、status == "done"になるまでポーリングリクエストをループし、その後動画URLが存在することをアサートします。このガイドの後半にあるテストのウォークスルーに従うために、Apidogを無料でダウンロードしてください。

button

Grok画像-動画APIとは？

Grok画像-動画APIは、xAIの動画生成製品の一部です。grok-imagine-videoモデルの下にあり、出力動画の開始フレームとして画像を受け入れます。モデルは画像コンテンツとテキストプロンプトを分析し、シーンをアニメーション化する自然な動きを生成します。

APIエンドポイントは次のとおりです。

POST https://api.x.ai/v1/videos/generations

認証には標準のベアラー（Bearer）トークンを使用します。

Authorization: Bearer YOUR_XAI_API_KEY

キーはxAIコンソールで取得します。同じAPIインターフェースは、テキスト-動画（imageパラメーターを省略）、動画の延長、および動画の編集もサポートしています。

画像から動画への処理の仕組み

リクエストボディのimageパラメーターは、出力動画の**最初のフレーム**を指定します。モデルは画像を置き換えません。そこから始まります。最初のフレームのすべてのピクセルはソース画像から取得されます。その後、モデルはプロンプトに基づいて、そのシーンが時間とともにどのように動くかを予測します。

例：日の出の山湖の写真を提示します。プロンプトには「朝霧が漂い、水面に穏やかな波紋が広がる」とあります。出力動画の最初のフレームはあなたの写真です。その後のフレームでは、プロンプトに従って水と霧がアニメーション化されます。

これは、モデルが最初のフレーム自体を生成するテキスト-動画とは異なります。画像-動画では、開始シーンを正確に制御できます。

画像-動画を選択すべきケース：

既存の製品写真、風景、またはポートレートを動かしたい場合。
ブランドアセットが最初のフレームで一貫した視覚的アイデンティティを必要とする場合。
動きが現実または特定のシーンに基づいているように感じさせたい場合。

テキスト-動画を選択すべきケース：

参照画像なしで視覚的なアイデアを模索している場合。
モデルにシーン構成全体を決定させたい場合。
最初のフレームの精度よりも反復の速度が重要な場合。

前提条件

最初の呼び出しを行う前に、次のものが必要です。

console.x.aiの**xAIアカウント**。
xAIコンソールからの**APIキー**。これはハードコーディングせずに環境変数に保管してください。
**Python 3.8以降**または**Node.js 18以降**（このガイドの例では両方を使用します）。
**公開アクセス可能な画像URL**、またはデータURIとしてbase64エンコードされた画像。

キーを環境変数として設定します。

export XAI_API_KEY="your_key_here"

より高レベルのクライアントが必要な場合は、xAI Python SDKをインストールしてください。

pip install xai-sdk

生のHTTP呼び出しの場合、requests（Python）またはfetch（Node.js）以外の追加パッケージは必要ありません。

最初の画像-動画リクエストを行う

curlの使用

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

応答はすぐにrequest_idとともに返されます。

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

動画はまだ準備ができていません。生成はxAIのインフラストラクチャで非同期に行われます。結果をポーリングする必要があります。

Python (生のHTTPリクエスト) の使用

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")

base64画像の利用

画像がローカルにあるか、公開アクセスできない場合は、データURIとしてエンコードします。

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

結果のポーリング

動画生成は非同期です。動画がxAIのサーバーでレンダリングされている間、APIはrequest_idを返します。ステータスエンドポイントをポーリングする必要があります。

GET https://api.x.ai/v1/videos/{request_id}

ステータスフィールドは次の値に変化します。

ステータス	意味
`"processing"`	動画はまだレンダリング中です
`"done"`	動画の準備ができており、URLが応答に含まれています
`"failed"`	何らかの問題が発生しました

完了した応答は次のようになります。

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

完全なPythonポーリングループ

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# 使用例
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

ポーリング間隔は5秒以上に保ってください。APIには1分あたり60リクエスト（1秒あたり1リクエスト）のレート制限があります。複数のジョブを同時に厳密にポーリングすると、その予算をすぐに使い果たしてしまう可能性があります。

xAI Python SDKの使用

xai-sdkライブラリは、非同期パターンをラップします。client.video.generate()はジョブを送信し、動画の準備ができるまでブロックし、すべてのポーリングを内部で処理します。

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")

SDKは、ポーリングループ、ステータスチェック、エラー伝播を処理します。HTTPポーリングを自分で管理することなく、クリーンなアプリケーションコードが必要な場合は、このアプローチを使用してください。

ポーリング間隔、リトライ戦略、またはロギングを細かく制御したい場合は、生のHTTPリクエストアプローチの方が柔軟性があります。

解像度、期間、アスペクト比の制御

Grok動画APIを使用すると、出力フォーマットを直接制御できます。

期間

durationパラメーターは1秒から15秒までの整数を受け入れます。デフォルトは6秒です。

"duration": 10

動画が長くなるほどコストも高くなります。10秒のクリップは、同じ解像度で1秒のクリップの約10倍の費用がかかります。

解像度

2つのオプションが利用可能です。

値	説明
`"480p"`	デフォルト。低コスト、高速生成。
`"720p"`	高品質。1秒あたり0.07ドル（480pは0.05ドル）。

"resolution": "720p"

アスペクト比

aspect_ratioパラメーターは出力フレームの寸法を制御します。

値	用途
`"16:9"`	デフォルト。風景シーン向けのワイドスクリーン。
`"9:16"`	モバイルまたはソーシャルストーリー向けの縦長。
`"1:1"`	Instagramやソーシャルサムネイル向けの正方形。
`"4:3"`	クラシックな写真またはプレゼンテーション形式。
`"3:4"`	ポートレート写真。
`"3:2"`	標準的な写真トリミング。
`"2:3"`	縦長のポートレート形式。

imageを提供する場合、アスペクト比はソース画像の寸法に合わせてデフォルト設定されます。オーバーライドまたはトリミングする場合は明示的に設定してください。

スタイルガイダンスのための参照画像の使用

reference_imagesパラメーターはimageパラメーターとは異なります。その違いを理解することが重要です。

image: 動画の**最初のフレーム**となるソース写真。モデルはこの開始点からアニメーションを作成します。

reference_images: 生成される動画の**スタイル、コンテンツ、または視覚的コンテキスト**をガイドする最大7枚の画像の配列。これらは出力のフレームではありません。モデルが動きや外観をどのようにレンダリングするかに影響を与えます。

出力動画に既存のアセットの視覚的特性を取り入れたいが、それを開始フレームとしたくない場合にreference_imagesを使用します。

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

この例では、product-shot.jpgが最初のフレームです。参照画像は、照明とスタイル処理をガイドします。

最初のフレームとなる画像を一切提供せずに参照画像を提供することもできます。その場合、モデルは参照画像からスタイルガイダンスを得て、テキスト-動画出力を生成します。

動画の延長と編集

APIは、初期生成に加えて2つの追加操作をサポートしています。

動画の延長

POST /v1/videos/extensionsは、既存の動画を受け取り、そこから追加の秒数を生成します。これは、1回あたりの呼び出し制限である15秒を超えないように、複数の生成パスからより長いクリップを作成するのに役立ちます。

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

応答は同じ非同期パターンに従います。延長されたクリップについてはGET /v1/videos/{request_id}をポーリングします。

動画の編集

POST /v1/videos/editsは、既存の動画にプロンプトによってガイドされた修正を適用します。最初から再生成することなく、コンテンツや動きの特定の部分を変更できます。

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

延長と編集の両方とも非同期であり、同じポーリングパターンを使用します。

料金内訳：10秒の動画にかかる費用

xAI動画APIは、入力画像の処理と出力動画の期間の2つのコンポーネントに対して課金します。

コンポーネント	費用
入力画像	1枚あたり0.002ドル
480pでの出力	1秒あたり0.05ドル
720pでの出力	1秒あたり0.07ドル

例：10秒の720p動画

入力画像：0.002ドル
出力：10秒 × 0.07ドル = 0.70ドル
合計：0.702ドル

例：6秒の480p動画（デフォルト設定）

入力画像：0.002ドル
出力：6秒 × 0.05ドル = 0.30ドル
合計：0.302ドル

入力画像料金は、同じ画像URLを再利用した場合でも、生成リクエストを送信するたびに適用されます。同じ基本画像を反復して使用する場合は、生成呼び出しを適切に計画してください。

テキスト-動画（imageパラメーターなし）は0.002ドルの入力料金はかかりませんが、それ以外の点では同じ1秒あたりの料金が適用されます。

ApidogでGrok動画API統合をテストする方法

非同期パターンは、単純なワンショットのリクエストテストではカバーできないテストの課題を生み出します。次のことを確認する必要があります。

生成リクエストがrequest_idを返すこと。
ポーリングリクエストが、待機中に"processing"ステータスを正しく処理すること。
最終応答にstatus == "done"が含まれ、動画URLが空でないこと。

Apidogのテストシナリオは、これらのステップを1つの自動化されたフローにまとめます。構築方法は次のとおりです。

ステップ1：新しいテストシナリオを作成する

Apidogでテストモジュールを開き、+ボタンをクリックして新しいシナリオを作成します。「Grok画像-動画非同期フロー」と名前を付けます。

ステップ2：生成リクエストを追加する

カスタムPOSTリクエストステップを追加します。

URL: https://api.x.ai/v1/videos/generations
メソッド: POST
ヘッダー: Authorization: Bearer {{xai_api_key}}
ボディ (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

ステップ3：request_idを抽出する

POSTステップの後、**変数を抽出**プロセッサを追加します。次のように設定します。

変数名: video_request_id
ソース: 応答ボディ
抽出方法: JSONPath
JSONPath式: $.request_id

Apidogは抽出された値を{{video_request_id}}に保存し、後続のステップで使用できるようにします。

ステップ4：ポーリングループを構築する

**For**ループプロセッサを追加します。ループ内にポーリングリクエストを追加します。

URL: https://api.x.ai/v1/videos/{{video_request_id}}
メソッド: GET
ヘッダー: Authorization: Bearer {{xai_api_key}}

現在のステータスをキャプチャするために、ループ内に**変数を抽出**プロセッサを追加します。

変数名: video_status
JSONPath: $.status

レート制限に達しないように、ステータス抽出後に**待機**プロセッサ（5000ms）を追加します。

ループの**ブレイク条件**を次のように設定します: {{video_status}} == "done"。

ステップ5：動画URLをアサートする

Forループの後、同じポーリングエンドポイントへの最後のGETステップを追加します。**アサーション**プロセッサを追加します。

フィールド: $.video.url
条件: 空ではない

このアサーションは、テストが合格する前に動画URLが存在することを確認します。

より複雑なポーリングパターンやCI/CD統合など、Apidogで非同期APIをテストする方法の詳細については、専用ガイドを参照してください。

シナリオの実行

テストシナリオビューで「実行」をクリックします。ApidogはPOSTを実行し、request_idを抽出し、status == "done"になるまでポーリングをループし、その後アサーションを評価します。テストレポートには、各ステップのステータスとタイミングが表示されます。

このシナリオは、Apidog CLIを使用してCI/CDパイプラインに組み込むことができます。

apidog run --scenario grok-video-async-flow --env production

よくあるエラーとその修正

401 Unauthorized (認証されていない)

APIキーがないか、無効です。Authorizationヘッダーの形式を確認してください: Bearer YOUR_XAI_API_KEY。xAIコンソールでキーがアクティブであることを確認してください。

422 Unprocessable Entity (処理できないエンティティ)

リクエストボディが不正です。一般的な原因としては、modelフィールドがない、promptが空である、またはimage.urlにアクセスできないなどがあります。使用する前にブラウザで画像URLをテストしてください。

画像URLにアクセスできない

生成時にxAIのサーバーが画像URLを取得できる必要があります。プライベートURL、localhostアドレス、または認証の背後にあるURLは失敗します。代わりに公開CDNまたはbase64データURIを使用してください。

ステータスが「processing」のまま停止する

生成には、解像度と期間に応じて30秒から数分かかります。ステータスが10分を超えて"processing"のままの場合、ジョブが停止している可能性があります。新しいリクエストを送信してください。xAI APIは現在、"failed"とは別にタイムアウト信号を公開していません。

レート制限エラー (429)

APIは1分あたり60リクエスト、1秒あたり1リクエストを許可しています。複数のジョブを同時にポーリングしている場合は、リクエストをずらしてください。最低でもポーリング呼び出しの間にtime.sleep(1)を追加してください。

Base64アップロードが拒否された

データURIに正しいMIMEタイププレフィックスが含まれていることを確認してください。JPEGファイルにはdata:image/jpeg;base64,を、PNGファイルにはdata:image/png;base64,を使用してください。

アスペクト比の不一致

ソース画像の比率と大きく異なる明示的なaspect_ratioを設定すると、モデルがクロップまたはレターボックスを行う場合があります。最良の結果を得るには、アスペクト比をソース画像に合わせてください。

まとめ

Grok画像-動画APIは、静止写真から短いアニメーションクリップへの直接的なパスを提供します。画像とプロンプトをPOSTし、request_idを受け取り、完了までポーリングし、MP4をダウンロードします。grok-imagine-videoモデルは、2026年1月にArtificial Analysisのリーダーボードでトップにランクされました。その1ヶ月だけで10億本を超える動画が生成されました。この規模は、基盤となるモデルがいかに有能であるかを反映しています。

非同期ポーリングパターンは、ほとんどの統合で問題が発生する箇所です。Apidogのテストシナリオにおける適切なテストは、変数抽出ステップ、ブレイク条件付きポーリングループ、および最終的なURLアサーションをカバーします。この組み合わせにより、本番環境に到達する前に問題を特定できます。

button

Apidogを無料でダウンロードして、統合の構築を始めましょう。クレジットカードは必要ありません。

よくある質問

Grok画像-動画APIにはどのモデル名を使用すればよいですか？

モデル名はgrok-imagine-videoです。POSTリクエストボディのmodelフィールドとして渡してください。

imageパラメーターとreference_imagesパラメーターの違いは何ですか？

imageパラメーターは、出力動画の最初のフレームを設定します。モデルはその開始画像から前方へアニメーションを作成します。reference_images配列は、フレームとして使用されることなく、スタイルとコンテンツのガイダンスを提供します。両方を同じリクエストで組み合わせることができます。

動画生成にはどれくらいの時間がかかりますか？

生成時間は期間と解像度によって異なります。6秒の480p動画は通常1〜3分かかります。15秒の720p動画は4〜8分かかる場合があります。レート制限を超えないように、5秒ごとにポーリングしてステータスを確認してください。

ローカルファイルをソース画像として使用できますか？

はい。ローカルファイルをbase64データURI（例: data:image/jpeg;base64,{encoded_bytes}）としてエンコードしてください。その文字列をimageオブジェクト内のurl値として渡します。

aspect_ratioを指定しなかった場合どうなりますか？

imageパラメーターを提供する場合、アスペクト比はソース画像のネイティブな比率に合わせてデフォルト設定されます。画像なしでテキスト-動画を生成する場合のデフォルトは16:9です。

10秒の720p動画はいくらかかりますか？

入力画像は0.002ドルかかります。出力は10秒 × 0.07ドル = 0.70ドルです。合計で、動画1本あたり約0.702ドルです。

レート制限は何ですか？

APIは1分あたり60リクエスト、1秒あたり1リクエストを許可しています。これには、生成POSTとポーリングGETリクエストの両方が含まれます。

15秒を超える動画を延長できますか？

はい、POST /v1/videos/extensionsエンドポイントを使用します。まず最大15秒の初期クリップを生成し、その後追加の生成パスで延長します。各延長も非同期ポーリングパターンに従います。