チュートリアル

hiapi API で grok-imagine の画像から画像を生成する方法：curl、Python、そして動作するリクエスト

Jul 11, 2026

grok-imagine/image-to-image は、1 枚以上の参照画像とテキストプロンプトを受け取り、編集後の画像を返します。商品写真のスタイルを変えたり、背景を差し替えたり、最大 3 枚の参照画像を 1 つの出力に融合したりできます。hiapi では、統一されたタスク API を通じて動作します。タスクを作成し、ポーリング（またはコールバックを受信）し、結果をダウンロードします。このガイドでは、正確なリクエスト構造を解説し、すぐにコピー＆ペーストして使える curl と Python のサンプルを提供します。

構築するもの + 前提条件

目標：参照画像 1 枚とプロンプトを送信し、編集後の画像の URL を受け取り、ダウンロードする——まずはポーリングによるインタラクティブな操作、次にコールバックを使った本番バージョンです。

必要なものは 1 つだけ：hiapi API キーです。ダッシュボードから取得してください——sk-... のような形式で、各呼び出し時に Authorization: Bearer ヘッダーに含めます。

参照画像は公開アクセス可能な URL である必要があります（モデルはサーバー側でそれらを取得します）。そのため、事前に CDN またはオブジェクトストレージにホストしてください。

最小限の動作例（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/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

必須フィールドは 2 つだけです——prompt と image_urls——これで完全なリクエストになります。レスポンスにはタスク ID が data.taskId の下に含まれます：

{
  "data": {
    "taskId": "<task-id>"
  }
}

結果をポーリング：

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

タスクの実行中、data.status が進捗を報告します。これが success になると、画像 URL は data.output[0].url にあります。fail の場合は、data.error にエラーコードとメッセージが含まれます。

重要な詳細：出力 URL は署名付きで有効期限があります（ペイロードに expireAt が含まれます）。タスク成功後はすぐにファイルをダウンロードしてください——元の出力 URL を保存したりホットリンクしたりしないでください。

curl -o result.png "<data.output[0].url>"

Python での同じ例

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

完全な入力スキーマ

フィールド	必須	型	説明
`prompt`	✅	string	何を変更するか / 目標の外観
`image_urls`	✅	URL 配列	1〜3 枚の参照画像、公開アクセス可能であること
`aspect_ratio`	任意	enum	`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`	任意	enum	`1k` または `2k`——小文字
`output_format`	任意	enum	`jpeg`、`png`、または `webp`

このスキーマは厳格です：認識されないフィールドはすべて 400 で拒否されます。size も seed も n もありません——ピクセルサイズを使うモデルのコード（例：size: "1024x1024"）を移植している場合は、ここでは aspect_ratio + resolution に置き換えてください。各タスクは 1 枚の画像を返します。バリエーションを得るには、複数のタスクを送信してください。

複数参照画像：最大 3 枚の入力画像

image_urls は最大 3 枚の参照画像を受け付け、モデルがそれらを融合します——たとえば、商品画像 1 枚 + 背景プレート 1 枚 + スタイル参照 1 枚です。3 枚を超えて送信すると、API はリクエストを即座に拒否します：

invalid input: image_urls: maxItems: got 4, want 3

最も重要な画像（通常は被写体）を先頭に置き、プロンプトで各参照画像がそれぞれ何を提供するかを説明してください。

自動アスペクト比

aspect_ratio: "auto" は、固定の画角を強制するのではなく、モデルが参照画像から出力比率を導出できるようにします——商品写真や構図を保持したい編集にとって適切なデフォルトです。明示的な比率は、ターゲットの配置に明確な要件がある場合にのみ設定してください（例：ストーリー枠用の 9:16、キービジュアルバナー用の 16:9）。

本番環境での注意点

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

バッチ処理やサーバー側のワークロードでは、ポーリングループをスキップしてください——タスク作成時にコールバックを登録すると、hiapi が最終結果をエンドポイントに POST します：

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when は "final" のみをサポートします——タスクが success または fail に到達したときに 1 回呼び出され、中間の進捗イベントは送信されません。

