StarMagicStarMagic
日本語
简体中文简繁體中文繁EnglishEN日本語日EspañolES한국어KO
統合ガイド
StarMagicStarMagic
日本語
简体中文简繁體中文繁EnglishEN日本語日EspañolES한국어KO

GPT Image 2 画像生成

  • GPT Image 2（gpt-image-2）モデルはテキストから画像、画像から画像、画像編集などの生成モードに対応
  • 非同期処理モード、返却されたタスクIDで照会
  • 生成された画像リンクは24時間有効です、お早めに保存してください

認証

Authorizationstringheader必須

##すべてのAPIにBearer Token認証が必要です## **APIキーの取得：** [APIキー管理ページ](https://starmagic.ai/app/api-keys)にアクセスしてAPIキーを取得してください **リクエストヘッダーに追加：** ``` Authorization: Bearer YOUR_API_KEY ```

Authorization: Bearer YOUR_API_KEY

リクエストボディ

application/json
modelenum<gpt-image-2>必須

画像生成モデル名、公式チャネル、より優れた安定性と制御性、商用シナリオに適しています

"gpt-image-2"
promptstring必須

生成する画像を説明するプロンプト、または入力画像の編集方法を説明するプロンプト **制限:** - 最大 `32000` 文字（Unicode コードポイント単位、日本語・中国語・韓国語・英語などに対応）

"海面に広がる色鮮やかな美しい夕焼け"
image_urlsstring<uri>[]

画像から画像への変換および画像編集機能のための参照画像URLリスト **注意:** - リクエストあたりの入力画像数: `1~16` 枚 - 1 枚あたりのサイズ: `50MB` 以内 - サポートされるファイル形式: `.jpeg`、`.jpg`、`.png`、`.webp` - 画像URLはサーバーから直接アクセス可能であるか、アクセス時に直接ダウンロードする必要があります（通常、これらのURLは`.png`、`.jpg`などの画像ファイル拡張子で終わります） - 画像から画像 / 画像編集のシナリオでは、渡された参照画像自体にも追加の画像入力トークン消費が発生します

[
  "https://example.com/image1.png",
  "https://example.com/image2.png"
]
mask_urlstring<uri>

インペインティング マスク URL — 参照画像の再生成したい領域を指定します。**画像編集モードでのみ有効**（`image_urls` と併用必須）です。純粋なテキストから画像への生成では、マスクは黙って無視されます。 **形式要件：** - **アルファチャンネル付き PNG である必要があります**：透明ピクセル（`alpha < 255`）= 再生成領域、不透明ピクセル = 元画像保持 - **マスクの寸法は参照画像と完全に一致**する必要があります（幅 × 高さ、ピクセル単位） - リクエストごとに 1 枚のマスクのみ **注意：** - `image_urls` に少なくとも 1 枚の参照画像が必要です。マスク単独では効果がありません - よくあるエラー： - `Invalid mask image format - mask image missing alpha channel`：アップロードされた画像にアルファチャンネルがありません（JPEG、不透明 PNG など）。透明領域のある PNG として再エクスポートしてください。 - `Invalid mask image format - mask size does not match image size`：マスクのサイズが参照画像と一致しません。参照画像と同じピクセル寸法にリサイズしてください。

"https://example.com/mask.png"
sizestring

生成画像のサイズ。**比率形式**と**明示的ピクセル形式**の両方に対応、デフォルトは `auto` **① 比率形式（推奨、15 種類）** - `1:1`: 正方形 - `1:2` / `2:1`: 超縦長 / 横長 - `1:3` / `3:1`: 極端な縦長 / 横長（3:1 の境界） - `2:3` / `3:2`: 標準の縦 / 横 - `3:4` / `4:3`: クラシックな縦 / 横 - `4:5` / `5:4`: SNS でよく使われる - `9:16` / `16:9`: スマホ / デスクトップのワイド画面 - `9:21` / `21:9`: ウルトラワイド **② 明示的ピクセル形式**: `WxH`（または `W×H`）、例: `1024x1024`、`1536x1024`、`3840×2160` - 幅・高さはいずれも `16` の整数倍 - 各辺の範囲: `[16, 3840]` - ピクセル予算: `655,360 ≤ width × height ≤ 8,294,400`（約 0.65 MP ~ 8.29 MP） - アスペクト比: `≤ 3:1` **③ `auto`**: モデルが自動的にサイズを決定（このとき `resolution` は無効） **オーバー時の処理:** - 比率 + `resolution` の組み合わせがピクセル予算を超える場合、比率を保ったまま自動的に最大まで縮小されます（例: 4K 2:1 → 3840×1920）

