---
name: eapil-gpt2-image
description: Use when generating or editing images through the EAPIL/Playones OpenAI-compatible Images API, including gpt-image-2, image prompt enhancement, reference-image edits, masks, multipart image uploads, local prompt galleries, saved image files, or decoded b64_json image responses.
---

# EAPIL GPT Image 2

## Overview

Call the deployed OpenAI-compatible Images API at `https://api-n-cd.playones.com/v1` for `gpt-image-2` image generation and image editing. The endpoint and model are fixed. The API key must come from the user at runtime, either as a temporary direct key or from an environment variable.

This skill includes a local prompt reference library under `references/`, adapted from `https://github.com/wuyoscar/gpt_image_2_skill`, for prompt enhancement before generation.

## Hard Rules

- Use base URL `https://api-n-cd.playones.com/v1`.
- Use model `gpt-image-2`.
- Accept keys in this order: direct `--api-key`, `EAPIL_API_KEY`, then `OPENAI_API_KEY`.
- Recommend `EAPIL_API_KEY` for repeated EAPIL use, but do not refuse generation only because the user supplied a direct key or only has `OPENAI_API_KEY` set.
- Never write real API keys into skill files, source files, docs, commits, screenshots, or logs.
- Never print the full `Authorization` header or full base64 image data.
- Save decoded images into the user's opened project root by default. Do not leave final images in `/tmp` unless the user asks.
- For image edits, use multipart form data. Do not force `Content-Type` in direct `curl`; let `curl -F` set the multipart boundary.
- Before generating or editing, ask whether the user wants prompt enhancement. If enhanced, show the final prompt with Chinese comparison and wait for explicit confirm/approval before calling the API.

## API Key Policy

Preferred long-term setup:

```bash
export EAPIL_API_KEY="<user-provided-key>"
```

Accepted fallback if already configured:

```bash
export OPENAI_API_KEY="<user-provided-key>"
```

Accepted temporary key for a one-off call:

```bash
python3 scripts/eapil_gpt2_image.py generate \
  --api-key "<user-provided-key>" \
  --prompt "A realistic white-and-orange cat near a sunny window" \
  --output white-orange-cat.png
```

When a user pastes a key in chat, use it only for the current command. Recommend moving it to `EAPIL_API_KEY`, but do not block the generation.

## Prompt Enhancement Workflow

For every generation or editing request:

1. Confirm operation: generation or editing.
2. Ask: `Do you want prompt enhancement before I generate/edit the image?`
3. If the user says no, use the user's prompt unchanged.
4. If the user says yes, read `references/gallery.md` to choose the nearest category.
5. Read `references/craft.md` and the relevant `references/gallery-*.md` category file. For hybrid requests, read at most two or three relevant category files.
6. Draft an enhanced prompt using the user's intent, concrete visual constraints, and relevant gallery patterns.
7. Show the enhanced prompt in this exact three-section format:

```markdown
**API execution prompt**
<The exact prompt that will be sent to the API. Keep required in-image text in the user-requested language.>

**中文对照**
<中文对照仅供用户确认理解，review only. Do not send this section to the API unless the user explicitly asks to use it.>

**In-image text**
- "<exact visible text>" — <language>, keep exactly
```

8. Wait for the user to confirm the prompt is acceptable before API execution.
9. Run the bundled Python script from the user's opened project root unless there is a reason to use direct `curl`.
10. Save returned images as local image files in the project root, using a clear filename.

For edits, the enhanced prompt must be surgical: state what changes, what stays unchanged, and any identity/layout/text/lighting/pose/composition invariants.

Visible text inside the generated image must follow the user's requested language. The Chinese comparison is a review aid, not an instruction to translate on-image text. If the user asks for English poster copy, keep that exact English copy in `API execution prompt` and list it under `In-image text`; if the user asks for Simplified Chinese, Traditional Chinese, Japanese, or any other language in the image, preserve that exact language and wording.

## Prompt References

- `references/gallery.md`: category routing index for the full local prompt gallery.
- `references/craft.md`: cross-category prompt-craft checklist.
- `references/gallery-*.md`: concrete examples by category, including posters, UI mockups, photography, product, research figures, diagrams, anime, fashion, architecture, and edit workflows.
- `references/openai-cookbook.md`: official OpenAI image prompting guide mirror from the upstream reference set.
- `references/ATTRIBUTION.md`: source and license notes.

Use these files for prompt enhancement only. Do not import external CLI assumptions from the upstream skill; this skill keeps the EAPIL endpoint, model, and dependency-free script.

## Python Script

