audio_codebuddy/coze-skill

Coze Skill 接入指南

概述

将我们的 TTS 能力包装成 Coze Skill，让字节系 AI 助手（豆包、Coze）能直接调用。

接入步骤

步骤 1：注册 Coze 开发者账号

1. 访问 https://www.coze.cn
2. 注册并完成企业认证（个人开发者也行）
3. 进入「开放平台」→「技能开发」

步骤 2：创建 Skill

1. 点击「创建技能」
2. 选择「API 接入」模式
3. 上传 skill.json 配置文件
4. 填入 API 基础信息：
   • Base URL: https://api.your-domain.com
   • Auth: Bearer Token

步骤 3：实现 API 后端

参考 docs/openapi/tts-api.yaml 实现以下端点：

端点	方法	说明
/v1/tts/voices	GET	列出音色
/v1/tts/detect	POST	智能推荐
/v1/tts/synthesize	POST	短文本同步合成
/v1/tts/async-synthesize	POST	长文本异步合成
/v1/tts/tasks/{task_id}	GET	查询任务
/v1/tts/instruct	POST	自然语言指令

步骤 4：测试 Skill

在 Coze 工作台：

1. 创建一个 Bot
2. 添加我们的 TTS Skill
3. 测试对话：
   • 用户：帮我用温柔女声说"你好世界"
   • Bot 应自动调用 synthesize 接口
   • 返回音频 URL 给用户

步骤 5：发布 Skill

1. 提交审核（通常 1-3 天）
2. 审核通过后上架到 Coze Skill 市场
3. 所有 Coze 用户都能搜索到并使用

关键设计要点

1. 响应式 API 设计

Coze 会根据 skill.json 自动生成调用界面，所以：

• 每个端点的 parameters 要清晰
• description 用中文，要详细
• example 给具体示例

2. 错误处理友好

Coze 会把 API 错误直接显示给用户，所以：

• 错误信息用中文
• 给出修复建议（如"文本太短，请提供至少 10 个字符"）
• 不要暴露内部错误码细节

3. 异步任务支持

长文本合成用异步模式：

• 返回 task_id 给 Coze
• Coze 用户得到"正在生成中"提示
• 通过 callback_url 通知完成
• 或让用户主动查询

4. 自然语言指令

/v1/tts/instruct 端点是杀手锏：

• 用户说"用磁性男声，悲伤语气"
• Coze 直接调用此端点
• 后端解析自然语言 → 参数 → 生成音频

商业模式

免费层

• 每月 10000 字符免费
• 吸引个人用户试用

付费层

• ¥0.001/字符（约 ¥1/千字）
• 企业用户 ¥0.0005/字符

Coze 分成

• Coze 平台抽成 20%
• 我们实际拿到 80%

流量预期

按 Coze 平台数据估算：

• 月活 Skill 平均调用量：5 万 - 50 万次/月
• 头部 TTS Skill：100 万+ 次/月
• 单次平均 200 字 → 月消耗 1 亿字
• 收入预期：¥10 万 - ¥100 万/月

下一步行动

• 注册 Coze 开发者账号
• 实现 /v1/tts/* 端点（基于现有 /tts/* 改造）
• 测试 Skill 在测试 Bot 中
• 提交审核上架
• 在 Dify、GPTs、豆包等其他平台复制