"auto"
resolutionenum<1K | 2K | 4K>

解像度階層のショートカットパラメータ。`size` が比率形式の場合のみ有効、明示的ピクセル形式ではこのフィールドは無視されます **ピクセルバジェット規則**（目標総ピクセル数と `size` の比率から幅と高さを算出、結果は 16 の倍数に揃えられます）: - `1K`: ~1 MP（1024² = 1,048,576 ピクセル） - `2K`: ~4 MP（2048² = 4,194,304 ピクセル） - `4K`: ~8.29 MP（3840×2160 = 8,294,400 ピクセル、上限値） **横向き / 正方形の実際の出力サイズ**（縦向きは対応する横向きの幅と高さを入れ替えたもの、例: `2:3` = `3:2` の反転）: | 比率 | 1K | 2K | 4K | |---|---|---|---| | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `2:1` | 1456×720 | 2896×1456 | 3840×1920 \* | | `3:1` | 1776×592 | 3552×1184 | 3840×1280 \* | | `3:2` | 1248×832 | 2512×1680 | 3520×2352 | | `4:3` | 1184×880 | 2368×1776 | 3312×2480 \* | | `5:4` | 1152×912 | 2288×1824 | 3216×2576 | | `16:9` | 1360×768 | 2736×1536 | 3840×2160（UHD）| | `21:9` | 1568×672 | 3136×1344 | 3840×1632 \* | \* はピクセル予算を超えたため比率を保って自動縮小された組み合わせを表します。値は大文字小文字を区別しません。

"1K"
qualityenum<low | medium | high>

レンダリング品質。モデルの「思考の深さ」を制御し、出力トークン数と費用に直接影響します。デフォルトは `medium` | 値 | タイル基数 | 相対コスト（1024²）| |---|---|---| | `low` | 16 | ~0.11× | | `medium` | 48 | 1.0× | | `high` | 96 | ~4.0× |

"medium"
ninteger

生成する画像の枚数。各画像は個別に課金されます **注意:** - テキスト入力トークンは `n` に比例して拡大します

1
callback_urlstring<uri>

タスク完了後の HTTPS コールバックアドレス **コールバックタイミング：** - タスクが完了、失敗、またはキャンセルされた時にトリガーされます - 課金確認完了後に送信されます **セキュリティ制限：** - HTTPS プロトコルのみサポート - 内部 IP アドレスへのコールバックは禁止（127.0.0.1、10.x.x.x、172.16-31.x.x、192.168.x.x など） - URL の長さは `2048` 文字以内 **コールバックメカニズム：** - タイムアウト：`10` 秒 - 失敗時最大 `3` 回リトライ（`1` 秒/`2` 秒/`4` 秒後にリトライ） - コールバックレスポンスボディの形式はタスククエリ API のレスポンス形式と一致 - コールバックアドレスが 2xx ステータスコードを返した場合は成功とみなされ、その他のステータスコードはリトライをトリガーします

"https://your-domain.com/webhooks/image-task-completed"

レスポンス

application/json
成功

レスポンスボディ

createdinteger

タスク作成タイムスタンプ

1757156493
idstring

タスクID

"task-unified-1757156493-imcg5zqt"
modelstring

実際に使用されたモデル名

"gpt-image-2"
objectenum<image.generation.task>

具体的なタスクタイプ

"image.generation.task"
progressinteger

タスク進行状況のパーセンテージ (0-100)

0
statusenum<pending | processing | completed | failed>

タスクステータス

"pending"
task_infoobject
{
  "can_cancel": true,
  "estimated_time": 100
}
typeenum<text | image | audio | video>

タスクの出力タイプ

"image"
usageobject

使用量と課金情報

{
  "billing_rule": "per_call",
  "credits_reserved": 2.5,
  "user_group": "default"
}
POST/v1/images/generations
curl --request POST \
  --url https://api.starmagic.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2",
  "prompt": "海面に広がる色鮮やかな美しい夕焼け"
}'
レスポンス: 成功
{
  "created": 1757156493,
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "gpt-image-2",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  },
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 2.5,
    "user_group": "default"
  }
}