tutorial9 分で読める

GPT Image 2 でネイティブ 4K 画像を生成する: アスペクト比とアップスケールのワークフロー

現行の GPT Image 2 契約でネイティブ 4K を生成する。size にはアスペクト比、resolution には 4k を指定する。文書化された upscale: true フラグはなく、4K のピクセル寸法は選んだ比率に依存する。

ToAPIs Engineering & Evaluation Team
TL;DR - 要点まとめ
  • 正確な gpt-image-2 は resolution を第一級のティアとして公開する。値は 1k、2k、4k。ネイティブ 4K は POST /v1/images/generations で resolution: "4k" を送ることであり、サーバー側の upscale: true フラグでも、1024x1024 のような size 文字列でもない。
  • size はアスペクト比(1:1、16:9、その他の文書化された比率)である。API リファレンスはピクセル表を公開しており、16:9 の 4k は 3840x2160、1:1 の 4k は 2880x2880 である。
  • 現行プレイグラウンドは resolution が 4K のとき 5:4 と 4:5 を省略する。一方、API のサイズ表にはこの 2 つの比率の 4k ピクセル値が載っている。必要な場合はライブのリファレンスで確認すること。
  • ジョブは非同期である。タスク id を永続化し、GET /v1/images/generations/{id} をポーリングする。クライアントのタイムアウトは、特に 4k では、失敗の証明にならない。
  • 古い 1024px / 2048px の単価で予算を組まないこと。アカウントで、そのモデル ID の現行ティア別レートを確認する。

GPT Image 2 でネイティブ 4K 画像を生成する: アスペクト比とアップスケールのワークフロー

対象モデル: gpt-image-2
推論エンドポイント: https://api.toapis.com/v1/images/generations
関連: GPT Image 2 API ガイド · インペインティングとアウトペインティング · グローバルミラーとプロキシ · API サイズリファレンス


1. クイックスタートと性能概要 (TL;DR)

  • 目的: 実際に必要なアスペクト比で、文書化された 4K ティアの画像を、1 回の gpt-image-2 リクエストから得る。
  • 契約: モデル ID gpt-image-2 で POST /v1/images/generations を呼ぶ。size はアスペクト比(1:1、16:9、その他の文書化された比率)。resolution は 1k、2k、または 4k。公式リファレンスは各組み合わせのピクセル寸法を公開している。
  • 送ってはならないもの: size: "2048x2048"、正確な gpt-image-2 上の quality: "hd"、2048 px の描画を 3840x2160 に変えると称する発明された upscale: true フィールド。4K は第一級の resolution 値である。
  • 非同期プロトコル: 投入はタスク id を返す。GET /v1/images/generations/{id}(または GET /v1/tasks/{id})を completed または failed までポーリングする。4K ジョブは 1K の下書きより時間がかかることがある。クライアントのタイムアウトは失敗の証明ではない。
  • FinOps: 1k で下書きし、採用したプロンプトを 4k に上げ、現行のティア別レートを確認する。古い 1024 px / 2048 px の価格行を予測へコピーしない。

2. アスペクト比、解像度ティア、ネイティブ 4K 出力

現行の gpt-image-2 契約は形とティアを分けている。size がアスペクト比、resolution が品質ティアを選び、サービスが両方からピクセル幅と高さを導く。だから「4K 画像」が常に 3840x2160 なのではない。そのサイズは size: "16:9" と resolution: "4k" の文書化された結果である。正方形の 4K 出力は 2880x2880 と文書化されている。

公式リファレンスのプリセット比率は次のとおりである。

1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21

auto を渡して上流に任せることもできるが、最終的な比率とピクセルサイズは保証されない。正確な gpt-image-2 には custom のピクセルサイズフィールドは文書化されていない。カスタムの width:height 比率(例: 7:4)は gpt-image-2-vip と gpt-image-2-official に文書化され、それぞれの制限(辺は 16 の倍数、長辺は最大 3,840 px、比率は最大 3:1、総画素は 655,360 から 8,294,400)に従う。

正確な gpt-image-2 の公式サイズ表は次のとおりである。

size1k2k4k
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

この表の横に、次の 2 点を置く。

  • 現行の ToAPIs プレイグラウンドは 4K でも 3:2 と 2:3 を残すが、5:4 と 4:5 は外す。上の表には、この 2 つの比率の 4k ピクセル値がある。製品で 4k の 5:4 や 4:5 が必要なら、ライブリクエストで確認し、プレイグラウンドの制約を API の上限だと決めつけないこと。
  • 画面によって小文字(4k)と大文字(4K)が混在する。公式の gpt-image-2 例は小文字、プレイグラウンド設定は 1K / 2K / 4K を使う。クライアントでは API リファレンスに従い、大文字小文字を第二のパラメータとして扱わないこと。

粗い 2×2 のノード格子が六角形ゲートウェイを通って、より細かい高解像度格子へ流れる

図 1: 解像度は第一級のリクエストフィールドである。文書化された経路は 4k を直接要求することであり、後処理のアップスケーラーフラグを発明することではない。

ToAPIs には、ネイティブ 2048 px の描画を 3840x2160 に変える文書化された upscale: true スイッチはない。すでに 1K または 2K の画像があり、より大きな結果が欲しい場合、対応している手順は新しい生成を行うことである(任意で下書きを reference_images に入れ)、resolution: "4k" を指定する。自前の素材で測定していない限り、文字の鮮明さ、「300 DPI 印刷マスター」、ノイズのないアップスケールを約束してはならない。

