跳转到主要内容
POST
/
v1
/
images
/
generations
cURL
curl 'https://www.bettertoken.ai/v1/images/generations' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png"
  }'
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt

Use this file to discover all available pages before exploring further.

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。

​
推荐请求值

所有文生图请求建议显式传入这些字段： 
{
  "model": "gpt-image-2",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
多张图片建议由客户端或服务端任务队列发起多次独立请求。不要依赖单次请求 n > 1。

​
推荐尺寸

size比例适用场景
auto自动自动选择尺寸
1024x10241:1方图，通用头像、封面、素材图
1536x10243:2横图，海报、banner、场景图
1024x15362:3竖图，移动端封面、人物海报
2048x20481:1高清方图
2048x115216:9高清横图
3840x216016:94K 横图
2160x38409:164K 竖图
size 表示期望的图片比例和尺寸档位。实际返回图片像素可能由服务端映射或调整。客户端不应把返回图片强行裁切到请求值，建议以解码后的真实图片尺寸为准。

​
保存返回图片

成功响应为 OpenAI 兼容图片响应结构： 
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}
客户端应读取 data[0].b64_json 并将其作为 base64 图片内容保存。响应中可能出现额外字段，例如 revised_prompt，客户端应允许这些字段存在。 建议所有请求都显式指定 output_format: "png"。这样保存为 .png 即可，不需要再解析文件头判断格式。 
import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8"))
b64_json = response["data"][0]["b64_json"]

if "," in b64_json and "base64" in b64_json.split(",", 1)[0]:
    b64_json = b64_json.split(",", 1)[1]

image_bytes = base64.b64decode(b64_json)
Path("output.png").write_bytes(image_bytes)
不要依赖 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 客户端超时建议设置为数分钟级别。
  • 对传输层异常、408、409、425、429 和 5xx 可以重试。
  • 对 400、401、参数缺失、格式错误不要自动重试。
  • 重试时使用指数退避，例如等待 3s、8s、15s。
  • 如果业务不能接受重复图片，应用层应记录自己的请求 ID，避免用户重复提交。

​
错误处理

错误响应通常是 JSON。展示错误时，建议按顺序读取：
  1. error.message
  2. message
  3. HTTP status text
HTTP 状态码含义建议处理
400请求格式错误、缺少参数、JSON 解析失败、尺寸格式错误检查请求体，不要自动重试。
401API Key 缺失或无效检查 Authorization header。
402额度或余额不足提示用户充值或更换可用 key。
429触发限速、并发限制或上游繁忙等待后重试，建议指数退避。
5xx网关或上游服务异常可重试，仍失败时记录 request id 和错误信息。

​
接入检查清单

  • 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；2048x1152 和 3840x2160 为 16:9；2160x3840 为 9:16。实际返回像素可能由服务端映射或调整，客户端应以解码后的真实图片尺寸为准。

可用选项:
auto,
1024x1024,
1536x1024,
1024x1536,
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[]