minimax-client 0.1.0

Async Rust client for the MiniMax TTS, music, image, and voice APIs
Documentation

minimax-client

Crates.io 文档 CI 许可证

中文 | English

一个异步、强类型的 Rust MiniMax API 客户端。

支持的 API

  • 流式与非流式语音合成
  • 歌词、音乐与翻唱生成
  • 文生图
  • 音色查询、设计、删除、上传与复刻
  • 区域或自定义 API 地址
  • 复用 reqwest::Client,支持自定义请求超时

安装

[dependencies]
minimax-client = "0.1"
futures-util = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

本 crate 默认使用 rustls。如需使用系统原生 TLS:

minimax-client = { version = "0.1", default-features = false, features = ["native-tls"] }

最低支持的 Rust 版本为 1.86。

快速开始

设置 API Key:

export MINIMAX_API_KEY="your-api-key"

流式合成 PCM 音频:

use futures_util::StreamExt;
use minimax_client::{types::TtsRequest, MinimaxClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MinimaxClient::from_env()?;
    let request = TtsRequest {
        text: "你好,欢迎使用 MiniMax。".into(),
        ..Default::default()
    };

    let mut stream = client.tts_stream(&request);
    while let Some(chunk) = stream.next().await {
        let audio = chunk?;
        println!("收到 {} 字节音频", audio.len());
    }

    Ok(())
}

一次性获取完整的非流式响应:

use minimax_client::{types::TtsRequest, MinimaxClient};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = MinimaxClient::from_env()?;
let result = client
    .tts_synthesize(&TtsRequest {
        text: "你好,MiniMax。".into(),
        ..Default::default()
    })
    .await?;

std::fs::write("speech.pcm", result.audio_bytes)?;
# Ok(())
# }

更多用法请参阅 API 文档和 examples 目录。

配置

MinimaxClient::new 默认使用 https://api.minimaxi.com,请求超时时间为 5 分钟。可以通过 builder 方法修改:

use std::time::Duration;
use minimax_client::{MinimaxClient, BASE_URL_GLOBAL};

let client = MinimaxClient::new("your-api-key")
    .with_base_url(BASE_URL_GLOBAL)
    .with_timeout(Duration::from_secs(120));

可用的区域地址常量包括 BASE_URL_GLOBAL、BASE_URL_US_WEST 和 BASE_URL_CHINA。

错误处理

Error 可以区分网络传输错误、HTTP 错误、响应数据错误和 MiniMax API 错误,并提供常用的错误分类方法:

# use minimax_client::{MinimaxClient, types::TtsRequest};
# async fn run(client: MinimaxClient, request: TtsRequest) {
match client.tts_synthesize(&request).await {
    Ok(result) => println!("收到 {} 字节", result.audio_bytes.len()),
    Err(error) if error.is_rate_limited() => println!("请求过于频繁,请稍后重试"),
    Err(error) if error.is_auth_error() => println!("请检查 MINIMAX_API_KEY"),
    Err(error) => eprintln!("{error}"),
}
# }

示例

可运行示例位于 examples/。这些示例会调用真实的 MiniMax API, 运行前需要在环境变量或本地 .env 文件中设置 MINIMAX_API_KEY:

# TTS、歌词和音乐接口综合测试
cargo run --example client_test

# 生成歌词并流式生成音乐
cargo run --example music_lyrics

# 文生图
cargo run --example image_test

# 音色查询、设计和删除
cargo run --example voice_test

# TTS 首包延迟测试
cargo run --example ttaf_test

# 小新音色复刻与情绪测试
cargo run --example xiaoxin_clone
cargo run --example xiaoxin_emotion

xiaoxin_clone 和 xiaoxin_emotion 使用 examples/data/xiaoxin/ 中的示例音频。该目录会随 Git 仓库一起提供, 但不会打进 crates.io 发布包,因此需要从仓库克隆后再运行这两个示例。

测试

测试套件完全在本地运行,不会调用 MiniMax API:

cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo doc --no-deps

许可证

本项目采用 MIT 许可证。