主题
语言

图像生成（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图像描述。
nnumber仅限 1 个：每次生成都是一个独立任务，并有各自的价格。如需生成多张图像，请发送多个请求。
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 报价中的价格相同。生成失败时会返回 502，并显示“Nothing was charged”，不会产生任何费用。扣除的金额会在 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。它的工作方式与上面的生成相同：响应、等待时间、x-pv-media-job-id 以及与带源图像的 POST /api/media/generate 相同的价格都不变；编辑失败不会收费。模型的编辑模式从目录中选取。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 字段中被接受，并会解析为同一个公共模型。它不会发布在发现列表或定价信息中。

← 上一页视觉（聊天中的图像）下一页 →视频生成迁移
GetVibe API 图像生成 — OpenAI 兼容的 Images API | GetVibe API