hiapi-gpt-image-2

# HiAPI GPT Image 2 Use this skill when the user wants image generation through the HiAPI GPT Image 2 family. ## Requirements - Node.js 18 or newer. - `HIAPI_API_KEY` must be set in the environment. - `HIAPI_BASE_URL` is optional and defaults to `https://api.hiapi.ai`. Important links: - Get API key: https://www.hiapi.ai/en/register - Pricing: https://www.hiapi.ai/en/pricing - Docs: https://docs.hiapi.ai Never invent an image result. If the API call fails, report the status code, compact error message, and the next action from the Error Guidance section. ## Generate An Image Run: ```bash node scripts/hiapi-gpt-image-2.mjs --prompt "Create a launch poster for an AI note app" --aspect-ratio 16:9 ``` Preflight and route examples: ```bash node scripts/hiapi-gpt-image-2.mjs --prompt "..." --aspect-ratio 9:21 --resolution 4K --route ext --quality high --dry-run --estimate node scripts/hiapi-gpt-image-2.mjs --prompt "..." --route beta --size 1536x1024 node scripts/hiapi-gpt-image-2.mjs --resume-task-id <task-id> ``` Supported models: - `gpt-image-2/text-to-image` - `gpt-image-2/image-to-image` For image-to-image requests, use `gpt-image-2/image-to-image` and pass `--input-url` once per reference image. The API field is `input.input_urls`; supported count is 1 to 16 public JPEG, PNG, or WebP images. Supported aspect ratios: - `auto` - `1:1` - `3:2` - `2:3` - `16:9` - `9:16` - `4:3` - `3:4` - `5:4` - `4:5` - `2:1` - `1:2` - `3:1` - `1:3` - `21:9` - `9:21` Supported resolutions: - `1K` - `2K` - `4K` Optional background (`--background`): - `auto` - `opaque` - `transparent` Cross-field constraints on the default route: - `aspect_ratio=auto` (or omitted) only supports `resolution=1K`. - `resolution=2K` is unavailable for `5:4`, `4:5`, `3:1`, `1:3`, and `9:21`. - `resolution=4K` is unavailable for `3:1`, `1:3`, and `9:21`; text-to-image also excludes `1:1` at 4K. - `background` (any value) only supports `resolution=1K`; omit it for 2K/4K. ## Routes (`--route`) | Route | Models | Parameters | Use when | | --- | --- | --- | --- | | `default` (omit) | both | `aspect_ratio`, `resolution`, optional `background`; image-to-image `input_urls` 1-16 | Standard choice, transparent/opaque background, many references. | | `beta` | text-to-image only | `--size auto` or `WIDTHxHEIGHT` (3-5 digits each, lowercase `x`, e.g. `1536x1024`) replaces aspect ratio and resolution | Exact pixel size at a flat price. | | `ext` (multi-ratio 4K) | both | every aspect ratio at `1K`/`2K`/`4K`, required `--quality low\|medium\|high` (default `low`); image-to-image sends `image_urls` 1-6; no `background` | Ratios the default route blocks at 2K/4K (for example `9:21` 4K) or explicit quality control. | Defaults: ext text-to-image uses `aspect_ratio=1:1`; ext image-to-image uses `auto` (follow the input). Routes are priced differently; run `--estimate` before choosing. The CLI validates all route and cross-field rules locally, so an unsupported combination never becomes a rejected paid task. ## Paid-Task Safety And Recovery - `--dry-run` validates and prints the exact payload without an API key or network call. `--estimate` adds a public pricing snapshot (`paidTaskCreated: false`). Use them before any large or high-quality generation. - Every create sends an `Idempotency-Key` header. The key is printed on stderr before submission and the task ID immediately after. If the create call fails ambiguously, retry with `--idempotency-key <same key>`; never submit a fresh request blindly. - `--resume-task-id <task-id>` polls and downloads an existing task without creating a new one. Use it after a timeout, a lost terminal, or an expired local file. - A hard skill update blocks only new task creation; `--dry-run`, `--estimate`, and `--resume-task-id` keep working. The script writes generated data URI images to `outputs/` and prints JSON with the saved file paths or remote URLs. ## API Contract This skill calls: ```text POST /v1/tasks GET /v1/tasks/{taskId} ``` with: ```json { "model": "gpt-image-2/text-to-image", "input": { "prompt": "...", "aspect_ratio": "16:9", "resolution": "1K" } } ``` Image-to-image: ```json { "model": "gpt-image-2/image-to-image", "input": { "prompt": "...", "input_urls": ["https://example.com/source.png"], "aspect_ratio": "16:9", "resolution": "2K" } } ``` Routed requests add a top-level `route` and use that route's input shape: ```json { "model": "gpt-image-2/text-to-image", "route": "ext", "input": { "prompt": "...", "aspect_ratio": "9:21", "resolution": "4K", "quality": "high" } } { "model": "gpt-image-2/image-to-image", "route": "ext", "input": { "prompt": "...", "image_urls": ["https://example.com/source.png"], "resolution": "1K", "quality": "medium" } } { "model": "gpt-image-2/text-to-image", "route": "beta", "input": { "prompt": "...", "size": "1536x1024" } } ``` `POST /v1/tasks` returns `data.taskId`. Poll `GET /v1/tasks/{taskId}` until status is `success`. Expected image output is in `data.output[]`, commonly: ```json { "data": { "status": "success", "output": [{ "type": "image", "url": "https://cdn.example.com/image.png" }] } } ``` For details, read `references/api.md` and `references/output.md`. ## Result Lifecycle And Production Notes - **Callbacks (production):** Polling `GET /v1/tasks/{taskId}` is fine for this CLI and local debugging. For production backends, HiAPI recommends a top-level `callback.url` with `when: final` so HiAPI notifies your service instead of you polling. This skill does not send `callback`; see `references/api.md`. - **Output retention (paid if extended):** Generated outputs are temporary and expire about 7 days after creation; downloads are always free. By default this skill uses the temporary tier. To keep specific outputs longer, run with `--storage persistent` — the output then uses the persistent tier, billed at `$0.05 / GB · month` (charged daily). Only suggest this after telling the user it costs money; point them to https://docs.hiapi.ai/storage/. Deleting a persistent output stops its charges. ## Check Configuration Run: ```bash node scripts/check-config.mjs ``` Use `--live` only when you want to verify that the configured key can reach the HiAPI pricing endpoint. ## Error Guidance - Missing `HIAPI_API_KEY`: tell the user to create or copy a key from https://www.hiapi.ai/en/register and export it. - HTTP `401` or `403`: tell the user to verify the HiAPI API key. - HTTP `402`, insufficient balance, credits, quota, or payment errors: tell the user to add credits or check billing at https://www.hiapi.ai/en/dashboard and review pricing at https://www.hiapi.ai/en/pricing. - HTTP `429`: tell the user to wait and retry or reduce concurrent image generations. - Content policy or safety errors: ask the user to revise the prompt. - No extractable image: explain that this skill expects `data.output[]` to contain an image URL or data URI after the task succeeds. - Optional skill update notice: tell the user the printed update command can be run later. - Required skill update notice: tell the user the printed update command must be run before creating new images. Recovery (`--resume-task-id`) and preflight still work. - Timeout or lost connection after creation: resume with `--resume-task-id`; do not create another task.