このページの内容
GPT Image 2 API
一貫した非同期APIを使い、プロンプトと任意の参照画像から実運用向けのGPT Image 2画像を1枚生成できます。Imyaがタスク状態、現在のプランに基づく料金、生成アセットを管理します。
REST API · v1 · 非同期タスク
最初のリクエストを送信する
APIは非同期です。タスクを作成して返されたtask IDを保存し、結果が準備できるまでタスクを取得します。
- 1
APIキーを作成
Imyaアカウントの設定画面でキーを発行します。
- 2
タスクを作成
モデルID、プロンプト、出力オプションを送信します。
- 3
結果を取得
成功または失敗になるまでタスクを取得します。
認証と冪等性
Imya APIキーをBearerトークンとして送信します。生成POSTには一意のIdempotency-Keyも必須です。安全に再試行しても、二重のタスク作成や課金は発生しません。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY画像生成タスクを作成
非同期のGPT Image 2タスクを作成し、credits_reservedとして返される正確なクレジットをアトミックに差し引きます。
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gpt-image-order-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"aspect_ratio": "1:1",
"resolution": "1K",
"n": 1
}'タスクを取得
最新のタスク状態、最終クレジット使用量、生成アセット、または構造化エラーを返します。取得間隔は5秒以上にしてください。短い間隔のリクエストもレート制限に数えられますが、上流の状態は更新されません。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| model | string | はい | gpt-image-2を指定します。 |
| prompt | string | はい | 画像生成用のテキストプロンプトです。 |
| aspect_ratio | string | いいえ | auto、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、3:1、1:3、21:9、9:21のいずれかです。 |
| resolution | string | いいえ | 1K、2K、4Kのいずれかです。一部のアスペクト比は1Kのみ対応します。 |
| n | number | いいえ | 1のみ指定できます。生成画像は常に1枚です。 |
| image_urls | string[] | いいえ | 画像から画像を生成する場合の公開HTTPS参照画像を1〜16枚指定します。 |
レスポンス
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 13
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:42.000Z",
"credits_reserved": 13,
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}クレジット課金
基本料金は1Kが10クレジット、2Kが15クレジット、4Kが24クレジットです。サーバーはAPIキー所有者の現在のプラン係数を適用し、実際の料金をcredits_reservedとして返します。例は通常アカウントで1K画像を生成した場合の13クレジットです。常にレスポンス値を使用してください。nは1固定です。
タスクステータス
pendingタスクを受け付け、開始を待っています。
processingモデルが指定された画像を生成しています。
succeeded生成が完了し、dataにアセットが含まれます。
failed生成に失敗しました。構造化されたerrorオブジェクトを確認してください。
エラー
400Idempotency-Keyがないか、JSONの形式が不正です。
401APIキーがないか、無効です。
402アカウントのクレジットが不足しています。
403APIアカウントが無効です。
404タスクが存在しないか、このアカウントに属していません。
409同じ冪等キーが異なるリクエスト本文で再利用されました。
413リクエスト本文が64 KiBを超えています。
422モデル、プロンプト、アスペクト比、解像度、n、または参照画像が無効です。
429APIキーのレート制限または同時実行数の上限に達しました。
5xxリクエストを完了または送信できませんでした。
Imya 公開 API の共通仕様
以下のルールは、すべての公開画像・動画生成 API に適用されます。モデル固有のパラメータと料金は、このページのパラメータ表を確認してください。
課金と安全な再試行
新しいタスクが受理されると、credits_reserved に表示された正確なクレジットがアトミックに差し引かれます。同じ Idempotency-Key と同じリクエスト本文を再送しても、二重課金されません。
タイムアウトと返金
30 分以内に最終状態へ到達しないタスクは失敗になります。対象クレジットの返金は一度だけ行われ、元の有効期限が維持されます。
レートと同時実行制限
API キーごとに 60 秒間で最大 120 リクエストです。同一アカウントでは画像タスクを最大 5 件、動画タスクを最大 3 件まで同時実行できます。429 応答には Retry-After が含まれる場合があるため、返された場合は従ってください。
ポーリングと所有権
タスク作成時に返された id を使い、GET /v1/tasks/{id} を 5 秒以上の間隔で取得してください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。作成したアカウントだけが結果を参照でき、現在は Webhook、SDK、バッチ送信に対応していません。
エラーとコンテンツ安全性
公開エラーはサニタイズされ、上流の認証情報、内部 URL、インフラ情報を公開しません。安全でないプロンプトは生成前に prompt_blocked で拒否される場合があります。
画像結果の保存期間
無料アカウントの画像結果は 7 日間、有効な有料プランまたは Lifetime アカウントでは最長 30 日間保存されます。削除後は空の成功応答ではなく、status が failed、error.code が media_deleted の応答を返します。
GPT Image 2 API 本番環境導入ガイド
安定した GPT Image 2 連携は、1 回の長時間 HTTP リクエストではなく、小規模な非同期ジョブシステムとして設計します。モデルの選択肢を設定に集約し、Imya タスクから返される id を必ず保存し、再試行を決定的にしてください。以下はローカルのサンプルから本番環境へ進む際の実践的な指針です。
モデル仕様からパラメーターを選ぶ
送信前に、このページのパラメーター表に対してすべてのリクエストを検証します。開発中は最小のサポート済み入出力から始め、製品に必要な場合にだけ品質、サイズ、長さ、または参照数を増やします。ユーザー入力のプロンプトとファイルは、API を呼び出す前に長さ、種類、容量を自社サーバーで確認してください。
参照画像を使う場合は順序を保ち、ユーザーがすべてのアップロード画像を使用できる権利を持つことを確認します。
復旧できる非同期フローを設計する
画像タスクを送信し、返却された id を自社のジョブレコードと共に保存し、バックグラウンドワーカーで状態を取得します。GET /v1/tasks/{id} は 5 秒以上の間隔でポーリングしてください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。公開 status は pending、processing、succeeded、failed の 4 種類だけです。タスクのハード期限は 30 分です。最終状態を受信するか期限に達したら停止します。現在、Webhook、SDK、バッチ送信は利用できないため、HTTP リクエストとポーリングで連携します。
- 01UI を更新する前に、id、status、credits_reserved、リクエスト識別子を永続化します。
- 02一時的なネットワークエラーではバックオフし、429 の Retry-After に従い、通信エラーから新しい有料タスクを自動作成しないでください。
- 03同一アカウントの同時実行は最大 5 件の画像タスクです。API キーごとに 60 秒間で最大 120 リクエストです。
課金と再試行を決定的にする
新しいタスクが受理されると、credits_reserved で返された正確なクレジットがアトミックに差し引かれます。意図した作成ごとに 1 つの Idempotency-Key を生成し、リクエストと一緒に保存します。同じ Key と同じ本文の再送は元のタスクを返し、二重課金されません。リクエストを変更した場合は新しい Key を使います。
失敗タスクが返金対象の場合、Imya はクレジットを一度だけ返し、元の有効期限を維持します。公開 status は failed のままで、決済処理中は error.code が refund_pending、返金完了後は credits_refunded が応答に含まれます。id で照合し、クライアント側でクレジットを発行しないでください。
認証情報、所有権、生成メディアを保護する
API キーはサーバーに保存し、ブラウザーやモバイルバンドルに埋め込まないでください。返された各 id を作成者の認証済みユーザーまたはワークスペースに関連付け、結果を表示する前に確認します。公開エラーはサニタイズされています。サポート用に独自のリクエスト ID とタスク id を記録し、プロンプト、非公開 URL、認証情報は露出しないでください。
画像結果は無料アカウントで 7 日間、有効な有料プランまたは Lifetime アカウントで最長 30 日間利用できます。削除後は応答の status が failed、error.code が media_deleted になります。製品で保存が必要な結果は、ユーザーの同意と自社のプライバシーポリシーに従って、自社管理のストレージに複製してください。
本番環境チェックリスト
- 送信前にモデル固有のフィールドを検証する。
- 意図したタスクごとに Idempotency-Key とリクエスト本文を保存する。
- タスク状態を永続化し、5 秒以上の間隔でポーリングする。
- アカウントの同時実行数と API キーのレート制限を実施する。
- 4 種類の公開 status を明示的に処理する。failed では error.code の media_deleted または refund_pending を確認し、credits_refunded で返金完了を確認する。
- 認証情報をサーバー側に保ち、結果の保存ポリシーを定義する。
よくある質問
ワーカーはどのくらいの間隔でポーリングすべきですか？
5 秒以上の間隔にします。処理中のタスクには、バックオフを伴うより遅いポーリングも適切です。
クレジットはいつ差し引かれますか？
新しいタスクが受理された時点で、credits_reserved の正確な額がアトミックに差し引かれます。
再試行で二重課金されますか？
同じ Idempotency-Key と完全に同じリクエスト本文の再送は、元のタスクを返し、再課金されません。
タスクが最終的に失敗したらどうしますか？
明確な製品向けエラーを表示し、サポート用に id を保持し、対象となる 1 回限りの返金はサーバーに完了させます。存在しない refunded status を待たず、credits_refunded で結果を確認します。
実装前にモデルを試しますか？
GPT Image 2のオンライン生成ツールを開き、コードを書かずにプロンプトと出力設定を比較できます。
GPT Image 2をオンラインで試す