GPT-Image-2.5 / 2 Серия навыка агента

pip install openai

gpt-image-2/
├── SKILL.md
├── scripts/
│   └── gpt_image.py
└── .env          # created in step ②, holds your key

APIYI_API_KEY=sk-your-api-key

---
name: gpt-image-2
description: Generate or edit images via APIYI's GPT-Image 2.5 / 2 series — gpt-image-2.5-flare / gpt-image-2.5-sunburst / gpt-image-2 (official) and gpt-image-2.5-all / gpt-image-2-all / gpt-image-2-vip (reverse). Use this when the user asks to create, draw, render, or generate an image/illustration/poster, or to edit, retouch, restyle, fuse, or inpaint existing images.
allowed-tools: Bash(python3 *)
---

# GPT-Image-2 Series Image Skill

Generate or edit images through the APIYI platform using the GPT-Image 2.5 / 2 series. One script covers six models, switched by `--model`:

- `gpt-image-2.5-flare` (default, official): speed-first; supports `size` / `quality` (incl. `xhigh` / `max`) / `mask` inpainting; token-based billing.
- `gpt-image-2.5-sunburst` (official): editing-precision-first, same parameters as flare; the pick for edits / multi-image fusion.
- `gpt-image-2` (official): previous generation, same parameters (`quality` up to `high`).
- `gpt-image-2.5-all` (reverse): ChatGPT web 2.5 reverse line, flat \$0.03/img, same parameters as `-all`.
- `gpt-image-2.5-flare-vip` / `gpt-image-2.5-sunburst-vip` (reverse, Adobe line 2.5): flat \$0.03/img, lockable `size`, `quality` (up to `high`) and transparent background; `mask` only regenerates the whole image.
- `gpt-image-2-all` (reverse, ChatGPT line): fastest, flat \$0.03/img; **no `size`/`quality`** — put size in the prompt.
- `gpt-image-2-vip` (reverse, Adobe line): can lock `size` (30 tiers incl. 4K), flat \$0.03/img; **no `quality`/`mask`**.

## Key configuration

The script auto-reads `APIYI_API_KEY` from a `.env` file in the skill folder (an environment variable of the same name also works).
The script depends on the OpenAI SDK; if it reports a missing package, ask the user to run `pip install openai`.

## Usage

The first argument is the prompt; for editing/fusion, pass one or more local image paths with `-i`:

```bash
# Изображение из текста (по умолчанию официальный gpt-image-2.5-flare, с качеством)
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Оранжевый кот в солнечных очках в баре на берегу моря, кинематографичный стиль" -o cat.png --size 1536x1024 --quality high

# Самый быстрый и дешёвый вариант: обратный 'all' (укажите размер в промпте, не передавайте size)
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Постер фестиваля в плоской иллюстративной стилистике, книжная ориентация 2:3" -o poster.png --model gpt-image-2-all

# Нужен фиксированный 4K: обратный 'vip'
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Ночной вид на город с высоты птичьего полёта" -o city.png --model gpt-image-2-vip --size 3840x2160

# Объединение нескольких изображений (до 16, повторяйте -i)
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Поместите человека с изображения 1 в сцену изображения 2, сохраните цвета изображения 3" -i person.png -i scene.png -i style.png -o fused.png

# Ретуширование (маска, только официальные модели; рекомендуется gpt-image-2.5-sunburst)
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Замените область под маской круглым окном" -i room.png --mask mask.png -o edited.png

# Несколько одновременно (максимум 5, параллельно)
python3 ${CLAUDE_SKILL_DIR}/scripts/gpt_image.py "Черновые варианты постера фестиваля" -o draft.png -n 3 --model gpt-image-2-all
```

Arguments:

