Grok Imagine 1.0 動画生成 API:エンドポイント、認証スコープ、エラー処理
対象モデル:
grok-imagine-video-official、grok-imagine-video-1.5-official
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連記事: Grok Video 実践ガイド · OpenAI 互換アクセス · 公式 Imagine 生成 · 公式 Imagine 延長
1. クイックスタートと性能概要 (TL;DR)
- ID: 「Grok Imagine 1.0」という題でも、使う文字列は ToAPIs が実際に公開しているものです。2026-11-10 付けの公開カタログスナップショットは
grok-imagine-video-officialとgrok-imagine-video-1.5-officialを掲載しています(どちらも image-generation とopenai-videoに現れます)。2026-11-17 にgrok-imagine-1.0のドキュメントパスを確認したところ HTTP 404 でした。 - 認証:
Authorization: Bearer $TOAPIS_API_KEYを送ります。公式ページは、これらの呼び出し向けの OAuth スコープ、細かい権限名、スコープ発見エンドポイントを文書化していません。 - エンドポイント: 作成は
POST /v1/videos/generations、ポーリングはGET /v1/videos/generations/{id}です。公式チャネル出力の延長はPOST /v1/videos/{video_id}/extend、公開動画 URL しかない場合はPOST /v1/videos/extendにvideo_urlsを付けます。静止画のアップロードはPOST /v1/uploads/imagesです。 - 能力:
grok-imagine-video-officialはテキストから動画、画像から動画、複数参照に対応し、解像度は480pまたは720p、尺は 1–15 秒、延長は 2–10 秒です。grok-imagine-video-1.5-officialはファーストフレームの画像から動画のみで、ちょうど 1 枚のimageが必須、1080pを使え、延長は非対応です。 - 課金の形(リファレンスページに固定単価はありません): 出力は解像度帯ごとに秒課金、入力画像は枚数課金、延長はソース動画の尺も課金します。ライブの口座レートを確認してください。
2. エンドポイント、認証、モデル契約
公式ドキュメントは https://toapis.com(中国本土は https://toapis.cn)を使います。本シリーズの他ガイドは https://api.toapis.com を使います。オリジンは 1 つにそろえてください。次のパスはすべて同じ Bearer ヘッダーを使います。
| 操作 | メソッドとパス | モデルに関する注記 |
|---|---|---|
| 静止画のアップロード | POST /v1/uploads/images | Multipart file。JPEG、PNG、WebP、GIF、最大 30 MB。data.url を読む |
| 動画の作成 | POST /v1/videos/generations | 両方の公式 Imagine ID |
| ステータス照会 | GET /v1/videos/generations/{id} | 生成と延長タスクで同じパス |
| 以前のタスクから延長 | POST /v1/videos/{video_id}/extend | grok-imagine-video-official のみ。video_id は直前の生成タスク id |
| 公開 URL から延長 | POST /v1/videos/extend | 同じ公式 ID。パスに id が無いときは video_urls が必須 |
| カタログ ID | 文書化されたジョブ | 尺 | 解像度 | 画像 | 延長 |
|---|---|---|---|---|---|
grok-imagine-video-official | テキストから動画、ファーストフレーム、複数参照 | 1–15 秒(デフォルト 8) | 480p、720p | 任意の image と reference_images。合計最大 7 枚 | 2–10 秒(duration のデフォルトは 6) |
grok-imagine-video-1.5-official | ファーストフレームの画像から動画のみ | 1–15 秒(デフォルト 8) | 480p、720p、1080p | image は必須(ファーストフレームちょうど 1 枚)。追加の reference_images も 7 枚上限に含まれる | 非対応 |
公式 Imagine リファレンスのアスペクト比には 16:9、9:16、4:3、3:4、3:2、2:3、1:1 が含まれます。その ID とチャネルで確認済みの値を送ってください。
「生成」「延長」「アップロード」を個別に要求する公開スコープ文字列は文書化されていません。アクセス権は API キー、ユーザーグループ、チャネル設定が既に許している範囲です。権限や可用性で失敗した場合は、発明した scope クエリを付けるのではなく、キーのモデル一覧と エラーリファレンス を確認してください。

