Giggle Image Generation (Multi-Model)

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

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

# 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:

{"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:

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

Image-to-Image Reference: Three Input Methods

The image-to-image API's reference_images is an array of objects. Each element can be one of these three formats (can be mixed):

Method 1: URL

{
  "prompt": "A cute orange cat sitting on the windowsill in the sun, realistic style",
  "reference_images": [
    {
      "url": "https://assets.giggle.pro/private/example/image.jpg?Policy=EXAMPLE_POLICY&Key-Pair-Id=EXAMPLE_KEY_PAIR_ID&Signature=EXAMPLE_SIGNATURE"
    }
  ],
  "generate_count": 1,
  "model": "nano-banana-2-fast",
  "aspect_ratio": "16:9",
  "watermark": false
}

Method 2: Base64

{
  "prompt": "A cute orange cat sitting on the windowsill in the sun, realistic style",
  "reference_images": [
    {
      "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
    }
  ],
  "generate_count": 1,
  "model": "nano-banana-2-fast",
  "aspect_ratio": "16:9",
  "watermark": false
}

Base64 format: Pass the raw Base64 string directly. Do not add the data:image/xxx;base64, prefix.

Method 3: asset_id

{
  "prompt": "A cute orange cat sitting on the windowsill in the sun, realistic style",
  "reference_images": [
    {
      "asset_id": "vvsdsfsdf"
    }
  ],
  "generate_count": 1,
  "model": "nano-banana-2-fast",
  "aspect_ratio": "16:9",
  "watermark": false
}

For multiple reference images, add more objects to the reference_images array.

Interaction Guide

When the user request is vague, guide per the steps below. If the user has provided enough info, run the command directly.

Step 1: Model Selection

Question: "Which model would you like to use?"
Title: "Image Model"
Options:
- "seedream45 - Realistic & creative (recommended)"
- "midjourney - Artistic style"
- "nano-banana-2 - High quality"
- "nano-banana-2-fast - Fast generation"
multiSelect: false

Step 2: Aspect Ratio

Question: "What aspect ratio do you need?"
Title: "Aspect Ratio"
Options:
- "16:9 - Landscape (wallpaper/cover) (recommended)"
- "9:16 - Portrait (mobile)"
- "1:1 - Square"
- "Other ratios"
multiSelect: false

Step 3: Generation Mode

Question: "Do you need reference images?"
Title: "Generation Mode"
Options:
- "No - Text-to-image only"
- "Yes - Image-to-image (style transfer)"
multiSelect: false

Step 4: Execute and Display

Submit task → store task_id → inform user → proactively poll --query until terminal state, with a short update after each query; on terminal state, forward links or errors from stdout.

Link return rule: Image links in results must be full signed URLs (with Policy, Key-Pair-Id, Signature query params). Do not strip or omit &response-content-disposition=attachment when the API returns it — forward links as-is so downloads behave correctly. Correct: https://assets.giggle.pro/...?Policy=...&Key-Pair-Id=...&Signature=...&response-content-disposition=attachment (order of query params may vary). Wrong: unsigned URLs with only the base path, or URLs with response-content-disposition=attachment removed.