- 1st positional arg: the prompt (required).
- `--model`: `gpt-image-2` (default) / `gpt-image-2-all` / `gpt-image-2-vip`. You can also set a default with `APIYI_IMAGE_MODEL=...` in `.env`.
- `-i / --image`: input image path, repeatable (up to 16); omitted = text-to-image, present = edit/fusion.
- `-o / --out`: output filename, defaults to `output.png`.
- `-n / --count`: how many at once, **default 1**, max 5 (client-side concurrency; the script never sends `n`, avoiding per-image overbilling on reverse channels).
- `--size`: size, default `auto` (`gpt-image-2-all` ignores it — write size/ratio into the prompt).
- `--quality`: `low`/`medium`/`high`/`xhigh`/`max`/`auto`, **only effective on the three official models** (`xhigh` / `max` on the two 2.5 models only; the script omits it for reverse models).
- `--format`: `png`/`jpeg`/`webp`, official only.
- `--mask`: mask image, official edit only (PNG with alpha, applies to the first image).
- `--background`: `transparent`/`opaque`/`auto`, official only. With `transparent`, `--format` must be `png` or `webp`.

## Choice & red lines (important)

- **Default `gpt-image-2.5-flare` (official)**: everyday text-to-image; switch to `gpt-image-2.5-sunburst` for edits and mask inpainting.
- **Fast/cheap** → `gpt-image-2.5-all` / `gpt-image-2-all`; **locked size/4K** → `gpt-image-2-vip`.
- For reverse models (all/vip), **never pass `quality`**; for **`gpt-image-2-all` never pass `size`** (put it in the prompt). The script gates this automatically, but follow it when calling the script directly too.
- **Transparent backgrounds**: only the three official models have a `background` parameter. Add `--background transparent` to get a real alpha-channel image (`--format` must be `png`/`webp`). The reverse models all/vip have no such parameter — you can only ask for it in the prompt, and it is occasionally unreliable.

## Number of images & cost

- **Default to a single image**; use `-n` only when the user explicitly asks, max 5.
- Reverse 2.5-all/all/vip are flat \$0.03/img; the official models are token-based and `--quality high` is pricier (~\$0.05–0.21/img at 1K, `xhigh` / `max` more) — drop to `medium`/`low` or use a reverse model when budget matters.

## Output location (important)

- A **bare filename** for `-o` saves into a **`gpt-image-output/` folder at the project root**; a **path with a directory** is saved as given.
- Do not write images to `/tmp`, scratchpad, or other temp directories — the user won't find them.

## After running

The script prints one full path per image — report them all back to the user. If a request is rejected by moderation, relay the reason as-is and do not retry the same prompt.

#!/usr/bin/env python3
"""Generate / edit images via APIYI's gpt-image-2 series (gpt-image-2 official / gpt-image-2-all / gpt-image-2-vip reverse).
All use the OpenAI Images API (/v1/images/generations + /v1/images/edits), switched by --model. Needs: pip install openai"""
import argparse
import base64
import os
import sys
import urllib.request
from concurrent.futures import ThreadPoolExecutor

from openai import OpenAI

# Max images generated concurrently per call (server returns 1 per call; this simulates more client-side)
MAX_COUNT = 5

# Per-model capability gating: whether these params are accepted (never send the unaccepted ones)
MODEL_CAPS = {
    "gpt-image-2.5-flare":    {"size": True,  "quality": True,  "output_format": True,  "mask": True,  "background": True},   # official, speed-first
    "gpt-image-2.5-sunburst": {"size": True,  "quality": True,  "output_format": True,  "mask": True,  "background": True},   # official, editing-first
    "gpt-image-2":     {"size": True,  "quality": True,  "output_format": True,  "mask": True,  "background": True},   # official, previous gen
    "gpt-image-2.5-all": {"size": False, "quality": False, "output_format": False, "mask": False, "background": False},  # reverse, ChatGPT 2.5
    "gpt-image-2-all": {"size": False, "quality": False, "output_format": False, "mask": False, "background": False},  # reverse, ChatGPT
    "gpt-image-2-vip": {"size": True,  "quality": False, "output_format": False, "mask": False, "background": False},  # reverse, Adobe
    "gpt-image-2.5-flare-vip":    {"size": True,  "quality": True,  "output_format": False, "mask": False, "background": True},   # reverse, Adobe 2.5 (quality up to high; mask is not inpainting)
    "gpt-image-2.5-sunburst-vip": {"size": True,  "quality": True,  "output_format": False, "mask": False, "background": True},   # reverse, Adobe 2.5
    "gpt-image-2.5-vip":          {"size": True,  "quality": True,  "output_format": False, "mask": False, "background": True},   # alias of sunburst-vip
}


