语音合成与音色 API

EasyAI 提供统一的语音合成接口和音色克隆接口。接入顺序是：查询可用模型与音色 → 选择音色来源 → 提交文本 → 获取音频结果。

接口与认证

• 官方 BaseURL：https://51easyai.com/api/v1。私有部署使用 https://<你的域名>/api/v1。
• 所有接口携带 Authorization: Bearer <EasyAI API Key>，JSON 请求还需 Content-Type: application/json。
• 模型可见性、权限、余额和部署配置会影响可用列表。模型别名及音色以当前账号的实时查询结果为准。

下文 curl 示例使用环境变量：

export EASYAI_BASE_URL="https://51easyai.com/api/v1"
export EASYAI_API_KEY="替换为你的 EasyAI API Key"

1. voice_id 怎么获取

预置音色：查询所选模型的能力

curl -sS "$EASYAI_BASE_URL/models/list?type=text_to_speech" \
  -H "Authorization: Bearer $EASYAI_API_KEY"

返回结构示例（已省略其他字段；不代表每个部署均已启用此模型）：

{
  "modelList": [
    {
      "name": "speech-2.8-hd",
      "alias": "MiniMax-Speech-2.8-HD",
      "provider": "minimax",
      "capabilities": {
        "text_to_speech": {
          "default_voice_id": "male-qn-qingse",
          "voices": [
            {
              "id": "male-qn-qingse",
              "name": "青涩青年音色",
              "lang": "中文",
              "gender": "男"
            }
          ]
        }
      }
    }
  ],
  "count": 1
}

合成时，model 优先填写所选项的 alias；voice_id 填写该项 capabilities.text_to_speech.voices[].id。name 是音色的显示名称，不能代替 id。部分音色还返回 audio 试听地址、tags、accent、age 等信息。

安装了 jq 时，可展开模型与音色便于选择：

curl -sS "$EASYAI_BASE_URL/models/list?type=text_to_speech" \
  -H "Authorization: Bearer $EASYAI_API_KEY" \
  | jq '.modelList[] | {model: (.alias // .name), provider, voices: .capabilities.text_to_speech.voices}'

音色必须与模型及提供方匹配。例如 MiniMax 的音色 ID 不能直接用于豆包语音模型。若 voices 缺失或为空，不能自行构造 voice_001；请核对该模型的音色配置及是否支持自动音色、参考音频等模式。

自定义音色：查询本人的克隆记录

curl -sS "$EASYAI_BASE_URL/voice_clone/voices" \
  -H "Authorization: Bearer $EASYAI_API_KEY"

此接口返回 { "data": [...] }，每项的 voice_id 是合成音色 ID，id 是 EasyAI 克隆记录 ID。创建方式见本文「自定义音色」章节。

2. emotion 怎么获取

emotion 是模型支持的情绪字符串，不是需要创建或查询的音色 ID。EasyAI 当前没有独立的 emotion 列表接口。它可省略，让模型按文本自动选择情绪。

MiniMax Speech 常用选项如下；其他提供方不一定支持相同字段或取值：

fluent（流畅）和 whisper（低语）仅在 Speech 2.6 模型开放；Speech 2.8 不开放这两项。详细取值参考 MiniMax 语音合成参数。供应商文档中的 voice_setting.emotion 在 EasyAI 请求中可填写为顶层 emotion，如下文示例。

3. 合成语音

POST /speech/generations

请求示例

以下示例使用 MiniMax 的模型别名与预置音色。实际调用前先确认它们存在于你的模型列表中。

curl -sS -X POST "$EASYAI_BASE_URL/speech/generations" \
  -H "Authorization: Bearer $EASYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Speech-2.8-HD",
    "text": "你好，欢迎使用 EasyAI 语音合成。",
    "voice_id": "male-qn-qingse",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  }'

请求参数

上述速度、音量和音调范围仅针对 MiniMax。其他模型应按其能力与参数要求填写。MiniMax 的输出设置与声线效果见下文。

text_file_id 并非 EasyAI 文件上传接口 返回的 URL。当前 MiniMax 适配器按 text 长度选择处理流程，普通调用应传入 text，不要只传 text_file_id。

音色来源规则：voice_id / cloned_voice_id 与参考音频互斥。只有支持自动音色的模型才能省略全部音色来源；不能据此认为所有模型的 voice_id 都可省略。

MiniMax 声线、音效与音频设置

