> ## Documentation Index
> Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Images Generations API Solicitação e Uso

> OpenAI generation 集成指南 - Ace Data Cloud

A 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 de renderização de texto mais avançada, 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 OpenAI Images Generations API, que permite utilizar facilmente as funcionalidades de geração de imagens da série OpenAI.

## Processo de Solicitação

Para usar a OpenAI Images Generations API, primeiro acesse a página [OpenAI Images Generations API](https://platform.acedata.cloud/documents/openai-images-generations) e clique no botão "Acquire" para obter as credenciais necessárias para as requisições:

![](https://cdn.acedata.cloud/nyq0xz.png)

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 isso, retornará automaticamente à página atual.

Na primeira solicitação, será concedida uma cota gratuita para uso da API.

## Modelo GPT-Image-2

`gpt-image-2` é o modelo de geração de imagens de nova geração lançado pela OpenAI, que apresenta melhorias significativas em relação ao `dall-e-3` e `gpt-image-1` nos seguintes aspectos:

* **Melhor capacidade de seguir instruções**: consegue entender 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 logos, os 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) com 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.acedata.cloud`, que pode ser aberto diretamente no navegador ou incorporado em páginas web.

### Valores suportados para `size`

`gpt-image-2` apenas verifica o formato de `size`; desde que não seja `auto` ou uma string vazia, deve corresponder ao formato `WIDTHxHEIGHT` (por exemplo, `1024x1024`, `2048x1152`, `800x600`); qualquer outro formato retornará 400. **Todas as dimensões (1K / 2K / 4K / personalizadas) são cobradas por imagem, sem acréscimo por tamanho.**

Restrições rígidas do backend para tamanhos personalizados: largura e altura devem ser múltiplos de 16, lado maior ≤ 3840, total de pixels ≤ 8.294.400. Valores fora desse intervalo serão rejeitados pelo backend com resposta 4xx.

| Proporção | Recomendado 1K | Recomendado 2K | Recomendado 4K |
| --------- | -------------- | -------------- | -------------- |
| 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`**, e o modelo escolherá o tamanho padrão automaticamente.
>
> No nível 1K, o backend não garante alinhamento exato de pixels — por exemplo, ao passar `1024x1024`, pode receber `1254x1254`, mantendo a proporção. Se você reutilizar essa dimensão como `size`, a cobrança permanece a mesma.
>
> Chamadas 4K geralmente levam 4–8 minutos, recomendando-se o uso do `callback_url` para retorno assíncrono.

> **Sobre o parâmetro `n`**
>
> Atualmente, `gpt-image-2` **não suporta `n > 1`**: esse parâmetro será silenciosamente ignorado, e independentemente de passar `n=1` ou `n=10`, cada requisição retornará apenas 1 imagem, cobrando por 1 imagem. Para obter múltiplas imagens candidatas, faça múltiplas requisições concorrentes (recomendado usar `prompt` ou `seed` diferentes para evitar imagens muito similares). Essa limitação também se aplica a `gpt-image-1` / `gpt-image-1.5` e à série `nano-banana`. O único modelo que suporta nativamente `n > 1` é o `dall-e-2`; `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, você pode usar termos cinematográficos (filme 35mm, profundidade de campo rasa, luzes neon etc.) para controlar atmosfera e textura com precisão.

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
    }
  ]
}
```

Imagem gerada:

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png" width="500" className="m-auto" />
</p>

### 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.

```python theme={null}
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:

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/c6061f92-3fae-498e-af8e-688e7f415ba3_0.png" width="500" className="m-auto" />
</p>

O modelo reproduz fielmente o estilo Art Deco e renderiza claramente os textos `AMALFI` e `ITALIA 1958`.

### 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.

```python theme={null}
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:

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/64a3b932-a082-4cad-9f85-9d30474b104d_0.png" width="500" className="m-auto" />
</p>

A quantidade de livros (1 / 3 / 7) está exatamente conforme o prompt, algo difícil de alcançar 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.

```python theme={null}
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 (paisagem):

![](https://platform.cdn.acedata.cloud/gpt-image/6cd57e69-d237-4cc1-a666-759a93964a08_0.png)

### Assíncrono e Callback

Chamadas ao `gpt-image-2` geralmente levam 60–90 segundos. Caso não queira manter conexão longa, pode 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 está integrada na mesma interface `/openai/images/generations`, sem necessidade de trocar endpoint; basta alterar o campo `model` para qualquer um da tabela abaixo.

| Modelo            | Custo (Créditos / chamada) | Cenário de uso                                     |
| ----------------- | -------------------------- | -------------------------------------------------- |
| `nano-banana`     | 0.14                       | Geração comum, mais rápido e barato                |
| `nano-banana-2`   | 0.28                       | Qualidade e detalhes significativamente melhores   |
| `nano-banana-pro` | 0.35                       | Topo da linha, melhor composição, detalhes e texto |

> **Importante: Escopo de parâmetros suportados**
>
> Nano Banana usa uma camada adaptadora para o protocolo OpenAI e suporta apenas os parâmetros: `model`, `prompt`, `size`.
>
> * `size` é mapeado para `aspect_ratio` interno conforme tabela; tamanhos não listados caem 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 enviados, são ignorados.
> * Retorno segue formato OpenAI (`data[].url`), mas `created` é sempre `0`, não retorna `b64_json`, e `revised_prompt` é igual ao prompt original.

### Chamada básica

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
      "revised_prompt": "a small red apple on a white table, photoreal"
    }
  ]
}
```

Imagem gerada pode ser acessada diretamente pelo campo `url`:

<p>
  <img src="https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" width="500" className="m-auto" />
</p>

### Upgrade para modelo topo de linha `nano-banana-pro`

Basta alterar `model` para `nano-banana-pro`, demais parâmetros permanecem iguais:

```python theme={null}
payload = {
    "model": "nano-banana-pro",
    "prompt": "abstract painting",
    "size": "1024x1024"
}
```

Exemplo de retorno:

```json theme={null}
{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
      "revised_prompt": "abstract painting"
    }
  ]
}
```

<p>
  <img src="https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png" width="500" className="m-auto" />
</p>

### Callback assíncrono

O mecanismo `callback_url` funciona igualmente para nano-banana, com fluxo idêntico a outros modelos, veja seção [Callback assíncrono](#callback-assíncrono).

## Uso Básico

Agora você pode preencher os campos correspondentes na interface, conforme a imagem:

<p>
  <img src="https://cdn.acedata.cloud/zv58ug.png" width="500" className="m-auto" />
</p>

Na primeira vez usando a API, é necessário preencher pelo menos três campos: `authorization`, que pode ser selecionado na lista suspensa; `model`, que define o modelo OpenAI DALL-E a ser usado (temos 1 modelo principal, consulte a lista de modelos); e `prompt`, que é o texto para geração da imagem.

À direita, há o código gerado para a chamada, que pode ser copiado e executado diretamente ou testado clicando em "Try".

<p>
  <img src="https://cdn.acedata.cloud/pbss4f.png" width="500" className="m-auto" />
</p>

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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 as informações da imagem gerada, incluindo o link em `url`.

Imagem exibida:

<p>
  <img src="https://cdn.acedata.cloud/dz7u0x.png" width="500" className="m-auto" />
</p>

## Parâmetro de qualidade da imagem `quality`

Você pode definir parâmetros detalhados para a geração, como a qualidade da imagem: `standard` gera imagens padrão, enquanto `hd` cria imagens com detalhes mais finos e maior consistência.

Exemplo definindo `quality` como `standard`:

<p>
  <img src="https://cdn.acedata.cloud/1q303w.png" width="500" className="m-auto" />
</p>

Código gerado à direita pode ser copiado ou testado clicando em "Try".

<p>
  <img src="https://cdn.acedata.cloud/c0ps6i.png" width="500" className="m-auto" />
</p>

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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 qualidade `standard`:

<p>
  <img src="https://cdn.acedata.cloud/j5v15b.png" width="500" className="m-auto" />
</p>

Alterando para `hd`, obtém-se imagem com detalhes mais finos e maior consistência:

<p>
  <img src="https://cdn.acedata.cloud/vjpbqr.png" width="500" className="m-auto" />
</p>

## Parâmetro de tamanho da imagem `size`

Você pode definir o tamanho da imagem gerada.

Exemplo definindo tamanho `1024x1024`:

<p>
  <img src="https://cdn.acedata.cloud/dx5rwh.png" width="500" className="m-auto" />
</p>

Código gerado pode ser copiado ou testado:

<p>
  <img src="https://cdn.acedata.cloud/0sbybl.png" width="500" className="m-auto" />
</p>

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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`:

<p>
  <img src="https://cdn.acedata.cloud/o4pvvx.png" width="500" className="m-auto" />
</p>

Alterando para `1792x1024`:

![](https://cdn.acedata.cloud/4pilae.png)

O tamanho da imagem é claramente diferente. Mais tamanhos estão disponíveis, consulte a documentação oficial.

## Parâmetro de estilo da imagem `style`

O parâmetro `style` tem duas opções: `vivid` para imagens mais vívidas e `natural` para imagens mais naturais.

Exemplo definindo `style` como `vivid`:

<p>
  <img src="https://cdn.acedata.cloud/609l9i.png" width="500" className="m-auto" />
</p>

Código gerado pode ser copiado ou testado:

<p>
  <img src="https://cdn.acedata.cloud/ee3u9o.png" width="500" className="m-auto" />
</p>

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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`:

<p>
  <img src="https://cdn.acedata.cloud/e0rpc3.png" width="500" className="m-auto" />
</p>

Alterando para `natural`:

<p>
  <img src="https://cdn.acedata.cloud/q9tqwu.png" width="500" className="m-auto" />
</p>

`vivid` gera imagens mais vivas e realistas que `natural`.

## Parâmetro de formato do link da imagem `response_format`

O parâmetro `response_format` tem duas opções: `b64_json` codifica a imagem em Base64, e `url` retorna o link direto da imagem.

Exemplo definindo `response_format` como `url`:

<p>
  <img src="https://cdn.acedata.cloud/2zbgrg.png" width="500" className="m-auto" />
</p>

Código gerado pode ser copiado ou testado:

<p>
  <img src="https://cdn.acedata.cloud/a9exmp.png" width="500" className="m-auto" />
</p>

Exemplo em Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "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 (`url`) pode ser acessado diretamente: [Imagem 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)

Imagem:

<p>
  <img src="https://cdn.acedata.cloud/33hs4z.png" width="500" className="m-auto" />
</p>

Alterando para `b64_json`, o resultado é a imagem codificada em Base64:

```json theme={null}
{
  "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 que consomem recursos.

O fluxo é: o cliente envia a requisição com o campo `callback_url`; a API responde imediatamente com um `task_id` identificando a tarefa; quando a geração termina, o resultado é enviado via POST JSON para o `callback_url` especificado, incluindo o `task_id` para associação.

Exemplo prático:

Para demonstração, use um serviço público de webhook como [https://webhook.site/](https://webhook.site/) para obter uma URL de webhook, por exemplo:

![](https://cdn.acedata.cloud/cjjfly.png)

Copie a URL, por exemplo `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`.

Configure o campo `callback_url` com essa URL e envie a requisição:

```python theme={null}
import requests

url = "https://api.acedata.cloud/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:

```json theme={null}
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
```

Após alguns instantes, no webhook você verá o resultado da geração:

```json theme={null}
{
  "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 a resposta à requisição original.

## Tratamento de Erros

Se ocorrer erro na chamada, a API retorna código e mensagem de erro, por exemplo:

* `400 token_mismatched`: Requisição inválida, parâmetros faltando ou incorretos.
* `400 api_not_implemented`: Requisição inválida, parâmetros faltando 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 no servidor.

### Exemplo de resposta de erro

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusão

Este documento apresentou como usar a OpenAI Images Generations API para acessar facilmente as funcionalidades oficiais de geração de imagens do OpenAI DALL-E. Esperamos que ajude você a integrar e utilizar a API com sucesso. Em caso de dúvidas, entre em contato com nossa equipe de suporte técnico.
