> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Generations API Solicitação e Uso > OpenAI generation API guide - Ace Data Cloud OpenAI Images Generations API atualmente suporta vários modelos de geração de imagens, incluindo o clássico `dall-e-3`, a capacidade de renderização de texto mais forte `gpt-image-1`, a mais recente geração de **`gpt-image-2`**, e a série de modelos **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`** que são acessíveis através da mesma interface. Todos eles podem gerar imagens de alta qualidade com base em descrições de texto. Este documento apresenta principalmente o fluxo de uso da API OpenAI Images Generations, permitindo que utilizemos facilmente as funcionalidades de geração de imagens da série OpenAI. ## Fluxo de Solicitação Para usar a OpenAI Images Generations API, primeiro acesse o [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será retornado automaticamente à página atual. **Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço.** A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin). > 📘 Documentação completa: [OpenAI Images Generations API →](https://platform.acedata.cloud/documents/openai-images-generations) ## Modelo GPT-Image-2 `gpt-image-2` é o novo modelo de geração de imagens lançado pela OpenAI, que apresenta melhorias significativas em comparação com `dall-e-3` e `gpt-image-1` nas seguintes áreas: * **Capacidade de seguir instruções mais forte**: capaz de entender com precisão instruções estruturadas complexas sobre composição, contagem, relações de posição, etc. * **Renderização de texto mais clara**: em cenários como pôsteres, menus, infográficos, logotipos, o inglês e os números quase não apresentam confusão. * **Expressão de estilo mais rica**: suporte nativo a vários estilos, como retratos cinematográficos, pôsteres vintage, ilustrações infantis, fotografia de produtos, infográficos, entre outros. * **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 forma de chamada é idêntica à de outros modelos, basta definir o campo `model` como `gpt-image-2`. O `url` no resultado retornado é um link de imagem hospedado permanentemente em `platform.cdn.acedata.cloud`, que pode ser aberto diretamente no navegador ou incorporado em uma página da web. ### Rota de Transmissão Oficial / Variante Reversa (`:official` / `:reverse`) `gpt-image-2` utiliza a rota reversa por padrão. Através do sufixo do nome do modelo, é possível escolher explicitamente a rota: * **`gpt-image-2:official`**: rota de transmissão oficial. Suporta `n > 1` (retorno de várias imagens de uma vez) e resoluções reais de 2K / 4K, **cobrando por imagem, com um preço que é o dobro do preço padrão de `gpt-image-2`**. Atualmente, é fornecido apenas pelo canal openai-hk; se a rota não estiver disponível, retornará um erro diretamente, sem rebaixar para a rota reversa. * **`gpt-image-2:reverse`**: completamente equivalente ao `gpt-image-2` padrão (rota reversa), usado para declarar explicitamente que a rota reversa deve ser utilizada, sem alteração de preço. > A limitação "sobre o parâmetro `n`" abaixo se aplica apenas à rota padrão / reversa; `gpt-image-2:official` suporta `n > 1` e cobra por imagem. ### 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 a `LARGURAxALTURA` (por exemplo, `1024x1024`, `2048x1152`, `800x600`); qualquer outra forma retornará 400. **Todos os tamanhos (1K / 2K / 4K / personalizado) são cobrados uniformemente por imagem, sem aumento de preço por tamanho.** Restrições rígidas para tamanhos personalizados: largura e altura devem ser múltiplos de 16, lado longo ≤ 3840, total de pixels ≤ 8.294.400. Exceder esses limites resultará em rejeição e retorno de 4xx. | Proporção | 1K Recomendado | 2K Recomendado | 4K Recomendado | | --------- | -------------- | -------------- | -------------- | | 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. > Na faixa de 1K, a saída do upstream não garante alinhamento de pixels rigoroso — você pode passar `1024x1024` e receber `1254x1254`, mantendo a proporção. Se você passar isso novamente como `size`, a cobrança não muda. > Chamadas únicas de 4K geralmente levam de 4 a 8 minutos, recomenda-se usar em conjunto com o `callback_url` para callbacks assíncronos. > **Sobre o parâmetro `n`** > `gpt-image-2` atualmente **não suporta `n > 1`**: esse parâmetro será ignorado silenciosamente, independentemente de você passar `n=1` ou `n=10`, uma única solicitação retornará apenas 1 imagem e será cobrada apenas por 1 imagem. Se você precisar obter várias imagens candidatas de uma vez, por favor **inicie várias solicitações em paralelo** (recomenda-se passar diferentes `prompt` ou diferentes `seed`, caso contrário, as imagens obtidas podem ser altamente semelhantes). Essa limitação também se aplica a `gpt-image-1` / `gpt-image-1.5`, bem como à série `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`. `dall-e-2` é atualmente o único modelo que suporta nativamente `n > 1`; `dall-e-3` suporta apenas `n = 1`. Abaixo, apresentamos alguns exemplos reais de diferentes ângulos para sentir intuitivamente a capacidade do `gpt-image-2`. ### Cenário 1: Retrato Cinemático Palavras-chave podem usar termos cinematográficos (filme de 35mm, profundidade de campo rasa, luz de néon, etc.) para controlar com precisão a atmosfera e a textura. Código de exemplo de chamada 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": "Um retrato cinematográfico de uma jovem mulher em pé em uma loja de conveniência à noite, iluminada por suaves sinais de néon rosa e ciano através da janela. Filmado em filme de 35mm, profundidade de campo rasa, leve granulação, humor melancólico.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` O resultado retornado é o seguinte: ```json theme={null} { "success": true, "task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3", "created": 1777048800, "data": [ { "revised_prompt": "Um retrato cinematográfico de uma jovem mulher em pé em uma loja de conveniência à noite, iluminada por suaves sinais de néon rosa e ciano através da janela. Filmado em filme de 35mm, profundidade de campo rasa, leve granulação, humor melancólico.", "url": "https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png" } ] } ``` A imagem gerada é a seguinte:

### Cena Dois: Pôster de Viagem Vintage (com Renderização de Texto) `gpt-image-2` se destaca na tipografia e renderização de fontes, sendo muito adequado para gerar pôsteres, menus, cartões comemorativos e outros designs com texto. ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "Um pôster de viagem vintage da Costa Amalfitana, Itália. Ilustração estilizada em art-deco de casas amarelo-limão à beira do penhasco descendo para um mar turquesa, com um pequeno veleiro branco no porto. Tipografia ousada na parte superior lê AMALFI e na parte inferior ITALIA 1958. Paleta de cores limitada: creme, azul-marinho, amarelo-limão, terracota. Leve textura de grão de papel.", "size": "1024x1536" } ``` A imagem correspondente ao campo `url` do resultado retornado é a seguinte:

Pode-se ver que o modelo não apenas reproduziu com precisão o estilo visual do pôster Art Deco, mas também renderizou claramente e corretamente o texto do título `AMALFI` e `ITALIA 1958`. ### Cena Três: Composição Complexa e Contagem O seguinte prompt é usado para testar a capacidade do modelo de seguir instruções estruturadas sobre "quantidade" e "posição". ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "Uma estante de madeira composta por três prateleiras: Na prateleira superior, deve haver um livro. Na segunda prateleira, devem haver três livros. Na prateleira inferior, devem haver sete livros. Iluminação suave e quente, fotorealista, atmosfera aconchegante de biblioteca.", "size": "1024x1024" } ``` A imagem gerada é a seguinte:

