Documentation Index
Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
Use this file to discover all available pages before exploring further.
O OpenAI Images Generations API atualmente suporta vários modelos de geração de imagens, incluindo o clássico dall-e-3, o gpt-image-1 com capacidade aprimorada de renderização de texto, a mais recente geração gpt-image-2, bem como a série de modelos nano-banana / nano-banana-2 / nano-banana-pro acessados pela mesma interface. Todos eles podem gerar imagens de alta qualidade a partir de descrições textuais.
Este documento apresenta principalmente o fluxo de uso da API OpenAI Images Generations, que permite utilizar facilmente as funcionalidades de geração de imagens da série OpenAI.
Processo de Solicitação
Para usar o OpenAI Images Generations API, primeiro acesse a página OpenAI Images Generations API e clique no botão “Acquire” para obter as credenciais necessárias para as requisições:
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login para se registrar e entrar. Após o login, você será redirecionado automaticamente para esta página.
Na primeira solicitação, um crédito gratuito será concedido para uso da API.
Modelo GPT-Image-2
gpt-image-2 é o novo modelo de geração de imagens lançado pela OpenAI, que apresenta melhorias significativas em relação ao dall-e-3 e gpt-image-1 nos seguintes aspectos:
- Maior capacidade de seguir instruções: pode compreender com precisão instruções estruturadas complexas, como composição, contagem e relações de posição.
- Renderização de texto mais clara: em cenários como pôsteres, menus, infográficos e logotipos, textos em inglês e números quase não apresentam erros.
- Expressão de estilo mais rica: suporta nativamente vários estilos, como retratos cinematográficos, pôsteres vintage, ilustrações infantis, fotografia de produtos e infográficos.
- Suporte nativo a múltiplas proporções + alta resolução: cobre 5 proporções (1:1, 4:3, 3:4, 16:9, 9:16) em 3 níveis de resolução (1K / 2K / 4K).
A chamada é idêntica a outros modelos, basta definir o campo model como gpt-image-2. O campo url no resultado é um link permanente hospedado em platform.cdn.xhuoapi.ai, que pode ser aberto diretamente no navegador ou incorporado em páginas web.
Valores suportados para size e níveis de cobrança
gpt-image-2 apenas verifica o formato de size; desde que não seja auto ou vazio, deve corresponder ao formato WIDTHxHEIGHT (por exemplo, 1024x1024, 2048x1152, 800x600); qualquer outro formato retornará 400. A cobrança possui apenas dois níveis:
- Preço padrão 1K: entrada em qualquer tamanho recomendado 1K da tabela abaixo ou apelidos comuns 1K do upstream (
1254x1254, 1672x941, 941x1672 — estes são tamanhos reais retornados pelo upstream no nível 1K e, se reutilizados como size, não alteram o preço).
- Outros níveis (1.5×): qualquer tamanho fora do conjunto 1K acima, incluindo os presets 2K / 4K da tabela e quaisquer
WIDTHxHEIGHT personalizados.
Restrições rígidas do upstream para tamanhos personalizados: largura e altura devem ser múltiplos de 16, lado maior ≤ 3840, total de pixels ≤ 8.294.400. Tamanhos fora desse intervalo serão rejeitados com erro 4xx.
| Proporção | 1K (Preço padrão) | 2K recomendado (×1.5) | 4K recomendado (×1.5) |
|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1536x1024 | 2048x1536 | 3264x2448 |
| 3:4 | 1024x1536 | 1536x2048 | 2448x3264 |
| 16:9 | 1792x1024 | 2048x1152 | 3840x2160 |
| 9:16 | 1024x1792 | 1152x2048 | 2160x3840 |
Você também pode passar size: "auto" ou omitir o campo size, neste caso o modelo escolherá o tamanho padrão, cobrando pelo preço padrão 1K.
No nível 1K, o upstream não garante alinhamento exato de pixels — se você passar 1024x1024, pode receber 1254x1254, mantendo a proporção. Se reutilizar este valor como size, ainda será cobrado como 1K.
Chamadas 4K geralmente levam 4–8 minutos; recomenda-se usar o mecanismo de callback assíncrono callback_url descrito adiante.
Sobre o parâmetro n
gpt-image-2 atualmente não suporta n > 1: este parâmetro será silenciosamente ignorado; independentemente de passar n=1 ou n=10, cada requisição retorna apenas 1 imagem e cobra por 1 imagem. Se precisar de múltiplas imagens candidatas, faça múltiplas requisições concorrentes (recomenda-se variar prompt ou seed para evitar imagens muito semelhantes). Essa restrição também se aplica a gpt-image-1 / gpt-image-1.5 e à série nano-banana. O dall-e-2 é o único modelo que suporta nativamente n > 1; dall-e-3 suporta apenas n = 1.
A seguir, alguns exemplos reais para demonstrar as capacidades do gpt-image-2.
Cenário 1: Retrato cinematográfico
No prompt, podem ser usados termos cinematográficos (filme 35mm, profundidade de campo rasa, luzes neon etc.) para controlar atmosfera e textura com precisão.
Exemplo em Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "gpt-image-2",
"prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
"size": "1024x1536"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"success": true,
"task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3",
"created": 1777048800,
"data": [
{
"revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
"url": "https://platform.cdn.xhuoapi.ai/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
}
]
}
Imagem gerada:

