Giggle Generation Speech

文转音（Text-to-Audio）

通过 giggle.pro 平台将文本合成为 AI 语音/配音。支持多种音色、情绪和语速。

API Key：从环境变量 GIGGLE_API_KEY 或项目根目录 .env 文件中读取。

禁止内联 Python：所有命令必须通过 exec 工具直接执行。切勿使用 heredoc 内联代码。

执行流程（阶段 1 提交 + 阶段 2 Cron + 阶段 3 同步兜底）

语音生成通常需要 10–30 秒。采用「快速提交 + Cron 轮询 + 同步兜底」三阶段架构。

重要：切勿在 exec 的 env 参数中传递 GIGGLE_API_KEY。API Key 通过系统环境配置；脚本会自动读取。

阶段 0：引导用户选择音色与情绪（必须）

在提交任务前，必须先引导用户选择音色和情绪，不要使用默认值。

1. 执行 --list-voices 获取可用音色列表：

python3 scripts/text_to_audio_api.py --list-voices

2. 将音色列表以易读的方式展示给用户（包含 voice_id、name、style、gender 等信息），引导用户选择一个音色
3. 询问用户期望的情绪（如 joy、sad、neutral、angry、surprise 等），如用户无特殊要求可选 neutral
4. 用户确认音色和情绪后，再进入阶段 1 提交任务

阶段 1：提交任务（exec 在 10 秒内完成）

先向用户发送消息：「语音生成进行中，通常需要 10–30 秒，结果将自动发送。」

# 必须指定用户选择的音色和情绪
python3 scripts/text_to_audio_api.py \
  --text "今天天气真好" \
  --voice-id "Calm_Woman" \
  --emotion "joy" \
  --speed 1.2 \
  --no-wait --json

# 查看可用音色列表
python3 scripts/text_to_audio_api.py --list-voices

响应示例：

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

立即将 task_id 存入记忆（addMemory）：

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

阶段 2：注册 Cron（30 秒间隔）

使用 cron 工具注册轮询任务。必须严格遵循参数格式：

{
  "action": "add",
  "job": {
    "name": "giggle-generation-speech-<task_id 前 8 位>",
    "schedule": {
      "kind": "every",
      "everyMs": 30000
    },
    "payload": {
      "kind": "systemEvent",
      "text": "语音任务轮询：执行 exec python3 scripts/text_to_audio_api.py --query --task-id <完整 task_id>，按 Cron 逻辑处理 stdout。若 stdout 为非 JSON 纯文本，发送给用户并移除 Cron。若 stdout 为 JSON，不发送消息，继续等待。若 stdout 为空，立即移除 Cron。"
    },
    "sessionTarget": "main"
  }
}

Cron 触发处理（根据 exec stdout 判断）：

阶段 3：同步等待（乐观路径，Cron 未触发时的兜底）

无论 Cron 是否注册成功，都必须执行此步骤。

python3 scripts/text_to_audio_api.py --query --task-id <task_id> --poll --max-wait 120

处理逻辑：

• 返回纯文本（语音就绪/失败消息） → 原样转发给用户，移除 Cron
• stdout 为空 → Cron 已推送，移除 Cron，不发送消息
• exec 超时 → Cron 继续轮询

查看声音列表

当用户想查看可用音色时，执行：

python3 scripts/text_to_audio_api.py --list-voices

脚本会调用 GET /api/v1/project/preset_tones，将返回的 voice_id、name、style、gender、age、language 等字段展示给用户，方便用户选择。

链接返回规范

返回给用户的音频链接必须为完整签名 URL（含 Policy、Key-Pair-Id、Signature 等查询参数）。正确示例：https://assets.giggle.pro/...?Policy=...&Key-Pair-Id=...&Signature=...。错误：不要返回仅含基础路径的未签名 URL（无查询参数）。脚本已自动处理 ~ 编码为 %7E，转发时保持原样。

新请求 vs 查询旧任务

当用户发起新的语音生成请求时，必须执行阶段 1 提交新任务，不要复用记忆中的旧 task_id。

仅当用户明确询问之前任务的进度时，才从记忆中查询旧 task_id。

参数速查

交互引导

每次生成语音前，必须完成以下交互：

1. 若用户未提供文本，询问：「您想把哪段文字转换成语音？」
2. 必须引导用户选择音色：执行 --list-voices 获取音色列表，展示给用户并让用户选择，不要使用默认音色
3. 必须引导用户选择情绪：询问用户期望的情绪风格（如 joy、sad、neutral、angry、surprise 等）
4. 用户确认文本、音色、情绪后，再执行阶段 1 提交 → 阶段 2 注册 Cron → 阶段 3 同步等待