Fish.audio TTS 接口说明文档与 Java 客户端封装

package nexus.io.fishaudio.tts;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

import nexus.io.model.http.response.ResponseVo;
import nexus.io.tio.utils.environment.EnvUtils;
import nexus.io.tio.utils.http.OkHttpClientPool;

import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

/**
 * FishAudioClient 用于调用 Fish.audio 的 TTS 接口。
 */
public class FishAudioClient {
  public static final String TTS_URL = "https://api.fish.audio/v1";

  /**
   * 直接传入文本内容构造请求（使用默认参数）。
   *
   * @param text 需要合成的文本
   * @return ResponseVo 响应结果（成功时包含音频二进制数据）
   */
  public static ResponseVo speech(String text) {
    FishAudioTTSRequestVo req = new FishAudioTTSRequestVo().setText(text);
    // 其他参数均采用默认值，如 chunk_length = 200, format = "mp3" 等
    return speech(req);
  }

  /**
   * 传入 FishAudioTTSRequestVo 对象。
   *
   * @param vo 请求对象
   * @return ResponseVo 响应结果
   */
  public static ResponseVo speech(FishAudioTTSRequestVo vo) {
    String apiKey = EnvUtils.get("FISHAUDIO_API_KEY");
    return speech(apiKey, vo);
  }

  /**
   * 指定 API Key 调用接口。
   *
   * @param apiKey API密钥
   * @param vo     请求对象
   * @return ResponseVo 响应结果
   */
  public static ResponseVo speech(String apiKey, FishAudioTTSRequestVo vo) {
    String apiPrefixUrl = EnvUtils.get("FISHAUDIO_API_URL", TTS_URL);
    return speech(apiPrefixUrl, apiKey, vo);
  }

  /**
   * 完整的接口调用：指定 URL、API Key 和请求对象。
   *
   * @param apiPrefixUrl 接口前缀地址，如 https://api.fish.audio/v1
   * @param apiKey       API 密钥
   * @param vo           请求对象
   * @return ResponseVo   响应结果
   */
  public static ResponseVo speech(String apiPrefixUrl, String apiKey, FishAudioTTSRequestVo vo) {
    // 使用 msgpack 工具将请求对象序列化成二进制
    byte[] payload = nexus.io.fishaudio.tts.FishAudioMsgPackConverter.encodeFishAudioTTSRequestVo(vo);
    return speechRequest(apiPrefixUrl, apiKey, payload);
  }

  /**
   * 发起 HTTP 请求，返回鱼声平台 TTS 接口响应结果。
   *
   * @param apiPrefixUrl 接口前缀
   * @param apiKey       API 密钥
   * @param payload      msgpack 序列化后的请求数据
   * @return ResponseVo  响应结果，成功时包含音频二进制数据
   */
  public static ResponseVo speechRequest(String apiPrefixUrl, String apiKey, byte[] payload) {
    // 接口地址为 “/tts”
    String baseUrl = apiPrefixUrl + "/tts";
    Map<String, String> header = new HashMap<>();
    header.put("Authorization", "Bearer " + apiKey);
    header.put("content-type", "application/msgpack");
    // 指定 TTS 模型版本，默认 "speech-1.6"
    header.put("model", "speech-1.6");
    return execute(baseUrl, header, payload);
  }

  /**
   * 发送 HTTP 请求并处理响应（流式返回音频数据）。
   *
   * @param url     完整 URL
   * @param header  请求头信息
   * @param payload 请求体（msgpack二进制数据）
   * @return ResponseVo 响应结果
   */
  private static ResponseVo execute(String url, Map<String, String> header, byte[] payload) {
    MediaType mediaType = MediaType.parse("application/msgpack");
    RequestBody body = RequestBody.create(payload, mediaType);

    // 构建请求并添加请求头
    Request.Builder requestBuilder = new Request.Builder().url(url).post(body);
    for (Map.Entry<String, String> entry : header.entrySet()) {
      requestBuilder.addHeader(entry.getKey(), entry.getValue());
    }
    Request request = requestBuilder.build();

    OkHttpClient httpClient = OkHttpClientPool.get300HttpClient();

    try (Response response = httpClient.newCall(request).execute()) {
      int code = response.code();
      if (response.isSuccessful()) {
        // 成功时返回音频二进制数据
        return ResponseVo.ok(response.body().bytes());
      } else {
        // 失败时返回错误码和响应体
        String responseBody = response.body().string();
        return ResponseVo.fail(code, responseBody);
      }
    } catch (IOException e) {
      throw new RuntimeException(e.getMessage(), e);
    }
  }
}

package nexus.io.fishaudio.tts;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