Pode-se ver que a quantidade de livros na estante de três camadas (1 / 3 / 7) corresponde exatamente ao prompt, algo que era difícil de alcançar de forma estável na era do `dall-e-3`. ### Cena Quatro: Estilo de Ilustração (Horizontal) Ao especificar a mídia artística e palavras-chave emocionais, é possível guiar o modelo a produzir ilustrações estilizadas. ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "Uma ilustração suave e poética de um livro infantil de uma pequena raposa lendo um livro sob um cogumelo brilhante em uma floresta iluminada pela lua. Textura de aquarela e lápis, cores pastéis suaves, atmosfera sonhadora, sensação de desenho à mão.", "size": "1536x1024" } ``` A ilustração horizontal gerada é a seguinte: ![](https://platform.cdn.acedata.cloud/gpt-image/6cd57e69-d237-4cc1-a666-759a93964a08_0.png) ### Assíncrono e Callback `gpt-image-2` normalmente requer de 60 a 90 segundos para uma única chamada. Se não desejar manter uma conexão longa, pode-se usar o mecanismo de callback assíncrono `callback_url` que será apresentado posteriormente, o fluxo de chamada é idêntico ao de outros modelos. ## Série de Modelos Nano Banana A série `nano-banana` é um modelo de geração de imagens baseado no Gemini, que já está integrado através do mesmo endpoint `/openai/images/generations`, sem necessidade de mudar o endpoint, basta alterar o `model` para qualquer um dos listados na tabela abaixo. | Modelo | Cobrança (Créditos / Chamada) | Cenários Aplicáveis | | -------------------- | ----------------------------- | ------------------------------------------------------------------- | | `nano-banana` | 0.14 | Geração de imagens comuns, mais rápida e com menor custo | | `nano-banana-2-lite` | 0.14 | Modelo de imagem leve Gemini 3.1, suporta apenas 1K, baixa latência | | `nano-banana-2` | 0.28 | Qualidade e detalhes significativamente melhorados | | `nano-banana-pro` | 0.35 | O modelo flagship da série, melhor em composição, detalhes e texto | > **Importante: Faixa de suporte de parâmetros** > O Nano Banana se conecta ao protocolo OpenAI através de uma camada de adaptação, e em comparação com `gpt-image-*`, suporta apenas os seguintes parâmetros: `model`, `prompt`, `size`. > > * `size` será mapeado para `aspect_ratio` interno conforme a tabela abaixo, tamanhos não listados serão degradados para `1:1`: > * `1024x1024` / `512x512` / `256x256` → `1:1` > * `1792x1024` → `16:9` > * `1024x1792` → `9:16` > * Não suporta parâmetros como `n`, `quality`, `style`, `response_format`, `background`, `output_format`, etc.; se preenchidos, serão ignorados. > * A estrutura de retorno segue o formato OpenAI (`data[].url`), mas `created` é fixo em `0`, e não retornará `b64_json`, `revised_prompt` sempre será 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": "uma pequena maçã vermelha em uma mesa branca, fotorealista", "size": "1024x1024" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` O resultado retornado é o seguinte: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png", "revised_prompt": "uma pequena maçã vermelha em uma mesa branca, fotorealista" } ] } ``` 生成的图片可以直接通过返回的 `url` 字段访问：

### Upgrade para o modelo flagship `nano-banana-pro` Basta alterar `model` para `nano-banana-pro`, os demais parâmetros permanecem os mesmos: ```python theme={null} payload = { "model": "nano-banana-pro", "prompt": "pintura abstrata", "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": "pintura abstrata" } ] } ```

### Callback assíncrono O mecanismo de callback assíncrono `callback_url` é igualmente eficaz para o nano-banana, o fluxo de chamada é idêntico ao de outros modelos, consulte a seção [Callback assíncrono](#异步回调) abaixo. ## Uso básico A seguir, você pode preencher o conteúdo correspondente na interface, como mostrado na imagem:

Na primeira vez que usar esta interface, precisamos preencher pelo menos três conteúdos, um é `authorization`, que pode ser selecionado diretamente na lista suspensa. O outro parâmetro é `model`, que é a categoria do modelo que escolhemos usar do site oficial do OpenAI DALL-E, aqui temos principalmente 1 tipo de modelo, mais detalhes podem ser vistos nos modelos que fornecemos. O último parâmetro é `prompt`, que é a palavra-chave que inserimos para gerar a imagem. Você também pode notar que à direita há um código de chamada correspondente gerado, você pode copiar o código e executá-lo diretamente, ou pode clicar no botão "Try" para testar.

