Generate Image

Generate image

Generate an image from a user prompt, choose an available provider from environment keys, call the provider API safely, decode the returned image, save it in a sensible project location, and report the output path.

When to invoke

• "Generate an image of this concept."
• "Create a tileable game texture."
• "Make an icon or sprite for this app."
• "Use OpenAI gpt-image-2 for a polished mockup."
• "Use Gemini Nano Banana for quick visual iterations."

Inputs

Use $ARGUMENTS as the image prompt. Preserve the user's subject, style, dimensions, file format, and output path when specified. If $ARGUMENTS is empty, use the most recent user request as the prompt; if no prompt exists, return blocked with the missing input instead of inventing an image.

Prerequisites and context

• SKILL_IMAGE_GEN_OPENAI_KEY enables OpenAI image generation.
• SKILL_IMAGE_GEN_GEMINI_KEY enables Google Gemini image generation.
• Never print, commit, or persist API keys unless the user explicitly asks to configure the current shell profile.
• Save outputs under a relevant repository directory such as assets/, images/, public/, or the current directory.
• Create the output directory before writing the decoded image.

Provider selection

Onboarding

Only run onboarding when neither key is set. Explain the provider choices without generating anything:

If the user provides a key in the same session, set only the corresponding process environment variable (SKILL_IMAGE_GEN_OPENAI_KEY or SKILL_IMAGE_GEN_GEMINI_KEY) for the current run. Persist to a shell profile only when explicitly requested.

OpenAI API contract

{
  "model": "gpt-image-2",
  "prompt": "<user prompt>",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium"
}

Decode data[0].b64_json when present. If data[0].url is returned instead, download that URL and save the image. Escape special characters in the prompt before placing it in JSON.

Google Gemini API contract

{
  "contents": [{"parts": [{"text": "Generate an image: <user prompt>"}]}],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}

Handle API errors in error, safety blocks in promptFeedback.blockReason, and filtered completions with finishReason: "SAFETY".

Prompt enrichment

For batch generation, make independent API calls in parallel when tooling allows it, but write each output to a distinct path.

Procedure

1. Read $ARGUMENTS and determine prompt, provider preference, output directory, file name, and batch count.
2. Check SKILL_IMAGE_GEN_OPENAI_KEY and SKILL_IMAGE_GEN_GEMINI_KEY.
3. Select the provider using the provider table; run onboarding or return blocked when no key is available.
4. Enrich the prompt only with constraints that match the user's requested asset type.
5. Send the provider request with escaped JSON and without logging secrets.
6. Decode b64_json or inlineData.data, or download data[0].url when OpenAI returns a URL.
7. Save the image, create parent directories first, and verify the file exists and has a nonzero size.
8. Report the saved path, provider, model, and any safety or API warnings.

Gotchas

• Do not leak keys: redact Authorization and x-goog-api-key values in logs and responses.
• Do not resize user-requested textures after generation: post-generation resizing can break seamless tiling or pixel art sharpness.
• Do not assume text will be perfect: prefer OpenAI for text-heavy images and keep text short.
• Do not overwrite existing assets silently: choose a unique file name unless the user asked to replace a specific file.

Key handling note

Check whether SKILL_IMAGE_GEN_OPENAI_KEY and/or SKILL_IMAGE_GEN_GEMINI_KEY are available before choosing a provider.

Output template

## Image generation result

**Status:** complete | blocked | failed
**Provider:** OpenAI | Gemini | none
**Model:** `<model>`
**Prompt:** `<final prompt summary>`
**Output:** `<path/to/image>`

### Files
- `<path/to/image>`: <format>, <size if known>, <nonzero bytes verified>

### Validation
- API response decoded: pass | fail
- Output directory created: pass | fail
- Image file exists and is nonzero: pass | fail

Quality gate

• $ARGUMENTS or conversation context supplied a concrete image prompt.
• Provider selection followed the available environment keys and user preference.
• SKILL_IMAGE_GEN_OPENAI_KEY and SKILL_IMAGE_GEN_GEMINI_KEY were never printed or committed.
• The request used the correct provider URL, headers, model, size, and quality or modality fields.
• The response was decoded from data[0].b64_json, data[0].url, or inlineData.data as appropriate.
• The output directory exists and the saved image is nonzero bytes.
• Safety blocks, API errors, or missing keys are reported as blocked or failed with actionable detail.

References

• OpenAI API keys
• Google AI Studio API keys