---
title: "Integração de geração de imagens"
description: "Gere imagens usando a API do OpenAI Images, salve o resultado em Base64 e depure permissões de modelo e timeouts."
headingIds: {"API e preparação":"section-1","Gerar e salvar uma imagem":"section-2","Confirme o suporte do modelo antes de adicionar parâmetros":"section-3","Problemas comuns":"section-4"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentação mantida por [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Fontes e correções](https://1zheai.com/en/editorial/).

Encontrou um erro? [Contate o suporte](mailto:support@1zheai.com) com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

</aside>
O catálogo público de modelos deste site lista atualmente `gpt-image-1.5` e `chatgpt-image-latest` (verificado em 2026-10-16). Antes de usar, consulte os [modelos disponíveis na chave ](/pt/docs/api-models/) e depois confirme a API de imagens e os parâmetros no [catálogo de modelos do console ](https://1zheai.com/model-catalog?lng=pt).

Esta página fornece exemplos de integração conforme o protocolo do OpenAI Images; esta atualização de documentação não executou geração de imagens paga, portanto não considere os exemplos abaixo como testados para todas as combinações de modelos, tamanhos e qualidades.

## API e preparação

- Endereço completo: `POST https://1zheai.com/v1/images/generations`
- Base URL do SDK OpenAI: `https://1zheai.com/v1`
- Use a variável de ambiente `ONEZHE_API_KEY` deste site.
- Instale o SDK Python: `python -m pip install openai`.

## Gerar e salvar uma imagem

Salve como `generate-image.py` e execute no terminal `python generate-image.py`:

```python
import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=300.0,
    max_retries=0,
)
result = client.images.generate(
    model=os.environ.get("ONEZHE_IMAGE_MODEL", "gpt-image-1.5"),
    prompt="一只白色陶瓷茶杯放在浅灰色桌面上，柔和自然光，无文字。",
)
if not result.data:
    raise RuntimeError("响应没有图片数据，请检查错误信息与调用日志。")
item = result.data[0]
if item.b64_json:
    target = Path("generated-image.png")
    target.write_bytes(base64.b64decode(item.b64_json, validate=True))
    print(f"图片已保存到 {target.resolve()}")
elif item.url:
    print("返回的是图片地址，请及时下载：", item.url)
else:
    raise RuntimeError("响应没有 b64_json 或 url。")
```

O exemplo usa o formato de saída padrão. Se especificar JPEG / WebP ou outro formato, altere também a extensão do arquivo ao salvar. Não grave a string Base64 diretamente em um arquivo de texto e renomeie para PNG.

## Confirme o suporte do modelo antes de adicionar parâmetros

Primeiro valide com uma requisição contendo apenas `model` e `prompt`. Parâmetros como tamanho, qualidade, fundo transparente e formato de saída não são universais em todos os modelos de imagem; não copie diretamente nomes de modelos ou parâmetros proprietários de outros provedores.

Quando retornar `data[].b64_json`, faça a decodificação Base64; quando retornar `data[].url`, baixe imediatamente, não trate a URL temporária como armazenamento permanente. A aplicação precisa organizar o armazenamento dos resultados por conta própria.

## Problemas comuns

| Situação | Método de diagnóstico |
| --- | --- |
| 400 parâmetro não suportado | Remova parâmetros opcionais como tamanho e qualidade personalizados e valide item por item |
| 403 / 404 | Verifique o ID do modelo de imagem, as permissões da chave e o caminho completo da API |
| Tempo de espera longo | Defina um timeout razoável para a geração e exiba um estado em andamento, evitando cliques repetidos que enviem requisições duplicadas |
| Sem imagem após timeout | Primeiro consulte os logs de chamada; não receber o resultado não significa que o upstream não processou a requisição |
| Deseja editar uma imagem existente | A edição de imagem é outra API e forma de entrada; o exemplo de geração de imagem por texto desta página não a substitui diretamente |

Referência de parâmetros do protocolo [OpenAI imagem de geração de referência ](https://developers.openai.com/api/reference/resources/images/methods/generate). Os custos seguem o catálogo de modelos em tempo real deste site; a estratégia de retry está em [timeout e retry ](/pt/docs/retries/).