> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialvision.tisyk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax 视频接口参考

> MiniMax 文本生视频与图像生视频接口

## 检索(用于视频下载,异步音频下载)

`GET /minimax/v1/files/retrieve`

根据 `file_id` 检索文件元数据与下载链接，用于视频生成或异步语音合成结果下载。

### 请求参数 (Query / Path)

<ParamField query="file_id" type="string">
  文件的唯一标识符。通过查询视频生成任务状态接口成功后返回的 file\_id 获得
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/minimax/v1/files/retrieve" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "file": {
    "bytes": 0,
    "created_at": 1700469398,
    "download_url": "www.downloadurl.com",
    "file_id": "${file_id}",
    "filename": "output_aigc.mp4",
    "purpose": "video_generation"
  }
}
```

***

## 查询异步语音合成任务

`GET /minimax/v1/query/t2a_async_query_v2`

根据 `task_id` 查询 T2A 任务状态；成功后通过 `file_id` 检索音频文件。

[https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query)

### 请求参数 (Query / Path)

<ParamField query="task_id" type="string" required>
  提交任务时返回的 task\_id
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/minimax/v1/query/t2a_async_query_v2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "file_id": 95157322514496,
  "status": "Processing",
  "task_id": 95157322514444
}
```

***

## 查询视频生成任务

`GET /minimax/v1/query/video_generation`

根据 `task_id` 查询视频生成任务状态。

### 请求参数 (Query / Path)

<ParamField query="task_id" type="string" required>
  提交任务时返回的 task\_id
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/minimax/v1/query/video_generation" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "file_id": "string",
  "status": "Preparing",
  "task_id": "string",
  "video_height": 0,
  "video_width": 0
}
```

***

## 上传示例音频

`POST /minimax/v1/files`

需要上传的文件。填写文件的路径地址

支持上传的文件需遵从以下规范：

上传的音频文件格式需为：mp3、m4a、wav格式
上传的音频文件的时长小于8s
上传的音频文件大小需不超过20mb

### 请求体参数 (Body)

<ParamField body="file" type="string" required>
  选择音频文件（mp3/m4a/wav）
</ParamField>

<ParamField body="purpose" type="string" required>
  prompt\_audio
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "file": "",
  "purpose": "prompt_audio"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/files" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file": "",
  "purpose": "prompt_audio"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "file": {
    "bytes": 5896337,
    "created_at": 1700469398,
    "file_id": "${file_id}",
    "filename": "复刻音频",
    "purpose": "voice_clone"
  }
}
```

***

## 异步语音合成

`POST /minimax/v1/t2a_async_v2`

提交文本转语音异步任务。`text` 与 `text_file_id` 二选一；提交后通过 `GET /minimax/v1/query/t2a_async_query_v2` 轮询。

[https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create)

### 请求体参数 (Body)

<ParamField body="aigc_watermark" type="boolean">
  是否添加 AIGC 水印
</ParamField>

<ParamField body="audio_setting" type="object">
  音频输出设置
</ParamField>

<ParamField body="language_boost" type="string">
  语言增强（如 `Chinese`、`English`）
</ParamField>

<ParamField body="model" type="string" required>
  T2A 模型
</ParamField>

<ParamField body="text" type="string">
  待合成文本（与 `text_file_id` 二选一）
</ParamField>

<ParamField body="text_file_id" type="integer">
  文本文件 ID（与 `text` 二选一）
</ParamField>

<ParamField body="voice_setting" type="object" required>
  音色设置
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "model": "speech-02-hd",
  "text": "真正的危险不是计算机开始像人一样思考，而是人开始像计算机一样思考。",
  "voice_setting": {
    "pitch": 0,
    "speed": 1,
    "voice_id": "moss_audio_ce44fc67-7ce3-11f0-8de5-96e35d26fb85",
    "vol": 1
  }
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/t2a_async_v2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "speech-02-hd",
  "text": "真正的危险不是计算机开始像人一样思考，而是人开始像计算机一样思考。",
  "voice_setting": {
    "pitch": 0,
    "speed": 1,
    "voice_id": "moss_audio_ce44fc67-7ce3-11f0-8de5-96e35d26fb85",
    "vol": 1
  }
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "file_id": 0,
  "task_id": 0,
  "task_token": "string",
  "usage_characters": 0
}
```

***

## 同步语音合成 V2

`POST /minimax/v1/t2a_v2`

[https://platform.minimaxi.com/docs/api-reference/speech-t2a-http](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http)

### 请求参数 (Query / Path)

<ParamField header="Content-Type" type="string" required>
  请求体的媒介类型，必须设置为 application/json 以确保请求数据的格式为 JSON
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "model": "speech-02-hd",
  "text": "你好，欢迎使用语音合成服务！",
  "voice_setting": {
    "voice_id": "moss_audio_ce44fc67-7ce3-11f0-8de5-96e35d26fb85"
  }
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/t2a_v2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "speech-02-hd",
  "text": "你好，欢迎使用语音合成服务！",
  "voice_setting": {
    "voice_id": "moss_audio_ce44fc67-7ce3-11f0-8de5-96e35d26fb85"
  }
}'
```

