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

要約

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

Apidogを今すぐ試す

はじめに

2026年1月28日、xAIはgrok-imagine-videoモデルを公開APIアクセス向けにリリースしました。公開から1ヶ月で12億本の動画生成を達成し、Artificial Analysisのテキスト-動画リーダーボードで1位を獲得しました。写真と説明プロンプトをAPIに送信するだけで、その写真を短い動画クリップとしてMP4ダウンロードできます。

このAPIは非同期フロー（ジョブ送信→完了までポーリング）を採用しており、POSTの200レスポンスのみでは統合テストは不十分です。"processing", "done", "failed"の各状態を現実的なネットワーク条件下で正しく処理することが重要です。

Apidogのテストシナリオなら、/v1/videos/generationsのPOST→request_id抽出→status == "done"までのポーリングループ構築→動画URLのアサートまで一連の自動テストを簡単に実装可能です。本記事後半のハンズオンに沿って、Apidogでテストを始めましょう。

Grok画像-動画APIとは？

Grok画像-動画APIは、xAIの動画生成製品の1機能です。grok-imagine-videoモデルを使用し、画像を動画の開始フレームとして受け付けます。画像とテキストプロンプトからシーンを自然にアニメーション化します。

APIエンドポイント：

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

認証はBearerトークンです。

Authorization: Bearer YOUR_XAI_API_KEY

APIキーは公式xAIコンソールから取得します。

同じエンドポイントでテキスト-動画（image省略）、動画延長、編集も可能です。

画像から動画への処理フロー

リクエストボディのimageパラメータは、出力動画の最初のフレームを指定します。モデルはこの画像を変更せずに開始し、プロンプトに基づいて動きを生成します。

例：山湖の写真＋「朝霧が漂い、水面に穏やかな波紋」→最初のフレームは写真、その後のフレームで水や霧が動く。

• 画像-動画: 開始シーンを完全制御したい場合
• テキスト-動画: 画像なしでゼロからシーン生成したい場合

前提条件

APIコール前に以下を準備してください。

1. console.x.aiのxAIアカウント
2. APIキー（環境変数で管理推奨）
3. Python 3.8+またはNode.js 18+（本記事例で使用）
4. 公開アクセス可能な画像URLまたはbase64データURI

画像例：

APIキーを環境変数にセット：

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": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

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画像を使いたい場合

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

結果のポーリング

動画生成は非同期です。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ならポーリングやエラー処理も自動。

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

細かいポーリングやリトライ設定をしたい場合は生HTTPを選択してください。

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

• 期間: duration（1～15秒、デフォルト6秒）
  

  "duration": 10
  

  長いほどコスト増。10秒は1秒の10倍。

• 解像度: "480p"（デフォルト）, "720p"
  | 値 | 説明 |
  |---------|---------------------------|
  | "480p" | 低コスト、高速 |
  | "720p" | 高品質、1秒0.07ドル |
  

  "resolution": "720p"
  

• アスペクト比: aspect_ratio
  | 値 | 用途 |
  |--------|-------------------------------|
  | "16:9" | デフォルト、ワイド |
  | "9:16" | 縦型、SNSストーリー |
  | "1:1" | インスタやサムネイル |
  | "4:3" | クラシック写真 |
  | "3:4" | ポートレート |
  | "3:2" | 標準写真 |
  | "2:3" | 縦型標準 |

imageを指定するとデフォルトで画像比率に自動設定。変更したい場合は明示指定。

---

スタイルガイド用の参照画像

• image: 最初のフレームとなる画像
• reference_images: スタイルや雰囲気をガイドする画像配列（最大7枚）。フレームにはならない。

例：

{
  "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"
}

参照画像だけで、imageなしも可能です（その場合はテキスト-動画生成＋スタイルガイド）。

動画の延長と編集

• 動画の延長: 既存動画に追加生成。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
    }'
  

  結果は同じ非同期パターンでポーリング。

• 動画の編集: 既存動画の一部をプロンプトで変更。
  

  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秒の動画の場合

