语音合成

文字转语音：音频文件 + 逐字 / 逐句时间轴，同步或异步拿结果，按字或按次计费。

POST /v1/audio/speech

curl -X POST https://api.gomiservice.com/v1/audio/speech \
  -H "Authorization: Bearer sk-gomi-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc-tts",
    "text": "欢迎使用芯剪，这是一次语音合成测试。",
    "voice": "zh_female_shuangkuaisisi_moon_bigtts",
    "params": "{\"speed\":110,\"format\":\"mp3\"}",
    "request_id": "tts-20261104-0001"
  }'

字段	必填	说明
`model`	是	语音合成模型 code，见 `GET /v1/models`（`output_type` 为 `speech` 的那些）
`text`	是	要合成的文本。长度上限由模型决定（标准版 1024 字节，旗舰 / MiniMax 更长）
`voice`	是	音色 code，从音色清单里选
`request_id`	是	幂等键，规则同提交生成：重试复用同一个值，不会重复合成、重复扣费
`params`	否	JSON 字符串，语速 / 音量 / 情感 / 格式等，见下
`wait_seconds`	否	同步等待秒数，见下。不传 = 30

同步还是异步：一个接口

不传 wait_seconds（或传 0）：服务端最多等 30 秒，合成完成就在这次响应里直接返回音频地址和时间轴（status 为 succeeded）。语音合成一般几秒内完成，绝大多数调用一次就拿到结果。
传 -1：不等，立刻返回 pending 的任务，拿 task_id 去查询任务。
传 1~90：等这么多秒。到点还没完成就返回当前状态（pending / running），同样拿 task_id 再查。

等待不另收费。客户端超时请设到 wait_seconds + 20 秒以上；超时了用同一个 request_id 重试，拿回的是原来那个任务。

参数：params

{ "params": "{\"speed\":110,\"volume\":100,\"emotion\":\"happy\",\"format\":\"wav\",\"sample_rate\":\"16000\"}" }

各模型支持的参数和取值范围以 GET /v1/models 返回的 capability 为准（settings 列启用的参数，properties 给范围）。常见的：

参数	说明
`speed`	语速，百分比，100 = 原速
`volume`	音量，百分比，100 = 原音量
`pitch`	音调。旗舰 / MiniMax 是半音（−12 ~ 12），标准版是百分比
`emotion`	情感，取值随音色而定（音色清单里的 `emotions`），不支持的音色传了会被厂商拒
`emotion_scale`	情感强度 1~5（旗舰）
`language`	语种提示，如 `zh-cn` / `en` / `ja`；MiniMax 是 `Chinese` / `English` 这类写法
`format`	音频格式：`mp3` / `wav` / `pcm` / `ogg_opus`（MiniMax：`mp3` / `wav` / `pcm` / `flac` / `opus`）
`sample_rate`	采样率，字符串写法，如 `"24000"`
`bitrate`	码率（mp3），如 `"160000"`
`silence_duration`	文末静音毫秒数（火山）

不认识的参数、取值不在范围内都会被拒（INVALID_REQUEST），不会静默忽略。

情感

三个模型控制情绪的方式不一样，音色清单里能看出该用哪种：

模型	怎么控	怎么知道可选值
`volc-tts` 的 2.0 音色（音色清单里 `supports_instruction: true`）	`params.instruction`：自由文本描述情绪 / 语气 / 方言 / 语速，如「用特别痛心的语气说」「用四川话、慢一点」	没有枚举，随便写；不计费
`volc-tts` 的 1.0 多情感音色（名字带「多情感」，如 `zh_female_shuangkuaisisi_emo_v2_mars_bigtts`）	`params.emotion` + 可选 `emotion_scale`（1–5，默认 4）	音色清单里的 `emotions`，每个音色不一样
`volc-tts-lite`	`params.emotion`	音色清单里的 `emotions`
`minimax-tts`	`params.emotion`	所有音色一样：`happy / sad / angry / fearful / disgusted / surprised / calm / fluent`（不传时模型按文本自动判断）

{ "params": "{\"instruction\":\"用低沉沙哑的语气、带着沧桑与绝望地说\"}" }
{ "params": "{\"emotion\":\"happy\",\"emotion_scale\":5}" }

emotion 必须在该音色的 emotions 里，否则提交被拒（INVALID_REQUEST，错误里列出可选值）；emotions 为空的音色传 emotion 也会被拒。这样做是因为厂商对不支持的情感不报错——要么没声音、要么当没传
instruction 只有 supports_instruction: true 的音色接受，其他音色传了被拒
同一个音色不会既有 emotions 又 supports_instruction，两种方式不用混

