giggle-generation-image

Giggle 图像生成（多模型）

来源：giggle-official/skills · API：giggle.pro

通过 giggle.pro 的 Generation API 生成 AI 图像。支持多种模型（Seedream、Midjourney、Nano Banana）。提交任务 → Agent 主动轮询，使用 --query 直到任务完成（参见 持续更新进度）。无需 Cron。

API 密钥：设置系统环境变量 GIGGLE_API_KEY。登录后前往 giggle.pro 获取密钥：左侧边栏 → API Key（API 密钥）。如果未配置，脚本会提示你设置。

禁止内联 Python：所有命令都必须通过 exec 工具执行。切勿使用 python3 << 'EOF' 或 heredoc 内联代码。

出错后不重试：如果脚本执行遇到错误，不要重试。直接向用户报告错误并停止。

支持的模型

模型	描述
seedream45	Seedream，写实且富有创意
midjourney	Midjourney 风格
nano-banana-2	Nano Banana 2
nano-banana-2-fast	Nano Banana 2 快速版

---

执行流程：提交并查询

图像生成是异步的（通常需要 30–120 秒）。提交任务以获取 task_id，然后持续查询，直到任务达到终止状态。

重要：切勿在 exec 的 env 参数中传入 GIGGLE_API_KEY。API 密钥从系统环境变量中读取。

---

持续更新进度（默认启用；用户无需在提示词中要求）

图像任务通常会在 约 30 秒至 2 分钟内完成。用户无需要求你检查进度。

1. 提交后立即告知用户任务已提交，提供 task_id，并说明预计耗时（通常约 30 秒至 2 分钟；批量任务或大型模型耗时更长）。
2. 主动轮询：每隔约 15–30 秒运行一次 --query，直到任务进入终止状态——不要等用户来询问。
3. 每次查询后报告状态；如果 JSON 显示 processing / pending，请转述当前状态，并告知用户你会继续检查——不要保持沉默。
4. 任务完成时：成功时提供完整的签名图像链接；失败时说明原因。如果任务在 约 15 分钟后仍未进入终止状态，请说明情况、提供 task_id，并建议重试或后续跟进。
5. 如果用户明确选择不轮询，则只提交一次并提供 task_id，只有在用户要求时才查询。

---

步骤 1：提交任务

# 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

响应示例：

{"status": "started", "task_id": "xxx"}

将 task_id 存入记忆（addMemory）：

giggle-generation-image task_id: xxx (submitted: YYYY-MM-DD HH:mm)

告知用户：图像任务已提交；你会自动轮询，并在有结果后立即报告——无需反复询问是否已完成。

---

步骤 2：持续查询直至完成（默认：主动轮询）

每次提交当前任务后，都要反复运行以下命令（每隔约 15–30 秒一次，直到任务进入终止状态或超时），不要等用户来询问：

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

行为：

• completed：向用户输出图像链接 → 停止轮询
• failed/error：输出错误消息 → 停止轮询
• processing/pending：标准输出中为 JSON → 告知用户当前状态，并说明会继续检查 → 继续轮询

如果用户在你轮询期间发问，请根据最新状态作答。

---

新请求与查询旧任务

用户发起新的图像生成请求时，运行提交命令来创建新任务。不要重复使用记忆中的旧 task_id。

对于正在进行的任务，按上述方式主动轮询。对于先前的任务，在用户询问或要求更新时，查询该 task_id（也可继续轮询）。

---

参数参考

参数	默认值	描述
--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	文生图：1K、2K、4K（图生图部分支持）
--generate-count	1	要生成的图像数量
--reference-images	-	图生图参考图；支持 URL、base64、asset_id
--watermark	false	添加水印（图生图）

---

图生图参考图：三种输入方式

图生图 API 的 reference_images 是一个对象数组。每个元素可以采用以下三种格式之一（可以混合使用）：

方法 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
}

方法 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 格式：直接传入原始 Base64 字符串。不要添加 data:image/xxx;base64, 前缀。

方法 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
}

多张参考图时，可在 reference_images 数组中添加更多对象。

---

交互指南

当用户的请求较为模糊时，请按照以下步骤引导。如果用户提供的信息足够，则直接运行命令。

步骤 1：选择模型

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

步骤 2：宽高比

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

步骤 3：生成模式

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

步骤 4：执行并展示

提交任务 → 保存 task_id → 告知用户 → 主动轮询 --query，直到任务进入终态，并在每次查询后简短更新；进入终态后，将 stdout 中的链接或错误转发给用户。

链接返回规则：结果中的图像链接必须是完整的签名 URL（包含 Policy、Key-Pair-Id、Signature 查询参数）。如果 API 返回了 &response-content-disposition=attachment，不要删除或省略该参数；请原样转发链接，以确保下载正常。正确示例：https://assets.giggle.pro/...?Policy=...&Key-Pair-Id=...&Signature=...&response-content-disposition=attachment（查询参数的顺序可能不同）。错误示例：仅包含基础路径的未签名 URL，或删除了 response-content-disposition=attachment 的 URL。