図 1: 1 つの Bearer API キーでアップロード、生成または延長、ステータスポーリングを認可します。公式 1.5 の ID には延長の枝はありません。
非公式の Grok Video ファミリー(grok-video-1.0 / grok-video-1.5)は Grok Video 実践ガイド を見てください。それらは別契約であり、この延長パスは継承しません。
3. 本番実装: cURL と Python
ステップ 1: cURL — 公式チャネルのテキストから動画
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
grok-imagine-video-1.5-official のファーストフレームジョブは同じパスを使い、"image": "https://example.com/portrait.jpg" が必須で、"resolution": "1080p" も指定できます。例の URL はアクセス可能な公開アドレスに置き換えてください。ファイルがローカルなら先にアップロードします。
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
ステップ 2: Python — 生成、ポーリング、任意の延長
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> dict:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
timeout=30,
)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
タスク id ではなく公開 MP4 から延長する場合は、同じ公式モデル、プロンプト、duration、video_urls リストを POST /v1/videos/extend に送ってください。grok-imagine-video-1.5-official で延長を呼ばないでください。
4. エラー処理とステータスマトリクス
下表は切り分けの起点であり、ToAPIs のエラーコードと完全一致することを保証しません。HTTP の照会が成功しても、タスクの status を読む必要があります。エラーリファレンス は、リクエストエラー、失敗タスクの error.reason、Webhook ペイロードを区別しています。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 無効なフィールド、1.5-official で必須の image 欠落、枚数超過、延長非対応モデルへの延長 | 正確な公式 ID、尺(生成は 1–15、延長は 2–10)、解像度(1080p は 1.5-official のみ)、メディアがすべて公開 URL かを確認する |
401 | API キーの欠落または無効 | キーをローテーションし、Authorization: Bearer を確認する。未文書化の scope パラメータを回避策にしない |
429 | レートまたは同時実行の制限 | Retry-After があれば従い、ジッター付きでバックオフする |
5xx またはクライアントタイムアウト | ゲートウェイまたは上流の一時障害 | 再投入の前に既存のタスク id を照会する |
status: queued または in_progress | エラーではない | 待って再ポーリングする |
status: failed で content_policy_rejected | 安全性または著作権の審査 | プロンプトとすべての参照素材を点検する。適合した入力でも出力が拒否されることがある |
status: failed で insufficient_user_balance または token_quota_exceeded | 残高またはトークン枠 | 残高と周期的な上限の両方を確認する |
status: failed で generation_timeout、model_unavailable、service_busy | 上流のタイムアウトまたは可用性 | まず既存 id を確認し、タスクが終端になってからバックオフ付きで再試行する |
5. 料金と FinOps ROI
公式 Imagine の生成・延長ページが述べているのは固定の公開単価ではなく、課金の形です。
ドラフトの数字ではなく、アカウントと SKU が返すレートを使ってください。
grok-imagine-video-1.5-officialには必ず 1 回の入力画像課金が含まれます。 ファーストフレーム画像が必須だからです。- 延長は無料の続きではありません。 公式の延長課金は、生成した延長秒数に加えてソース動画の尺も含みます。延長を重ねると、長くなったソースを再度課金します。ループを組む前にライブの見積もりでこの動作を確認してください。
- 企画ドラフトの単価や SLA 数値を再利用しないでください。 ToAPIs 料金ページの公式ベンダー参考行は表示用であり、口座の請求と一致するとは限りません。
- まず
720pと中尺で試し、一度に 1 変数だけ変え、クライアントタイムアウト後は状態を確認するまで再投入しないでください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: grok-imagine-1.0 ではなく grok-imagine-video-official または grok-imagine-video-1.5-official を送り、認証は公開 OAuth スコープ行列のない Bearer API キー、1.5-official はファーストフレームのみで延長不可、延長尺は 2–10 秒でソース尺も課金され、HTTP エラーと status: failed は必ず区別します。
7. アクションチェックリスト
- ToAPIs 開発者ポータル でキーを作成する。
-
GET /v1/models?type=videoで、キーからgrok-imagine-video-officialまたはgrok-imagine-video-1.5-officialが見えることを確認する。 -
720pの公式チャネル生成をスモークテストし、GET /v1/videos/generations/{id}をポーリングし、expires_atの前にファイルをダウンロードする。 - 続きが必要なら
grok-imagine-video-officialと 2–10 秒のdurationだけで延長し、見積もりにソース尺の課金が含まれることを確認する。 - 次のステップ: 現行カタログは 公式 Imagine モデルガイド と 公式 Imagine 1.5 モデルガイド。意図が非公式の
grok-video-*ファミリーなら Grok Video 実践ガイド を読む。