/**
 * 表示参考音频，用于 in-context 学习。
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
public class FishAudioReferenceAudio {
  // 二进制格式的参考音频数据
  private byte[] audio;
  // 参考音频对应的文字描述
  private String text;
}

package nexus.io.fishaudio.tts;

import java.util.List;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

/**
 * 请求 Fish.audio TTS 接口时使用的参数对象。
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
public class FishAudioTTSRequestVo {
  // 合成的文本内容
  private String text;

  // 音频分片长度（范围 100 ~ 300），默认 200
  private Integer chunk_length = 200;

  // 输出音频格式，可选 "wav"、"pcm"、"mp3"，默认 "mp3"
  private String format = "mp3";

  // 当 format 为 mp3 时使用的比特率，可选 64, 128, 192，默认 128
  private Integer mp3_bitrate = 128;

  // 参考音频列表，用于 in-context 学习，可传入多个
  private List<FishAudioReferenceAudio> references;

  // 直接指定参考音频的在线资源 id（例如 "7f92f8afb8ec43bf81429cc1c9199cb1"），可选
  private String reference_id;

  // 是否对文本进行标准化处理，默认为 true
  private Boolean normalize = true;

  // 延迟模式，"normal"（稳定模式）或 "balanced"（低延迟模式，约 300ms），默认 "normal"
  private String latency = "normal";
}

package nexus.io.fishaudio.tts;

import java.io.ByteArrayOutputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.List;

/**
 * HardCodedMsgPackConverter 将 FishAudioTTSRequestVo 对象手动转换为 msgpack 格式字节数组，
 * 采用 Map 结构（与 ormsgpack.OPT_SERIALIZE_PYDANTIC 生成的结构一致）。
 */
public class FishAudioMsgPackConverter {

  /**
   * 将 FishAudioTTSRequestVo 对象编码为 msgpack 格式的字节数组（Map 格式）。
   *
   * @param vo 请求对象
   * @return msgpack 编码后的字节数组
   */
  public static byte[] encodeFishAudioTTSRequestVo(FishAudioTTSRequestVo vo) {
    try {
      ByteArrayOutputStream baos = new ByteArrayOutputStream();
      DataOutputStream out = new DataOutputStream(baos);

      // 我们将 vo 编码为一个 Map，共包含 8 个键值对
      writeMapHeader(out, 8);

      // 键 "text"
      writeString(out, "text");
      writeString(out, vo.getText());

      // 键 "chunk_length"
      writeString(out, "chunk_length");
      writeInt(out, vo.getChunk_length());

      // 键 "format"
      writeString(out, "format");
      writeString(out, vo.getFormat());

      // 键 "mp3_bitrate"
      writeString(out, "mp3_bitrate");
      writeInt(out, vo.getMp3_bitrate());

      // 键 "references"
      writeString(out, "references");
      List<FishAudioReferenceAudio> refs = vo.getReferences();
      if (refs == null) {
        writeArrayHeader(out, 0);
      } else {
        writeArrayHeader(out, refs.size());
        for (FishAudioReferenceAudio ref : refs) {
          encodeFishAudioReferenceAudio(out, ref);
        }
      }

      // 键 "reference_id"
      writeString(out, "reference_id");
      if (vo.getReference_id() == null) {
        writeNil(out);
      } else {
        writeString(out, vo.getReference_id());
      }

      // 键 "normalize"
      writeString(out, "normalize");
      writeBoolean(out, vo.getNormalize());

      // 键 "latency"
      writeString(out, "latency");
      writeString(out, vo.getLatency());

      out.flush();
      return baos.toByteArray();
    } catch (IOException e) {
      throw new RuntimeException("Error encoding FishAudioTTSRequestVo", e);
    }
  }

  /**
   * 将 FishAudioReferenceAudio 对象编码为 msgpack 格式数据（Map 格式），包含 2 个键值对：audio 和 text。
   */
  private static void encodeFishAudioReferenceAudio(DataOutputStream out, FishAudioReferenceAudio ref) throws IOException {
    // 编码为 Map，包含 2 个字段
    writeMapHeader(out, 2);
    // 键 "audio"
    writeString(out, "audio");
    byte[] audio = ref.getAudio();
    if (audio == null) {
      writeNil(out);
    } else {
      writeByteArray(out, audio);
    }
    // 键 "text"
    writeString(out, "text");
    writeString(out, ref.getText());
  }

  //////////////// 以下为 msgpack 编码辅助方法 ////////////////

  // 写入 Map 头（如果 size < 16 使用 fixmap）
  private static void writeMapHeader(DataOutputStream out, int size) throws IOException {
    if (size < 16) {
      out.writeByte(0x80 | size); // fixmap
    } else if (size < 65536) {
      out.writeByte(0xde);
      out.writeShort(size);
    } else {
      out.writeByte(0xdf);
      out.writeInt(size);
    }
  }

