weber87na/openai-image

OpenAI Image Generation & Native GIF

This skill is a self-contained Agent Skills package, installable per project or per user. The folder containing this file is the skill root directory; do not assume a fixed installation path or the current working directory. All Python commands must be executed via uv — do not use bare python, pip, or create your own venv.

Capabilities and Limitations

• Static images: PNG, JPEG, WebP.
• Native animated GIFs: uses output_format=gif, frame_count, frame_duration_ms with a single /v1/images/generations call.
• Default model: gpt-image-2.6-sunburst; for rapid iteration, use gpt-image-2.6-flare. Do not pass colloquial names like gpt-image2.6 as model IDs.
• GIF currently requires GIF preview access for the chosen model, not just a ChatGPT / Codex / Copilot subscription.
• GIF supports 2–16 frames, default 9; default duration 200 ms per frame, minimum 20 ms, API rounds to 10 ms, max 655350 ms. Default animation ~1.8 s; actual time depends on output data.
• Does not duplicate a single image into multiple frames, rename PNG to GIF, or silently fall back to multiple generations or other paid services on failure.
• This CLI is dedicated to text-to-image only; it does not offer image editing, streaming, video generation, or local animation compositing. No Pillow, FFmpeg, or OpenAI SDK dependencies.

Workflow

1. Determine static image vs. animation; preserve the user's specified subject, composition, text, style, and output path.
2. For animation, fill in details like "motion, fixed camera, consistent background, seamless loop". Do not alter requirements without consent. Use default frame count and speed if unspecified; if API limits are exceeded, explain and ask for trade-offs.
3. Remind that this uses OpenAI API credits; only call the API when the user authorizes image generation. Merely loading the skill, reading help, or performing a dry-run does not constitute authorization for paid testing. Never send source code, credentials, or other confidential data.
4. Verify uv --version. If uv is not installed, ask the user to install uv — do not install system tools on their behalf.
5. Check that OPENAI_API_KEY exists; never print the contents of .env or the key, never ask to paste it into a chat, and never write it into source code or repositories. Use existing environment variables from the process. If a dotenv file is needed, confirm the project path or the absolute path of the explicitly specified .env, then load it with uv run --env-file <path>. Do not look for credentials in the skill installation directory. This tool only connects to https://api.openai.com; it does not read OPENAI_BASE_URL.
6. Resolve the absolute path to the CLI from the skill root directory. First run with --dry-run to validate parameters, then execute one real request. Write output files to the user's working project directory, not into the skill installation folder. For initial setup, use the provided blank configuration template and usage guide; do not overwrite existing configurations.
7. Check exit code and result JSON. The tool validates the response format, parses GIF chunks, ensures at least two frames, and reports actual dimensions, frame count, and total duration before writing to disk. This is container/format validation, not full pixel decoding or visual quality acceptance; only perform visual checks if the harness supports image preview.
8. Provide a link to the output file; if GIF is not previewed, do not claim the visual quality has been verified. If the frame count differs from what was requested, emit a warning—do not hide it.

Execution

First set $skillDir to the absolute path of the skill root directory, then execute from the user's working project. For full configuration, static image/GIF examples, and parameters, see the usage guide.

$script = Join-Path $skillDir 'scripts\openai_image.py'
uv run --no-env-file --script "$script" --prompt 'Original watercolor style of Taiwan mountains and morning mist, no text' --output outputs\mountains.png --dry-run

• --dry-run does not require an API key, does not call the API, and does not write files; it will display the prompt. Do not use confidential content in this mode. uv may still download a Python runtime if missing.
• Remove --dry-run only after obtaining authorization to generate images. When a dotenv file is needed, replace --no-env-file with --env-file <absolute path to user-specified .env>.
• GIF files use the .gif extension and allow --frames 9 --frame-duration-ms 200; n=1 refers to the complete animation, not the number of frames.
• Do not send parameters like response_format, stream, partial_images, or output_compression that are not applicable to GIF generation.
• By default, no size is specified; custom sizes must be multiples of 16, with an aspect ratio between 1:3 and 3:1. GIFs have additional model-specific size constraints—do not assume static image sizes are valid.
• No --overwrite flag is provided unless the user explicitly agrees to replace an existing file.

Error Handling

• Missing key: stop and ask the user to set it in their environment; never paste the key into the conversation.
• HTTP 401 / 403 / 404: check credentials, full model ID, organization verification, and GIF preview access.
• HTTP 400: check size, format, frame parameters, and model support; do not automatically degrade to other formats or compositing solutions.
• HTTP 429, 5xx, timeouts, or connection interruptions: may have been processed and billed; report first, then resend only with user consent.
• Non-animated GIF, incorrect format, invalid Base64, or incomplete GIF: refuse to report success and do not write to the target file.
• If the output path does not exist, create parent directories automatically; existing files will not be overwritten by default. The file system must support hard links to atomically save without overwriting; if not, report an error without silently overwriting.

Verification

The offline test uses only a local HTTP mock server—it does not read a real key, connect to OpenAI, or incur costs:

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

Tests do not imply that model/GIF preview access has been granted or that end-to-end paid verification has been completed. Actual generation requires a valid key and user authorization.

Calling in an Agent

• Copilot: use /openai-image, or say "Draw an image / make an animated GIF using OpenAI."
• Codex: use $openai-image, or request this skill in natural language; the Codex interface configuration does not affect the shared commands.
• If not found, confirm the current harness supports the installation location and restart the dialogue or reload the skills list. Copilot CLI and Codex can share .agents/skills; some Copilot harnesses use .github/skills. Move the entire folder—do not copy the same skill to multiple locations scanned simultaneously.

Official References

Implementation parameters are based on official documentation consulted on 2026-11-09; model access, limits, and pricing may change.

• Image Generation Guide: GPT Image 2.6
• Images API: Native GIF Parameters
• Sunburst Model
• Flare Model
• Codex skills
• Copilot CLI skills