Skip to main content
POST
cURL
POST /v1/images/generations text-to-image endpoint는 application/json request body를 사용합니다. prompt를 제출하고 HTTP request를 열어 둔 뒤 같은 response의 data[0].b64_json에서 생성된 이미지를 읽으세요.
https://www.bettertoken.ai/v1Base URL로 사용하세요. Authorization: Bearer YOUR_API_KEY를 통해 BetterToken API Key를 전달하세요.
페이지 오른쪽의 Playground에서 Authorization 및 request body를 입력한 다음 https://www.bettertoken.ai/v1/images/generations로 request를 직접 보낼 수 있습니다.
API keys를 frontend browser code, Git repositories, tickets, screenshots 또는 logs에 넣지 마세요. server-side proxy calls에서는 API keys를 server environment variables 또는 secret manager에만 저장하세요.

curl 빠른 시작

https://www.bettertoken.ai/v1을 Base URL로 사용하고 https://www.bettertoken.ai/v1/images/generations로 request를 보내세요.

권장 값

모든 request에서 다음 fields를 명시적으로 보내세요.
여러 independent requests를 보내 여러 images를 생성하세요. n > 1인 단일 request에 의존하지 마세요.

권장 sizes

size는 예상 aspect ratio와 size tier를 나타냅니다. 실제 반환 pixels는 server에 의해 mapping 또는 adjusted될 수 있습니다. output을 요청한 값으로 강제로 crop하지 말고 decoded image dimensions를 사용하세요.

이미지 저장

성공한 response는 다음 OpenAI-compatible image response shape를 따릅니다.
data[0].b64_json을 읽어 base64 image content로 저장하세요. response에는 revised_prompt 등의 extra fields가 포함될 수 있으므로 client에서 이 fields를 허용하세요. 항상 output_format: "png"를 설정하세요. 그런 다음 file headers를 검사하지 않고 decoded image를 .png로 저장하세요.

JavaScript 예시(Node.js)

JPEG 또는 WebP files를 직접 받기 위해 output_format: "jpeg" 또는 output_format: "webp"에 의존하지 마세요. 현재 endpoint는 여전히 PNG image content를 반환할 수 있습니다. product에 JPEG 또는 WebP가 필요하면 먼저 PNG를 받은 후 자체 code에서 변환하세요.

Response flow

이 endpoint는 synchronous입니다. POST /images/generations를 보낸 후 server가 response할 때까지 현재 HTTP request를 열어 두세요. generation에 성공하면 image content가 data[0].b64_json으로 반환됩니다. endpoint는 task_id를 반환하지 않으며 별도의 status query 또는 result download endpoint가 없습니다.

Timeouts 및 retries

  • HTTP client timeouts를 몇 분으로 설정하세요.
  • transport errors, 408, 409, 425, 4295xx는 retry하세요.
  • 400, 401, missing parameters 또는 malformed requests는 자동 retry하지 마세요.
  • 3s, 8s, 15s 등의 exponential backoff를 사용하세요.
  • duplicate images를 허용할 수 없다면 retry하기 전에 자체 request ID를 기록하세요.

Error handling

errors는 일반적으로 JSON을 반환합니다. error를 표시할 때는 error.message를 먼저 읽고 message, HTTP status text 순서로 읽으세요.

Integration checklist

  • Base URL은 https://www.bettertoken.ai/v1입니다.
  • header에는 Authorization: Bearer YOUR_API_KEY가 포함됩니다.
  • request는 application/jsonPOST /images/generations를 사용합니다.
  • modelgpt-image-2, response_formatb64_json, output_formatpng, n1입니다.
  • size1024x1024 등의 권장 값 중 하나입니다.
  • HTTP client가 generation에 몇 분을 허용합니다.

관련 문서

인증

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>
기본값:YOUR_MODEL_ID
필수

固定使用 YOUR_MODEL_ID。

사용 가능한 옵션:
YOUR_MODEL_ID
예시:

"YOUR_MODEL_ID"

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[]