long-text-tts

name	long-text-tts
description	将超长文本（最多10万字符）异步转换为语音音频，支持多音库/语速/语调设置，适用于有声内容、新闻播报等场景
license	MIT

能力概述

百度 AI 长文本语音合成服务，通过两步异步接口将超长文本转换为音频：

1. 创建任务（POST /rpc/2.0/tts/v1/create）：提交文本数组，返回 task_id
2. 查询任务（POST /rpc/2.0/tts/v1/query）：轮询任务状态，成功后返回 speech_url 音频链接

能力维度	说明
文本上限	总字数不超过 10 万字符
音频格式	mp3-16k（默认）、mp3-48k、wav
音库选项	度小美(0)、度小宇(1)、度逍遥(3)、度丫丫(4)
语速/音调/音量	均为 0–15，默认均为 5
任务状态	Running / Success / Failure / Created
结果有效期	音频下载链接储存 72 小时
平台支持	Web、MiniProgram

平台差异关键说明：

差异点	Web	MiniProgram
音频播放方式	<audio> 标签或 Audio 对象，直接使用 Supabase Storage 公开 URL	Taro InnerAudioContext，使用 https 链接（须将 http 升级为 https）
轮询计数器实现	useRef 防止重复轮询链	同 Web，必须用 useRef 而非 useState
缓存策略	优先读 Supabase DB 缓存的 speech_url，避免重复调用	同 Web

---

生成期用法（Agent 直接调用）

完整异步工作流：提交任务 → 轮询直到成功/失败。详见 references/tts-create-api.md（提交接口）和 references/tts-query-api.md（查询接口）。

// 完整异步工作流：submit → poll → result
const apiKey = process.env["INTEGRATIONS_API_KEY"]!; // platform_managed，密钥由平台注入

async function createTTSTask(
  text: string[],
  options?: {
    format?: "mp3-16k" | "mp3-48k" | "wav";
    voice?: 0 | 1 | 3 | 4;
    speed?: number;
    pitch?: number;
    volume?: number;
    break?: number;
  }
): Promise<string> {
  const body: Record<string, unknown> = { text };
  if (options?.format !== undefined) body.format = options.format;
  if (options?.voice !== undefined) body.voice = options.voice;
  if (options?.speed !== undefined) body.speed = options.speed;
  if (options?.pitch !== undefined) body.pitch = options.pitch;
  if (options?. !== ) body. = options.;
   (options?. !== ) body. = options.;

   response =  (
    ,
    {
      : ,
      : {
        : ,
        : ,
      },
      : .(body),
    }
  );
   (!response.)   ();
   json =  response.();
   (!json.)   ();
   json.  ;
}

  (): <{
  :  |  |  | ;
  ?: ;
}> {
   response =  (
    ,
    {
      : ,
      : {
        : ,
        : ,
      },
      : .({ : [taskId] }),
    }
  );
   (!response.)   ();
   json =  response.();
   taskInfo = json.?.[];
   (!taskInfo)   ();
   {
    : taskInfo.,
    : taskInfo.?.,
  };
}

  (): <> {
   taskId =  (text, options);

    = ;
    =  *  * ; 
   deadline = .() + ;

   (.() < deadline) {
      ( (r, ));
     result =  (taskId);
     (result. ===  && result.) {
       result.;
    }
     (result. === ) {
        ();
    }
    
  }
    ();
}

---

生成后用法（应用内通过 Edge Function 调用）

需要两个 Edge Function：tts-create（提交任务）和 tts-query（查询结果）。

• tts-create 的完整代码及前端调用见 references/tts-create-api.md
• tts-query 的完整代码及前端调用（含轮询、缓存、错误处理）见 references/tts-query-api.md

前端整体架构（Web & MiniProgram 通用）：

1. 调用 tts-create Edge Function 提交任务，获取 task_id
2. 将 task_id 存入 Supabase DB（状态 Running）
3. 使用 useRef 计数器轮询 tts-query，避免双重轮询链
4. 任务成功后，Edge Function 将 speech_url 转存至 Supabase Storage，返回永久 publicUrl
5. 将 publicUrl 更新至 DB（状态 Success），前端展示播放控件

下次加载时优先从 DB 读取 speech_url；如已有完成记录，直接使用缓存 URL，跳过轮询。

---

注意事项

• 密钥安全：INTEGRATIONS_API_KEY 仅在 Edge Function 服务端使用，严禁暴露到前端
• 计费：每次调用 tts-create 计费，原价 ¥13.5/千次，折扣价 ¥11.25/千次；tts-query 不计费
• 错误处理：务必处理 429（配额超限）和 402（余额不足）；Baidu TTS error_code: 18 表示 QPS 超限，需退避重试
• 音频链接有效期：speech_url 仅保留 72 小时，应在 Edge Function 侧及时转存至 Supabase Storage
• MiniProgram 特别说明：原始 speech_url 使用 http，微信小程序会阻断非 https 资源，需升级协议或使用 Supabase Storage 的 https URL