def caps_of(model):
    # Unknown models fall back to the official capability set
    return MODEL_CAPS.get(model, MODEL_CAPS["gpt-image-2.5-flare"])


def load_api_key():
    """Prefer the env var; otherwise look for a .env in the script dir and its parent."""
    key = os.environ.get("APIYI_API_KEY")
    if key:
        return key
    here = os.path.dirname(os.path.abspath(__file__))
    for d in (here, os.path.dirname(here)):
        env_path = os.path.join(d, ".env")
        if os.path.exists(env_path):
            with open(env_path, encoding="utf-8") as f:
                for line in f:
                    line = line.strip()
                    if line.startswith("APIYI_API_KEY") and "=" in line:
                        return line.split("=", 1)[1].strip().strip('"').strip("'")
    return None


def project_root():
    """Walk up from the script location to the first dir containing .git or .claude; else cwd."""
    d = os.path.dirname(os.path.abspath(__file__))
    while True:
        if os.path.isdir(os.path.join(d, ".git")) or os.path.isdir(os.path.join(d, ".claude")):
            return d
        parent = os.path.dirname(d)
        if parent == d:
            return os.getcwd()
        d = parent


def resolve_paths(out, count):
    """Decide output paths. Bare filename -> <project_root>/gpt-image-output/; a path with a dir -> as given."""
    if os.path.dirname(out):
        base_path = os.path.abspath(out)
    else:
        out_dir = os.path.join(project_root(), "gpt-image-output")
        os.makedirs(out_dir, exist_ok=True)
        base_path = os.path.join(out_dir, out)

    if count == 1:
        return [base_path]
    base, ext = os.path.splitext(base_path)
    return [f"{base}-{i}{ext}" for i in range(1, count + 1)]


def decode_image(item):
    """Get image bytes: b64_json may be pure base64 or a data:image-prefixed data URL (reverse models); or only a url."""
    raw = getattr(item, "b64_json", None)
    if raw:
        if raw.startswith("data:"):
            raw = raw.split(",", 1)[1]  # strip the data:image/png;base64, prefix
        return base64.b64decode(raw)
    url = getattr(item, "url", None)
    if url:
        with urllib.request.urlopen(url, timeout=360) as r:
            return r.read()
    raise RuntimeError("response has neither b64_json nor url")


def one_image(client, model, args):
    """Make one request, return image bytes; raise on failure (caught by _safe). Never sends n (default 1; concurrency for more)."""
    cap = caps_of(model)
    if args.image:
        # Edit / multi-image fusion: reopen files each call to avoid sharing handles across threads
        files = [open(p, "rb") for p in args.image]
        try:
            kwargs = dict(model=model, image=files if len(files) > 1 else files[0], prompt=args.prompt)
            if cap["size"] and args.size:
                kwargs["size"] = args.size
            if cap["quality"] and args.quality:
                kwargs["quality"] = args.quality
            if cap["output_format"] and args.format:
                kwargs["output_format"] = args.format
            if cap["background"] and args.background and args.background != "auto":
                kwargs["background"] = args.background
            if cap["mask"] and args.mask:
                kwargs["mask"] = open(args.mask, "rb")
            resp = client.images.edit(**kwargs)
        finally:
            for fh in files:
                fh.close()
    else:
        # Text to image
        kwargs = dict(model=model, prompt=args.prompt)
        if cap["size"] and args.size:
            kwargs["size"] = args.size
        if cap["quality"] and args.quality:
            kwargs["quality"] = args.quality
        if cap["output_format"] and args.format:
            kwargs["output_format"] = args.format
        if cap["background"] and args.background and args.background != "auto":
            kwargs["background"] = args.background
        resp = client.images.generate(**kwargs)
    return decode_image(resp.data[0])