***

## 提交视频生成任务

`POST /minimax/v1/video_generation`

文生视频或图生视频。提交后返回 `task_id`，通过 `GET /minimax/v1/query/video_generation` 轮询结果。

### 请求体参数 (Body)

<ParamField body="aigc_watermark" type="boolean">
  是否添加 AIGC 水印
</ParamField>

<ParamField body="callback_url" type="string">
  任务完成回调 URL
</ParamField>

<ParamField body="duration" type="integer">
  视频时长（秒）
</ParamField>

<ParamField body="fast_pretreatment" type="boolean">
  是否缩短优化耗时（仅 2.3/02 模型）
</ParamField>

<ParamField body="first_frame_image" type="string">
  首帧图片 URL 或 Base64（图生视频）；`MiniMax-Hailuo-2.3-Fast` 必填
</ParamField>

<ParamField body="last_frame_image" type="string">
  尾帧图片 URL 或 Base64（首尾帧生视频）
</ParamField>

<ParamField body="model" type="string" required>
  模型名称
</ParamField>

<ParamField body="prompt" type="string" required>
  视频内容描述提示词
</ParamField>

<ParamField body="prompt_optimizer" type="boolean">
  是否自动优化 prompt
</ParamField>

<ParamField body="resolution" type="string">
  分辨率（大写 P）
</ParamField>

<ParamField body="subject_reference" type="array">
  主体参考（S2V-01 模型）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "aigc_watermark": false,
  "callback_url": "https://your-domain.com/api/video/callback",
  "duration": 6,
  "first_frame_image": "https://filecdn.minimax.chat/public/fe9d04da-f60e-444d-a2e0-18ae743add33.jpeg",
  "last_frame_image": "https://filecdn.minimax.chat/public/97b7cd08-764e-4b8b-a7bf-87a0bd898575.jpeg",
  "model": "MiniMax-Hailuo-02",
  "prompt": "A little girl grow up [推进].",
  "prompt_optimizer": true,
  "resolution": "1080P"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/video_generation" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "aigc_watermark": false,
  "callback_url": "https://your-domain.com/api/video/callback",
  "duration": 6,
  "first_frame_image": "https://filecdn.minimax.chat/public/fe9d04da-f60e-444d-a2e0-18ae743add33.jpeg",
  "last_frame_image": "https://filecdn.minimax.chat/public/97b7cd08-764e-4b8b-a7bf-87a0bd898575.jpeg",
  "model": "MiniMax-Hailuo-02",
  "prompt": "A little girl grow up [推进].",
  "prompt_optimizer": true,
  "resolution": "1080P"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "task_id": "106916112212032"
}
```

***

## 音色复刻

`POST /minimax/v1/voice_clone`

基于上传的音频文件复刻音色，生成自定义 `voice_id`。

[https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone)
上传的音频文件格式需为：mp3、m4a、wav 格式
上传的音频文件的时长最少应不低于 10 秒，最长应不超过 5 分钟
上传的音频文件大小需不超过 20 mb
若使用该参数，则两个子属性（prompt\_audio、prompt\_text）都为必填项

### 请求体参数 (Body)

<ParamField body="aigc_watermark" type="boolean">
  是否在试听音频末尾添加音频节奏标识
</ParamField>

<ParamField body="clone_prompt" type="object">
  示例音频对象，增强相似度和稳定性 上传示例音频所得
</ParamField>

<ParamField body="file_id" type="integer" required>
  待复刻音频的 file\_id，通过文件上传接口获得。音频要求：mp3/m4a/wav 格式，10秒-5分钟，\<20MB
</ParamField>

<ParamField body="language_boost" type="string">
  增强对指定语言/方言的识别能力。可设置为 auto 自动判断，或指定具体语言
</ParamField>

<ParamField body="model" type="string">
  试听音频使用的语音模型 speech-2.6-hd, speech-2.6-turbo, speech-02-hd, speech-02-turbo
</ParamField>

<ParamField body="need_noise_reduction" type="boolean">
  是否开启降噪
</ParamField>

<ParamField body="need_volume_normalization" type="boolean">
  是否开启音量归一化
</ParamField>

<ParamField body="text" type="string">
  复刻试听文本（限制 1000 字符，支持语气词标签）
</ParamField>

<ParamField body="voice_id" type="string" required>
  自定义音色 ID（长度 8-256，首字符必须为字母，允许数字/字母/-/，末位不可为 -/ ）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "file_id": 12345678,
  "voice_id": "my-custom-voice-001"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/voice_clone" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": 12345678,
  "voice_id": "my-custom-voice-001"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

***

## 音色设计

`POST /minimax/v1/voice_design`

根据文本描述生成自定义音色，返回可用于语音合成的 `voice_id`。

### 请求参数 (Query / Path)

<ParamField header="Content-Type" type="string">
  请求体 Content-Type，一般为 application/json
</ParamField>

<ParamField header="Authorization" type="string">
  Bearer API Key
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "aigc_watermark": false,
  "preview_text": "夜深了，古屋里只有他一人。窗外传来若有若无的脚步声，他屏住呼吸，慢慢地，慢慢地，走向那扇吱呀作响的门……",
  "prompt": "讲述悬疑故事的播音员，声音低沉富有磁性。",
  "voice_id": "yssj00043333"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/minimax/v1/voice_design" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "aigc_watermark": false,
  "preview_text": "夜深了，古屋里只有他一人。窗外传来若有若无的脚步声，他屏住呼吸，慢慢地，慢慢地，走向那扇吱呀作响的门……",
  "prompt": "讲述悬疑故事的播音员，声音低沉富有磁性。",
  "voice_id": "yssj00043333"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "code": 0,
  "data": {
    "task_id": "task_example_001"
  },
  "message": "success"
}
```

