giggle-generation-image

Files (3)

• SKILL.md
• generation_api.py · scripts/
• requirements.txt · scripts/

SKILL.md (first lines)

# Giggle Image Generation (Multi-Model)

**Source**: [giggle-official/skills](https://github.com/giggle-official/skills) · API: [giggle.pro](https://giggle.pro/)

Generates AI images via giggle.pro's Generation API. Supports multiple models (Seedream, Midjourney, Nano Banana). Submit task → **agent proactively polls** with `--query` until done (see **Continuous progress updates**). No Cron.

**API Key**: Set system environment variable `GIGGLE_API_KEY`. Obtain the key at [giggle.pro](https://giggle.pro/) while logged in: **left sidebar** → **API Key** (**API 密钥**). The script will prompt if not configured.

> **No inline Python**: All commands must be executed via the `exec` tool. **Never** use `python3 << 'EOF'` or heredoc inline code.

> **No Retry on Error**: If script execution encounters an error, **do not retry**. Report the error to the user directly and stop.

## Supported Models

| Model | Description |
|-------|-------------|
| seedream45 | Seedream, realistic and creative |
| midjourney | Midjourney style |
| nano-banana-2 | Nano Banana 2 |
| nano-banana-2-fast | Nano Banana 2 fast |

---

## Execution Flow: Submit and Query

Image generation is asynchronous (typically 30–120 seconds). **Submit** a task to get `task_id`, then **query** until the task reaches a terminal state.

> **Important**: **Never** pass `GIGGLE_API_KEY` in exec's `env` parameter. API Key is read from system environment variable.

---

## Continuous progress updates (default; user need not put this in their prompt)

Image jobs usually finish in **~30 seconds–2 minutes**. The user does **not** need to ask you to check progress.

1. **Right after submit**, say you submitted, give `task_id`, and set expectations (~30s–2m typical; longer if batch or heavy model).
2. **Poll proactively**: run `--query` about every **15–30 seconds** until terminal—**do not** wait for the user to ask.
3. **After each query**, report status; for `processing` / `pending` JSON, paraphrase and say you will keep checking—**do not** go silent.
4. **When done**: forward full **signed image** links on success; explain failures. If still non-terminal after **~15 minutes**, explain, give `task_id`, and suggest retry or follow-up.
5. **If the user explicitly opts out** of polling, submit once + `task_id`, then query only when they ask.

---

### Step 1: Submit Task

```bash
# Text-to-image (default seedream45)
python3 scripts/generation_api.py \
  --prompt "description" --aspect-ratio 16:9 \
  --model seedream45 --resolution 2K \
  --no-wait --json

# Text-to-image - Midjourney
python3 scripts/generation_api.py \
  --prompt "description" --model midjourney \
  --aspect-ratio 16:9 --resolution 2K \
  --no-wait --json

# Image-to-image - Reference URL
python3 scripts/generation_api.py \
  --prompt "Convert to oil painting style, keep composition" \
  --reference-images "https://example.com/photo.jpg" \
  --model nano-banana-2-fast \
  --no-wait --json

# Batch generate multiple images
python3 scripts/generation_api.py \
  --prompt "description" --generate-count 4 \
  --no-wait --json
```

Response example:
```json
{"status": "started", "task_id": "xxx"}
```

**Store task_id in memory** (`addMemory`):
```
giggle-generation-image task_id: xxx (submitted: YYYY-MM-DD HH:mm)
```

**Tell the user**: Image task submitted; you will poll automatically and report as soon as there is a result—no need to repeatedly ask if it is ready.

---

### Step 2: Query Until Done (default: proactive polling)

After each submit for the **current** task, **repeatedly** run (every ~15–30s until terminal or timeout), **without waiting for the user to ask**:

```bash
python3 scripts/generation_api.py --query --task-id <task_id>
```

**Behavior**:
- **completed**: Output image links for user → **stop** polling
- **failed/error**: Output error message → **stop** polling
- **processing/pending**: JSON in stdout → tell user status + that you will keep checking → **continue** polling

If the user asks while you are polling, answer with the latest status.

---

## New Request vs Query Old Task

**When the user initiates a new image generation request**, run submit to create a new task. Do not reuse old task_id from memory.

**For the in-flight task**, use proactive polling as above. **For a previous task**, query (and optionally poll) that `task_id` when the user asks or requests updates.

---

## Parameter Reference

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--prompt` | required | Image description prompt |
| `--model` | seedream45 | seedream45, midjourney, nano-banana-2, nano-banana-2-fast |
| `--aspect-ratio` | 16:9 | 16:9, 9:16, 1:1, 3:4, 4:3, 2:3, 3:2, 21:9 |
| `--resolution` | 2K | Text-to-image: 1K, 2K, 4K (image-to-image partially supported) |
| `--generate-count` | 1 | Number of images to generate |

From giggle-official/skills, MIT.

More from giggle-official/skills