正確な gpt-image-2 は任意の background: "transparent" と、最大 14 件の reference_images URL も受け付ける。現行プレイグラウンド契約では quality を公開しない。quality は gpt-image-2-vip などの ID のフィールドである。


3. 本番実装: cURL と Python

本シリーズの国際向け例は https://api.toapis.com を使う。公式ドキュメントは中国本土の利用者に https://toapis.cn を使うよう案内している。環境ごとにオリジンは一つに保つ。

ステップ 1: ネイティブ 4K を cURL で投入する

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
    "size": "16:9",
    "resolution": "4k",
    "n": 1,
    "response_format": "url"
  }'

このリクエストは文書上 3840x2160 を目指す。正方形の 4K マスターなら size を 1:1 にする(文書化サイズは 2880x2880)。9:16 のストーリー枠なら size: "9:16"(文書化サイズは 2160x3840)。

ステップ 2: Python で下書きしてから昇格する

1k で反復し、採用したプロンプト(と任意の参考 URL)を保存してから 4k で再投入する。ポーリング補助は ミラーとプロキシのガイド と同じ非同期契約である。

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_image(
    prompt: str,
    size: str = "16:9",
    resolution: str = "1k",
    model: str = "gpt-image-2",
    reference_images: list[str] | None = None,
) -> str:
    payload = {
        "model": model,
        "prompt": prompt,
        "size": size,
        "resolution": resolution,
        "n": 1,
        "response_format": "url",
    }
    if reference_images:
        payload["reference_images"] = reference_images
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(
        f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
    )


if __name__ == "__main__":
    prompt = (
        "Wide architectural photograph of a concrete pavilion at dusk, "
        "still water in the foreground, no typography, no logos"
    )
    draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
    print("Draft:", draft_id, poll_image_task(draft_id))
    final_id = dispatch_image(prompt, size="16:9", resolution="4k")
    print("4K:", final_id, poll_image_task(final_id, deadline_s=300))

4K のポーリング期限は 1K の下書きより長く取る。タスク id はすぐに永続化し、クライアントがタイムアウトしても後から状態を確認できるようにする。後でクライアントを gpt-image-2-vip(カスタム比率、quality)や gpt-image-2-official に切り替える場合は、変数を一つずつ変え、その ID のリファレンスを読み直すこと。課金単位は自動的には一致しない。


4. エラー処理とステータスマトリクス

次の分類は切り分けの出発点であり、ToAPIs の正確なエラーコードを保証するものではない。HTTP 投入が成功しても、タスクの status を読む必要がある。

HTTP ステータスよくある分類推奨アクション
400不正なフィールド、または未対応の組み合わせsize が文書化された比率であること、resolution が 1k / 2k / 4k であること、2048x2048 のようなピクセル文字列や文書化されていない upscale フラグを送っていないことを確認する
401API キーの欠落または無効ToAPIs ダッシュボードでキーをローテーションし、Authorization ヘッダーを確認する
429レートまたは同時実行の制限Retry-After があれば従い、ジッター付きでバックオフし、安全なときだけ再試行する
5xx またはネットワークタイムアウトゲートウェイまたは上流の一時的な問題再投入の前にタスク状態を確認する。4K ジョブはクライアントタイムアウト後も in_progress のことがある

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. 料金と FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • 古い単価を再利用しないこと。たとえば 1024 px の $0.024 や 2048 px の $0.072。これらの行は、すでに古いサイズ契約に属する。
  • GPT Image 2 モデルガイド は現在、標準 gpt-image-2 について ToAPIs ランディング比較として 1K / 2K / 4K で 1 枚あたり $0.015 / $0.020 / $0.025 を示している。掲載上の比較として扱い、アカウントと実際に呼ぶモデル ID に適用されるレートを確認すること。
  • 費用を抑えるループは、1k で下書きし、採用したプロンプト(と参考画像)を 4k に上げることである。成功したジョブが 2 件あれば、アカウント条項に別段の定めがない限り 2 枚分の課金になる。同じプロンプトを無料で拡大できる、といった文書化された近道はない。
  • 公式ベンダーのトークン価格と ToAPIs のリクエスト単位価格は互換ではない。gpt-image-2-vip や公式チャネルの SKU に移る場合は、その ID の料金表を読み直すこと。
  • 背景は GPT Image 2 料金記事 を参照し、予測に入れる前に現行カタログで数字を検証すること。

6. よくある質問

詳細は frontmatter の FAQ を参照。要約: 4K は第一級の resolution 値であり、upscale フラグではない。ピクセル寸法は size と resolution の両方に依存する。size に 1024x1024 を送らない。4k で 5:4 / 4:5 が必要ならライブ API で確認する。掲載されている 1K / 2K / 4K レートはアカウントで確かめる。


7. アクションチェックリスト

  • ToAPIs 開発者ポータル でキーを作成する。
  • 環境ごとにベース URL を一つに決め(https://api.toapis.com、必要な場合は https://toapis.cn)、size: "16:9" と resolution: "1k" で cURL 断片をスモークテストする。
  • 同じプロンプトを resolution: "4k" に上げ、その比率の文書化ピクセルサイズを確認する(16:9 なら 3840x2160)。
  • タスク id を永続化し、4K のポーリング期限を長く取り、429 では Retry-After に従う。
  • 次の読み物: 既存フレームを編集するなら インペインティングとアウトペインティングのガイド、パラメータ全体は API ガイド。

記事内で紹介されたモデルとAPI

OpenAIIMAGE

GPT-Image-2

現在のレート:3 credits /request
OpenAIIMAGE

GPT-Image-2 VIP

現在のレート:3.38 credits /request

関連記事