Skip to main content
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 The text-to-image endpoint uses an application/json request body. Submit a prompt, keep the HTTP request open, and read the generated image from data[0].b64_json in the same response.
Use https://www.bettertoken.ai/v1 as the Base URL. Pass your BetterToken API Key through Authorization: Bearer YOUR_API_KEY.
You can enter Authorization and the request body in the Playground on the right side of the page, then send the request directly to https://www.bettertoken.ai/v1/images/generations.
Do not put API keys in frontend browser code, Git repositories, tickets, screenshots, or logs. For server-side proxy calls, store API keys only in server environment variables or a secret manager.
Send these fields explicitly in every request: 
{
  "model": "gpt-image-2",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
Generate multiple images by sending multiple independent requests. Do not rely on a single request with n > 1.
sizeRatioUse case
autoAutoAutomatic size selection
1024x10241:1Square images, avatars, covers, assets
1536x10243:2Landscape posters, banners, scenes
1024x15362:3Portrait mobile covers and posters
2048x20481:1High-resolution square images
2048x115216:9High-resolution landscape images
3840x216016:94K landscape images
2160x38409:164K portrait images
size represents the expected aspect ratio and size tier. The actual returned pixels may be mapped or adjusted by the server. Use the decoded image dimensions instead of forcibly cropping the output to the requested value.

​
Save the image

A successful response follows the OpenAI-compatible image response shape: 
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}
Read data[0].b64_json and save it as base64 image content. The response may include extra fields such as revised_prompt; allow these fields in your client. Always set output_format: "png". Then save the decoded image as .png without inspecting file headers. 
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)
Do not rely on output_format: "jpeg" or output_format: "webp" to directly receive JPEG or WebP files. The current endpoint may still return PNG image content. If your product needs JPEG or WebP, receive PNG first and convert it in your own code.

​
Response flow

This endpoint is synchronous. After sending POST /images/generations, keep the current HTTP request open until the server responds. When generation succeeds, the image content is returned in data[0].b64_json. The endpoint does not return a task_id, and there is no separate status query or result download endpoint.

​
Timeouts and retries

  • Set HTTP client timeouts to several minutes.
  • Retry transport errors, 408, 409, 425, 429, and 5xx.
  • Do not retry 400, 401, missing parameters, or malformed requests automatically.
  • Use exponential backoff such as 3s, 8s, and 15s.
  • If duplicate images are unacceptable, record your own request ID before retrying.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
model
enum<string>
default:gpt-image-2
required

固定使用 gpt-image-2。

Available options:
gpt-image-2
Example:

"gpt-image-2"

​
prompt
string
required

图片生成提示词。

Example:

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

​
n
integer
default:1

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

Required range: 1 <= x <= 1
Example:

1

​
size
enum<string>
default:1024x1024

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

Available options:
auto,
1024x1024,
1536x1024,
1024x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Example:

"1024x1024"

​
response_format
enum<string>
default:b64_json

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

Available options:
b64_json
Example:

"b64_json"

​
output_format
enum<string>
default:png

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

Available options:
png
Example:

"png"

Response

Image generation result.

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

​
created
integer
Example:

1710000000

​
data
object[]