--- name: tomoviee-text2sfx description: 通过 Wondershare OpenAPI 网关（https://openapi.wondershare.cc）调用 Tomoviee 文本转音效 API（tm_text2sfx），根据文本提示生成音效。当用户请求执行 text_to_sound_effect 操作或相关任务时使用。

Tomoviee AI 文本转音效

概述

根据文本提示生成音效。

• API 能力标识：tm_text2sfx
• 任务创建端点：https://openapi.wondershare.cc/v1/open/capacity/application/tm_text2sfx
• 结果查询端点：https://openapi.wondershare.cc/v1/open/pub/task

服务提供商与端点来源验证

请使用以下映射关系验证服务提供商身份及运行时端点：

• 厂商门户：https://www.tomoviee.ai 和 https://www.tomoviee.cn
• 本技能所使用的 API 网关主机：https://openapi.wondershare.cc
• 本技能仅向 openapi.wondershare.cc 发起运行时 API 调用

凭证处理

• app_key 和 app_secret 仅用于构造 Authorization: Basic 请求头。
• 凭证仅驻留在进程内存中，本技能不会将其写入磁盘。
• 切勿将凭证提交至 SKILL.md、脚本文件或代码仓库中的任何文件。

快速开始

安装依赖

pip install requests

身份认证

python scripts/generate_auth_token.py YOUR_APP_KEY YOUR_APP_SECRET

Python 客户端

from scripts.tomoviee_text2sfx_client import TomovieeText2SfxClient

client = TomovieeText2SfxClient("app_key", "app_secret")

API 使用方法

基础示例

task_id = client.text_to_sound_effect(
    prompt="Heavy rain falling on roof with distant thunder",
    duration=30,
    qty=1,
)

result = client.poll_until_complete(task_id)
import json
audio_url = json.loads(result["result"])["audio_path"][0]
print(audio_url)

参数说明

• prompt（必填）：音效描述文本
• duration（必填）：音效持续时间（单位：秒），取值范围为 5–180
• qty（可选）：生成结果数量，取值范围为 1–4
• callback（可选）：回调 URL
• params（可选）：透传回调参数

异步工作流

1. 创建任务并获取 task_id
2. 调用 poll_until_complete(task_id) 轮询任务状态直至完成
3. 从 result 中解析输出音频 URL

任务状态码：

• 1：排队中（queued）
• 2：处理中（processing）
• 3：成功（success）
• 4：失败（failed）
• 5：已取消（cancelled）
• 6：超时（timeout）

资源文件

• scripts/tomoviee_text2sfx_client.py — 主 API 客户端实现
• scripts/tomoviee_text_to_sound_effect_client.py — 兼容性导入适配层
• scripts/generate_auth_token.py — 认证令牌生成辅助工具
• references/audio_apis.md — 针对 tm_text2sfx 的精简 API 参考文档
• references/prompt_guide.md — 面向音效生成的提示词编写指南

外部资源

• 开发者门户（全球版）：https://www.tomoviee.ai/developers.html
• API 文档（全球版）：https://www.tomoviee.ai/doc/
• 开发者门户（中国大陆版）：https://www.tomoviee.cn/developers.html
• API 文档（中国大陆版）：https://www.tomoviee.cn/doc/
• 本软件包所使用的 API 网关主机：https://openapi.wondershare.cc