{"skill":{"slug":"gpt-image-2-generation","displayName":"gpt image 2 generation","summary":"Generate images from text prompts using the WellAPI gpt-image-2 model. Use this skill whenever the user asks to create, draw, render, or generate an image, p...","description":"---\nname: gpt-image-2-generation\ndescription: Generate images from text prompts using the WellAPI gpt-image-2 model. Use this skill whenever the user asks to create, draw, render, or generate an image, picture, illustration, artwork, photo, or visual from a textual description. Handles API key onboarding, authenticated requests to https://wellapi.ai/v1/images/generations, and decoding the returned base64 image into a local file.\nversion: 1.0.0\nlicense: MIT\nmetadata:\n  openclaw:\n    primaryEnv: WELLAPI_API_KEY\n    envVars:\n      - name: WELLAPI_API_KEY\n        required: false\n        description: WellAPI bearer token used to authenticate against the gpt-image-2 endpoint. If unset, the skill will read it from the local config file or prompt the user to enter one.\n    requiredBinaries:\n      - python3\n    capabilities:\n      - network\n      - filesystem\n---\n\n# gpt-image-2-generation\n\nGenerate images from natural-language prompts using the **gpt-image-2** model hosted at [WellAPI](https://wellapi.ai). The skill calls `POST https://wellapi.ai/v1/images/generations`, decodes the returned `b64_json`, and writes the image to disk.\n\n## When to use\n\nTrigger this skill when the user asks for things like:\n\n- \"Generate an image of a sunset over the ocean\"\n- \"Draw a cat wearing a top hat\"\n- \"Create a 1024x1024 picture of …\"\n- \"Make an illustration / poster / artwork of …\"\n- Any other request to produce a visual from a textual description.\n\nIf the user asks for image *editing* (in-painting, variations, etc.), this skill currently only covers text-to-image generation; tell the user so.\n\n## Prerequisites\n\n1. **API key** — The user must supply a WellAPI key.\n   - If the environment variable `WELLAPI_API_KEY` is set, it will be used.\n   - Otherwise the skill looks for a local config file:\n     - Linux/macOS: `~/.config/gpt-image-2-generation/config.json`\n     - Windows:    `%USERPROFILE%\\.config\\gpt-image-2-generation\\config.json`\n   - If neither is present, the skill prompts the user to register and enter a key (see *First-run onboarding* below).\n2. **Python 3.7+** with the standard library only (no third-party packages required).\n\n## First-run onboarding (no API key found)\n\nWhen 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\":\n\n> 请粘贴你的 **WellAPI API Key**。\n> 如果还没有，请前往 https://wellapi.ai/register?channel=c_qqn3vdvc 注册后领取免费 API Key。\n>\n> Please paste your **WellAPI API Key**.\n> If you don't have one yet, register at https://wellapi.ai/register?channel=c_qqn3vdvc to get a free key.\n\nWait for the user to reply with the key, then call the helper script to securely store it:\n\n```bash\npython3 scripts/setup_api_key.py\n```\n\nThe 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.\n\n## How to generate an image\n\nUse 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.\n\n### Required argument\n\n| Flag | Meaning |\n|------|---------|\n| `--prompt` | The text description of the image to generate. |\n\n### Optional arguments (defaults match the WellAPI example)\n\n| Flag | Default | Allowed values |\n|------|---------|----------------|\n| `--n`        | `1`         | integer, number of images |\n| `--size`     | `1024x1024` | e.g. `512x512`, `1024x1024`, `1024x1536`, `1536x1024` |\n| `--quality`  | `low`       | `low`, `medium`, `high` |\n| `--format`   | `jpeg`      | `jpeg`, `png`, `webp` |\n| `--model`    | `gpt-image-2` | model name |\n| `--output`   | `./gpt-image-2_<timestamp>.<format>` | output file path. When `--n > 1`, an index suffix is added. |\n| `--api-key`  | (auto)      | overrides env / config file |\n| `--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. |\n\n### Example invocations\n\n```bash\n# Minimal\npython3 scripts/generate_image.py --prompt \"大海\"\n\n# Custom size + format + output path\npython3 scripts/generate_image.py \\\n  --prompt \"A futuristic city skyline at dusk, cyberpunk style\" \\\n  --size 1024x1024 \\\n  --quality high \\\n  --format png \\\n  --output ./city.png\n```\n\nThe script prints the absolute path(s) of the saved image(s) on success and exits non-zero on failure.\n\n## Request / response contract\n\n**Request body** sent to `https://wellapi.ai/v1/images/generations`:\n\n```json\n{\n  \"model\": \"gpt-image-2\",\n  \"prompt\": \"大海\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"quality\": \"low\",\n  \"format\": \"jpeg\"\n}\n```\n\n**Headers**\n\n```\nAuthorization: Bearer <WELLAPI_API_KEY>\nContent-Type: application/json\n```\n\n**Response** (the image is in `data[i].b64_json`):\n\n```json\n{\n  \"created\": 1778236581,\n  \"data\": [{ \"b64_json\": \"iVBORw0KGg...\" }],\n  \"output_format\": \"png\",\n  \"quality\": \"low\",\n  \"size\": \"1024x1024\",\n  \"usage\": { \"input_tokens\": 8, \"output_tokens\": 196, \"total_tokens\": 204 }\n}\n```\n\nThe skill base64-decodes each `b64_json` entry and writes the bytes to disk using `output_format` (or the requested `--format`) as the file extension.\n\n## Workflow for the agent\n\n1. Parse the user's image request → extract `prompt`, and any explicit `size`, `quality`, `format`, `n`.\n2. Resolve the API key (env → config file → prompt user via `scripts/setup_api_key.py`).\n3. 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.\n4. Report the saved file path(s) to the user. If running in an environment that can render images, also display the result.\n5. 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.\n\n### Non-200 responses → group capacity hint\n\nWhenever 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`.\n\nTell the user (translate to their language if needed):\n\n> 接口返回非 200 状态码，可能是该 API Key 所属分组资源不足。请登录 https://wellapi.ai 的「API 令牌管理」，把此 API Key 的分组修改为 **「官转OpenAI分组」** 或 **「优质官转OpenAI分组」**，保存后重新让我生成图片即可。\n\nOnly 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.\n\n## Files in this skill\n\n- `SKILL.md` — this file (metadata + instructions)\n- `scripts/generate_image.py` — performs the generation\n- `scripts/setup_api_key.py` — interactive helper to store the API key\n- `scripts/api_key.py` — shared helpers for locating/loading the key\n- `README.md` — marketplace listing\n\n## Security notes\n\n- The API key is stored locally in the user's home directory with `0600` permissions and is **never** committed, logged, or echoed.\n- All network traffic goes only to `https://wellapi.ai`.\n- The skill does not execute or evaluate any data returned by the API beyond base64-decoding the image bytes.\n","tags":{"gpt-image":"1.0.1","image-generation":"1.0.1","latest":"1.0.1","text-to-image":"1.0.1","wellapi":"1.0.1","gpt-image-2":"1.0.0"},"stats":{"comments":0,"downloads":369,"installsAllTime":14,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1778312156692,"updatedAt":1778492885325},"latestVersion":{"version":"1.0.1","createdAt":1778374161624,"changelog":"- Streamlined and shortened API key onboarding prompt for first-time users.\n- Added group capacity error handling guidance for non-200 responses, including recommended group settings for WellAPI API Keys.\n- Documented new `--timeout` argument to handle potentially long synchronous image generation (default 600s).\n- Clarified workflow to wait for script completion and only retry upon user confirmation after group change.\n- Minor documentation updates for clarity and to reduce unnecessary information during setup.","license":"MIT-0"},"metadata":{"setup":[{"key":"WELLAPI_API_KEY","required":false}],"os":null,"systems":null},"owner":{"handle":"laolujava","userId":"s17f6wwwdbyz238kxwh90tkmex86aewb","displayName":"LuTong","image":"https://avatars.githubusercontent.com/u/7344866?v=4"},"moderation":null}