***

## 文本合成

`POST /v1/messages`

MiniMax 文本对话接口（Apifox 导出路径为 `/v1/messages`，非 `/minimax/v1/` 前缀）。

[https://platform.minimaxi.com/docs/api-reference/text-post](https://platform.minimaxi.com/docs/api-reference/text-post)

### 请求体参数 (Body)

<ParamField body="max_completion_tokens" type="integer">
  最大补全 token 数
</ParamField>

<ParamField body="messages" type="array" required>
  对话消息列表
</ParamField>

<ParamField body="model" type="string" required>
  模型名称 / 型号 ID
</ParamField>

<ParamField body="stream" type="boolean">
  是否流式返回
</ParamField>

<ParamField body="stream_options" type="object">
  流式选项
</ParamField>

<ParamField body="temperature" type="number">
  采样温度；越高越随机
</ParamField>

<ParamField body="top_p" type="number">
  核采样概率阈值
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "max_completion_tokens": 2048,
  "messages": [
    {
      "content": "你是一个专业、友好的AI助手。",
      "name": "AI助手",
      "role": "system",
      "x-i18n": {
        "en-US": {
          "name": "AI assistant"
        }
      }
    },
    {
      "content": "帮我写一首关于秋天的诗。",
      "name": "张三",
      "role": "user",
      "x-i18n": {
        "en-US": {
          "name": "John Doe"
        }
      }
    }
  ],
  "model": "MiniMax-M2.1",
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.9,
  "top_p": 0.95
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/messages" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "max_completion_tokens": 2048,
  "messages": [
    {
      "content": "你是一个专业、友好的AI助手。",
      "name": "AI助手",
      "role": "system",
      "x-i18n": {
        "en-US": {
          "name": "AI assistant"
        }
      }
    },
    {
      "content": "帮我写一首关于秋天的诗。",
      "name": "张三",
      "role": "user",
      "x-i18n": {
        "en-US": {
          "name": "John Doe"
        }
      }
    }
  ],
  "model": "MiniMax-M2.1",
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.9,
  "top_p": 0.95
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "base_resp": {
    "status_code": 0,
    "status_msg": ""
  },
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "audio_content": "",
        "content": "您好！请问有什么可以帮您？",
        "name": "MiniMax AI",
        "reasoning_content": "...省略",
        "role": "assistant"
      }
    }
  ],
  "created": 1755153113,
  "id": "04ecb5d9b1921ae0fb0e8da9017a5474",
  "input_sensitive": false,
  "input_sensitive_type": 0,
  "model": "MiniMax-M1",
  "object": "chat.completion",
  "output_sensitive": false,
  "output_sensitive_int": 0,
  "output_sensitive_type": 0,
  "usage": {
    "completion_tokens": 223,
    "completion_tokens_details": {
      "reasoning_tokens": 214
    },
    "prompt_tokens": 26,
    "total_characters": 0,
    "total_tokens": 249
  }
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.