テーマ
言語

画像生成（OpenAI Images API）

OpenAI Images API 形式での同期画像生成です。パラメーター、最大 300 秒の待機、完成した画像に対する請求のみ、Cherry Studio の設定について説明します。編集は非同期の /api/media/generate を経由します。

POST /v1/images/generations は OpenAI Images API 形式で画像を生成します。リクエストを送信すると、同じレスポンスで画像が返されます。これは POST /api/media/generate と同じキュー上のアダプターです。モデル、価格、残高チェック、サプライヤーのフェイルオーバー、請求が共有されるため、同じ生成であればどちらのアドレスでも料金は同じです。

POSThttps://getvibeapi.com/v1/images/generations
curl https://getvibeapi.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"a red bicycle on a bridge","n":1,"size":"1024x1024"}'

レスポンス（HTTP 200）：

{
  "created": 1792706400,
  "data": [{ "url": "https://getvibeapi.com/media/r/…/0.png" }]
}

キーは Authorization: Bearer sk-pv-… または x-api-key として渡します。公式 OpenAI SDK はそのまま動作します。

from openai import OpenAI

client = OpenAI(base_url="https://getvibeapi.com/v1", api_key="sk-pv-...", timeout=600)
image = client.images.generate(model="nano-banana", prompt="a red bicycle on a bridge", size="1024x1024")
print(image.data[0].url)

ボディパラメータ

パラメータータイプ説明
modelreq.string/api/media-catalog の画像モデル ID（kind: "image"）です。例：nano-banana、gpt-image-2、flux-2。ベンダー接頭辞付き ID（google/nano-banana）と固定バリアント（gpt-image-2:network）も受け付けられます。動画モデルと音声モデルはここでは 400 で拒否されます。
promptreq.string画像の説明です。
nnumber1 件のみです。各生成は、それぞれ固有の価格を持つ別個のジョブになります。複数の画像を生成する場合は、複数のリクエストを送信してください。
sizestringアスペクト比として処理されます：1024x1024 → 1:1、1792x1024 → 16:9、1024x1792 → 9:16、1536x1024 → 3:2、1024x1536 → 2:3。その他の値も正確に縮約されます（1920x1080 → 16:9）。モデルが提供していない比率は、対応サイズの一覧とともに拒否されます。最も近い値への置き換えはありません。"auto" またはフィールドなしの場合は、モデルのデフォルトになります。
qualitystringカタログで quality パラメーターが指定されているモデルに限ります。対応していない値は拒否されます。"auto" の場合は省略されます。
response_format"url" | "b64_json"デフォルトでは url です。b64_json はファイルをレスポンス本文で返します（最大 20 MB）。
userstring受け付けられますが、無視されます。

未知のフィールド、および background、style、output_format、output_compression、moderation、stream、partial_images は、暗黙的に削除されるのではなく、名前に基づいて 400 で拒否されます。そうでなければ、要求していない画像の料金を支払うことになるためです。元画像が必要なモデル（編集、アップスケーリング、インペインティング）は、ここでは画像を渡す方法がないため動作しません。POST /api/media/generate を使用してください。

待機とタイムアウト

ジョブが完了するまで、最大 300 秒間リクエストを保持します。所要時間の中央値はモデルによって 15～85 秒です。最も遅いモデルでは、個々の生成に 3～4 分かかります。クライアントのタイムアウトを少なくとも 300 秒に設定してください（OpenAI SDK のデフォルトは 600 です）。

  • ジョブの作成後に発生したエラーを含め、すべてのレスポンスにジョブ ID を示す x-pv-media-job-id ヘッダーが含まれます。
  • ジョブが 300 秒以内に完了しなかった場合、504 と cause: image_generation_timeout が返され、メッセージにジョブ ID が含まれます。生成は継続して実行されるため、GET /api/media/jobs/{id} から取得してください。
  • 接続が切断された場合（アプリのタイムアウト、ネットワーク障害）でも、ジョブは完了まで処理されます。GET /v1/images/generations?limit=20（最大 100）には、このキーの最近の画像と、そのステータス、リンク、請求額 cost_rub が一覧表示されます。

請求

