Geração de Imagens
Geração e edição síncrona de imagens. Sem polling de tarefas.
Quando usar
- Texto para imagem, imagem para imagem, inpainting mascarado.
- Fundo transparente, saída WebP/JPEG, GIF animado com GPT-Image.
- O usuário nomeia um modelo de imagem ou solicita um tamanho, qualidade ou formato específico.
Quando não usar
- Vídeo, música, fala ou o modelo de decisão Jev. Use as skills dedicadas.
- O usuário deseja comparar preços primeiro: execute
models --category image.
Pré-requisitos
Resolva a chave de API nesta ordem (a primeira correspondência vence):
skills/image-generation/config.json→api_keyskills/ai-gateway/config.json→api_keyAIGW_IMAGE_API_KEYAIGW_API_KEYOPENAI_API_KEY
Armazene uma credencial com:
python3 core/gateway.py login --key sk-xxx --skill image
--base-url escreve o endereço do gateway no arquivo de configuração. Ordem de resolução: config da skill, config compartilhada, AIGW_IMAGE_BASE_URL, AIGW_BASE_URL, depois o padrão definido em core/config.json.
Comandos
# Texto para imagem
python3 core/gateway.py image generate --prompt "um panda vermelho em um banco, luz suave" \
--model <modelo> --size 1024x1024 --quality high --output-format png
# Múltiplas imagens
python3 core/gateway.py image generate --prompt "folha de adesivos" --n 4
# PNG transparente (requer um nível de modelo que suporte saída alfa)
python3 core/gateway.py image generate --prompt "adesivo de raposa cartunesca, bordas limpas" \
--background transparent --output-format png
# GIF animado (requer um nível de modelo compatível com GIF)
python3 core/gateway.py image generate --prompt "um pequeno robô acena, em loop" \
--output-format gif --frame-count 9 --frame-duration-ms 200
# Editar / inpainting
python3 core/gateway.py image edit --prompt "deixe o céu laranja no pôr do sol" \
--image input.png --mask mask.png
# Editar com círculo de marcação transparente (GPT-Image 2.5+)
python3 core/gateway.py image edit --prompt "substitua o objeto circulado por uma maçã vermelha" \
--image input.png --markup markup.png
# Descobrir modelos e aliases
python3 core/gateway.py models --category image
python3 core/gateway.py resolve nano-banana
Parâmetros
| Flag | Obrigatório | Observações |
|---|---|---|
--prompt | sim | Descrição textual. |
--model | não | ID exato do modelo. Omita quando apenas um modelo de imagem estiver disponível. |
--size | não | 1024x1024, 1536x1024, auto ou valores específicos do modelo. Use uma variante -1k para o nível de preço mais baixo. |
--n | não | Contagem de imagens. Limite máximo 128. |
--quality | não | auto / low / medium / high; GPT-Image 2.5+ também xhigh, max. |
--output-format | não | png / jpeg / webp; GPT-Image 2.6 adiciona svg, gif. |
--background | não | transparent requer png ou webp. |
--moderation | não | auto / low. |
--complexity | não | Profundidade de planejamento GPT-Image 2.6: low / medium / high. Não altera a cobrança. |
--output-compression | não | 0-100, apenas JPEG/WebP. |
--frame-count | não | 2-64, apenas GIF. Deve ser um inteiro não negativo. |
--frame-duration-ms | não | 20-2000, apenas GIF. |
--markup | não | Apenas edição. Sobreposição PNG transparente circulando a região de edição; apenas GPT-Image 2.5+. |
--group | não | Roteamento para um grupo de cobrança específico. |
Endpoints
POST /v1/images/generations— JSON, síncrono.POST /v1/images/edits— multipart, nome do campoimage[],maskopcional.
A resposta carrega itens data[]. Cada item contém b64_json ou url. A CLI decodifica base64, baixa URLs e escreve arquivos em outputs/image/<YYYY-MM-DD>/. Se o download for recusado, a URL original é retornada em urls.
Modelos de imagem Gemini também aceitam /v1/images/generations, com size mapeado para imageSize mais aspectRatio. Verificado: 2048x2048 retorna 2048x2048. GPT-Image 2.6 também aceita tamanhos de pixel explícitos; verificado: 3840x2160 retorna 3840x2160.
Resolução
| Necessidade | Valor de size | Resultado |
|---|---|---|
| 1K quadrado | 1024x1024 | 1024x1024 ou 1254x1254 |
| 2K quadrado (Gemini) | 2048x2048 | 2048x2048 |
| 4K paisagem | 3840x2160 | 3840x2160 |
Use uma variante de modelo -1k para o nível de preço mais baixo; tamanhos maiores cobram o mesmo preço por chamada apenas quando o modelo tem preço fixo.
Um ID de modelo terminando em -1k (gpt-image-2.6-1k, -flare-1k, -sunburst-1k) sempre retorna 1K. Solicitar 4K dele ecoa o tamanho solicitado, mas retorna silenciosamente cerca de 1254x1254; portanto, verifique as dimensões de saída em vez de confiar na solicitação.
--output-format svg suporta apenas --n 1; o upstream rejeita lotes maiores. Mantenha solicitações GIF/SVG em n=1 e divida os lotes você mesmo.
Formatos e transparência
| Capacidade | Requisito |
|---|---|
png / jpeg / webp | Geralmente disponível. |
| Fundo transparente | Requer png ou webp. Apenas níveis de modelo mais recentes emitem alfa; níveis de entrada o rejeitam. |
| GIF animado | Modelos de imagem gerados a partir do nível 2.6. Requer --output-format gif mais --frame-count (2-64) e --frame-duration-ms (20-2000). |
| Saída SVG | A partir do nível 2.6, apenas geração. O endpoint de edição rejeita svg e gif. |
Quando um formato é rejeitado com 400, o nível de modelo selecionado não o suporta. Mude para um nível mais recente em vez de tentar novamente o mesmo modelo.
Alguns modelos aceitam background: transparent sem erro e ainda retornam uma imagem opaca. Sempre verifique o resultado em vez de confiar na solicitação:
file outputs/image/<data>/<nome>.png # "RGBA" ou "color_type 6" significa alfa real
Um resultado RGB significa que a flag foi ignorada. Tente novamente em um nível de modelo diferente ou pós-processe o fundo branco localmente.
Edição
image edit envia arquivos locais como multipart, portanto a imagem de entrada não precisa ser pública.
--imageé repetível; até 16 entradas são aceitas.--maskmarca a área de repintura;--markupcircula a região de edição no GPT-Image 2.5 e posteriores, e é passado como um arquivo multipart.- O endpoint de edição aceita apenas saída
png/jpeg/webp.svgegifsão apenas para geração. - A imagem retornada mantém o enquadramento de entrada, a menos que o prompt solicite o contrário.
Verificado: uma imagem local através de image edit funciona tanto em um modelo GPT-Image quanto em um modelo Gemini Image, cada um retornando uma imagem editada com a composição original preservada.
Erros
| Status | Significado | Ação |
|---|---|---|
| 400 | Parâmetro inválido ou capacidade de modelo não suportada | Corrija a flag; verifique models --category image. |
| 401 | Chave ausente ou inválida | Execute login novamente e depois doctor. |
| 402 | Cota insuficiente | Informe o usuário para recarregar. |
| 429 | Limite de taxa ou limite de concorrência | Aguarde e tente novamente. |
| 503 | Modelo não disponível no grupo desta chave | Troque de modelo ou use uma chave desse grupo. |
| 5xx | Falha do upstream | Tente novamente uma vez e depois exiba a mensagem original. |