Grok Image 2.0 の画像編集 API の使い方 — 参照画像1枚とひと言で画像を編集

Grok Image 2.0 の画像編集 API の使い方 — 公開アクセス可能な参照画像1枚と編集指示を渡し、POST /v1/tasks で送信してポーリングで取得した data.output[0].url が編集後の画像です。1枚固定 $0.065、1K と 2K は同価格、マスクもレイヤーも不要です。

Grok Image 2.0 は HiAPI で提供開始済みです。画像編集モデルページを開いて 画像を1枚アップロードすれば編集できます。新規ユーザーは登録で200クレジットが付与され、画像編集1枚（130クレジット）に十分です。

TL;DR

• これは何か： grok-imagine-image-2.0/image-to-image、xAI 製。参照画像1枚と自然言語の指示で画像を編集し、背景の差し替え、小物の追加、素材や色の変更ができます。
• 料金： 1枚 $0.065。1K / 2K、low / medium は同価格。成功した画像生成のみ課金、失敗は自動返金。$10 で約153枚。
• 最短の呼び出し方： 必須は prompt と image の2項目のみ。image は1つの URL 文字列で、配列ではありません。

Grok Image 2.0 の画像編集にはどんなパラメータがありますか？

フィールド	必須	値	説明
prompt	はい	文字列	編集指示
image	はい	文字列	公開アクセス可能な JPG / JPEG / PNG / WebP の URL。配列ではない
resolution	いいえ	1k、2k	デフォルトは 1k
quality	いいえ	low、medium	デフォルトは medium。medium はディテールが良く、low は高速
aspect_ratio	いいえ	テキスト生成画像と同じ14の値	渡せますが効果なし。出力のアスペクト比は参照画像に従う

1回で編集できる参照画像は1枚のみ、1タスクで1枚出力します。複数枚は複数タスクを送信して並行実行します。上表にないフィールド名や値のリクエストは 400 を返します。

オンライン試用と API の2つのルート

オンライン試用（1分）

1. 画像編集モデルページを開き、ログインして参照画像をアップロードします。
2. 編集指示を入力し、解像度を選択します。
3. 「実行」をクリックし、タスク成功後に参照画像と生成画像を比較します。

API 連携（5分）

1. コンソールで API Key を作成します。
2. 参照画像を公的にアクセス可能な場所（自前の CDN やオブジェクトストレージ）に置きます。
3. POST /v1/tasks でタスクを送信し、ポーリングまたはコールバックを設定します。
4. 成功したらすぐに data.output[0].url をダウンロードします。

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

すぐに画像編集プロンプトを試す：老いた弦楽器職人を木屑の工房から陽光の市へ移し、人物はそのまま。このプロンプトで生成 →（リンクはプロンプトを事前入力するだけです。参照画像はモデルページでご自身でアップロードし、解像度は 2K を選択）

参照画像	生成画像

curl と Python：初めての画像編集を動かす

まず API Key を設定します：

export HIAPI_API_KEY="sk-..."

すべてのリクエストに Authorization: Bearer sk-<key> を付けます。画像編集は非同期で、HiAPI の他のモデルと同じタスク API を共用します。参照画像はサーバー側が取得するため、ローカルファイルのパスは不可で、公開アクセス可能な URL である必要があります。

ステップ1、タスクを作成：

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

すぐに taskId が返ります：

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

ステップ2、終状態までポーリング：

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status を確認します：success は成功、fail は失敗、それ以外は待機を続けます。成功レスポンスの例：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

storage: "temp" と expireAt に注意：生成画像の URL は一時的です。タスク完了後すぐにダウンロードするか、自分のオブジェクトストレージに転送してください。出力のアスペクト比は参照画像に従うため、例では効果のない aspect_ratio を省略しています。

Python 版：

まず requests をインストールし（python3 -m pip install requests）、上記の HIAPI_API_KEY を設定します。スクリプトは最大10分ポーリングします。タイムアウト後は taskId を保持して問い合わせを続けてください。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

リリース前に何に注意すべきですか？

• 参照画像は先に公網へ置く。 ユーザーがアップロードした画像がプライベートバケットや localhost にあると、プラットフォームが取得できずタスクは非同期で失敗します。送信前に URL が公開アクセス可能であることを確認し、長期有効なアドレスを使ってください（期限切れの署名付きリンクは不可）。

• 指示は「何を保つか、何だけ変えるか」で書く。 まず変えてはいけない部分を書き、次に変える部分を書きます。変更範囲が狭いほど安定します。他の書き方は画像編集プロンプトテンプレートを参照。

• バッチはコールバックを使い、タイトループでポーリングしない。

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" はタスクが成功または失敗の終状態に達したときに通知します。受信側は taskId で重複排除します。

• 生成画像はすぐに転送保存。 data.output[0].url は一時アドレスで、expireAt に従って期限切れになります。

• 1タスクにつき1回だけ送信。 レスポンスを受け取ったら taskId と業務タスクの対応関係を保存します。重複送信は複数タスクを作成して別々に課金される可能性があります。作成リクエストがタイムアウトして ID を受け取れなかった場合は、まずタスク記録を確認してから再送信するか決めてください。

• resolution を明示する。 デフォルトは 1k。1K と 2K は同価格（$0.065）なので、本番用途では "2k" を直接指定してください。

• エラー処理。 まず HTTP ステータスとレスポンスの code、message を確認し、その後 data を読み取ります。パラメータや認証エラーは修正してから再送信してください。タスクが fail を返したらエラーを記録してポーリングを停止します。

関連記事

• Grok Image 2.0 テキスト生成画像モデルページ：同シリーズ、テキストのみで新しい画像を生成。
• Grok Image 2.0 API の料金はいくら？
• Grok Image 2.0 テキスト生成画像 API 連携
• Grok Image 2.0 画像編集プロンプトテンプレート
• 認証とクイックスタート

よくある質問

image は URL 1つか配列か？ 1つの文字列 URL です。配列を渡すと型エラーになります。複数画像の融合が必要な場合は、複数の参照画像をサポートするモデルに切り替えてください。

「additional properties not allowed」が出たら？ input は prompt、image、aspect_ratio、resolution、quality のみ受け付けます。他の編集モデルでよくある image_urls、strength、mask、seed、negative_prompt はここでは使えないので削除してください。

ブラウザで参照画像を開けるのに、タスクが失敗することがあるのはなぜ？ プラットフォームはサーバー側で画像を取得するため、参照画像はログイン不要で公網からアクセス可能である必要があります。署名付きリンクは取得完了まで有効であることが必要です。アクセス権限、フォーマット、リンクの有効期限を確認してから送信してください。

一度に複数枚の画像を編集できますか？ できません。1枚入力、1枚出力です。バッチ処理は複数タスクを送信して並行実行してください。

画像編集はなぜテキスト生成画像より高いのですか？ 画像編集は $0.065、テキスト生成画像は $0.052 で、25% 高く、それが「参照画像1枚で編集する」能力に対応します。

出力 URL はどのくらい有効ですか？ 一時ストレージで、レスポンスの expireAt が Unix タイムスタンプです。タスク成功後すぐにダウンロードまたは転送保存してください。

結果を同期的に待つ必要がありますか？ いいえ。作成 API はタスクがキューに入るとすぐに返します。短いスクリプトは GET /v1/tasks/<taskId> でポーリングし、本番環境では callback を設定してください。

今すぐ最初の画像を編集

まず HIAPI_API_KEY を設定し、curl と Python の例の image アドレスを自分の公網画像 URL に置き換えてください。先に効果を見たい場合は、画像編集モデルページを開き、画像をアップロードして上記のプロンプトを貼り付けてください。