> ## 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.
# OpenAI 互換画像生成 API：GPT Image 2 ガイド
> GPT Image 2 と BetterToken の OpenAI 互換 API を使用してテキストから画像を生成します。API Key、Base URL、パラメーター、Python、JavaScript、エラーを説明します。
`POST /v1/images/generations`
テキストから画像を生成する Endpoint では、`application/json` のリクエスト本文を使用します。プロンプトを送信し、HTTP リクエストを開いたままにして、同じレスポンスの `data[0].b64_json` から生成画像を読み取ります。
`https://www.bettertoken.ai/v1` を `Base URL` として使用します。BetterToken API Key は `Authorization: Bearer YOUR_API_KEY` で渡します。
ページ右側の Playground で `Authorization` とリクエスト本文を入力し、`https://www.bettertoken.ai/v1/images/generations` へ直接リクエストを送信できます。
API Key をフロントエンドのブラウザーコード、Git リポジトリ、チケット、スクリーンショット、ログに含めないでください。サーバー側のプロキシ呼び出しでは、API Key はサーバーの環境変数またはシークレットマネージャーにのみ保存してください。
## curl でのクイックスタート
Base URL として `https://www.bettertoken.ai/v1` を使用し、`https://www.bettertoken.ai/v1/images/generations` にリクエストを送信します。
```bash theme={null}
curl -X POST "https://www.bettertoken.ai/v1/images/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A product photo of a green ceramic mug on a studio table",
"size": "1024x1024",
"n": 1,
"response_format": "b64_json",
"output_format": "png"
}'
```
## 推奨値
すべてのリクエストで、次のフィールドを明示的に送信してください。
```json theme={null}
{
"model": "gpt-image-2",
"n": 1,
"response_format": "b64_json",
"output_format": "png"
}
```
| パラメーター | 送信する値 | 用途 |
| ----------------- | ------------- | ----------------------------------------- |
| `model` | `gpt-image-2` | 画像モデルを選択します。 |
| `prompt` | テキストによる説明 | 必須の画像説明です。被写体、スタイル、構図、重要な制約を含めます。 |
| `size` | 例：`1024x1024` | 出力サイズとアスペクト比を選択します。 |
| `n` | `1` | 1 リクエストで生成する画像数です。複数画像には個別のリクエストを送信します。 |
| `response_format` | `b64_json` | `data[0].b64_json` に base64 形式で画像内容を返します。 |
| `output_format` | `png` | 結果を PNG として保存できます。 |
複数の画像を生成する場合は、複数の独立したリクエストを送信してください。`n > 1` を指定した 1 回のリクエストに依存しないでください。
## 推奨サイズ
| `size` | 比率 | 用途 |
| ----------- | ------ | ------------------------- |
| `auto` | 自動 | サイズを自動選択 |
| `1024x1024` | `1:1` | 正方形の画像、アバター、カバー、アセット |
| `1536x1024` | `3:2` | 横長のポスター、バナー、シーン |
| `1024x1536` | `2:3` | 縦長のモバイルカバーとポスター |
| `1536x1152` | `4:3` | 標準的な横長画像、商品画像、コンテンツグラフィック |
| `1152x1536` | `3:4` | 標準的な縦長画像、モバイルカバー、縦長ポスター |
| `2048x2048` | `1:1` | 高解像度の正方形画像 |
| `2048x1152` | `16:9` | 高解像度の横長画像 |
| `3840x2160` | `16:9` | 4K 横長画像 |
| `2160x3840` | `9:16` | 4K 縦長画像 |
`size` は想定するアスペクト比とサイズ区分を表します。実際に返されるピクセルはサーバーでマッピングまたは調整される場合があります。出力を要求値に無理に切り抜くのではなく、デコードした画像の寸法を使用してください。
## 画像を保存する
成功時のレスポンスは、次の OpenAI 互換画像レスポンス形式に従います。
```json theme={null}
{
"created": 1710000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
}
]
}
```
`data[0].b64_json` を読み取り、base64 の画像内容として保存します。レスポンスには `revised_prompt` などの追加フィールドが含まれる場合があるため、クライアントでこれらのフィールドを許可してください。
常に `output_format: "png"` を設定してください。その後、ファイルヘッダーを確認せずに、デコードした画像を `.png` として保存します。
```python theme={null}
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)
```
### JavaScript の例（Node.js）
```js theme={null}
import { writeFile } from "node:fs/promises";
const response = await fetch("https://www.bettertoken.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2",
prompt: "A green ceramic mug on a studio table",
size: "1024x1024",
n: 1,
response_format: "b64_json",
output_format: "png",
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const { data } = await response.json();
const b64Json = data[0].b64_json.replace(/^data:.*;base64,/, "");
await writeFile("output.png", Buffer.from(b64Json, "base64"));
```
`output_format: "jpeg"` または `output_format: "webp"` を指定して、JPEG または WebP ファイルを直接受け取れることに依存しないでください。現在の Endpoint は PNG の画像内容を返す場合があります。プロダクトで JPEG または WebP が必要な場合は、まず PNG を受け取り、自身のコードで変換してください。
## レスポンスの流れ
この Endpoint は同期式です。`POST /images/generations` を送信した後、サーバーが応答するまで現在の HTTP リクエストを開いたままにしてください。生成に成功すると、画像内容が `data[0].b64_json` に返されます。
この Endpoint は `task_id` を返さず、個別のステータス照会や結果ダウンロード用の Endpoint もありません。
## タイムアウトと再試行
* HTTP クライアントのタイムアウトは数分に設定します。
* 通信エラー、`408`、`409`、`425`、`429`、`5xx` は再試行します。
* `400`、`401`、パラメーター不足、形式不正のリクエストは自動再試行しないでください。
* `3s`、`8s`、`15s` などの指数バックオフを使用します。
* 重複画像を許容できない場合は、再試行前に独自のリクエスト ID を記録します。
## エラー処理
エラーは通常 JSON で返されます。エラーを表示する場合は、まず `error.message`、次に `message`、最後に HTTP ステータステキストを読み取ります。
| HTTP ステータス | 意味 | 対処方法 |
| ---------- | ----------------------------- | ------------------------------------------------ |
| `400` | JSON の形式不正、パラメーター不足、または未対応サイズ | リクエスト本文を確認します。自動再試行しないでください。 |
| `401` | API Key がない、または無効 | `Authorization: Bearer YOUR_API_KEY` ヘッダーを確認します。 |
| `402` | 残高またはクォータが不足 | 残高を追加するか、利用可能なキーを使用します。 |
| `429` | レート制限、同時実行数制限、または上流の混雑 | 待機して指数バックオフで再試行します。 |
| `5xx` | ゲートウェイまたは上流の障害 | リクエストを再試行します。失敗が続く場合は、リクエスト ID とエラーメッセージを記録します。 |
## 統合チェックリスト
* Base URL は `https://www.bettertoken.ai/v1` です。
* ヘッダーには `Authorization: Bearer YOUR_API_KEY` を含めます。
* リクエストでは `application/json` と `POST /images/generations` を使用します。
* `model` は `gpt-image-2`、`response_format` は `b64_json`、`output_format` は `png`、`n` は `1` です。
* `size` には `1024x1024` などの推奨値を指定します。
* HTTP クライアントで生成用に数分を許容します。
## 関連ドキュメント
* [画像から画像への変換](/ja/api-reference/images-edits)
* [GPT Image 2 が利用可能になりました](/ja/model-updates/gpt-image-2)
## OpenAPI
````yaml api-reference/openapi.json POST /v1/images/generations
openapi: 3.1.0
info:
title: BetterToken GPT Image 2 API
description: >-
OpenAI-compatible image generation and image editing endpoints for
BetterToken.
version: 1.0.0
servers:
- url: https://www.bettertoken.ai
security:
- bearerAuth: []
paths:
/v1/images/generations:
post:
tags:
- GPT Image 2
summary: 文生图（图片生成）
description: >-
使用 GPT Image 2 根据文本提示词生成图片。请求使用 application/json，成功响应中的图片内容位于
data[0].b64_json。
operationId: createImageGeneration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextToImageRequest'
example:
model: YOUR_MODEL_ID
prompt: 一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感
'n': 1
size: 1024x1024
response_format: b64_json
output_format: png
responses:
'200':
$ref: '#/components/responses/ImageResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl 'https://www.bettertoken.ai/v1/images/generations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"model": "YOUR_MODEL_ID",
"prompt": "一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感",
"n": 1,
"size": "1024x1024",
"response_format": "b64_json",
"output_format": "png"
}'
components:
schemas:
TextToImageRequest:
type: object
required:
- model
- prompt
properties:
model:
type: string
description: 固定使用 YOUR_MODEL_ID。
enum:
- YOUR_MODEL_ID
default: YOUR_MODEL_ID
example: YOUR_MODEL_ID
prompt:
type: string
description: 图片生成提示词。
example: 一张未来感 AI 产品海报，浅色背景，玻璃质感，干净构图，高级科技感
'n':
type: integer
description: 推荐固定为 1。多张图片建议发起多次独立请求。
minimum: 1
maximum: 1
default: 1
example: 1
size:
$ref: '#/components/schemas/ImageSize'
response_format:
type: string
description: 推荐固定为 b64_json，便于稳定保存图片。
enum:
- b64_json
default: b64_json
example: b64_json
output_format:
type: string
description: 推荐固定为 png。不要依赖 jpeg 或 webp 直接返回对应格式。
enum:
- png
default: png
example: png
additionalProperties: false
ImageSize:
type: string
description: >-
图片尺寸和比例档位。auto 为自动；1024x1024 和 2048x2048 为 1:1；1536x1024 为 3:2；1024x1536
为 2:3；1536x1152 为 4:3；1152x1536 为 3:4；2048x1152 和 3840x2160 为
16:9；2160x3840 为 9:16。实际返回像素可能由服务端映射或调整，客户端应以解码后的真实图片尺寸为准。
enum:
- auto
- 1024x1024
- 1536x1024
- 1024x1536
- 1536x1152
- 1152x1536
- 2048x2048
- 2048x1152
- 3840x2160
- 2160x3840
default: 1024x1024
example: 1024x1024
ImageResponse:
type: object
description: >-
OpenAI-compatible image response. Clients should read data[0].b64_json
and allow additional fields such as revised_prompt.
properties:
created:
type: integer
example: 1710000000
data:
type: array
items:
type: object
properties:
b64_json:
type: string
description: Base64-encoded image content.
example: iVBORw0KGgoAAAANSUhEUgAA...(truncated)
revised_prompt:
type: string
description: Optional revised prompt.
additionalProperties: true
additionalProperties: true
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: invalid request
type:
type: string
example: invalid_request_error
code:
type: string
example: invalid_request
additionalProperties: true
message:
type: string
example: insufficient quota
additionalProperties: true
responses:
ImageResponse:
description: Image generation result.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageResponse'
example:
created: 1710000000
data:
- b64_json: iVBORw0KGgoAAAANSUhEUgAA...(truncated)
BadRequest:
description: 请求格式错误、缺少参数、JSON 或 multipart 解析失败、尺寸格式错误。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: API Key 缺失或无效。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: 额度或余额不足。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: 触发限速、并发限制或上游繁忙。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServerError:
description: 网关或上游服务异常。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: BetterToken API Key
description: >-
Use your BetterToken API Key as a bearer token. Do not expose API keys
in frontend browser code, screenshots, logs, tickets, or Git
repositories.
````