HiAPI
Ja
ブログ

チュートリアル

hiapi API で grok-imagine-quality/image-to-image を使う方法：curl、Python、利用可能なリクエスト

Jul 11, 2026
hiapi API で grok-imagine-quality/image-to-image を使う方法：curl、Python、利用可能なリクエスト

本ガイドでは、hiapi の統一タスク API を使って grok-imagine-quality/image-to-image（Grok Imagine シリーズの中でより高忠実度な階層）で既存の画像を変換する方法を説明します。ソース画像とテキストプロンプトを送信し、結果をポーリングして取得し、生成された画像をダウンロードします。以下の各リクエストとレスポンスの構造はすべて実際の API で検証済みです。

必要なもの

  • hiapi API キー — ダッシュボードで作成します。
  • ソースとして使用する 1〜3 個の公開アクセス可能な画像 URL。プラットフォームはサーバー側で入力メディアを取得・正規化するため、ローカルファイルパスや base64 ペイロードは使用できません — まず API からアクセス可能な場所に画像をホストしてください。

以上です。SDK は不要で、タスク API は単なる HTTPS + JSON です。

リクエストパターン

grok-imagine-quality/image-to-image は非同期タスクエンドポイントで動作します。POST /v1/tasks でタスクを作成し、その後 GET /v1/tasks/<taskId> をポーリングする（またはコールバックを登録する）ことで完了まで待機します。

入力スキーマは厳格です — 未知のフィールドは 400 で拒否されます：

フィールド 型 必須 説明
prompt string ✅ ソース画像に対して行う内容
image_urls string[] ✅ 1〜3 個のソース/参照画像の公開 URL
aspect_ratio string – 次のいずれか：auto、2:1、20:9、19.5:9、16:9、4:3、3:2、1:1、2:3、3:4、9:16、9:19.5、9:20、1:2
resolution string – 1k または 2k — 小文字（1K は 400 を返します）
output_format string – jpeg、png、webp

注意すべきは、存在しないものです：size も n も seed も strength も consistency の調整項目もありません。出力がソース画像にどの程度従うかは、プロンプトと渡す参照画像によって制御されます — 下記の FAQ を参照してください。

最小限の動作例（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-quality/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a light gray background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

作成に成功するとタスク ID が返されます：

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx"
  }
}

タスクが終了状態になるまでポーリングします：

curl https://api.hiapi.ai/v1/tasks/task_xxxxxxxxxxxx \
  -H "Authorization: Bearer sk-<your-key>"

実行中は data.status が進行中を示し、完了すると success になり、画像は data.output に配置されます：

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx",
    "status": "success",
    "output": [
      {
        "url": "https://.../result.png?...&expireAt=...",
        "expireAt": 1760000000
      }
    ]
  }
}

⚠️ 出力 URL は一時的です（expireAt に注意）。タスク成功後すぐにバイトをダウンロードして自身のストレージに保存してください — 結果 URL を直リンクしないでください。

タスクが失敗した場合、data.status は fail になり、data.error には code と message が含まれます。

Python：作成、ポーリング、ダウンロード

requests のみを使う完全なスクリプト：

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_urls: list[str]) -> str:
    payload = {
        "model": "grok-imagine-quality/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # 1-3 public URLs
            "aspect_ratio": "1:1",
            "resolution": "2k",         # lowercase: "1k" or "2k"
            "output_format": "png",
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt="Turn this product photo into a clean studio shot on a light gray background",
        image_urls=["https://your-cdn.example.com/source.jpg"],
    )
    print("task:", task_id)

    task = wait_task(task_id)
    url = task["output"][0]["url"]

    # The output URL expires -- download immediately and persist yourself
    img = requests.get(url, timeout=120).content
    with open("result.png", "wb") as f:
        f.write(img)
    print(f"saved result.png ({len(img)} bytes)")

本番環境での注意点

ポーリングの代わりにコールバックを使う

一回限りのスクリプト以外のあらゆる場面では、コールバックを登録してポーリングループを省略してください。トップレベルの callback オブジェクトを追加します（model や input と同じ階層）：

