gpt-image-2-generation#

Generate images from natural-language prompts using the gpt-image-2 model hosted at WellAPI. The skill calls POST https://wellapi.ai/v1/images/generations, decodes the returned b64_json, and writes the image to disk.

When to use#

Trigger this skill when the user asks for things like:

• "Generate an image of a sunset over the ocean"
• "Draw a cat wearing a top hat"
• "Create a 1024x1024 picture of …"
• "Make an illustration / poster / artwork of …"
• Any other request to produce a visual from a textual description.

If the user asks for image editing (in-painting, variations, etc.), this skill currently only covers text-to-image generation; tell the user so.

Prerequisites#

1. API key — The user must supply a WellAPI key.

   • If the environment variable WELLAPI_API_KEY is set, it will be used.
   • Otherwise the skill looks for a local config file:
     • Linux/macOS: ~/.config/gpt-image-2-generation/config.json
     • Windows: %USERPROFILE%\.config\gpt-image-2-generation\config.json
   • If neither is present, the skill prompts the user to register and enter a key (see First-run onboarding below).

2. Python 3.7+ with the standard library only (no third-party packages required).

First-run onboarding (no API key found)#

When no key can be located, before making any API call show the user this short prompt verbatim (translate to the user's language if appropriate) — do not expand it into multiple "options / methods", do not show shell commands, do not ask follow-up questions like "do you already have a key":

请粘贴你的 WellAPI API Key。 如果还没有，请前往 https://wellapi.ai/register?channel=c_qqn3vdvc 注册后领取免费 API Key。

Please paste your WellAPI API Key. If you don't have one yet, register at https://wellapi.ai/register?channel=c_qqn3vdvc to get a free key.

Wait for the user to reply with the key, then call the helper script to securely store it:

bash

python3 scripts/setup_api_key.py

The script reads the key from stdin and persists it to the per-user config file with 0600 permissions. Never echo or log the full key after it is captured. Do not describe environment-variable alternatives unless the user explicitly asks.

How to generate an image#

Use the bundled script scripts/generate_image.py. It accepts CLI arguments, builds the request, sends it with Authorization: Bearer <key>, decodes the base64 image, and writes the file.

Required argument#

FlagMeaning--promptThe text description of the image to generate.

Optional arguments (defaults match the WellAPI example)#

FlagDefaultAllowed values--n``1integer, number of images--size``1024x1024e.g. 512x512, 1024x1024, 1024x1536, 1536x1024``--quality``low``low, medium, high``--format``jpeg``jpeg, png, webp``--model``gpt-image-2model name--output``./gpt-image-2_<timestamp>.<format>output file path. When --n > 1, an index suffix is added.--api-key(auto)overrides env / config file--timeout``600 (or $WELLAPI_TIMEOUT)HTTP timeout in seconds. The endpoint is synchronous and a single image typically takes 1–3 minutes, so keep this generous.

Example invocations#

bash

# Minimal
python3 scripts/generate_image.py --prompt "大海"

# Custom size + format + output path
python3 scripts/generate_image.py \
  --prompt "A futuristic city skyline at dusk, cyberpunk style" \
  --size 1024x1024 \
  --quality high \
  --format png \
  --output ./city.png

The script prints the absolute path(s) of the saved image(s) on success and exits non-zero on failure.

Request / response contract#

Request body sent to https://wellapi.ai/v1/images/generations:

json

{
  "model": "gpt-image-2",
  "prompt": "大海",
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "format": "jpeg"
}

Headers

text

Authorization: Bearer <WELLAPI_API_KEY>
Content-Type: application/json

Response (the image is in data[i].b64_json):

json

{
  "created": 1778236581,
  "data": [{ "b64_json": "iVBORw0KGg..." }],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": { "input_tokens": 8, "output_tokens": 196, "total_tokens": 204 }
}

The skill base64-decodes each b64_json entry and writes the bytes to disk using output_format (or the requested --format) as the file extension.

Workflow for the agent#

1. Parse the user's image request → extract prompt, and any explicit size, quality, format, n.
2. Resolve the API key (env → config file → prompt user via scripts/setup_api_key.py).
3. Run scripts/generate_image.py with the parsed arguments. The endpoint is synchronous and commonly takes 1–3 minutes — wait for the script to return; do not abort or retry early. If your tool runner has its own command timeout, raise it (e.g. ≥ 600s) before invoking the script.
4. Report the saved file path(s) to the user. If running in an environment that can render images, also display the result.
5. On HTTP errors, surface the upstream error message verbatim and suggest checking the API key, quota, or prompt content. On a real timeout, retry once or pass --timeout / set WELLAPI_TIMEOUT to a larger value.

Non-200 responses → group capacity hint#

Whenever WellAPI returns a non-200 status (typical examples: 400, 401, 403, 404, 429, 5xx), the script appends a remediation hint to its error output. Always relay this hint to the user verbatim — the most common root cause is that the API Key's group does not have available capacity for gpt-image-2.

Tell the user (translate to their language if needed):

接口返回非 200 状态码，可能是该 API Key 所属分组资源不足。请登录 https://wellapi.ai 的「API 令牌管理」，把此 API Key 的分组修改为 「官转OpenAI分组」 或 「优质官转OpenAI分组」，保存后重新让我生成图片即可。

Only after the user confirms they have switched groups (or explicitly asks to retry) should you re-invoke scripts/generate_image.py. Do not silently retry on 4xx/5xx — the same group will fail again.

Files in this skill#

• SKILL.md — this file (metadata + instructions)
• scripts/generate_image.py — performs the generation
• scripts/setup_api_key.py — interactive helper to store the API key
• scripts/api_key.py — shared helpers for locating/loading the key
• README.md — marketplace listing

Security notes#

• The API key is stored locally in the user's home directory with 0600 permissions and is never committed, logged, or echoed.
• All network traffic goes only to https://wellapi.ai.
• The skill does not execute or evaluate any data returned by the API beyond base64-decoding the image bytes.