weber87na/openai-image

Desenho e GIF Nativo com OpenAI

Este skill é um pacote de Agent Skills independente e copiável, que suporta instalação em projetos e pessoal. O diretório onde este arquivo está localizado é o diretório raiz do skill. Não assuma um local de instalação fixo ou o diretório de trabalho atual. Todos os comandos Python devem ser executados via uv, sem usar python, pip ou criar um ambiente virtual manualmente.

Capacidades e Limitações

• Imagens estáticas: PNG, JPEG, WebP.
• GIFs animados nativos: usando output_format=gif, frame_count, frame_duration_ms, em uma única chamada a /v1/images/generations.
• Modelo padrão: gpt-image-2.6-sunburst; para iteração rápida, pode-se escolher gpt-image-2.6-flare. Não use nomes informais como gpt-image2.6 como ID do modelo.
• Atualmente, GIFs exigem acesso à pré-visualização de GIF do modelo escolhido, e não apenas uma assinatura do ChatGPT / Codex / Copilot.
• GIFs suportam de 2 a 16 quadros, com padrão de 9 quadros; duração padrão de 200 ms por quadro, mínimo de 20 ms, a API arredonda para múltiplos de 10 ms e o limite de codificação é 655350 ms. A animação padrão dura cerca de 1,8 segundos; o tempo real depende dos dados de saída.
• Não copia a mesma imagem para múltiplos quadros, não renomeia PNG para GIF, nem tenta silenciosamente gerar múltiplas imagens ou usar outros serviços pagos em caso de falha.
• Este CLI foca em geração de texto para imagem, não oferecendo edição de imagem, streaming, geração de vídeo ou síntese de animação local. Não depende de Pillow, FFmpeg ou do OpenAI SDK.

Fluxo de Trabalho

1. Determine se é imagem estática ou animação; mantenha o assunto, composição, texto, estilo e caminho de saída especificados pelo usuário.
2. Para animações, complemente a descrição com "movimento, câmera fixa, fundo consistente, transição suave entre início e fim". Não altere a solicitação sem consentimento. Use valores padrão para número de quadros e velocidade, se não especificados; se exceder os limites da API, explique e pergunte sobre as compensações.
3. Lembre que o uso da API OpenAI consome créditos; chame a API somente com autorização do usuário para desenhar. Ações como criar o skill, ler a documentação ou fazer dry-run não autorizam o teste pago. Não envie código-fonte, credenciais ou outros dados confidenciais.
4. Verifique uv --version. Se o uv não estiver instalado, peça ao usuário para instalar o uv, não instale ferramentas do sistema por conta própria.
5. Verifique apenas se OPENAI_API_KEY existe; nunca imprima o conteúdo de .env ou da chave, não peça para colá-la no chat, nem a escreva em código-fonte ou repositório. Use variáveis de ambiente existentes; se precisar de dotenv, confirme o projeto de trabalho do usuário ou o caminho absoluto explícito do .env, e carregue com uv run --env-file <caminho>. Não procure credenciais de outros projetos no diretório de instalação do skill. Esta ferramenta conecta-se apenas a https://api.openai.com e não lê OPENAI_BASE_URL.
6. A partir do diretório raiz do skill, resolva o caminho absoluto do CLI. Primeiro faça um dry-run para verificar os parâmetros e depois execute uma requisição real. O caminho de saída deve ser relativo ao projeto de trabalho do usuário, não ao diretório de instalação do skill. Na configuração inicial, use o modelo de configuração em branco e o guia de uso anexos; não sobrescreva configurações existentes.
7. Verifique o código de saída e o JSON de resultado. A ferramenta valida o formato de retorno; para GIF, analisa o bloco, confirma pelo menos dois quadros, reporta as dimensões reais, número de quadros e duração total, antes de escrever o arquivo. Esta é uma verificação de contêiner e formato, não uma decodificação completa de pixels ou aceitação de qualidade visual; quando houver capacidade de pré-visualização de imagem, verifique a aparência.
8. Forneça links para os arquivos gerados; se o GIF não for pré-visualizado, não afirme que os efeitos visuais foram verificados. Se o número de quadros não corresponder, apresente um aviso, não oculte.