{
  "model": "grok-imagine-quality/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

when は "final" のみをサポートします — タスクが終了状態（success または fail）に達したときに、ちょうど 1 回の POST を受け取ります。経験則：

  • ポーリングは CLI、ノートブック、バッチジョブなど、プロセスがもともと存続している場面に適しています。3〜5 秒ごとにポーリングしてください。サブ秒間隔で叩き続けないでください。
  • コールバックは Web バックエンドに適しています。保留中の接続もなく、生成中にワーカースレッドを占有することもありません。Webhook の本文を盲目的に信頼するのではなく、サーバー側で GET /v1/tasks/<taskId> を再取得してペイロードを検証してください。

冪等性

タスク作成自体は冪等ではありません — プロセスが POST /v1/tasks の後、taskId を永続化する前にクラッシュすると、リトライによって 2 つ目のタスクが作成され（課金も）されます。待機を開始する前に、taskId を内部ジョブ ID をキーとして自身のストレージに永続化し、再起動時には再作成するのではなく保存済みの taskId をポーリングして復元してください。

エラー処理

実際に遭遇するエラー：

  • 401 permission_denied — API キーが無効、またはこのモデルへのアクセス権がありません。レスポンス本文にはサポートチームに送れる request_id が含まれます：

    {
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

  • 400 INVALID_REQUEST — スキーマ違反で、正確なメッセージが付きます。このモデルの実際の例：

    • prompt: missing required field "prompt" — 必須フィールドを忘れています。
    • image_urls: maxItems: got 12, want 3 — 参照画像が多すぎます（最大 3 個）。
    • resolution: value must be one of '1k', '2k' — 1K/4K を送信しました。
    • additional properties 'seed' not allowed — このモデルが受け付けないフィールドを渡しました。

  • 終了状態 fail — タスクは受け付けられましたが生成に失敗しました（例：ソース URL を取得できない）。data.error.message を確認し、入力を修正してから新しいタスクを作成してください。

5xx とネットワークエラーにはバックオフ付きリトライを使用してください。400 はリトライしないでください — ペイロードを修正するまで同じように失敗します。

品質階層の選択（そして「一貫性」はどうなった？）

hiapi 上の Grok Imagine シリーズは、階層とモダリティごとに別々のモデル ID に分かれています。画像から画像への場合、次のいずれかを選択できます：

階層はそのままモデル ID です — input 内に quality パラメータはありません（送信すると 400 additional properties 'quality' not allowed が返ります）。両階層の画像あたりの価格は価格ページに記載されています。

関連記事

よくある質問

一貫性や強度のパラメータはありますか？ ありません。入力スキーマは prompt、image_urls、aspect_ratio、resolution、output_format のみを受け付け、それ以外は 400 で拒否されます。出力がソース画像にどの程度従うかを制御するには、プロンプトで保持すべき内容を明示し（「製品とラベルは完全に同じに保ち、背景だけを変える」）、image_urls で最大 3 枚の参照画像を渡してください。

ローカルファイルをアップロードしたり base64 を送信できますか？ 直接はできません — image_urls は URL を受け付け、プラットフォームがサーバー側で取得します。任意の公開アクセス可能なストレージ（S3、R2、CDN）にファイルをアップロードし、その URL を渡してください。

ソース画像は何枚まで渡せますか？ 1〜3 枚です。空の配列は minItems: got 0, want 1 で失敗し、3 枚を超えると maxItems で失敗します。

対応している解像度とアスペクト比は？ resolution は 1k または 2k（小文字のみ）。aspect_ratio は 2:1 から 1:2 までの 14 個の値に対応し、auto、16:9、1:1、9:16、モバイル向けの 9:19.5/9:20 を含みます。

出力 URL の有効期間はどのくらいですか？ すべての出力には expireAt タイムスタンプが付きます。結果は一時的なものとして扱い、タスク成功後すぐにバイトをダウンロードして自身で保存してください。

複数のバリエーションを生成するには？ n パラメータはありません — バリエーションごとにタスクを作成します。タスクは独立して実行されるため、複数を並行して送信できます。

キーが正しいのに 401 permission_denied と表示されるのは？ キーは存在しますが、このモデルを使用できません（プランまたは権限スコープの制約）。ダッシュボードでキーのモデル権限を確認するか、エラーレスポンス本文の request_id を使ってサポートに問い合わせてください。

タグimage-to-imageチュートリアルAPI

関連記事

すべての記事を見る →

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む