HiAPI APIでgrok-imagine/image-to-imageを呼び出す方法：curlとPythonガイド

grok-imagine/image-to-imageが開発者に提供する機能

grok-imagine/image-to-imageは画像変換エンドポイントです。参照画像とプロンプトを渡すと、プロンプトに従いつつ、視覚的には参照画像との関連を保った新しい画像を返します。ゼロからの生成ではなく、ガイド付き生成と考えるとよいでしょう。HiAPI上で呼び出すモデルidはgrok-imagine/image-to-imageであり、リクエストの残りの部分はすべて、どのような変更を望むかを記述するためのものです。

出力が既存の素材の何らかを保持しなければならない場合——背景を差し替えたい商品写真、レンダリングしたいキャラクターの下書き、スタイルを変えたい構図——は、テキストからの画像生成呼び出しではなくこのエンドポイントを選ぶべきです。テキストからの画像生成は、元画像がなく説明だけがある場面に適しています。image-to-imageは、元画像そのものが仕様の一部である場面に適しています。

HiAPIはこれを単一の統一インターフェースとして公開しているため、あなたの統合作業は1種類のリクエスト構造を組み立て、1種類のレスポンス構造を処理するだけにとどまります。モデルシリーズごとに個別のSDKを導入する必要も、エンドポイントごとに認証方式を学び直す必要もありません。

リクエストの解剖：モデル、参照画像、プロンプト

有効な呼び出しは概念的には4つの部分から成ります。コードを書く前にそれぞれを正しく理解しておけば、後のデバッグ作業の大半を省けます。

モデルid

modelフィールドには文字列grok-imagine/image-to-imageを指定します。これはクライアント内の定数として扱い、コードベースのあちこちに散らばるハードコードされたリテラルにはしないでください。将来別のHiAPIモデルを試す場合に、変更箇所が1か所で済むようにするためです。

参照画像

参照画像はアンカーです。その提供方法は選択した転送方式によって異なります。APIが取得可能なURLか、インラインのbase64データかです。インラインは、その場で生成した画像や公開アクセスできない画像に適しています。すでにホスティングしている素材にはURLを優先し、どこにも公開されていないユーザーアップロードにはインラインデータを優先してください。いずれの転送方式でも、送信前に画像を検証してください。対応形式であること、サイズがゼロでないこと、意味のある寸法であることを確認します。

プロンプト

プロンプトが記述するのは変換であり、シーン全体ではありません。参照画像にすでに被写体が含まれているなら、変更すべき内容——スタイル、ライティング、背景、素材——を記述し、変わらない部分は暗黙のままにしておきます。参照画像に見えている内容を過剰に指定すると、役に立つどころか画像条件付けと衝突しがちです。

アスペクト比の扱い

残る部分は出力サイズをどう決めるかであり、これが次の節のテーマです。リクエストを組み立てるコードの中では、これら4つの部分を分離して、それぞれを独立に検証・ログ記録できるようにしてください。

auto aspectオプションの使用

auto aspectオプションは、明示的な幅と高さを固定する代わりに、APIに出力サイズを選ばせます。有効にすると、サービスはリクエストの文脈——最も重要なのは参照画像——から適切なアスペクト比を導き出し、出力の形状が既定の画枠に押し込まれるのではなく、入力に対してより合理的になります。

これは見た目以上に重要です。参照画像の比率と一致しないサイズを固定すると、レターボックス状のアーティファクト、被写体の不自然な切り取り、あるいは元画像の構図を無視した構図が生じます。auto aspectはジオメトリを入力に追従させることで、こうした不一致を避けます。

autoを有効のままにすべき場合

• 参照画像がユーザー由来で、形状がさまざまである。
• プロトタイピング中で、そのユースケースにどのサイズが合うかまだ分からない。
• 出力が、最終的にどうせトリミングやスケーリングを行う下流パイプラインに入る。

サイズを明示的に固定すべき場合

