Image-Gen

使用时机

• 用户想要根据文本描述生成 AI 图像
• 用户说“生成图片”、“画一张”、“创建图像”、“配图”
• 用户说“生成图片”、“画一张”、“AI图”
• 用户需要封面图、插图或概念图

不使用时机

• 用户想要创建音频内容（使用 /podcast、/speech）
• 用户想要创建视频（使用 /explainer）
• 用户想要编辑现有图像（不支持）
• 用户想要从 URL 提取内容（使用 /content-parser）

目的

使用 Labnana API 生成 AI 图像。支持带有可选参考图像的文本提示、多种分辨率和宽高比。图像保存为本地文件。

硬性约束

• 不使用 shell 脚本。根据资源中列出的 API 参考文件构建 curl 命令
• 始终阅读 shared/authentication.md 获取 API 密钥和请求头
• 遵循 shared/common-patterns.md 进行错误处理
• 图像生成使用不同的基础 URL：https://api.marswave.ai/openapi/v1
• 在任何交互之前，始终按照 shared/config-pattern.md 阅读配置
• 输出保存到 .listenhub/image-gen/YYYY-MM-DD-{jobId}/ — 绝不保存到 ~/Downloads/

步骤 -1：API 密钥检查

遵循 shared/config-pattern.md § API Key Check。如果密钥缺失，立即停止。

步骤 0：配置设置

遵循 shared/config-pattern.md 步骤 0（零问题引导）。

如果文件不存在 — 静默创建默认配置并继续：

mkdir -p ".listenhub/image-gen"
echo '{"outputDir":".listenhub","outputMode":"inline"}' > ".listenhub/image-gen/config.json"
CONFIG_PATH=".listenhub/image-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")

不要询问任何设置问题。 直接进入交互流程。

如果文件存在 — 静默读取配置并继续：

CONFIG_PATH=".listenhub/image-gen/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/image-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")

设置流程（仅用户主动请求重新配置时）

仅在用户明确要求重新配置时运行。显示当前设置：

当前配置 (image-gen)：
  输出方式：{inline / download / both}

然后询问：

1. outputMode：遵循 shared/output-mode.md § 设置流程问题。

立即保存：

NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")

交互流程

步骤 1：图像描述

自由文本输入。询问用户：

请描述你想要生成的图像。

如果提示词非常短（少于 10 个单词）且用户没有要求逐字生成，则提供帮助丰富提示词的建议。否则，按原样使用。

步骤 2：模型

询问：

问题："使用哪个模型？"
选项：
  - "pro (推荐)" — gemini-3-pro-image-preview，质量更高
  - "flash" — gemini-3.1-flash-image-preview，更快更便宜，支持极端宽高比 (1:4, 4:1, 1:8, 8:1)

步骤 3：分辨率和宽高比

一起询问（独立参数）：

问题："使用什么分辨率？"
选项：
  - "1K" — 标准质量
  - "2K (推荐)" — 高质量，性价比好
  - "4K" — 超高质量，生成速度较慢

问题："使用什么宽高比？"
选项（所有模型）：
  - "16:9" — 横屏，宽屏
  - "1:1" — 正方形
  - "9:16" — 竖屏，手机屏幕
  - "其他" — 2:3, 3:2, 3:4, 4:3, 21:9

如果选择了 flash 模型，还可以提供：1:4（窄竖屏）、4:1（宽横屏）、1:8（极端竖屏）、8:1（全景）

步骤 4：参考图像（可选）

问题："是否有参考图像用于风格指导？"
选项：
  - "有，我有 URL" — 提供参考图像 URL
  - "有，我有本地文件" — 提供本地文件路径
  - "无参考" — 仅根据提示词生成

URL 模式：收集 URL（逗号分隔，最多 14 个）。对于每个 URL，根据后缀推断 mimeType 并构建：

{ "fileData": { "fileUri": "<url>", "mimeType": "<推断>" } }

后缀映射：.jpg/.jpeg → image/jpeg，.png → image/png，.webp → image/webp，.gif → image/gif

本地文件（base64）模式：收集文件路径（逗号分隔，最多 14 个）。对于每个文件，编码为 base64 并根据后缀推断 mimeType：

# macOS
BASE64_REF=$(base64 -i /path/to/image.png)
# Linux
BASE64_REF=$(base64 -w 0 /path/to/image.png)

构建：

{ "inlineData": { "data": "<base64编码>", "mimeType": "<推断>" } }

后缀映射：.jpg/.jpeg → image/jpeg，.png → image/png，.webp → image/webp，.heic → image/heic，.heif → image/heif

步骤 5：确认并生成

总结所有选择：

准备生成图像：

  提示词：{提示词文本}
  模型：{pro / flash}
  分辨率：{1K / 2K / 4K}
  宽高比：{比例}
  参考图像：{有 — N 个 URL / 有 — N 个本地文件 / 无}

  继续？

在调用 API 之前等待明确确认。

工作流程

