MiniMax Speech 2.8

MiniMax Speech 2.8 通过统一异步任务接口生成长文本语音。首版仅接受直接文本，单次最多 50,000 个 Unicode code point；暂不开放文件输入、音色克隆和音色设计。

模型与定价

模型	每万计费字符标准价
`speech-2.8-hd`	155.33 积分
`speech-2.8-turbo`	88.76 积分

计费字符完全由服务端派生，不接受客户传入的计数：

每个 Unicode 汉字计 2。
其他 Unicode code point（字母、标点、空格、换行、emoji 等）均计 1。

例如 你好, AI! 共 9 个计费字符：你、好 合计 4，逗号、空格、A、I、感叹号合计 5。可通过 POST /v1/estimate 或 Playground 查看最终两位小数预估。

创建任务

curl -X POST https://api.aivideoapi.ai/v1/audio/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "text": "真正的危险不是计算机开始像人一样思考(sighs)，而是人开始像计算机一样思考。",
      "voice_setting": {
        "voice_id": "audiobook_male_1",
        "speed": 1,
        "vol": 1,
        "pitch": 0,
        "emotion": "calm"
      },
      "audio_setting": {
        "audio_sample_rate": 32000,
        "bitrate": 128000,
        "format": "mp3",
        "channel": 1
      },
      "language_boost": "auto",
      "aigc_watermark": false
    }
  }'

创建响应返回平台任务 ID：

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}

请求字段

字段	类型	必填	说明
`model`	string	是	`speech-2.8-hd` 或 `speech-2.8-turbo`
`input`	object	是	下述语音参数
`callback_url`	string	否	接收完成或失败回调的公网 HTTP(S) URL

Input 字段

字段	类型	必填	说明
`text`	string	是	非空直接文本，最多 50,000 个 Unicode code point
`voice_setting`	object	是	音色与表达设置
`audio_setting`	object	否	输出编码设置；上游默认 MP3
`language_boost`	string	否	指定语言/方言增强，或使用 `auto`
`pronunciation_dict`	object	否	`tone` 自定义发音词典
`voice_modify`	object	否	音高、强度、音色和音效处理
`aigc_watermark`	boolean	否	是否添加 MiniMax 音频节奏标识，默认 `false`

本接口不支持 text_file_id、文本文件上传、音色克隆或音色设计。

音色设置

字段	类型	范围	说明
`voice_id`	string	非空	必填音色 ID
`speed`	number	0.5–2	语速
`vol`	number	大于 0 且不超过 10	音量
`pitch`	integer	-12–12	音高偏移
`emotion`	string	`happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`calm`	Speech 2.8 情绪；拒绝 `fluent`、`whisper`
`english_normalization`	boolean	—	是否启用英文文本规范化

可使用 MiniMax 系统音色，例如 audiobook_male_1。自定义克隆/设计音色只有在它属于本平台所配置的 MiniMax 账户时才能使用；其他 MiniMax 账户中的 voice_id 无法通过你的 AI Video API Key 访问。

音频设置

字段	类型	可用值
`format`	string	`mp3`、`pcm`、`flac`、`wav`、`pcmu_raw`、`pcmu_wav`、`opus`
`audio_sample_rate`	integer	常规格式：8000、16000、22050、24000、32000、44100；Opus：8000、12000、16000、24000、48000
`bitrate`	integer	仅 MP3：32000、64000、128000、256000
`channel`	integer	`1` 或 `2`

Opus 必须显式提供受支持的采样率；pcmu_raw、pcmu_wav 必须为 8000 Hz；非 MP3 格式不能传 bitrate。

语言增强

language_boost 支持 auto、Chinese、Chinese,Yue、English、Arabic、Russian、Spanish、French、Portuguese、German、Turkish、Dutch、Ukrainian、Vietnamese、Indonesian、Japanese、Italian、Korean、Thai、Polish、Romanian、Greek、Czech、Finnish、Hindi、Bulgarian、Danish、Hebrew、Malay、Persian、Slovak、Swedish、Croatian、Filipino、Hungarian、Norwegian、Slovenian、Catalan、Nynorsk、Tamil、Afrikaans。

发音词典与音效

{
  "pronunciation_dict": {
    "tone": ["危险/dangerous"]
  },
  "voice_modify": {
    "pitch": 0,
    "intensity": 0,
    "timbre": 0,
    "sound_effects": "spacious_echo"
  }
}

voice_modify 的三个数值字段均为 -100 到 100 的整数；sound_effects 可为 spacious_echo、auditorium_echo、lofi_telephone 或 robotic。音效仅支持 MP3、WAV、FLAC 输出。

预估积分

curl -X POST https://api.aivideoapi.ai/v1/estimate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-turbo",
    "input": {
      "text": "你好, AI!",
      "voice_setting": { "voice_id": "audiobook_male_1" }
    }
  }'

预估接口与真实提交使用完全相同的服务端 billable_characters、计价公式、两位小数规则和账户倍率。

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态为 pending → processing → completed 或 failed。由于 MiniMax 异步语音接口不提供客户取消能力，MiniMax Speech 任务不可取消。建议每 2 秒左右查询一次平台任务；平台会在多实例间统一控制上游查询频率，低于 MiniMax 每秒 10 次的限制。

HTTP 429、MiniMax 1002、网络异常和 5xx 等暂时查询失败只会保持任务处理中，不会标记失败或退款。只有 MiniMax 权威返回 Failed / Expired，或提交在 MiniMax 受理前被拒绝，才会执行一次退款；已完成任务永远不会进入退款路径。

如果提交请求可能已经发出，但连接在收到权威响应或任务 ID 前中断，平台会把结果标记为需要人工核对并保留预扣积分。此时自动退款可能造成 MiniMax 已受理并产生费用、平台却误退积分。

完成响应

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "model": "speech-2.8-hd",
  "credits_consumed": 0.7,
  "output": {
    "urls": ["https://file.aivideoapi.ai/audio/2026/08/11/example.mp3"],
    "metadata": {
      "file_id": "95157322514496",
      "filename": "speech.mp3",
      "bytes": 5896337,
      "format": "mp3",
      "storage": "r2",
      "source_url_expires_in": 86400
    }
  },
  "usage": { "characters": 45 }
}

成功后平台优先把文件转存到 R2，返回默认有效 24 小时的签名地址。若转存失败，任务会立即回退到 MiniMax 原始地址（约 9 小时有效）。该交付回退绝不会把成功任务改成失败，也不会触发退款。可读取 output.metadata.storage 与 source_url_expires_in 判断实际来源和有效期。

回调

创建任务时传入 callback_url。平台会向该 URL 发送与查询接口一致的完成/失败任务结构。重复轮询或重复回调不会造成重复完成或重复退款。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。