def main():
    api_key = load_api_key()
    if not api_key:
        sys.exit("No API key found: add a line APIYI_API_KEY=sk-xxx to the .env in the skill folder")

    default_model = os.environ.get("APIYI_IMAGE_MODEL", "gpt-image-2.5-flare")
    # Synchronous blocking call; image generation is slow, so give a generous 360s timeout
    client = OpenAI(api_key=api_key, base_url="https://api.apiyi.com/v1", timeout=360)

    parser = argparse.ArgumentParser(description="GPT-Image 2.5 / 2 series image generation")
    parser.add_argument("prompt", help="Prompt / edit instruction")
    parser.add_argument("--model", default=default_model,
                        help="gpt-image-2.5-flare (official, default) / gpt-image-2.5-sunburst (official, edits) / gpt-image-2 (official, previous gen) / gpt-image-2.5-all / gpt-image-2-all (reverse, fastest) / gpt-image-2-vip (reverse, lockable size) / gpt-image-2.5-flare-vip / gpt-image-2.5-sunburst-vip (reverse 2.5, lockable size + quality)")
    parser.add_argument("-i", "--image", action="append", default=[],
                        help="Input image path (repeatable, up to 16; presence = edit/fusion mode)")
    parser.add_argument("-o", "--out", default="output.png", help="Output filename")
    parser.add_argument("-n", "--count", type=int, default=1,
                        help=f"How many at once, default 1, max {MAX_COUNT} (client-side concurrency)")
    parser.add_argument("--size", default="auto",
                        help="Size, e.g. 1024x1024 / 2048x1152 / auto (gpt-image-2-all ignores it; put it in the prompt)")
    parser.add_argument("--quality", default="high",
                        help="Quality low / medium / high / auto (only effective on gpt-image-2 official)")
    parser.add_argument("--format", default="png", help="Output format png / jpeg / webp (official only)")
    parser.add_argument("--mask", help="Mask image (official edit only, PNG with alpha, applies to the first image)")
    parser.add_argument("--background", default="auto", choices=["transparent", "opaque", "auto"],
                        help="Background; transparent yields an alpha-channel image (official only, needs --format png/webp)")
    args = parser.parse_args()

    # jpeg has no alpha channel and is mutually exclusive with transparency — catch it locally, do not hand the user a 400
    if args.background == "transparent" and args.format == "jpeg":
        sys.exit("--background transparent cannot be combined with --format jpeg (no alpha channel); use png or webp")

    count = args.count
    if count < 1:
        count = 1
    if count > MAX_COUNT:
        print(f"Note: max {MAX_COUNT} at once; clamped {args.count} to {MAX_COUNT}.", file=sys.stderr)
        count = MAX_COUNT

    paths = resolve_paths(args.out, count)

    def task(path):
        data = one_image(client, args.model, args)
        with open(path, "wb") as f:
            f.write(data)
        return os.path.abspath(path)

    failures = 0
    with ThreadPoolExecutor(max_workers=count) as pool:
        for path, result in zip(paths, pool.map(lambda p: _safe(task, p), paths)):
            ok, value = result
            if ok:
                print(f"Image saved to {value}")
            else:
                failures += 1
                print(f"Image {os.path.basename(path)} failed: {value}", file=sys.stderr)

    if failures == count:
        sys.exit("All generations failed.")


def _safe(fn, arg):
    try:
        return True, fn(arg)
    except Exception as e:  # noqa: BLE001 — one failure should not abort the other concurrent tasks
        return False, str(e)


if __name__ == "__main__":
    main()

... gpt_image.py "prompt"                              # default gpt-image-2.5-flare (official, speed-first)
... gpt_image.py "make it watercolor" -i in.png --model gpt-image-2.5-sunburst   # official, editing-first
... gpt_image.py "prompt" --model gpt-image-2            # official, previous generation
... gpt_image.py "prompt" --model gpt-image-2.5-all      # reverse, ChatGPT web 2.5
... gpt_image.py "prompt" --model gpt-image-2-all      # reverse, fastest, cheapest
... gpt_image.py "prompt" --model gpt-image-2-vip --size 3840x2160   # reverse, locked 4K

APIYI_IMAGE_MODEL=gpt-image-2-all