経験則：インタラクティブなツールにはポーリング（ユーザーが視聴している。5 秒の sleep ループで問題ない）、パイプラインにはコールバック（数十のタスクが実行中。タスクごとにポーラーを用意したくない）。コールバックハンドラーでも出力をすぐにダウンロードしてください——受け取る URL は他の URL と同様に期限切れになります。

冪等性とリトライ

タスク API は「送信」と「結果」を分離しているため、安全なリトライが簡単になります：

create が返した瞬間に taskId を永続化する。プロセスが後でクラッシュした場合、保存済みの ID をポーリングして復元してください——再作成しないでください。
create 呼び出しが失敗し taskId が返されなかった場合にのみリトライする（ネットワークエラー、5xx）。すでに ID を返したリクエストを再送信すると、2 つ目の別課金タスクが生成されます。
status: "fail" は終端状態として扱う。入力を修正（またはフォールバックにルーティング）して新しいタスクを送信してください。失敗したタスクは再開されません。

よくあるエラー

表示される内容	意味	修正方法
`401`——`permission_denied`	キーが間違っている、またはキーにこのモデルへのアクセス権がない	ダッシュボードでキーを確認
`400 INVALID_REQUEST`——`missing required field "prompt"` / `"image_urls"`	必須入力の欠落	両方のフィールドが必須です
`400 INVALID_REQUEST`——`additional properties '...' not allowed`	不明なフィールド（例：`size`、`seed`、`n`）	厳格なスキーマ——上表のフィールドのみを使用
`400 INVALID_REQUEST`——`image_urls: maxItems`	参照画像が 3 枚を超えている	3 枚に削減
`404`——`task not found`	GET 時の `taskId` が間違っている、または別アカウントのもの	保存した ID を確認
ポーリング時の `status: "fail"`	受け付けられたが生成に失敗	`data.error` を読み、入力を調整して再送信

認証失敗は 401 で、エラー本文に "code": "permission_denied" が含まれることに注意してください——キーは存在するがこのモデルへのアクセス権がない場合も含まれるため、明示的にマッチングする価値があります。

次のステップ

モデル詳細とオンライン体験：grok-imagine/image-to-image
より高い忠実度が必要ですか？品質ティアも同じリクエスト構造を使用します：grok-imagine-quality/image-to-image
プロンプトのみから始める（参照画像なし）：grok-imagine テキストから画像
両ティアの画像 1 枚あたりのコスト：料金
完全なタスク API リファレンス：ドキュメント

よくある質問

参照画像は何枚まで渡せますか？ image_urls に最大 3 枚です。それ以上は API がハード拒否します（maxItems: got N, want 3）。

ピクセルで出力サイズを設定できますか？ できません。size フィールドはありません——aspect_ratio（14 の列挙値）で形状を、resolution（1k または 2k、小文字）で鮮明さを制御します。それ以外は 400 を返します。

aspect_ratio: "auto" は何をしますか？ 固定の画角を強制するのではなく、モデルが参照画像の比率に従うようにします——構図を保持したい編集でよく選ばれます。

結果 URL の有効期限はどのくらいですか？ 署名付き URL で有効期限があります（出力ペイロードの expireAt）。タスク成功後できるだけ早くバイトをダウンロードしてください。ホットリンクしないでください。

ポーリングとコールバックのどちらを使うべきですか？ インタラクティブな使用では約 5 秒ごとのポーリングで十分です。バッチパイプラインでは callback: {"url": ..., "when": "final"} を渡し、タスクごとに 1 回 POST を処理してください——"final" が唯一サポートされるトリガー条件です。

1 回の呼び出しで複数のバリエーションを取得できますか？ できません——n パラメータはありません。バリエーションごとに 1 タスクを送信してください。いずれにせよ並列で実行されます。

grok-imagine-quality/image-to-image との違いは何ですか？ リクエスト構造は同じで、忠実度がより高い（コストもより高い）レンダリングティアです。標準ティアでプロトタイプを作成し、残すものを品質ティアで再実行してください。画像 1 枚あたりのコストは料金ページで比較できます。