Modo de Execução

Primeiro, defina $skillDir como o caminho absoluto do diretório raiz do skill, de acordo com o local de carregamento. Em seguida, execute a partir do projeto de trabalho do usuário. Para configuração completa, exemplos de imagem estática/GIF e parâmetros, consulte o guia de uso.

$script = Join-Path $skillDir 'scripts\openai_image.py'
uv run --no-env-file --script "$script" --prompt 'Montanhas e névoa matinal de Taiwan em estilo aquarela original, sem texto' --output outputs\mountains.png --dry-run

• --dry-run não precisa de chave API, não chama a API, não escreve arquivos; ele mostra o prompt e não deve conter dados confidenciais. O uv pode baixar o ambiente de execução Python na primeira vez que faltar.
• Remova --dry-run somente após obter autorização para desenhar. Se precisar de dotenv, substitua --no-env-file por --env-file <caminho absoluto do .env especificado pelo usuário>.
• GIFs usam extensão .gif, e pode-se especificar --frames 9 --frame-duration-ms 200; n=1 representa a animação completa, não o número de quadros.
• Não envie parâmetros como response_format, stream, partial_images, output_compression que não são aplicáveis a GIFs.
• Por padrão, não especifique tamanho; tamanhos personalizados devem ser múltiplos de 16 e proporção entre 1:3 e 3:1. GIFs têm limitações de tamanho do modelo; não presuma que o tamanho estático sempre se aplica.
• Não forneça --overwrite, a menos que o usuário concorde explicitamente em substituir arquivos existentes.

Tratamento de Erros

• Chave ausente: pare, peça ao usuário para definir a chave em seu ambiente; não cole a chave no chat.
• HTTP 401 / 403 / 404: verifique as credenciais, o ID completo do modelo, a verificação da organização e a permissão de pré-visualização de GIF.
• HTTP 400: verifique tamanho, formato, parâmetros de quadros e suporte do modelo; não degrade automaticamente para outros formatos ou soluções de síntese.
• HTTP 429, 5xx, timeout ou falha de conexão: a requisição pode ter sido processada e cobrada; reporte primeiro, e com o consentimento do usuário, reenvie.
• GIF não animado, formato incorreto, Base64 inválido ou GIF incompleto: recuse o sucesso do relatório, não escreva no arquivo de destino.
• Quando o caminho de saída não existir, crie automaticamente as pastas pai; arquivos existentes não serão substituídos por padrão. O sistema de arquivos deve suportar links físicos para salvar atomicamente sem sobrescrever; se não suportar, reporte o erro, não sobrescreva silenciosamente.

Verificação (Testes)

Os testes offline usam apenas um servidor HTTP simulado local; não leem chaves reais, não se conectam à OpenAI e não geram custos:

$tests = Join-Path $skillDir 'tests\test_openai_image.py'
uv run --no-env-file --script "$tests"

Os testes não significam que a permissão de modelo / pré-visualização de GIF foi obtida ou que a validação ponta a ponta paga foi concluída. A geração real requer uma chave válida e autorização do usuário.

Chamando no agente

• Copilot: Use /openai-image, ou diga diretamente "Desenhe uma imagem / faça um GIF animado com a OpenAI".
• Codex: Use $openai-image, ou solicite em linguagem natural o uso deste skill; a configuração de interface do Codex não afeta comandos compartilhados.
• Se não for encontrado, verifique se o harness atual suporta o local de instalação e reinicie a conversa ou recarregue a lista de skills. O CLI do Copilot e o Codex podem compartilhar .agents/skills; alguns harnesses do Copilot usam .github/skills. Mova a pasta completa, não copie skills com o mesmo nome para locais que serão escaneados simultaneamente.

Referências Oficiais

Os parâmetros de implementação baseiam-se na documentação oficial consultada em 09/11/2026; o acesso ao modelo, limitações e preços podem variar.

• Guia de Geração de Imagens: GPT Image 2.6
• API de Images: Parâmetros de GIF Nativo
• Modelo Sunburst
• Modelo Flare
• Skills do Codex
• Skills do Copilot CLI