Prefer the bundled dependency-free Python script for stable calls: `scripts/eapil_gpt2_image.py`.

Run it from the user's project root so relative `--output` paths save into that project. It resolves the key from `--api-key`, `EAPIL_API_KEY`, or `OPENAI_API_KEY`, calls the fixed endpoint/model, decodes `b64_json` or data URL responses, writes image files, and prints JSON summaries with output paths and byte counts.

Generation:

```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py generate \
  --prompt "A realistic white-and-orange cat sitting near a sunny window, natural light, detailed fur" \
  --output white-orange-cat.png
```

Generation with a temporary direct key:

```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py generate \
  --api-key "<user-provided-key>" \
  --prompt "A clean product photo of a white ceramic mug on a walnut desk, soft morning light" \
  --quality high \
  --output white-mug.png
```

Edit:

```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
  --image input.png \
  --prompt "Turn the cat's scarf blue while preserving the cat, pose, background, and lighting" \
  --output edited-cat.png
```

Multi-reference edit:

```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
  --image person.png \
  --image product.png \
  --prompt "Place the product from image 2 beside the person in image 1. Match lighting and preserve both identities." \
  --output combined.png
```

Edit with mask:

```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
  --image input.png \
  --mask mask.png \
  --prompt "Fill the masked region with a small green plant matching the original lighting and perspective" \
  --output masked-edit.png
```

Common options:

| Option | Applies to | Notes |
|---|---|---|
| `--api-key` | both | Temporary one-off key; prefer `EAPIL_API_KEY` for repeated use. |
| `--size` | both | Default `1024x1024`. |
| `--quality` | both | `auto`, `low`, `medium`, `high`; omit when unsure about gateway support. |
| `--n` | both | Multiple outputs are saved as `_0`, `_1`, etc. |
| `--background` | both | Forwarded only when supplied. |
| `--moderation` | generation | Forwarded only when supplied. |
| `--output-format` | both | `png`, `jpeg`, or `webp`. |
| `--output-compression` | both | Forwarded only when supplied. |
| `--user` | both | Optional end-user identifier. |

## Direct API Calls

Use `POST /images/generations` with JSON if making a direct request instead of the Python script.

```bash
curl -sS "https://api-n-cd.playones.com/v1/images/generations" \
  -H "Authorization: Bearer ${EAPIL_API_KEY:-$OPENAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a white ceramic mug on a walnut desk, soft morning light",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'
```

Use `POST /images/edits` with multipart form fields for edits. Include one or more `image` files and optionally a `mask` file.

```bash
curl -sS "https://api-n-cd.playones.com/v1/images/edits" \
  -H "Authorization: Bearer ${EAPIL_API_KEY:-$OPENAI_API_KEY}" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a minimal warm studio backdrop while preserving the subject" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"
```

## Error Checks

- `401` or `403`: missing, expired, or unauthorized key.
- `404`: wrong endpoint path or deployed gateway route unavailable.
- `400`: malformed JSON, unsupported field, missing prompt, invalid multipart form, bad image format, or an optional parameter the gateway does not accept.
- Empty `data`: upstream returned no image result; inspect the response body and request log if available.
- Multipart failures: remove any manual `Content-Type` header and use `curl -F`.

## Prompt Guidance

- Generation prompts should specify canvas/aspect, subject, style, composition, lighting, background, exact text, and exclusions.
- Put required in-image text in straight quotes.
- When prompt enhancement is used, provide `API execution prompt`, `中文对照`, and `In-image text` sections before asking for confirmation.
- The Chinese comparison must not translate or replace visible image text unless the user explicitly requested Chinese visible text.
- For posters, UI, research figures, data visualizations, product renders, and Chinese text, use `references/craft.md` plus the closest gallery category before drafting.
- Edit prompts should state both what changes and what must remain unchanged.
- Prefer `response_format=b64_json` for deterministic file saving.

## Common Mistakes

- Hardcoding the user's key: always reject this, even for "fully runnable" examples.
- Refusing a user-provided key just because it is not in `EAPIL_API_KEY`.
- Ignoring `OPENAI_API_KEY` when it is already configured.
- Generating immediately after prompt enhancement without user confirm/approval.
- Sending the `中文对照` section to the API when it is only meant for review.
- Translating required `In-image text` away from the user-requested language.
- Printing raw base64 responses: summarize length or save to a file instead.
- Saving generated images outside the project root without telling the user.
- Adding unsupported convenience fields without checking the endpoint behavior.
- Setting multipart `Content-Type` manually in direct `curl`: this can break boundary parsing.
