hiapi API で grok-imagine-1.5/image-to-video を使う方法：curl、Python、そしてそのまま実行できるリクエスト

概要

• これは何か： hiapi の統合タスク API を使って grok-imagine-1.5/image-to-video で静止画像をショート動画にアニメーション化する方法を解説する、コピー＆ペースト可能なガイドです。
• 流れ： POST /v1/tasks でタスクを作成し、GET /v1/tasks/<taskId> をポーリング（またはコールバックを登録）し、期限切れになる前に data.output[0].url から MP4 をダウンロードします。
• 入力スキーマ（実際の API で検証済み）： image_urls のエントリを 1 つだけ受け付け、prompt は任意、duration は 1〜15 秒、resolution は 480p/720p、aspect_ratio は auto、1:1、16:9、9:16、3:2、2:3 のいずれかです。その他のフィールドは受け付けません。

何を構築するか、何を用意するか

目標：ソース画像とモーションプロンプトを送信し、Grok Imagine 1.5 が生成したショート動画 MP4 クリップを取得することです。

前提条件：

• hiapi API キー — ダッシュボード で作成します。キーは sk-... の形式で、Authorization: Bearer リクエストヘッダーに指定します。
• 公開アクセス可能なソース画像 URL（JPEG/PNG）。 API はサーバー側で画像を取得するため、localhost のリンクや認証が必要なファイルは使用できません。
• 任意の HTTP クライアント。以下の例では curl と Python の requests を使用します。

モデル id はサフィックスなしの裸の文字列 grok-imagine-1.5/image-to-video です。

最小限の実行可能な例：curl

タスクを作成：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

送信に成功すると 200 と taskId が返ります：

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

タスクが終態に達するまでポーリングします（status は queued → handling → success または fail の順に遷移します）：

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

完了したタスク（実際のレスポンス、一部省略）：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5",
    "model": "grok-imagine-1.5/image-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/.../01KWVVSTX0TJ32AD45F6ZQ08W5-0.mp4",
        "expireAt": 1783951451
      }
    ]
  },
  "message": "success"
}

⚠️ storage: "temp" と expireAt は、ダウンロード URL が一時的であることを意味します。タスク成功後すぐに MP4 をダウンロードし、自社のインフラに保存してください — ホットリンクしないでください。

最小限の実行可能な例：Python

完全なスクリプト — 作成、ポーリング、ダウンロード：

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

入力リファレンス（スキーマが実際に受け付ける内容）

これらの制約は推測ではなく実際のバリデータに由来します — それ以外を送信すると 400 INVALID_REQUEST が返り、正確なメッセージが付随します：

フィールド	型	ルール
image_urls	文字列配列	必須、ちょうど 1 つの URL（maxItems: 1）
prompt	文字列	任意 — 動き、カメラワーク、雰囲気を記述
duration	整数	1〜15 秒
resolution	文字列	480p または 720p
aspect_ratio	文字列	auto、1:1、16:9、9:16、3:2、2:3

補足：

• このモデルには seed、negative_prompt、fps、motion_strength、camera_fixed フィールドはありません。スキーマは未知のプロパティを拒否する（additional properties ... not allowed）ため、動きやカメラワークは完全に prompt で制御してください。
• タスクごとに参照画像は 1 枚のみです。2 枚渡すと image_urls: maxItems: got 2, want 1 が返ります。
• aspect_ratio: "auto" はソース画像自体の比率に従います — これは通常、商品画像で望まれる挙動です。
• 旧モデルの grok-imagine/image-to-video は 1 クリップ最大 30 秒を受け付けますが、1.5 は上限 15 秒です。1 秒あたりの料金は両方同じで、480p は $0.015、720p は $0.0282 です。

本番環境での注意点

ポーリングの代わりにコールバックを使う。 スクリプトを超えるあらゆる用途では、タスク作成時に webhook を登録してポーリングループを省略してください：

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url は公開された http(s) エンドポイントである必要があり、when は "final" のみサポートされます — タスクが success または fail に達したときに 1 回の POST を受け取ります。ポーリングは CLI やバッチ処理に向いていますが、大量のクリップを一括生成しつつ多数のポーラーをデプロイしたくない場合はコールバックが優れています。webhook の消失でタスクが放置されないよう、フォールバックのポーリング（例：数分ごとにコールバック未受信のタスクを確認）を残しておきましょう。

