跳转到主要内容
POST
cURL
POST /v1/images/generations 文生图接口使用 application/json 请求体。你提交文本提示词后,接口会同步等待生成完成,并在同一个响应的 data[0].b64_json 中返回图片内容。
使用 https://www.bettertoken.ai/v1 作为 Base URL。调用时通过 Authorization: Bearer YOUR_API_KEY 传入 BetterToken API Key。
你可以在页面右侧的 Playground 填写 Authorization 和请求体,直接在线调试。请求会发往 https://www.bettertoken.ai/v1/images/generations
不要把 API Key 放进前端浏览器代码,也不要提交到 Git 仓库、工单、截图或日志里。服务端代理调用时,应只在服务端环境变量或密钥管理系统里保存 API Key。

推荐请求值

所有文生图请求建议显式传入这些字段:
多张图片建议由客户端或服务端任务队列发起多次独立请求。不要依赖单次请求 n > 1

推荐尺寸

size 表示期望的图片比例和尺寸档位。实际返回图片像素可能由服务端映射或调整。客户端不应把返回图片强行裁切到请求值,建议以解码后的真实图片尺寸为准。

保存返回图片

成功响应为 OpenAI 兼容图片响应结构:
客户端应读取 data[0].b64_json 并将其作为 base64 图片内容保存。响应中可能出现额外字段,例如 revised_prompt,客户端应允许这些字段存在。 建议所有请求都显式指定 output_format: "png"。这样保存为 .png 即可,不需要再解析文件头判断格式。
不要依赖 output_format: "jpeg"output_format: "webp" 直接获得 JPEG 或 WebP 文件。当前接口实测可能仍返回 PNG 图片内容。如果业务需要 JPEG 或 WebP,建议先按 PNG 接收,再由业务代码自行转换格式。

响应流程

文生图接口是同步响应模式。客户端提交 POST /images/generations 后,应保持当前 HTTP 请求连接并等待服务端返回。生成成功时,图片内容会直接出现在同一个响应的 data[0].b64_json 字段中。 文生图不会返回 task_id,也没有单独的状态查询接口或结果下载接口。不需要轮询任务状态,也不能通过额外的 /images/... URL 再获取结果。

超时和重试

  • HTTP 客户端超时建议设置为数分钟级别。
  • 对传输层异常、4084094254295xx 可以重试。
  • 400401、参数缺失、格式错误不要自动重试。
  • 重试时使用指数退避,例如等待 3s8s15s
  • 如果业务不能接受重复图片,应用层应记录自己的请求 ID,避免用户重复提交。

错误处理

错误响应通常是 JSON。展示错误时,建议按顺序读取:
  1. error.message
  2. message
  3. HTTP status text

接入检查清单

  • Base URL 是 https://www.bettertoken.ai/v1
  • Header 包含 Authorization: Bearer sk-...
  • 请求使用 application/json
  • 模型固定为 gpt-image-2
  • response_format 固定为 b64_json
  • output_format 固定为 png
  • n 固定为 1
  • size 使用推荐尺寸之一。
  • 客户端能处理数分钟级别的生成耗时。
  • 日志和报错截图中不会泄露 API Key 或完整 base64 图片内容。

相关文档

授权

Authorization
string
header
必填

Use your BetterToken API Key as a bearer token. Do not expose API keys in frontend browser code, screenshots, logs, tickets, or Git repositories.

请求体

application/json
model
enum<string>
默认值:gpt-image-2
必填

固定使用 gpt-image-2。

可用选项:
gpt-image-2
示例:

"gpt-image-2"

prompt
string
必填

图片生成提示词。

示例:

"一张未来感 AI 产品海报,浅色背景,玻璃质感,干净构图,高级科技感"

n
integer
默认值:1

推荐固定为 1。多张图片建议发起多次独立请求。

必填范围: 1 <= x <= 1
示例:

1

size
enum<string>
默认值:1024x1024

图片尺寸和比例档位。auto 为自动;1024x1024 和 2048x2048 为 1:1;1536x1024 为 3:2;1024x1536 为 2:3;1536x1152 为 4:3;1152x1536 为 3:4;2048x1152 和 3840x2160 为 16:9;2160x3840 为 9:16。实际返回像素可能由服务端映射或调整,客户端应以解码后的真实图片尺寸为准。

可用选项:
auto,
1024x1024,
1536x1024,
1024x1536,
1536x1152,
1152x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
示例:

"1024x1024"

response_format
enum<string>
默认值:b64_json

推荐固定为 b64_json,便于稳定保存图片。

可用选项:
b64_json
示例:

"b64_json"

output_format
enum<string>
默认值:png

推荐固定为 png。不要依赖 jpeg 或 webp 直接返回对应格式。

可用选项:
png
示例:

"png"

响应

Image generation result.

OpenAI-compatible image response. Clients should read data[0].b64_json and allow additional fields such as revised_prompt.

created
integer
示例:

1710000000

data
object[]