Cenário 2: Pôster de viagem vintage (com renderização de texto)
gpt-image-2 apresenta estabilidade na tipografia e layout, ideal para pôsteres, menus, cartões com texto.
payload = {
"model": "gpt-image-2",
"prompt": "A vintage travel poster of the Amalfi Coast, Italy. Stylized art-deco illustration of cliffside lemon-yellow houses cascading down to a turquoise sea, with a small white sailboat in the harbor. Bold typography at the top reads AMALFI and at the bottom ITALIA 1958. Limited color palette: cream, sea-blue, lemon yellow, terracotta. Slight paper-grain texture.",
"size": "1024x1536"
}
Imagem gerada:

O modelo reproduz fielmente o estilo Art Deco, com os textos AMALFI e ITALIA 1958 claros e corretos.
Cenário 3: Composição complexa e contagem
Este prompt testa a capacidade do modelo de seguir instruções estruturadas sobre quantidade e posição.
payload = {
"model": "gpt-image-2",
"prompt": "A wooden bookshelf consisting of three shelves: On the top shelf, there should be one book. On the second shelf, there should be three books. On the bottom shelf, there should be seven books. Soft warm lighting, photorealistic, cozy library atmosphere.",
"size": "1024x1024"
}
Imagem gerada:

A quantidade de livros (1 / 3 / 7) está exatamente conforme o prompt, algo difícil de conseguir de forma estável na era do dall-e-3.
Cenário 4: Estilo ilustração (paisagem)
Especificando mídia artística e palavras-chave de emoção, o modelo gera ilustrações estilizadas.
payload = {
"model": "gpt-image-2",
"prompt": "A soft, poetic children's book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.",
"size": "1536x1024"
}
Imagem gerada:
Assíncrono e Callback
Chamadas ao gpt-image-2 normalmente levam 60–90 segundos. Para evitar conexões longas, pode-se usar o mecanismo de callback assíncrono callback_url, com fluxo idêntico a outros modelos.
Série Nano Banana
A série nano-banana é baseada no modelo Gemini e integrada pela mesma interface /openai/images/generations, sem necessidade de trocar endpoint; basta alterar o campo model para qualquer um da tabela abaixo.
| Modelo | Cobrança (Créditos / chamada) | Cenário de uso |
|---|
nano-banana | 0.14 | Geração comum, mais rápida e barata |
nano-banana-2 | 0.28 | Qualidade e detalhes significativamente melhores |
nano-banana-pro | 0.35 | Top da linha, melhor composição, detalhes e texto |
Importante: parâmetros suportados
Nano Banana adapta o protocolo OpenAI, mas suporta apenas os parâmetros: model, prompt, size.
size é mapeado para aspect_ratio interno conforme tabela abaixo; tamanhos não listados são convertidos para 1:1:
1024x1024 / 512x512 / 256x256 → 1:1
1792x1024 → 16:9
1024x1792 → 9:16
- Não suporta
n, quality, style, response_format, background, output_format; se passados, são ignorados.
- A resposta segue o formato OpenAI (
data[].url), mas created é sempre 0, não retorna b64_json, e revised_prompt é igual ao prompt original.
Chamada básica
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "nano-banana",
"prompt": "a small red apple on a white table, photoreal",
"size": "1024x1024"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
"revised_prompt": "a small red apple on a white table, photoreal"
}
]
}
Imagem gerada:

Upgrade para modelo topo de linha nano-banana-pro
Basta alterar model para nano-banana-pro, mantendo os demais parâmetros:
payload = {
"model": "nano-banana-pro",
"prompt": "abstract painting",
"size": "1024x1024"
}
Resposta:
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.xhuoapi.ai/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
"revised_prompt": "abstract painting"
}
]
}

Callback assíncrono
O mecanismo callback_url funciona igualmente para nano-banana, com fluxo idêntico a outros modelos, conforme seção Callback assíncrono.
Uso básico
Você pode preencher os campos na interface conforme mostrado:

Na primeira vez, é necessário preencher pelo menos três campos: authorization (selecionado no dropdown), model (modelo OpenAI DALL-E a ser usado; há 1 modelo principal disponível), e prompt (texto para gerar a imagem).
À direita, o código de chamada correspondente é gerado, que pode ser copiado e executado, ou você pode clicar em “Try” para testar diretamente.