Código de 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": "Um adorável filhote de lontra do mar" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Após a chamada, encontramos o resultado retornado como segue: ```json theme={null} { "created": 1721626477, "data": [ { "revised_prompt": "Uma imagem encantadora mostrando uma jovem lontra do mar, que nasceu marrom, com olhos amplos e charmosos. Ela está deitada de costas, remando nas águas calmas do mar. Seu denso e aveludado pelo parece molhado e brilhante, capturando a essência de seu habitat. A pequena criatura brinca curiosamente com uma concha do mar com suas pequenas patas, parecendo absolutamente inocente e encantadora em seu ambiente natural.", "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" } ] } ``` O resultado retornado contém vários campos, descritos a seguir: * `created`, ID gerado para esta geração de imagem, usado para identificar exclusivamente esta tarefa. * `data`, contém as informações do resultado da geração da imagem. Onde `data` inclui as informações específicas da imagem gerada pelo modelo, e o `url` é o link detalhado da imagem gerada, como pode ser visto na imagem abaixo.

## Parâmetro de qualidade da imagem `quality` A seguir, vamos apresentar como definir alguns parâmetros detalhados do resultado da geração da imagem, onde o parâmetro de qualidade da imagem `quality` contém duas opções, a primeira `standard` indica a geração de uma imagem padrão, e a outra `hd` indica que a imagem criada possui detalhes mais refinados e maior consistência. Abaixo, definimos o parâmetro de qualidade da imagem como `standard`, as configurações específicas estão na imagem abaixo:

Você também pode notar que à direita há um código de chamada correspondente gerado, você pode copiar o código e executá-lo diretamente, ou pode clicar no botão "Try" para testar.

Código de 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": "Um adorável filhote de lontra do mar", "quality": "standard" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Após a chamada, encontramos o resultado retornado como segue: ```json theme={null} { "created": 1721636023, "data": [ { "revised_prompt": "Um adorável filhote de lontra do mar está deitado brincando de costas na água, com seu pelo parecendo brilhante e macio. Uma de suas pequenas patas está se estendendo curiosamente, e ele tem uma expressão de pura alegria e calor em seu rosto enquanto olha para o céu. Seu corpo está cercado por bolhas de sua brincadeira na água. Uma brisa suave está brincando com seu pelo, tornando-o ainda mais encantador. A cena retrata a tranquilidade e o charme da vida marinha.", "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" } ] } ``` O resultado retornado é consistente com o conteúdo do uso básico, e pode-se ver que a imagem gerada com o parâmetro de qualidade `standard` é mostrada na imagem abaixo:

与上述相同操作，仅需将图片质量参数设置为 `hd` ，可以得到如下图所示的图片：

可以看到 `hd` 比 `standard` 生成的图片具有更精细的细节和更大的一致性。 ## 图片大小尺寸参数 `size` 我们还可以设置生成图片的尺寸大小，我们可以进行下面的设置。 下面设置图片的尺寸大小为 `1024 * 1024` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

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) ``` 调用之后，我们发现返回结果如下： ```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" } ] } ``` 返回的结果与基本使用的内容一致，可以看到图片的尺寸大小为 `1024 * 1024` 的生成图片如下图所示：

与上述相同操作，仅需将图片的尺寸大小为 `1792 * 1024` ，可以得到如下图所示的图片： ![](https://cdn.acedata.cloud/4pilae.png) 可以看到图片的尺寸大小很明显不一样，另外还可以设置更多尺寸大小，详情信息参考我们官网文档。 ## 图片风格参数 `style` 图片风格参数 `style` 包含俩个参数，第一种 `vivid` 表示生成的图片是更加生动的，另一种 `natural` 表示生成的图片更加的自然一点。 下面设置图片风格参数为 `vivid` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

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) ``` 调用之后，我们发现返回结果如下： ```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" } ] } ``` 返回的结果与基本使用的内容一致，可以看到图片风格参数为 `vivid` 的生成图片如下图所示：

与上述相同操作，仅需将图片风格参数为 `natural` ，可以得到如下图所示的图片：

