使用ガイド

hiapi API で gpt-image-2-beta を使う方法：パラメータ、コード、実行可能なサンプル

Sep 16, 2026

gpt-image-2-beta は、hiapi 上で GPT Image 2 にアクセスするためのミニマルで固定価格のルートです。入力フィールドは2つ、価格は1つ、アスペクト比や品質の調整項目はありません。このガイドでは、最小限の実行可能なサンプル、正確なパラメータ構造（オンラインエンドポイントのプローブで確認済み）、そしてデフォルトの gpt-image-2/text-to-image ルートとの比較を示し、どちらをいつ使うべきかを判断できるようにします。

前提条件

hiapi ダッシュボードの API Keys ページから API キーを取得する必要があります。キーは sk- で始まります。現在の1枚あたりの価格は、gpt-image-2-beta モデルページと料金ページを参照してください。

hiapi 上の他のすべての画像モデルと同様に、このモデルは統一された非同期タスクエンドポイントで動作します：

POST https://api.hiapi.ai/v1/tasks —— 生成タスクを作成する
GET https://api.hiapi.ai/v1/tasks/{taskId} —— タスクのステータスをポーリングする

beta ルートの違い

gpt-image-2/text-to-image（デフォルトルート）は aspect_ratio と resolution を受け付け、解像度ティアに応じて課金します（1K は $0.03、最大 4K で $0.06）。gpt-image-2-beta はこれらすべてを、1枚あたり一律 $0.02 の固定価格と、オプションの size フィールドに圧縮します——"1024x1024" や "1600x900" のような文字通りのピクセルサイズ文字列であり、比率ではありません。size を完全に省略した場合、モデルは自身のデフォルト出力サイズにフォールバックします。

その代償は、きめ細かい比率/解像度の制御を放棄し、より低くシンプルな価格を得るということです。正確な構図にこだわらず「安く1枚画像を生成したい」だけの場合に適しています。

最小限の実行可能なサンプル（curl）

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

完成した画像は data.output[0].url にあります。この URL は短い expireAt 有効期限を持っています——すぐにダウンロードして自分のストレージに再ホスティングしてください。本番コンテンツから直接リンクしないでください。

上記の curl 呼び出し（異なるプロンプトを使用）で生成されたサンプル画像。size: "1024x1024" を使用。

Python：作成 + ポーリング + ディスクへの保存

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

パラメータリファレンス

gpt-image-2-beta の input オブジェクトは2つのフィールドのみを受け付けます——この構造は additionalProperties: false であるため、それ以外の内容は黙って無視されるのではなく、即座に拒否されます。

フィールド	型	必須	説明
`prompt`	string	はい	生成する画像のテキスト記述。
`size`	string	いいえ	文字通りのピクセルサイズ。例：`"1024x1024"`、`"1600x900"`。アスペクト比のキーワードではありません。省略するとモデルのデフォルト出力サイズが使用されます。

サポートされない内容（および返されるエラー）

beta 構造は、デフォルトの gpt-image-2/text-to-image ルートや OpenAI Images API で使用されるフィールドを一切受け付けません——aspect_ratio、resolution、quality、background、moderation、output_format、output_compression、n、user、style などです。これらのいずれかを送信すると、即座に HTTP 400 が返されます。例：

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

デフォルトルートや OpenAI の Images API からコードを移行する場合は、まず prompt + size に絞り込んでから gpt-image-2-beta を指定してください。

料金：beta vs デフォルト vs @ext

ルート	価格	制御項目
`gpt-image-2-beta`	$0.02/枚固定	`size`（ピクセルサイズ）のみ
`gpt-image-2/text-to-image`（デフォルト）	$0.03（1K）/ $0.04（2K）/ $0.06（4K）	`aspect_ratio` + `resolution`
`gpt-image-2/text-to-image@ext`	$0.007–$0.76、品質 × 解像度による	16種類のアスペクト比、品質ティア

本番でルートを確定する前に、料金ページを確認してください——特定のモデルの価格は変更される可能性があります。

beta ルートで構築するためのヒント

上記のフィールドリストは現在の取り決めであり、恒久的なものではありません。beta ルートの構造や料金はデフォルトルートよりも変更されやすいため、本番で依存する場合は定期的にモデルページを再確認してください。
size はオプションであるため、レイアウトが特定のサイズに依存する場合は常に明示的に指定してください——現在のデフォルトが変わらないことに依存しないでください。
他の hiapi 画像モデルと同様に status: "fail" を処理してください：task.error.code / task.error.message を読み取り、毎回の失敗が一時的なものと仮定せず、バックオフで再試行してください。