Exemplo Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 1721626477,
"data": [
{
"revised_prompt": "A delightful image showcasing a young sea otter, who is born brown, with wide charming eyes. It is delightfully lying on its back, paddling in the calm sea waters. Its dense, velvety fur appears wet and shimmering, capturing the essence of its habitat. The small creature curiously plays with a sea shell with its small paws, looking absolutely innocent and charming in its natural environment.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Campos retornados:
created: ID único da tarefa de geração.
data: contém informações do resultado da imagem.
O campo data[].url é o link para a imagem gerada, que pode ser visualizado como mostrado:

Parâmetro de qualidade da imagem quality
Você pode configurar parâmetros detalhados da geração, como a qualidade da imagem. O parâmetro quality tem dois valores: standard para imagens padrão e hd para imagens com detalhes mais finos e maior consistência.
Exemplo definindo quality como standard:

O código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"quality": "standard"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 1721636023,
"data": [
{
"revised_prompt": "A cute baby sea otter is lying playfully on its back in the water, with its fur looking glossy and soft. One of its tiny paws is reaching out curiously, and it has an expression of pure joy and warmth on its face as it looks up to the sky. Its body is surrounded by bubbles from its playful twirling in the water. A gentle breeze is playing with its fur making it look more charming. The scene portrays the tranquility and charm of marine life.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Imagem gerada com quality = standard:

Alterando apenas para quality = hd, obtém-se a imagem abaixo:

hd apresenta detalhes mais finos e maior consistência.
Parâmetro de tamanho da imagem size
Também é possível configurar o tamanho da imagem gerada.
Exemplo definindo tamanho 1024x1024:

O código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"size": "1024x1024"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 1721636652,
"data": [
{
"revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Imagem gerada com tamanho 1024x1024:

Alterando para tamanho 1792x1024:
O tamanho da imagem é visivelmente diferente. Mais tamanhos estão disponíveis na documentação oficial.
Parâmetro de estilo da imagem style
O parâmetro style possui dois valores: vivid para imagens mais vivas e natural para imagens mais naturais.
Exemplo definindo style como vivid:

Código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"style": "vivid"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 1721637086,
"data": [
{
"revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Imagem gerada com style = vivid:

Alterando para style = natural:

vivid gera imagens mais vivas e realistas.
O parâmetro response_format tem dois valores: b64_json para codificação Base64 do link da imagem, e url para link direto da imagem.
Exemplo definindo response_format como url:

Código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"response_format": "url"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta:
{
"created": 1721637575,
"data": [
{
"revised_prompt": "A charming depiction of a baby sea otter. The otter is seen resting serenely on its back amidst the gentle, blue ocean waves. The baby otter's fur is an endearing mix of soft greyish brown shades, glinting subtly in the muted sunlight. Its small paws are touching, lifted slightly towards the sky as if playing with an unseen object. Its round, expressive eyes are wide in curiosity, sparking with life and innocence. Use a realistic style to evoke the otter's natural habitat and its adorably fluffy exterior.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Link da imagem gerada: Imagem URL, acessível diretamente:

Alterando para response_format = b64_json, obtém-se a imagem codificada em Base64:
{
"created": 1721638071,
"data": [
{
"b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==",
"revised_prompt": "A charming image of a young baby sea otter. The otter is gently floating on a calm blue sea, basking in the warm, golden rays of sunlight streaming down from a clear sky above. The otter's fur is a rich chocolate brown, and it looks incredibly soft and fluffy. The otter's eyes are bright and expressive, filled with childlike curiosity and joy. It has small, pricked ears and a button-like nose which adds to its overall cuteness. In the sea around it, twinkling droplets of water can be seen, pepped up by the sunlight, the sight is certainly a delightful one."
}
]
}
Callback assíncrono
Como a geração de imagens pode levar tempo, a API suporta callback assíncrono para evitar conexões HTTP longas e consumo excessivo de recursos.
O fluxo é: o cliente envia a requisição com o campo adicional callback_url. A API retorna imediatamente um resultado contendo task_id. Quando a tarefa é concluída, o resultado da geração é enviado via POST JSON para o callback_url informado, incluindo o task_id para associação.
Exemplo prático:
O Webhook é um serviço HTTP que recebe requisições; o desenvolvedor deve substituir pela URL do seu servidor HTTP. Para demonstração, usamos o site público https://webhook.site/, que gera uma URL de webhook, como mostrado:
Copie esta URL, por exemplo https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Configure o campo callback_url com esta URL e preencha os demais parâmetros:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Resposta imediata:
{
"task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Após alguns instantes, no Webhook você verá o resultado da geração:
{
"success": true,
"task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
"trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
"data": {
"created": 1721626477,
"data": [
{
"revised_prompt": "A delightful image showcasing a young sea otter...",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/..."
}
]
}
}
O campo task_id permite associar o resultado à requisição original.
Tratamento de erros
Se ocorrer erro na chamada da API, serão retornados códigos e mensagens correspondentes, por exemplo:
400 token_mismatched: requisição inválida, possivelmente parâmetros ausentes ou incorretos.
400 api_not_implemented: requisição inválida, possivelmente parâmetros ausentes ou incorretos.
401 invalid_token: não autorizado, token inválido ou ausente.
429 too_many_requests: muitas requisições, limite de taxa excedido.
500 api_error: erro interno do servidor.
Exemplo de resposta de erro
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
Conclusão
Este documento apresentou como usar o OpenAI Images Generations API para acessar facilmente as funcionalidades oficiais de geração de imagens do OpenAI DALL-E. Esperamos que este guia ajude você a integrar e utilizar a API com sucesso. Para dúvidas, entre em contato com nossa equipe de suporte técnico.