1. 构建请求：使用 provider、model、prompt、imageConfig 以及可选的 referenceImages（基于 URL 的 fileData 或基于 base64 的 inlineData）构建 JSON
2. 编码本地文件（如果使用 base64 模式）：对于每个本地文件路径，编码为 base64 并构建 inlineData 对象
3. 提交：POST https://api.marswave.ai/openapi/v1/images/generation，超时 600 秒
4. 提取图像：从响应中解析 base64 数据
5. 解码并呈现结果

从配置中读取 OUTPUT_MODE。遵循 shared/output-mode.md 的行为。

inline 或 both：将 base64 解码为临时文件，然后使用 Read 工具。

JOB_ID=$(date +%s)
echo "$BASE64_DATA" | base64 -D > /tmp/image-gen-${JOB_ID}.jpg

然后对 /tmp/image-gen-{jobId}.jpg 使用 Read 工具。图像将内联显示在对话中。

呈现：

图片已生成！

download 或 both：保存到工件目录。

JOB_ID=$(date +%s)
DATE=$(date +%Y-%m-%d)
JOB_DIR=".listenhub/image-gen/${DATE}-${JOB_ID}"
mkdir -p "$JOB_DIR"
echo "$BASE64_DATA" | base64 -D > "${JOB_DIR}/${JOB_ID}.jpg"

呈现：

图片已生成！

已保存到 .listenhub/image-gen/{YYYY-MM-DD}-{jobId}/：
  {jobId}.jpg

Base64 解码（跨平台）：

# Linux
echo "$BASE64_DATA" | base64 -d > output.jpg

# macOS
echo "$BASE64_DATA" | base64 -D > output.jpg
# 或
echo "$BASE64_DATA" | base64 --decode > output.jpg

重试逻辑：遇到 429（速率限制）时，等待 15 秒后重试。最多重试 3 次。

提示词处理

默认：直接传递用户的提示词，不做修改。

何时提供优化建议：

• 提示词非常短（几个词）且用户未要求逐字生成
• 询问：“是否需要帮助丰富提示词，添加风格/光线/构图等细节？”

绝不修改的情况：

• 长提示词、详细提示词或结构化提示词 — 认为用户是有经验的
• 用户说“请准确使用此提示词”

优化技巧（如果用户同意）：

• 风格：“赛博朋克” → 添加“霓虹灯，未来感，反乌托邦”
• 场景：一天中的时间、光线、天气
• 质量：“高度详细”、“8K 质量”、“电影级构图”
• 始终使用英文关键词（模型基于英文训练）
• 在提交前显示优化后的提示词

API 参考

• 图像生成：shared/api-image.md
• 错误处理：shared/common-patterns.md § 错误处理

可组合性

• 调用：无（直接 API 调用）
• 被调用：平台技能用于封面图（第二阶段）

示例

用户：“生成一张图片：赛博朋克城市夜景”

智能体工作流程：

1. 提示词较短 → 提供优化建议 → 用户拒绝
2. 询问模型 → “pro”
3. 询问分辨率 → “2K”
4. 询问比例 → “16:9”
5. 无参考

RESPONSE=$(curl -sS -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: skills" \
  --max-time 600 \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image-preview",
    "prompt": "cyberpunk city at night",
    "imageConfig": {"imageSize": "2K", "aspectRatio": "16:9"}
  }')

BASE64_DATA=$(echo "$RESPONSE" | jq -r '.candidates[0].content.parts[0].inlineData.data // .data')
JOB_ID=$(date +%s)
DATE=$(date +%Y-%m-%d)
JOB_DIR=".listenhub/image-gen/${DATE}-${JOB_ID}"
mkdir -p "$JOB_DIR"
echo "$BASE64_DATA" | base64 -D > "${JOB_DIR}/${JOB_ID}.jpg"

根据 outputMode 解码 base64 数据（参见 shared/output-mode.md）。

示例 2 — 使用本地参考图像（base64）

用户：“生成一张这种风格的图片”（提供本地文件路径）

智能体工作流程：

1. 询问提示词 → “a serene mountain lake at dawn”
2. 询问模型 → “pro”
3. 询问分辨率 → “2K”
4. 询问比例 → “16:9”
5. 参考图像 → 本地文件 → /path/to/style-reference.png

# 编码本地参考图像
BASE64_REF=$(base64 -i /path/to/style-reference.png)

RESPONSE=$(curl -sS -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d "{
    \"provider\": \"google\",
    \"model\": \"gemini-3-pro-image-preview\",
    \"prompt\": \"a serene mountain lake at dawn\",
    \"imageConfig\": {\"imageSize\": \"2K\", \"aspectRatio\": \"16:9\"},
    \"referenceImages\": [{\"inlineData\": {\"data\": \"$BASE64_REF\", \"mimeType\": \"image/png\"}}]
  }")

BASE64_DATA=$(echo "$RESPONSE" | jq -r '.candidates[0].content.parts[0].inlineData.data // .data')
JOB_ID=$(date +%s)
DATE=$(date +%Y-%m-%d)
JOB_DIR=".listenhub/image-gen/${DATE}-${JOB_ID}"
mkdir -p "$JOB_DIR"
echo "$BASE64_DATA" | base64 -D > "${JOB_DIR}/${JOB_ID}.jpg"

根据 outputMode 解码 base64 数据（参见 shared/output-mode.md）。