  // 写入 Array 头（如果 size < 16 使用 fixarray）
  private static void writeArrayHeader(DataOutputStream out, int size) throws IOException {
    if (size < 16) {
      out.writeByte(0x90 | size); // fixarray
    } else if (size < 65536) {
      out.writeByte(0xdc);
      out.writeShort(size);
    } else {
      out.writeByte(0xdd);
      out.writeInt(size);
    }
  }

  // 写入 nil 标记
  private static void writeNil(DataOutputStream out) throws IOException {
    out.writeByte(0xc0);
  }

  // 写入 Boolean 值
  private static void writeBoolean(DataOutputStream out, boolean value) throws IOException {
    out.writeByte(value ? 0xc3 : 0xc2);
  }

  // 写入整型数值（这里只处理正数，适用于本例中的 chunk_length 和 mp3_bitrate）
  private static void writeInt(DataOutputStream out, int value) throws IOException {
    if (value >= 0 && value < 128) {
      out.writeByte(value); // positive fixnum
    } else if (value < 256) {
      out.writeByte(0xcc);
      out.writeByte(value);
    } else if (value < 65536) {
      out.writeByte(0xcd);
      out.writeShort(value);
    } else {
      out.writeByte(0xce);
      out.writeInt(value);
    }
  }

  // 写入字符串
  private static void writeString(DataOutputStream out, String str) throws IOException {
    if (str == null) {
      writeNil(out);
      return;
    }
    byte[] utf8 = str.getBytes(StandardCharsets.UTF_8);
    int length = utf8.length;
    if (length < 32) {
      out.writeByte(0xa0 | length); // fixstr
    } else if (length < 256) {
      out.writeByte(0xd9);
      out.writeByte(length);
    } else if (length < 65536) {
      out.writeByte(0xda);
      out.writeShort(length);
    } else {
      out.writeByte(0xdb);
      out.writeInt(length);
    }
    out.write(utf8);
  }

  // 写入 byte 数组（二进制数据）
  private static void writeByteArray(DataOutputStream out, byte[] data) throws IOException {
    int length = data.length;
    if (length < 256) {
      out.writeByte(0xc4);
      out.writeByte(length);
    } else if (length < 65536) {
      out.writeByte(0xc5);
      out.writeShort(length);
    } else {
      out.writeByte(0xc6);
      out.writeInt(length);
    }
    out.write(data);
  }
}

package nexus.io.manim.services;

import java.io.FileOutputStream;
import java.io.IOException;

import org.junit.Test;

import nexus.io.fishaudio.tts.FishAudioClient;
import nexus.io.fishaudio.tts.FishAudioTTSRequestVo;
import nexus.io.model.http.response.ResponseVo;
import nexus.io.tio.utils.environment.EnvUtils;

public class FishAudioClientTest {

  @Test
  public void fishAudioTest() {
    EnvUtils.load();
    ResponseVo responseVo = FishAudioClient.speech("今天天气怎么样");
    if (responseVo.isOk()) {
      byte[] audioBytes = responseVo.getBodyBytes();
      try (FileOutputStream fos = new FileOutputStream("output.mp3")) {
        fos.write(audioBytes);
        System.out.println("MP3 文件已保存到 output.mp3");
      } catch (IOException e) {
        e.printStackTrace();
      }
    } else {
      System.err.println("请求失败：" + responseVo);
    }
  }

  @Test
  public void testWithReferenceId() {
    EnvUtils.load();
    // 构造请求对象，并指定参考语音ID（发音人）
    FishAudioTTSRequestVo vo = new FishAudioTTSRequestVo();
    vo.setText("今天天气怎么样");
    vo.setReference_id("03397b4c4be74759b72533b663fbd001");

    // 其它参数保持默认或根据需要进行设置，例如：
    vo.setChunk_length(200);
    vo.setFormat("mp3");
    vo.setMp3_bitrate(128);
    // 如果有需要使用参考音频（in-context learning），也可以通过 vo.setReferences(...) 传入对应参考语音数据

    // 使用 FishAudioClient 发起请求
    ResponseVo responseVo = FishAudioClient.speech(vo);
    if (responseVo.isOk()) {
      // 处理返回的音频数据，例如保存到文件
      byte[] audioBytes = responseVo.getBodyBytes();
      try (FileOutputStream fos = new FileOutputStream("output.mp3")) {
        fos.write(audioBytes);
        System.out.println("MP3 文件已保存到 output.mp3");
      } catch (IOException e) {
        e.printStackTrace();
      }
    } else {
      System.err.println("请求失败：" + responseVo.getBodyString());
    }
  }
}