Grok Imagine 動画 API

grok-imagine-video-1.5 はテキストから動画を生成し、参照画像も指定できます。タスクを送信してタスク ID をポーリングし、完了したら動画をダウンロードします。

Grok Imagine の画像生成は同期の OpenAI Images エンドポイントを使い、パラメータは動画と共通しません。Grok Imagine の画像生成を参照してください。

利用できるモデル

grok-imagine-video-1.5 はテキストから動画を生成するモデルで、参照画像をオプションで指定できます。先頭・末尾フレームの指定はなく、参照動画や参照音声もありません。

画像とチャットは Grok スイートプランから、動画は Grok ビデオプランから提供されます。これらは別々の 2 つのプランで、動画モデルに到達するにはキーに Grok ビデオが含まれている必要があります。1 つのキーに両方のプランを含めることもできます。実際に使用するキーで GET /v1/models を呼び出して確認してください。

解像度ティアごとと参照画像の公式価格はモデルカードに掲載されています:grok-imagine-video-1.5。動画のすべてのフィールドは、API リファレンスの動画タスクの送信に掲載されています。

リクエストパラメータ

• model は完全一致である必要があります。
• content は空でないテキストの text 要素のみの配列で、画像・動画・音声の要素は受け付けません。
• resolution はそのティアの秒単価で課金されます。reference_images ありの場合は 480p / 720p のみです。
• duration と aspect_ratio のデフォルトはサービス側で補完され、課金は完成時の duration_seconds に従います。
• フレームの比率には aspect_ratio を使用してください。ratio は拒否されます。
• reference_images はトップレベルの配列で、公開 HTTP(S) のみ、Data URL / asset:// は不可です。参照画像 1 枚ごとに別途課金されます。

ratio、frames、seed、camera_fixed、draft、draft_task、service_tier、generate_audio、watermark、return_last_frame は拒否されます。表にないその他のフィールド(トップレベルの image など)は検査されず、参照画像としても扱われません。

レスポンス

動画は Seedance と同じ task ラッパーを使います。Kling のようにトップレベルの id を読まないでください。

送信時のレスポンス

送信に成功すると 200 が返り、タスク ID が task.id(vt… の形式)に入っています。

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "pending",
    "outputs": []
  }
}

タスク照会のフィールド

task.id で GET /v1/video/tasks/{task_id} をポーリングしてください。

終了状態は completed と failed のみです。それ以外の値は実行中として扱ってください。

実行中

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "processing",
    "outputs": [],
    "error": null
  }
}

成功

完了したタスクには duration_seconds と、outputs に動画 URL が含まれます。

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "completed",
    "duration_seconds": 5,
    "outputs": [
      "https://api.hop-base.com/example-signed-video.mp4"
    ],
    "error": null
  },
  "usage": { "cost": 1.02, "cost_usd": 0.15, "currency": "CNY" }
}

失敗

実行に失敗しても照会は HTTP 200 です。task.status と task.error.message を確認してください。

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

最小の例

# 1. 送信
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "An orange cat runs across sunlit grass as the camera follows",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

# 2. 返された task.id でポーリング
curl https://api.hop-base.com/v1/video/tasks/vtタスクID \
  -H "Authorization: Bearer sk-your-key"

注意事項

• outputs は完了から 24 時間有効で、再度照会しても有効期限は延長されません。期限切れの URL は 410 を返します。早めにダウンロードして保存してください。
• 審査に掛かったプロンプトは、error.message に content-moderated を含む失敗タスクになります。
• reference_images ありの場合、解像度は 480p / 720p のみです。
• 参照画像は公開 HTTP(S) URL のみで、最大枚数は未検証です。
• 動画は画像・チャットと別のプランです。呼び出すには Grok ビデオのプランをキーに追加してください。

よくあるエラーと対処

送信時のエラーは 400 で、error.message のみ(code なし)です。

エラーの原文:

grok-imagine-video-1.5 requires resolution: 480p / 720p / 1080p
model grok-imagine-video-1.5 does not support resolution 4k
grok-imagine-video-1.5 duration must be an integer in 1-15, got 20
grok-imagine-video-1.5 uses aspect_ratio for the frame ratio and does not support ratio
aspect_ratio must be one of 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3, got 21:9
grok-imagine-video-1.5 does not support parameter generate_audio
grok-imagine-video-1.5 only supports text segments in content; use reference_images for reference images
reference_images[0] must be a {"url": "..."} object
reference_images[0].url must be a publicly reachable http(s) address
grok-imagine-video-1.5 reference-to-video supports up to 720p; remove the reference images or choose 480p/720p
grok-imagine-video-1.5 accepts at most 14 reference images per request, got 15; remove 1 and try again
priority must be within 0-9, got 12
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

課金

完成した映像の秒数に応じて課金され、単価は resolution のティアで変わります。参照画像は 1 枚ごとに別途課金されます。失敗したタスクは課金されません。

タスク終了後は、照会レスポンスのルートの usage に cost_usd(このタスクで残高から実際に差し引かれた米ドル額。課金なしの失敗は 0)、cost(同じ課金額の人民元額)、currency(常に CNY)も含まれます。送信時の残高チェック(不足時は 402)など、すべての動画タスクに共通するルールは動画生成の概要を参照してください。

公式のリスト価格は料金ページに掲載されています。実際の適用レートはログイン後のモデル広場に表示され、各リクエストの実際の課金額はコンソールの使用状況ページで確認できます。

次のステップ

• Grok Imagine の画像生成: 画像を生成・編集する
• 動画生成の概要: 動画シリーズの比較と共通のタスクの流れ
• Grok: Grok のチャット・推論モデル(長コンテキストの料金、推論トークンの計上、サーバー側ツールの課金を含む)
• エラーコードと再試行: 各エラーコードの意味と再試行の要否