Skip to main content
POST
cURL
POST /v1/images/generations O endpoint de texto para imagem usa um corpo de solicitação application/json. Envie um prompt, mantenha a solicitação HTTP aberta e leia a imagem gerada em data[0].b64_json na mesma resposta.
Use https://www.bettertoken.ai/v1 como Base URL. Passe sua BetterToken API Key por Authorization: Bearer YOUR_API_KEY.
Você pode informar Authorization e o corpo da solicitação no Playground à direita da página e enviar a solicitação diretamente para https://www.bettertoken.ai/v1/images/generations.
Não coloque API Keys no código de frontend do navegador, em repositórios Git, tickets, capturas de tela ou logs. Para chamadas por proxy no servidor, armazene API Keys somente em variáveis de ambiente do servidor ou em um gerenciador de segredos.

Início rápido com curl

Use https://www.bettertoken.ai/v1 como Base URL e envie uma solicitação para https://www.bettertoken.ai/v1/images/generations:

Valores recomendados

Envie estes campos explicitamente em cada solicitação:
Gere várias imagens enviando várias solicitações independentes. Não dependa de uma única solicitação com n > 1.

Tamanhos recomendados

size representa a proporção e a faixa de tamanho esperadas. Os pixels retornados podem ser mapeados ou ajustados pelo servidor. Use as dimensões da imagem decodificada em vez de recortar à força a saída para o valor solicitado.

Salve a imagem

Uma resposta bem-sucedida segue o formato de resposta de imagem compatível com OpenAI:
Leia data[0].b64_json e salve-o como conteúdo de imagem base64. A resposta pode incluir campos extras, como revised_prompt; permita esses campos no cliente. Defina sempre output_format: "png". Depois salve a imagem decodificada como .png, sem inspecionar cabeçalhos de arquivo.

Exemplo JavaScript (Node.js)

Não dependa de output_format: "jpeg" ou output_format: "webp" para receber diretamente arquivos JPEG ou WebP. O endpoint atual ainda pode retornar conteúdo de imagem PNG. Se seu produto precisar de JPEG ou WebP, receba PNG primeiro e converta-o no seu código.

Fluxo de resposta

Este endpoint é síncrono. Depois de enviar POST /images/generations, mantenha a solicitação HTTP atual aberta até o servidor responder. Quando a geração é bem-sucedida, o conteúdo da imagem é retornado em data[0].b64_json. O endpoint não retorna task_id, e não há endpoint separado para consulta de status ou download do resultado.

Timeouts e novas tentativas

  • Defina timeouts do cliente HTTP para vários minutos.
  • Tente novamente erros de transporte, 408, 409, 425, 429 e 5xx.
  • Não tente novamente automaticamente 400, 401, parâmetros ausentes ou solicitações malformadas.
  • Use backoff exponencial, como 3s, 8s e 15s.
  • Se imagens duplicadas forem inaceitáveis, registre seu próprio ID de solicitação antes de tentar novamente.

Tratamento de erros

Os erros geralmente retornam JSON. Ao mostrar um erro, leia primeiro error.message, depois message e, por fim, o texto de status HTTP.

Checklist de integração

  • A Base URL é https://www.bettertoken.ai/v1.
  • O cabeçalho contém Authorization: Bearer YOUR_API_KEY.
  • A solicitação usa application/json e POST /images/generations.
  • model é gpt-image-2, response_format é b64_json, output_format é png e n é 1.
  • size é um dos valores recomendados, como 1024x1024.
  • Seu cliente HTTP permite vários minutos para a geração.

Documentação relacionada

Autorizações

Authorization
string
header
obrigatório

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

Corpo

application/json
model
enum<string>
padrão:YOUR_MODEL_ID
obrigatório

固定使用 YOUR_MODEL_ID。

Opções disponíveis:
YOUR_MODEL_ID
Exemplo:

"YOUR_MODEL_ID"

prompt
string
obrigatório

图片生成提示词。

Exemplo:

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

n
integer
padrão:1

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

Intervalo obrigatório: 1 <= x <= 1
Exemplo:

1

size
enum<string>
padrão: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。实际返回像素可能由服务端映射或调整,客户端应以解码后的真实图片尺寸为准。

Opções disponíveis:
auto,
1024x1024,
1536x1024,
1024x1536,
1536x1152,
1152x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Exemplo:

"1024x1024"

response_format
enum<string>
padrão:b64_json

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

Opções disponíveis:
b64_json
Exemplo:

"b64_json"

output_format
enum<string>
padrão:png

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

Opções disponíveis:
png
Exemplo:

"png"

Resposta

Image generation result.

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

created
integer
Exemplo:

1710000000

data
object[]