冪等性。 タスク作成はサーバー側で重複排除されないため、ネットワークタイムアウト後の単純なリトライは二重送信と二重課金を引き起こす可能性があります。作成呼び出しが返った直後に taskId を永続化し、リトライ時にはまず自分のストレージを確認してください。送信と永続化の間でクラッシュした場合は、最近のタスク一覧（GET /v1/tasks）を取得し、再送信する前にモデル + 作成時刻で照合します。

エラーハンドリング。 実際に遭遇する失敗パターン：

• 401 と {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} — キーが正しくないか、そのキーにこのモデルへのアクセス権がありません。レスポンスにはサポート用の request_id が含まれます。
• 400 と error_code: "INVALID_REQUEST" — スキーマ違反です。message が失敗した具体的なフィールドとルールを示します（例：duration: maximum: got 99, want 15）。リクエストボディを修正し、盲目的にリトライしないでください。
• 402 残高不足 — 動画モデルは送信時にクォータを事前チェックします。チャージ後に再送信してください。
• タスク自体が status: "fail" — 生成側の失敗です。data.error を確認し、バックオフしてリトライしてください。ソース画像にアクセスできないことがよくある原因です。

出力をすぐに保存する。 繰り返す価値があります：output[0].url は一時ストレージ上にあり、expireAt タイムスタンプが付いています。success を確認した瞬間に、MP4 を自分のストレージバケットへストリーミングしてください。パイプラインが成功後、ダウンロード前にクラッシュした場合は、id でタスクを再取得してください — URL は expireAt までは有効ですが、永久ではありません。

関連記事

• grok-imagine-1.5/image-to-video モデルページ — 料金、パラメータ、ブラウザ内プレイグラウンド
• grok-imagine/image-to-video の使い方 — 前世代モデル、同じタスクフロー、30 秒上限
• Grok Imagine テキストから動画へのガイド — 画像ではなくプロンプトから始める
• hiapi API リファレンス — 完全なタスク API 契約

よくある質問

grok-imagine-1.5 の動画はどれくらいの長さにできますか？ 1〜15 秒で、整数の duration フィールドで設定します。それ以上をリクエストすると 400（duration: maximum: got X, want 15）が返ります。最大 30 秒が必要な場合は、旧モデルの grok-imagine/image-to-video を使用してください。

どの解像度とアスペクト比に対応していますか？ resolution は 480p または 720p、aspect_ratio は auto、1:1、16:9、9:16、3:2、2:3 です。720p での 9:16 は Shorts/Reels 風の縦型クリップに最適な組み合わせです。

複数の参照画像を渡せますか？ いいえ — このモデルの image_urls はちょうど 1 つの URL のみ受け付けます。複数参照のワークフローでは、タスクを連結するか、参照画像をあらかじめ 1 枚の入力画像に合成してください。

seed やネガティブプロンプトはありますか？ ありません。入力スキーマは seed、negative_prompt、fps などのフィールドを直接拒否します。動きのスタイル、カメラワーク、雰囲気はすべて prompt 文字列で制御します。

料金はいくらですか？ 生成された動画の秒数に応じた課金です：480p は $0.015/秒、720p は $0.0282/秒。6 秒のクリップは 480p で $0.09、720p で $0.1692 です。duration を指定しない場合はデフォルトで 8 秒です。その他の例は Grok Imagine 1.5 料金の内訳 をご覧ください。

なぜリクエストが 401 permission_denied を返すのですか？ API キーが正しくない/取り消されているか、そのキーにこのモデルへのアクセス権がありません。ダッシュボード でキーを確認し、Authorization: Bearer sk-... を送信していることを確認してください — Bearer プレフィックスがないと同じエラーになります。

ポーリングせずに動画の準備完了を知るには？ タスク作成時に "callback": {"url": "https://your-endpoint", "when": "final"} を付けます。タスクが終態に達すると、hiapi があなたのエンドポイントへ POST を送信します。フォールバックとして GET /v1/tasks/<taskId> をポーリングしてください。

なぜ動画 URL が数日後に機能しなくなるのですか？ 出力は一時ストレージ上にあり、各出力エントリには expireAt タイムスタンプが付いています。success 後すぐにファイルをダウンロードし、自分のストレージから配信してください。