Skill: coolhackboy/poyo-gpt-image-2 (version 1.0.0)

--- name: poyo-gpt-image-2 description: GPT Image 2 generation and editing on PoYo / poyo.ai via `https://api.poyo.ai/api/generate/submit`; use for `gpt-image-2`, `gpt-image-2-edit`, text-to-image, multi-image editing with `image_urls`, single-image output, `auto` or aspect-ratio sizes, custom `WIDTHxHEIGHT`, and 1K/2K/4K resolution control. metadata: {"openclaw":{"homepage":"https://docs.poyo.ai/api-manual/image-series/gpt-image-2","requires":{"bins":["curl"],"env":["POYO_API_KEY"]},"primaryEnv":"POYO_API_KEY"}} --- # PoYo GPT Image 2 Generation and Editing Use this skill for GPT Image 2 jobs on PoYo. It covers text-to-image generation, reference-image-guided generation, and multi-image editing payloads for `gpt-image-2` and `gpt-image-2-edit`. ## Use When - The user explicitly mentions `GPT Image 2`, `gpt-image-2`, or `gpt-image-2-edit`. - The task is text-to-image, image-to-image, or editing one or more supplied images. - The workflow needs broader aspect-ratio support, custom pixel size, or `1K` / `2K` / `4K` resolution control. ## Model Selection - `gpt-image-2`: text-to-image generation and optional reference-image-guided generation. - `gpt-image-2-edit`: editing based on one or more reference images and a text instruction; requires `image_urls`. ## Key Inputs - `prompt` is required inside `input` and is limited to 4000 characters. - `image_urls` is required for `gpt-image-2-edit` and supports multiple input images. - Each request returns a single image. - `size` supports `auto`, `1:1`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`, `16:9`, `9:16`, `21:9`, or custom `WIDTHxHEIGHT`. - `resolution` supports `1K`, `2K`, and `4K`. - Custom `WIDTHxHEIGHT` sizes require `resolution` to be `2K` or `4K`. - `auto` size or omitted `size` always uses `1K` resolution. ## Execution - Read `references/api.md` for endpoint details, model ids, key fields, example payloads, resolution notes, and polling notes. - Use `scripts/submit_gpt_image_2.sh` to submit a raw JSON payload from the shell. - If the user only needs a curl example, adapt one from `references/api.md` instead of rewriting from scratch. - After submission, report the `task_id` clearly so follow-up polling is easy. ## Output Expectations When helping with this model family, include: - chosen model id - whether the request is text-to-image, reference-guided generation, or editing - final payload or a concise parameter summary - selected `size` and `resolution` - whether reference images are involved - returned `task_id` if a request was actually submitted - next step: poll status or wait for webhook

path: scripts/submit_gpt_image_2.sh
content: #!/bin/sh
set -eu

[REDACTED_SECRET]"
if [ -z "$api_key" ]; then
  echo "Usage: submit_gpt_image_2.sh [api_key] [payload.json]" >&2
  echo "Or set POYO_API_KEY and pass [payload.json]. If no payload file is given, JSON is read from stdin." >&2
  exit 1
fi

payload="${2:-${1:+}}"
if [ -n "${POYO_API_KEY:-}" ]; then
  payload="${1:-}"
fi

if [ -n "$payload" ] && [ "$payload" != "$api_key" ]; then
  body=$(cat "$payload")
else
  body=$(cat)
fi

curl -sS https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $api_key" \
  -H 'Content-Type: application/json' \
  -d "$body"


path: references/api.md
content: # PoYo GPT Image 2 API Reference

## Endpoint

- Submit task: `https://api.poyo.ai/api/generate/submit`
- Status query: <https://docs.poyo.ai/api-manual/task-management/status>
- Source docs: <https://docs.poyo.ai/api-manual/image-series/gpt-image-2>
- Model page: <https://poyo.ai/models/gpt-image-2>
- OpenAPI JSON: <https://docs.poyo.ai/api-manual/image-series/gpt-image-2.json>

## Auth

Send:

```http
[REDACTED_SECRET]
Content-Type: application/json
```

Get API keys from <https://poyo.ai/dashboard/api-key>.

Recommended skill env var:

- `POYO_API_KEY`

## Models

- `gpt-image-2` — text-to-image generation and optional reference-image-guided generation
- `gpt-image-2-edit` — image editing from one or more reference images; requires `image_urls`

## Key input fields

- `model` (string, required) — choose `gpt-image-2` or `gpt-image-2-edit`
- `callback_url` (string, optional) — Webhook callback URL for result notifications
- `input.prompt` (string, required, max 4000 chars) — Prompt describing the target image or requested edit
- `input.image_urls` (string[], optional) — Reference image URLs; required for `gpt-image-2-edit`; supports multiple input images
- `input.size` (string, optional, default `auto`) — Output aspect ratio or custom pixel size
- `input.resolution` (string, optional, default `1K`) — Output resolution: `1K`, `2K`, or `4K`

## Size and resolution

Preset `size` values:

- `auto`
- `1:1`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`
- `16:9`, `9:16`, `21:9`

Custom size:

- Use `WIDTHxHEIGHT`, for example `2304x1536`.
- Custom size requires `resolution` to be `2K` or `4K`.
- `auto` size or omitted `size` always uses `1K` resolution.
- True `4K` billing applies only to `16:9`, `9:16`, `21:9`, or custom sizes with a 3840-pixel edge; other `4K` selections are billed as `2K`.

## Important constraints

- `gpt-image-2-edit` requires `image_urls`.
- Each request returns a single image.
- Public image URLs must be directly downloadable by the upstream provider.

## Text-to-image example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A premium product photo of a silver espresso machine on a clean white studio background, realistic lighting, high detail",
      "size": "1:1"
    }
  }'
```

## 2K generation example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A premium product photo of a silver espresso machine on a clean white studio background, realistic lighting, high detail",
      "size": "16:9",
      "resolution": "2K"
    }
  }'
```

## 4K generation example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A cinematic landscape with dramatic lighting, ultra-high detail",
      "size": "16:9",
      "resolution": "4K"
    }
  }'
```

## Custom size example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A premium product photo of a silver espresso machine on a clean white studio background",
      "size": "2304x1536",
      "resolution": "2K"
    }
  }'
```

## Edit example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2-edit",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "Use these reference images together to create a polished product photo: keep the flower subject, use the vase shape from the second image, replace the background with a clean white studio backdrop, and add a soft natural shadow",
      "image_urls": [
        "https://example.com/flower.jpg",
        "https://example.com/vase.jpg"
      ],
      "size": "1:1"
    }
  }'
```

## Polling notes

- PoYo returns a `task_id` after submission.
- If `callback_url` is present, PoYo sends a POST callback when the task reaches `finished` or `failed`.
- Whether or not callbacks are used, the same unified task status docs apply: <https://docs.poyo.ai/api-manual/task-management/status>.

## Practical guidance

- Use `gpt-image-2` for pure prompt generation; add `image_urls` only when reference-guided generation is needed.
- Use `gpt-image-2-edit` when the prompt asks to modify supplied images.
- Choose `auto` or omit `size` for default 1K output; specify `resolution` when the user needs 2K or 4K.
- Save the returned `task_id` immediately so status polling is straightforward.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)