以下是 2026-10-14 补齐的能力。私有部署需要更新到包含本次 MiniMax 参数补齐的前后端版本；旧版适配器仅传语速、音量、音调和情绪，并固定保存为 MP3。接口字段和范围按 MiniMax 同步语音文档 与 长文本语音文档 核对。

四种音效对应值：

声线微调和音效仅支持 MP3、WAV、FLAC。与 PCM、G.711 或 Opus 组合会返回参数错误；不应静默丢弃效果。数值 0 是有效设置，不能用省略零值的方式清理请求。

完整请求示例：

{
  "model": "MiniMax-Speech-2.8-HD",
  "text": "欢迎使用 EasyAI，请留意处理这个词的读音。",
  "voice_id": "male-qn-qingse",
  "speed": 1,
  "vol": 1,
  "pitch": 0,
  "emotion": "calm",
  "voice_modify": {
    "pitch": 20,
    "intensity": -10,
    "timbre": 15,
    "sound_effects": "spacious_echo"
  },
  "audio_format": "wav",
  "sample_rate": 32000,
  "channel": 1,
  "pronunciation_dict": { "tone": ["处理/(chu3)(li3)"] },
  "language_boost": "Chinese"
}

也兼容原生嵌套写法 voice_setting 和 audio_setting。例如 "voice_setting": {"voice_id": "male-qn-qingse", "pitch": 0}、"audio_setting": {"format": "wav", "sample_rate": 32000}。同时填写时，显式顶层字段优先，包括 0 和 false。普通接入建议使用上表的顶层字段，便于切换 EasyAI 提供方。

平台生成页、Canvas 与通用语音模板

选择 MiniMax 模型后，语音高级设置开放情绪、声线三项微调、音效、音频格式、采样率、MP3 码率、声道、发音词典和语言增强。普通音调与声线明亮度分别显示。选择其他提供方时，以该模型的能力显示参数。

通用语音模板使用 minimax_tts_params 对象保存这些高级设置，并完整传到 MiniMax 适配器。组内显式参数覆盖模板旧的格式、采样率等默认值；不能通过该组替换 model 或 voice_id。OpenAPI 调用无需套用此对象。已保存的旧模板需要使用更新后的模板配置，才能出现新增控件。

MiniMax 文本不足 8000 字符时使用供应商同步接口，达到 8000 字符时使用供应商长文本接口，EasyAI 会转换两者的采样率字段。同步专用参数 text_normalization_mode、subtitle_enable、subtitle_type 不用于长文本；语言支持也可能随模型版本变化。

声线微调调整当前音色的效果，不会创建新的 voice_id；要保存独立的自定义音色，请使用下文的录音克隆接口。

同步返回

默认等待任务完成，返回 JSON。成功结构示例（已省略计费等字段）：

{
  "task_id": "任务ID",
  "status": "success",
  "data": [
    {
      "type": "audio",
      "url": "https://example.com/output/speech.mp3"
    }
  ],
  "message": "合成语音成功"
}

读取 data 中 type: "audio" 项的 url 进行播放或下载。音频不会作为 MP3 二进制直接返回。失败时检查 HTTP 状态及响应中的 message、error_code 等错误信息。

异步返回与结果查询

长文本或需要避免 HTTP 长连接等待时，在相同请求上增加 -H "x-async: true"。

{
  "task_id": "任务ID",
  "status": "submitted",
  "message": "任务已提交，请稍后查看结果",
  "query_url": "任务结果查询地址"
}

submitted 表示已提交，尚未生成完成。使用返回的 query_url（若有），或查询：

curl -sS "$EASYAI_BASE_URL/ai/result/替换为任务ID" \
  -H "Authorization: Bearer $EASYAI_API_KEY"

查询仅允许访问当前用户自己的任务。完整查询状态及回调格式见 OpenAPI 接口文档。

4. 自定义音色：录音克隆

EasyAI 已提供 POST /voice_clone。先查询 GET /models/list?type=voice_clone，选择可用的克隆模型别名。当前 MiniMax 克隆模型的预置别名为 MiniMax-Voice-Clone，是否可用以部署配置为准。

上传录音并创建音色

可直接用 multipart/form-data 上传音频，不需要先调用文件上传接口，也不要手工设置 multipart 的 Content-Type / boundary。