送信時には請求されません。正常に完了した生成にのみ、/api/media-catalog および POST /api/media/price の見積もりと同じ価格で請求されます。生成に失敗した場合は、"Nothing was charged" と記載された 502 が返され、料金は発生しません。請求額は x-pv-cost-rub ヘッダーで返されます。残高で生成料金をまかなえない場合は、ジョブが開始される前に 402 が返されます。

data[].url 内のリンクは当社ドメインを指しており、生成完了後 7 日間有効です。その後は 410 media_result_expired になります。ファイルはご自身の環境に保存してください。

エラー

パラメータータイプ説明
400invalid_request_errorInvalid body: unknown_parameter, unsupported_parameter, unsupported_n, unsupported_size, unsupported_quality, unsupported_model_kind. Fix the request.
401 / 403authentication_error / permission_errorキーが無効であるか、呼び出し元の IP がキーの許可リストに登録されていません。
402insufficient_quotaこの生成に必要な残高が不足しています。ジョブは作成されませんでした。
404not_found_errormodel_not_found — そのような画像モデルはありません。/api/media-catalog を参照してください。
429rate_limit_errorメディアのレート制限です。Retry-After の後に再試行してください。
502upstream_error生成に失敗しました。料金は発生していないため、再試行できます。
503upstream_error現在、すべてのサプライヤーでモデルを利用できません。ジョブは作成されていないため、後でもう一度試すか、別のモデルを選択してください。
504upstream_errorimage_generation_timeout — ジョブはまだ実行中です。x-pv-media-job-id の ID を使用して取得してください。

デスクトップアプリ（Cherry Studio など）

OpenAI 互換プロバイダーを通じて画像を生成できるアプリであれば動作します。ここでは Cherry Studio を例に説明します。

  1. タイプ OpenAI のプロバイダーを、API アドレス https://getvibeapi.com（アプリが /v1 自体を追加します）と、ご自身の sk-pv-… キーで追加します。
  2. https://getvibeapi.com/api/media-catalog の ID（kind: "image" のエントリのみ）を使ってモデルを手動で追加します。例：nano-banana または gpt-image-2。アプリのモデル一覧にはテキストモデルが表示されます。メディアモデルは一覧にありません。
  3. 通常のチャットではなく、アプリのペイント／画像生成機能から生成してください。チャットはリクエストを /v1/chat/completions に送信しますが、そこでは画像モデルは動作しません。
  4. アプリでリクエストタイムアウトを設定できる場合は、少なくとも 300 秒に設定してください。アプリが途中で諦めた画像は GET /v1/images/generations に一覧表示されます。アプリから再試行すると、新しい生成が作成され、別途請求されます。

このようなアプリでアップロードした画像を編集するモードは/v1/images/editsと呼ばれ、こちらでも提供されています（以下をご覧ください）。

Editing: /v1/images/edits

POST /v1/images/editsはOpenAI SDKのリクエスト（multipart/form-data：image内のファイル、またはimage[]内の複数のファイルで、prompt、model、size、quality、response_formatを含むもの）またはimages: [{"image_url": "…"}]を含むJSONを受け取ります。上記の生成と同様に機能し、ソース画像がある場合のPOST /api/media/generateと同じレスポンス、同じ待機時間、同じx-pv-media-job-id、同じ料金になります。編集に失敗した場合は課金されません。モデルの編集モードはカタログから選択されます。maskは400 unsupported_parameterで拒否され、ソース画像を受け取らないモデルの場合はmodel_cannot_editで拒否されます。マスク編集を行うにはPOST /api/media/generateを使用してGET /api/media/jobs/{id}をポーリングしてください — 非同期生成ガイドをご覧ください。動画は同期的には生成されません。/v1/video/generationsと/v1/videosも410を返します（詳細）。

Nano Banana ProのID

カタログおよび新しいコードでは nano-banana-pro を使用してください。既存の非同期クライアントを移行する場合、値 gemini-3-pro-image は /api/media/generate リクエストの model フィールドでのみ引き続き受け入れられ、同じ公開モデルに解決されます。これはディスカバリや料金には公開されません。

← 前へVision（チャット内の画像）次へ →動画生成の移行
GetVibe API の画像生成 — OpenAI 互換 Images API | GetVibe API