RequestBeam

文档目录

RequestBeam 文档

GPT-Image-2 图像生成

使用 gpt-image-2 生成图片或根据参考图编辑图片，并通过当前 JSON 响应或 SSE 连接获取结果。

POSThttps://api.requestbeam.com/openai/v1/images/generations

gpt-image-2 是图片生成与参考图编辑模型，适合产品图、海报草图、插画、社交媒体素材、高分辨率视觉资产生成，以及基于一张或多张参考图的风格转换和融合编辑。

text
POST https://api.requestbeam.com/openai/v1/images/generations

验证

http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

快速开始

json
{
  "model": "gpt-image-2",
  "prompt": "一张极简黑色无线耳机产品海报，白色背景，干净棚拍光线，无文字",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}

Body

modelstring必填默认: gpt-image-2

图片模型 ID。固定填写 gpt-image-2。

promptstring必填

图片生成提示词。

建议写清楚主体、场景、构图、风格、材质、光线、颜色和是否包含文字。

ninteger默认: 1

生成图片张数。当前 gpt-image-2 公开合同只支持 1。

sizestring默认: auto

输出图片比例或像素尺寸。

常用值：

  • 1:1
  • 4:3
  • 16:9
  • 9:16
  • 1024x1024
  • 1536x1024
  • 1024x1536
  • 2048x2048
  • 2048x1152
  • 3840x2160
  • 2160x3840
  • auto
qualitystring默认: auto

输出质量。

可选值：

  • low
  • medium
  • high
  • auto
resolutionstring默认: 1k

输出分辨率档位。可选值为 1k、2k 和 4k。

可与 size 组合使用，例如 size: "16:9"、resolution: "2k"。

image_urlsarray<string>

参考图数组。传入后按提示词对参考图进行编辑或多图融合。

  • 最多 16 张。
  • 单张图片最大 20 MB，全部参考图合计最大 256 MB。
  • 支持公网可访问的图片 URL。
  • 支持 data:image/...;base64,... 格式的 base64 data URI。
  • 同一数组可以混合 URL 和 base64 data URI。
output_formatstring默认: png

输出格式。

可选值：

  • png
  • jpeg
  • webp
streamboolean默认: false

是否使用 SSE 流式响应。

参考图与图片编辑

参考图编辑复用同一个 JSON 接口，不需要切换 endpoint。请求中加入 image_urls，并在 prompt 中描述需要保留和修改的内容：

json
{
  "model": "gpt-image-2",
  "prompt": "保留产品主体，把背景改成深蓝色摄影棚，并增加柔和轮廓光",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}

多张参考图可以用于主体、构图或风格融合：

json
{
  "model": "gpt-image-2",
  "prompt": "使用第一张图的产品和第二张图的构图，生成一张干净的电商主图",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}

当前公开合同的边界：

  • 支持通过 image_urls 进行整图编辑、风格转换和多参考图融合。
  • 不提供独立的 POST https://api.requestbeam.com/openai/v1/images/edits 路由。
  • 不接收 multipart/form-data 文件上传；本地图片需要先转换为 base64 data URI，或上传为可访问 URL。
  • 不支持局部遮罩重绘。发送 mask、mask_url 或 maskUrl 会在预扣前返回 400；n 不为 1 时也会在预扣前拒绝。

请求示例

1:1 产品图

json
{
  "model": "gpt-image-2",
  "prompt": "一只透明玻璃水杯放在浅灰背景上，商业产品摄影，柔和阴影，无文字",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}

16:9 横版海报

json
{
  "model": "gpt-image-2",
  "prompt": "未来城市夜景海报，霓虹灯、雨后街道、电影感构图，无文字",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}

结果获取方式

此 OpenAI-compatible 接口不会先返回包含 data.jobId 的任务提交响应，让客户端 转为异步轮询：

  • stream: false 时，当前 HTTP 请求会等待生成完成，并在 JSON 响应中返回图片 URL。
  • stream: true 时，当前 SSE 连接会持续到 image_generation.completed 和

[DONE]。

因此不要使用 GET https://api.requestbeam.com/v1/jobs/{id} 查询本接口的结果。只有当某个异步创建接口明确 返回 jobId 时，才按照查询异步任务继续查询。

非流式响应

非流式响应返回图片 URL；上游提供计量信息时还会包含 usage。

json
{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}

流式响应

流式响应使用 SSE。最终事件返回图片 URL，随后结束。

text
event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]

尺寸速查

目标比例1K 推荐值2K 推荐值4K 推荐值
1:11024x10242048x2048不建议
3:21536x10242048x1360不建议
2:31024x15361360x2048不建议
4:31024x7682048x1536不建议
3:4768x10241536x2048不建议
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

错误响应

完整错误码、协议差异和排查步骤见错误码与错误处理。

错误响应使用平台统一格式。

json
{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}

常见错误：

  • 400：缺少必填参数或参数组合不支持。
  • 401：认证失败或 API Key 不正确。
  • 402：余额不足。
  • 404：模型不存在或暂未开放。
  • 429：请求频率超过限制。
  • 5xx：服务暂时不可用或图片生成失败。