curl -sS -X POST "$EASYAI_BASE_URL/voice_clone" \
  -H "Authorization: Bearer $EASYAI_API_KEY" \
  -F "model=MiniMax-Voice-Clone" \
  -F "voice_id=my_voice_20261014_001" \
  -F "display_name=我的自定义音色" \
  -F "file=@./sample.wav" \
  -F "text=你好，这是我的音色试听。" \
  -F "preview_model=speech-2.8-hd" \
  -F "need_noise_reduction=true" \
  -F "need_volume_normalization=true"

此处 voice_id 是你为新音色指定的唯一标识，合成时应使用返回的 voice_id。MiniMax 要求 8–256 位、以英文字母开头，仅含字母、数字、下划线和中划线，结尾不能为下划线或中划线，并且不能与已有音色重名。

当前 MiniMax 的录音要求为 MP3、M4A 或 WAV，时长 10 秒至 5 分钟，文件不超过 20 MB；EasyAI multipart 上传也限制单个文件为 20 MB。参考 MiniMax 音色克隆文档。

也可使用可被服务端及提供方读取的音频 URL，以 JSON 提交：

{
  "model": "MiniMax-Voice-Clone",
  "voice_id": "my_voice_20261014_002",
  "audio_url": "https://example.com/sample.wav",
  "display_name": "我的自定义音色",
  "text": "你好，这是我的音色试听。",
  "preview_model": "speech-2.8-hd"
}

克隆请求参数

选择一种音频来源即可；上传 file 时服务端自动处理临时音频。试听会执行语音生成并可能产生对应费用。

返回与后续使用

克隆成功返回结构示例（已省略其他字段；示例 ID / 地址请替换为实际返回值）：

{
  "status": "success",
  "voice_id": "my_voice_20261014_001",
  "demo_audio": "https://example.com/output/preview.mp3",
  "data": [
    {
      "type": "audio",
      "url": "https://example.com/output/preview.mp3"
    }
  ],
  "cloned_voice": {
    "id": "507f1f77bcf86cd799439011",
    "voice_id": "my_voice_20261014_001",
    "display_name": "我的自定义音色",
    "provider_code": "minimax",
    "platform_runtime_id": "原执行平台ID",
    "status": "active",
    "expires_at": "2026-10-21T00:00:00.000Z"
  }
}

若未传试听 text，demo_audio 可以不存在，data 可以为空；应检查 status 与克隆记录，而非仅依赖试听 URL。

后续通过相同用户的 API Key 查询 /voice_clone/voices，取记录的 id 填入 cloned_voice_id，再调用合成：

{
  "model": "MiniMax-Speech-2.8-HD",
  "text": "这段语音使用我刚刚创建的自定义音色。",
  "cloned_voice_id": "507f1f77bcf86cd799439011",
  "speed": 1,
  "vol": 1,
  "pitch": 0
}

• cloned_voice_id 使用记录 id，voice_id 使用音色标识，两者含义不同。也可直接传记录里的 voice_id；同一用户多个平台存在同名音色时，优先明确指定 cloned_voice_id。
• 克隆记录绑定当前用户和实际执行平台，合成只能路由至原平台。所选合成模型也必须在该平台可用，不能直接使用其他用户或其他供应商账号的克隆音色。
• 仅使用 status: "active" 且未过期的记录。当前 EasyAI 克隆记录按 7 天设置 expires_at，每次成功合成后重新延长 7 天；以列表实际返回值为准，过期后需要重新克隆。
• 删除本人音色使用 DELETE /voice_clone/voices/{voiceId}，voiceId 可填克隆记录 id 或 voice_id；服务端先处理上游删除，再标记本地记录。

5. 参考音频与音色设计的区别

支持参考音频的模型（例如启用了该能力的 SeedAudio）可以在单次合成时使用 reference_audio_url。该方式不会创建可复用的 EasyAI 克隆记录，也不会返回新的 voice_id：

{
  "model": "替换为支持参考音频的模型别名",
  "text": "你好，这是一段参考音频合成示例。",
  "reference_audio_url": "https://example.com/reference.wav"
}

此模式不要同时传 voice_id 或 cloned_voice_id。参考音频的格式、时长及模型支持情况由模型能力决定。

如果“自定义音色”指仅通过文字描述设计一个新音色，EasyAI 当前 OpenAPI 没有独立的 voice_design 接口。支持 text_prompt 的模型可以描述本次生成的声音风格，但不等同于创建持久音色 ID；需要重复使用的录音音色请走 /voice_clone。

常见问题