コンポーネント	費用
入力画像	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でも毎回入力画像料金がかかります。テキスト-動画は画像入力料金（0.002ドル）は不要。

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

非同期APIのテストには以下の自動化フローをApidogで構築します。

1. 生成POSTでrequest_idを取得
2. ポーリングGETで"processing"状態をハンドリング
3. "done"後に動画URLの存在をアサート

テストシナリオ構築手順

• ステップ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抽出（変数抽出プロセッサで$.request_id→video_request_idへ）

• ステップ4: ForループでポーリングGETリクエスト

  • URL: https://api.x.ai/v1/videos/{{video_request_id}}
  • ヘッダー: Authorization: Bearer {{xai_api_key}}
  • 変数抽出: $.status→video_status
  • 待機プロセッサ5000ms追加
  • ブレイク条件: {{video_status}} == "done"

• ステップ5: 完了後に動画URLをアサート

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

シナリオ実行例
テストシナリオ画面で「実行」。POST→request_id抽出→ループ→動画URLアサートまで自動実行し、各ステップの進捗と結果がレポートされます。

CLI経由でCI/CD統合も可能：

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

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

• 401 Unauthorized
  
  APIキー未設定または無効。ヘッダー形式Bearer YOUR_XAI_API_KEYとキーの有効性を確認。

• 422 Unprocessable Entity
  
  リクエストボディの必須フィールド漏れや画像URLアクセス不可。画像URLはブラウザで事前チェック。

• 画像URLにアクセス不可
  
  xAIサーバーから到達可能なURLまたはbase64データURIを使用。private/localhost/認証付きURLは不可。

• processingのまま進まない
  
  高解像度・長時間動画は遅延。10分以上変化なければ再リクエスト推奨。タイムアウトは現状APIから返却されません。

• 429 レート制限
  
  1分60回・1秒1回。複数ジョブ同時ポーリング時はインターバル追加。

• Base64アップロード失敗
  
  データURIのMIMEタイプが正しいか確認（例: JPEGならdata:image/jpeg;base64,）。

• アスペクト比不一致
  
  ソース画像と異なる比率を指定するとクロップ/レターボックスされることあり。最良結果には画像比率と同じaspect_ratioを設定。

まとめ

Grok画像-動画APIは、静止写真→短尺アニメクリップの自動化に最適です。シンプルなPOST→request_id取得→完了までポーリング→MP4ダウンロードという流れで実装できます。grok-imagine-videoは2026年1月時点で業界リーダーの実績。大規模運用でも安定したパフォーマンスが期待できます。

非同期処理を正しくテストするには、Apidogの変数抽出・ポーリングループ・アサーションを活用してください。これにより本番前のバグ検出・品質担保が容易になります。

Apidogを無料でダウンロードして、今すぐ統合テストを始めましょう。クレジットカード不要です。

よくある質問

Q. Grok画像-動画APIのモデル名は？

A. grok-imagine-videoです。POSTリクエストのmodelフィールドに指定。

Q. imageパラメータとreference_imagesの違いは？

A. imageは開始フレーム、reference_imagesはスタイルガイド。両方同時利用可能。

Q. 動画生成はどれくらい時間がかかる？

A. 6秒480pで約1～3分、15秒720pで4～8分。ポーリングは5秒間隔推奨。

Q. ローカルファイルも使える？

A. はい。base64データURI（例:data:image/jpeg;base64,xxxx）にエンコードしてimage.urlに指定。

Q. aspect_ratioを省略すると？

A. image指定時は画像の比率、テキスト-動画時は16:9がデフォルト。

Q. 10秒720p動画の料金は？

A. 入力画像0.002ドル＋出力0.70ドル＝合計0.702ドル。

Q. レート制限は？

A. 1分60回・1秒1回。POST/GETすべてに適用。

Q. 15秒を超える動画は？

A. POST /v1/videos/extensionsで分割生成・連結が可能。各延長も非同期パターン。

---

これで、Grok画像-動画APIの実装・テスト・運用のための実践的なガイドを完了します。