• UIや印刷ターゲットに固定スロットがあり、正確な出力ジオメトリが必要。
• サイズが視覚的に一致していなければならない画像のバッチを生成している。

実用的な進め方は、開発中はauto aspectを有効のままにし、実際の入力に対してAPIが返すサイズを確認してから、本番環境向けにサイズを固定するかどうかを決めることです。返された画像メタデータをリクエストと一緒に記録すれば、この判断を推測ではなく証拠に基づいて行えます。

利用可能なcurlリクエスト

以下のリクエストはプレースホルダーを除いて完全であり、プレースホルダーは山括弧で示しています。自分の値に置き換えればそのまま実行できます。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

置き換えるべきプレースホルダー

• $HIAPI_API_KEY —— キーはコマンドに貼り付けるのではなく、環境変数から読み取ります。変数が設定されていなければ、リクエストは認証エラーで失敗し、キーがシェル履歴に残ることもありません。
• <describe the transformation you want> —— 短く具体的な指示。たとえばスタイルや背景の変更など。
• <publicly reachable URL of your reference image> —— サービスが認証なしで取得できるURL。素材が非公開なら、代わりにインラインのbase64データを使用してください。

レスポンスの読み取り

初回実行時は出力をJSON整形ツールに通し、レスポンス構造を明確に確認してください。注目すべきは2点です。画像ペイロード（レスポンスモードによってURLかエンコードされたデータのいずれか）と、呼び出しが非同期で処理される場合のタスク識別子です。開発中は完全な生レスポンスをログに保存しておきましょう。何かおかしいと感じたときに「実際に何が返されたか」を答える最短の方法だからです。

同じリクエストをPythonで

Python版はcurlリクエストとフィールド単位で対応させるべきです。両者を揃えておく価値は、一方で再現したバグをもう一方で確認でき、変換を推測せずに済むことです。

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

エラー処理はどこに置くべきか

呼び出し側ではなく、呼び出しを包む関数の中に置きます。response.raise_for_status()は2xx以外のレスポンスを例外に変換するため、generate_from_referenceを囲む単一のtry/exceptが転送失敗とAPIによる拒否の両方をカバーできます。失敗理由を構造化してログ記録したい場合は、例外を投げる前に関数内でresponse.status_codeとエラー本文を確認してください。

クライアントを整潔に保つ

APIキーは起動時に一度読み取り、明示的なタイムアウトを設定し、生のレスポンスオブジェクトではなくパース済みのJSONを返します。呼び出し側はHTTPの詳細を知る必要はありません。テストではAPI_URLをスタブサーバーに向ければ、実際の生成呼び出しを消費せずにリクエスト組み立てロジックを検証できます。

同期レスポンスと非同期レスポンス

一部のimage-to-imageリクエストは十分に速く完了し、同じHTTPレスポンス内で結果を返します。他のリクエストはジョブとして処理されます。最初の呼び出しが識別子を返し、画像は後で利用可能になります。クライアントはどちらか一方を前提にしてはいけません。

両者をどう区別するか

毎回の呼び出し後にレスポンス本文を確認します。画像ペイロードが直接含まれていれば同期経路であり、それを抽出して返します。ジョブまたはタスク識別子が含まれていれば非同期経路であり、ジョブが終端状態に達するまでポーリングする必要があります。

両方に対応する構造設計

小さなディスパッチ関数を作れば、2つの経路をビジネスロジックの外に追い出せます。

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

トラブルを避けるためのポーリング規則

• タイトなループではなく、上限付きの指数バックオフを使う。
• 最大総待機時間を設定し、超えたら潔く失敗させる。
• 終端でない状態はすべて「待機継続」とみなし、最終状態は成功と失敗の2つだけとする。
• 各ポーリング時にジョブidを記録し、ログだけで停止したジョブを追跡できるようにする。

ディスパッチ方式にしておけば、同期動作と非同期動作を切り替えても、resolve_resultを呼ぶコードは一切変更不要です。

よくあるエラーコードのデバッグ