可以看到 `vivid` 比 `natural` 生成的图片具有更加生动逼真。 ## 图片链接的格式参数 `response_format` 最后一个图片链接的格式参数 `response_format` 也有俩种，第一种 `b64_json` 是对图片链接进行 Base64 编码，另一种 `url` 就是普通的图片链接，可以直接查看图片。 下面设置图片链接的格式参数为 `url` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

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) ``` Após a chamada, descobrimos que o resultado retornado é o seguinte: ```json theme={null} { "created": 1721637575, "data": [ { "revised_prompt": "Uma encantadora representação de um filhote de lontra marinha. A lontra é vista descansando serenamente de costas em meio às suaves ondas azuis do oceano. O pelo do filhote de lontra é uma mistura adorável de tons de marrom acinzentado suave, brilhando sutilmente sob a luz do sol suave. Suas pequenas patas estão tocando, levantadas ligeiramente em direção ao céu como se estivesse brincando com um objeto invisível. Seus olhos redondos e expressivos estão bem abertos em curiosidade, brilhando com vida e inocência. Use um estilo realista para evocar o habitat natural da lontra e seu exterior adoravelmente peludo.", "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" } ] } ``` O resultado retornado é consistente com o conteúdo de uso básico, pode-se ver que o parâmetro de formato da URL da imagem gerada com `url` é [URL da imagem](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) que pode ser acessada diretamente, o conteúdo da imagem é mostrado na figura abaixo:

Com a mesma operação acima, basta alterar o parâmetro de formato da URL da imagem para `b64_json`, e pode-se obter o resultado do link da imagem codificado em Base64, o resultado específico é mostrado na figura abaixo: ```json theme={null} { "created": 1721638071, "data": [ { "b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==", "revised_prompt": "Uma imagem encantadora de um jovem filhote de lontra marinha. A lontra está flutuando suavemente em um mar azul calmo, aproveitando os quentes raios de sol dourados que descem de um céu claro acima. O pelo da lontra é de um rico marrom chocolate, e parece incrivelmente macio e peludo. Os olhos da lontra são brilhantes e expressivos, cheios de curiosidade infantil e alegria. Ela tem pequenas orelhas pontudas e um nariz em forma de botão que acrescenta à sua fofura geral. No mar ao seu redor, gotas de água cintilantes podem ser vistas, iluminadas pela luz do sol, a cena é certamente encantadora." } ] } ``` ## Callback Assíncrono Como a API de Gerações de Imagens da OpenAI pode levar um tempo relativamente longo para gerar imagens, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema, portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo `callback_url` adicional, após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo de informação `task_id`, representando o ID da tarefa atual. Quando a tarefa for concluída, o resultado da imagem gerada será enviado para o `callback_url` especificado pelo cliente em formato JSON POST, que também incluirá o campo `task_id`, assim o resultado da tarefa pode ser associado pelo ID. Vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Aqui, para facilitar a demonstração, usamos um site de exemplo de Webhook público [https://webhook.site/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, como mostrado na figura: ![](https://cdn.acedata.cloud/cjjfly.png) Copie esta URL e você pode usá-la como Webhook, o exemplo aqui é `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Em seguida, podemos definir o campo `callback_url` para a URL do Webhook acima, ao mesmo tempo preenchendo os parâmetros correspondentes, como mostrado no código abaixo: ```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) ``` Ao clicar em executar, você pode descobrir que receberá imediatamente um resultado, como abaixo: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Após alguns momentos, podemos observar o resultado da imagem gerada na URL do Webhook, o conteúdo é o seguinte: ```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": "Uma imagem deliciosa mostrando uma jovem lontra marinha...", "url": "https://dalleprodsec.blob.core.windows.net/private/images/..." } ] } } ``` Pode-se ver que o resultado contém um campo `task_id`, o campo `data` inclui os mesmos resultados de geração de imagem que a chamada síncrona, e através do campo `task_id` é possível realizar a associação da tarefa. ## Tratamento de Erros Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a informação correspondente. Por exemplo: * `400 token_mismatched`：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos. * `400 api_not_implemented`：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos. * `401 invalid_token`：Não autorizado, token de autorização inválido ou ausente. * `429 too_many_requests`：Muitas solicitações, você excedeu o limite de taxa. * `500 api_error`：Erro interno do servidor, algo deu errado no servidor. ### Exemplo de resposta de erro ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "falha na busca" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusão Através deste documento, você já entendeu como usar a API de Geração de Imagens da OpenAI para utilizar facilmente a funcionalidade de geração de imagens do oficial OpenAI DALL-E. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.