Flyapsara TTS Skill

注册账号与创建 FLYAPSARA_API_KEY

• 在 Flyapsara 官网完成注册并登录（用户门户一般为 https://service.flyapsara.com；HTTP API 的 Base 默认为 https://service.flyapsara.com/api，与门户可能为同一主机、不同路径）。
• 登录后进入 API Key 管理（站点路由一般为 /account/api-keys，须在已登录状态下打开）。
• 新建 Key 时勾选（或授予）至少：voice:read、tts:task:create；若控制台提供试用相关权限，可选用 tts:trial:create 替代或与上述组合按官方说明为准。
• 创建成功后复制 sk_live_...，在运行环境配置 export FLYAPSARA_API_KEY='...'（或宿主等价方式）。勿把完整 Key 写入仓库、日志或聊天公开内容。
• 使用自建或私有化网关时，将 FLYAPSARA_BASE_URL 设为实际 API 根路径（须含网关前缀；公开默认值见 openapi.yaml 的 servers）。

何时使用

• 将文本转为语音、旁白、配音、朗读、生成 wav/mp3/pcm
• 方言、口音、情绪、风格（与网页「高级设置 → 自然语言控制」一致 → 使用 instruct2）

用户已给出可朗读的具体文本且希望听到音频时，应通过本 API 完成合成（勿仅用文字模拟朗读声、勿编造「不支持某方言」——方言由 instruct_text 描述，不依赖单独「方言音色名」）。

适用场景

• 视频配音、有声书片段、语音播报、内容朗读

不要使用

• 仅询问 TTS 原理、比较不同服务商
• 没有可提供合成的具体文本

行为优先级

• 用户明确要「生成语音 / 朗读 / 配音」且有正文：优先走 TTS API，不要只输出拟声文字或只解释步骤
• 细节与响应示例见 openapi.yaml、README.md

必填参数缺省策略（给 AI）

| 参数 | 用户未提供时 |

|------|----------------|

| voice_id | 先 GET /v1/tts/voices，从 data.voices[] 选一项的 voice_id（平台 + 当前 Key 用户克隆；含 is_user_voice / owner_user_id）。禁止编造 UUID。缺省可取列表第一项；instruct2 时须选带参考音的项（见下节）。 |

| output_format | 可省略；服务端默认 mp3。要 wav/pcm 再在 body 写明。 |

| language | 默认 zh；其他语言再显式指定。 |

| mode | 默认 zero_shot；方言/风格用 instruct2。 |

| text（instruct2） | 少于 6 个字符：优先请用户补充；无法交互时可扩写为不改变原意的短句，否则可能 INVALID_TEXT_TOO_SHORT。 |

HTTP 调用（给 AI / 集成方）

• Base：$FLYAPSARA_BASE_URL，默认 https://service.flyapsara.com/api
• 鉴权：Authorization: Bearer
• 信封：{ "ok": true|false, "data": ..., "error": ... }（见 openapi.yaml）
• 流程：

1. GET /v1/tts/voices → 选取合法 voice_id
2. POST /v1/tts/tasks（body 含 text、voice_id；reference_asset_id 已废弃）；建议头 Idempotency-Key
3. 轮询 GET /v1/tts/tasks/{task_id}（策略见下）
4. 仅当 data.status === succeeded 后请求 GET /v1/tts/tasks/{task_id}/result → data.result.download.url

轮询策略（须遵守）

• 间隔：约 2 秒
• 上限：建议 60 次（约 120s）；超时则停止轮询，向用户返回 task_id 并说明超时
• 终态：succeeded、failed、cancelled；中间态含 queued、running；亦可能出现 cancel_requested，继续轮询直至终态

失败处理（给 AI）

| 情况 | 建议 |

|------|------|

| 401 | Key 缺失/无效；检查 Authorization 与环境变量 |

| 403 | scope 不足；引导用户调整 Key |

| 429 | 配额用尽；稍后重试 |

| 创建任务后 voice / 参考音报错 | 重新 GET /v1/tts/voices，换 voice_id（instruct2 时优先换带 reference_asset_id 的项） |

| 轮询超时 | 返回 task_id，建议稍后 GET .../tasks/:id 自查 |

| failed / cancelled | 任务未成功结束时勿再依赖 /result 获取音频；向用户说明状态并附 task_id |

| GET .../result 返回 409（如 RESULT_NOT_READY） | 继续轮询任务状态后再请求 |

| download.url 403 或过期 | 重新 GET .../result；勿缓存为永久链接 |

交付给用户的内容（Agent）

• 具备落盘/本地文件能力的运行时：若已下载到本地可访问路径，可返回本地路径或平台提供的文件引用
• 否则：返回 data.result.download.url 与过期说明（预签名 URL 非永久）
• 落盘命名（可选）：tts_.；目录以当前工作目录为准。/mnt/data 等路径仅适用于部分沙箱，其他环境按实际可写目录处理

调用参数建议

• text（必填）
• voice_id（必填）：仅来自 GET /v1/tts/voices 返回的 UUID
• language：可省略时默认 zh
• output_format：省略则服务端 mp3；可选 wav / pcm
• mode：常用 zero_shot；方言/风格用 instruct2
• instruct_text：不要单独造 dialect 字段；方言、情绪、风格均写入 instruct_text；仅 mode=instruct2 时必填
• speed：约 0.4～2.0，默认 1

方言 / 自然语言控制（instruct2）

• 用户明确提到方言、口音、情绪、风格时，使用 mode: instruct2，并把指令写入 instruct_text（如「请用四川话表达。」）
• voice_id：必须来自本次 GET /v1/tts/voices 的列表项，不得伪造。方言由 instruct_text 控制，不是通过「查找叫四川话的 voice_id」实现
• instruct2 时：应选用返回项中 reference_asset_id 非空（已配置默认参考音）的音色，避免任务因缺参考失败；若首条无参考音，换选有参考的项
• 与官网一致：instruct2 + instruct_text + text。正文少于 6 个字符时优先请用户补充；自动化时可扩写为不改变原意的完整短句

示例请求体：

{
  "mode": "instruct2",
  "instruct_text": "请用四川话表达。",
  "text": "今天我要去玩。",
  "voice_id": "<从 GET /v1/tts/voices 选取且 reference_asset_id 非空的 voice_id>"
}

验证脚本（约 1 分钟）

scripts/smoke-tts.sh 为端到端示例，需 bash。scripts/run-smoke.sh 用于在换行符为 CRLF 的环境下调用主脚本。分发本 Skill 时请将二者置于同一 scripts/ 目录；run-smoke.sh 使用进程替换 <(...)，同样需要 bash。

cd /path/to/flyapsara-tts   # 改为本 Skill 实际所在路径
export FLYAPSARA_API_KEY="sk_live_你的密钥"
# 可选：export FLYAPSARA_BASE_URL="https://service.flyapsara.com/api"
bash scripts/smoke-tts.sh

方言示例：

export TTS_MODE=instruct2
export TTS_INSTRUCT_TEXT="请用广东话表达。"
export TTS_TEXT="今日天气不错，适合出门走走。"
bash scripts/smoke-tts.sh

依赖：curl；jq 与 python3 至少其一。Debian/Ubuntu：sudo apt install -y curl jq。Windows 拷贝后若报 $'\r'：先 bash scripts/run-smoke.sh，或对 smoke-tts.sh 去 CRLF。

调用策略

• 优先默认参数，除非用户明确要求
• 文本过长可分段调用