响应

同步拿到结果时：

{
  "task": {
    "task_id": "GMI-XXXXXXXXXXXXX",
    "status": "succeeded",
    "model": "volc-tts",
    "output_type": "speech",
    "created_at": 1793800000,
    "finished_at": 1793800003,
    "urls": ["https://…签名地址….mp3"],
    "cost_points": 1,
    "speech": {
      "duration_ms": 3120,
      "format": "mp3",
      "sample_rate": 24000,
      "text": "欢迎使用芯剪，这是一次语音合成测试。",
      "words": [
        { "text": "欢", "start_ms": 0, "end_ms": 180, "confidence": 0.98 },
        { "text": "迎", "start_ms": 180, "end_ms": 360, "confidence": 0.97 }
      ],
      "sentences": [
        { "text": "欢迎使用芯剪，这是一次语音合成测试。", "start_ms": 0, "end_ms": 3120 }
      ],
      "usage": { "text_words": 18 },
      "vendor": { "sentences": [ { "text": "…", "words": [ … ], "phonemes": [ … ] } ] }
    }
  }
}

字段	说明
`urls`	音频文件的签名地址（有效期内可直接下载；要长期保存请自行转存）
`speech.duration_ms`	音频时长，毫秒
`speech.format` / `sample_rate`	实际生效的格式和采样率
`speech.text`	合成的文本（旗舰版是厂商回的分句文本，其余是请求文本）
`speech.words`	逐字（英文逐词）时间戳，总是有，没有就是 `[]`。旗舰版带 `confidence`。做卡拉 OK 式高亮、精确剪切点用它
`speech.sentences`	分句时间轴，总是有，没有就是 `[]`
`speech.usage`	厂商报的计费量（旗舰 `text_words`、MiniMax `usage_characters`），没有则无此字段
`speech.vendor`	厂商其余字段原样：旗舰版的音素（`phonemes`）和句级原文、标准版的 `addition`、MiniMax 的 `extra_info` / `trace_id` / 字幕原文。以后厂商多给的也会原样出现在这里

异步或等待超时时 status 不是终态，没有 urls / speech，用 GET /v1/tasks/{task_id} 轮询，成功后同样的形状。

音色清单

curl "https://api.gomiservice.com/v1/audio/voices?model=volc-tts&language=zh&gender=female&page=1&page_size=50" \
  -H "Authorization: Bearer sk-gomi-你的Key"

参数	说明
`model`	必填，音色跟着模型走
`language` / `gender` / `accent` / `age_group`	筛选，取值见响应里的 `facets`
`keyword`	按名称模糊搜
`page` / `page_size`	分页，`page_size` 上限 200

{
  "voices": [
    {
      "code": "zh_female_shuangkuaisisi_moon_bigtts",
      "name": "爽快思思",
      "language": "zh", "gender": "female", "accent": "", "age_group": "adult",
      "emotions": [],
      "supports_instruction": true,
      "preview_url": "https://…试听….mp3"
    }
  ],
  "total": 120,
  "facets": { "languages": ["zh", "en"], "accents": [], "genders": ["female", "male"], "age_groups": ["adult"] }
}

emotions 是这个音色支持的情感取值，提交时放进 params.emotion；空数组表示这个音色不走枚举情感。supports_instruction 为 true 的音色用自由文本的 params.instruction 控制情绪（见情感）。Key 白名单限制了模型的话，不在白名单的模型查不到音色（API_MODEL_NOT_ALLOWED）。

计费

旗舰版（volc-tts）、MiniMax 按字数计费（含标点），标准版（volc-tts-lite）按次。提交响应里的 cost_points 就是这次的价格。
合成失败自动退还；同步等待不另收费。

常见错误

code	何时	处理
`INVALID_REQUEST`	提交时	漏了 `text` / `voice` / `request_id`；`params` 不是 JSON 或有不认识的参数；`request_id` 已用在另一类提交上
`API_MODEL_NOT_ALLOWED`	提交 / 查音色时	模型不在这把 Key 的白名单里
`AI_MODEL_NOT_FOUND`	提交时	模型不存在或已下架
`AI_UPSTREAM_FAILED`	执行时	厂商侧失败（音色不存在、情感不支持、文本超长等），点数已退还，`message` 里有原因

全部错误码见错误码。

本页目录