このエンドポイントでの失敗呼び出しの大半は、少数のカテゴリに収まります。以下のチェックリストを順に確認してください。最も多い原因から最も少ない原因の順に並んでいます。

認証失敗

レスポンスが認証問題を示しているなら、キーが欠落しているか、形式が誤っているか、送信されていません。呼び出しを実行するプロセスで環境変数が実際に設定されているか、ヘッダーが厳密にAuthorization: Bearer <key>になっているかを確認してください。シェルではキーが有効なのにサービスでは無効という場合は、通常、サービスの環境がシェル環境と異なることを意味します。

参照画像の検証エラー

画像関連の拒否は通常、次の4つのいずれかを意味します。URLが公開取得できない、形式が非対応、ペイロードが大きすぎる、画像が小さすぎるか破損している。ブラウザで認証情報なしにそのURLをテストしてください。そこで読み込めないなら、APIも取得できません。インラインbase64の場合は、エンコーディングが純粋なbase64であり、data-URLプレフィックスが付いていないこと（パラメータがそれを期待している場合を除く）を確認してください。

プロンプトとパラメータのエラー

空または大きすぎるプロンプト、あるいは不明なパラメータ値は検証レスポンスを生みます。送信した正確なペイロードをエラーと一緒にログ記録してください。失敗のかなりの部分は、値の問題ではなくフィールド名のタイプミスです。

レート制限

レート制限レスポンスは即時再試行ではなくバックオフを意味します。レスポンスヘッダーの再試行指示に従い、ジッターを加え、再試行回数を制限してください。バックオフなしの再試行は、一時的な制限を継続的な制限に変えてしまいます。

サーバー側エラー

5xxレスポンスはサーバー側の問題です。バックオフを伴う有限回の再試行を行い、継続する場合はレスポンスからリクエストidとタイムスタンプを取得し、調査中は同時実行数を下げてください。

本番稼働前のチェックリスト

動くリクエストは始まりにすぎず、終わりではありません。このエンドポイントで実際のトラフィックを処理する前に、以下を確認してください。

境界で入力を検証する

リクエストがあなたのサービスを離れる前に、参照画像の形式とサイズ、プロンプト長、パラメータ値を確認してください。不良入力をローカルで拒否する方が、往復するより速く安く、ユーザーにはより明確なエラーメッセージを返せます。

安全に再試行できるリクエストだけを再試行する

転送失敗、レート制限、5xxレスポンスには指数バックオフとジッターを伴う再試行を行います。検証エラーや認証エラーは再試行しないでください。同じように失敗するだけで、負荷を増やすだけです。

失敗を再現できるだけの情報を記録する

モデルid、プロンプトのハッシュまたは切り詰めた形、参照画像の識別子（完全なペイロードではなく）、レスポンスステータス、ジョブid（存在する場合）、リクエストidを記録してください。この情報群は通常、機密内容を保存せずに「何が起きたか」を答えるのに十分です。

キーをコードの外に置く

APIキーは環境またはシークレットマネージャーから読み取り、ソースコード内のリテラルからは決して読まないでください。定期的にキーをローテーションし、漏洩が疑われる場合は直ちに失効させてください。

コスト挙動に注意する

このエンドポイントの課金は生成によって決まるため、重要なレバーはリクエスト量、再試行、ポーリング頻度です。再試行の嵐を避け、ポーリングにバックオフをかけ、同じ変換が繰り返し要求される場面ではプロンプトと参照画像で結果をキャッシュしてください。想定をハードコードせず、HiAPIの料金パネルで現在のレートを確認しましょう。

うまくいかない経路をテストする

無効な画像URL、レート制限レスポンス、決して完了しない非同期ジョブに対するテストを書いてください。この3つが、気付かれないまま本番環境に入り込む可能性が最も高い失敗をカバーします。

リクエストの組み立て、レスポンスのディスパッチ、エラー処理が揃えば、grok-imagine/image-to-imageは特別扱いではなく、パイプラインの日常的な一部になります。