# Anthropic 主动缓存 Source: https://platform.minimaxi.com/docs/api-reference/anthropic-api-compatible-cache MiniMax 支持 Anthropic API 兼容，通过显式设置进行管理的 cache 使用方式，我们称之为主动缓存。 ## 快速开始 以下是使用 `cache_control` 块在 Anthropic 兼容API 中实现 prompt 缓存的快速示例： ```python Python theme={null} theme={null} import anthropic client = anthropic.Anthropic( base_url="https://api.minimax.cn/anthropic", api_key="" # 替换为您的 MiniMax API Key ) response = client.messages.create( model="MiniMax-M2.7", max_tokens=1024, system=[ { "type": "text", "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n", }, { "type": "text", "text": "", "cache_control": {"type": "ephemeral"} } ], messages=[{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}], ) print(response.usage.model_dump_json()) # 使用相同的缓存内容再次调用 # 只需要更改用户消息 response = client.messages.create(.....) print(response.usage.model_dump_json()) ``` ```JSON JSON theme={null} theme={null} {"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393} {"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393} ``` 在此示例中，《傲慢与偏见》的完整文本使用 `cache_control` 参数进行缓存。这使得大文本可以在多次 API 调用中复用而无需每次都重新处理。通过仅更改用户消息，您可以提出关于该书的各种问题，同时利用缓存的内容，从而获得更快的响应并降低成本。 *** ## Prompt 缓存的工作原理 当您发送启用了 prompt 缓存的请求时： 1. 系统检查指定缓存断点 (cache\_control) 之前的 prompt 前缀是否已被此前的请求缓存； 2. 如果找到，它将使用缓存版本，显著减少处理时间和成本； 3. 如果未找到，它将处理完整的 prompt 并在生成响应时对其进行缓存。 这在以下场景的使用中特别有用： * 包含许多示例的 prompt * 大量上下文或背景信息 * 具有一致指令的重复任务 * 长时间的多轮对话 缓存内容的**生命周期为 5 分钟**。每次命中缓存内容时，缓存生命周期都会自动刷新，无需额外费用。 *** ## 支持的模型和定价 Prompt 缓存引入了差异化的定价结构。下表显示了每个支持模型的百万 token 价格： | **模型** | **输入价格**
元/百万 tokens | **输出价格**
元/百万 tokens | **缓存读取**
元/百万 tokens | **缓存写入**
元/百万 tokens | | :------------------------------------------- | :------------------------: | :-------------------------: | :------------------------: | :------------------------: | | **MiniMax-M2.7** | 2.1 | 8.4 | 0.42 | 2.625 | | **MiniMax-M2.7-highspeed**
效果不变，更快，更高效 | 2.1 | 16.8 | 0.42 | 2.625 | | **MiniMax-M2.5** | 2.1 | 8.4 | 0.21 | 2.625 | | **MiniMax-M2.5-highspeed**
效果不变，更快，更高效 | 2.1 | 16.8 | 0.21 | 2.625 | | **MiniMax-M2.1** | 2.1 | 8.4 | 0.21 | 2.625 | | **MiniMax-M2.1-highspeed**
更快，更高效 | 2.1 | 16.8 | 0.21 | 2.625 | | **MiniMax-M2** | 2.1 | 8.4 | 0.21 | 2.625 | 上表反映了以下 prompt 缓存定价规则： * 缓存写入与缓存读取 token 价格以上表为准 *** ## 如何实现 Prompt 缓存 ### 构建 prompt 将静态可复用的内容（工具定义、系统指令、示例等）放在 prompt 的开头。使用 `cache_control` 参数标记可缓存内容的结束位置。 缓存前缀按以下顺序创建：`tools` → `system` → `messages`。此顺序形成一个层次结构，其中每个级别都建立在前一个级别之上。 ### 自动前缀检查 您可以在静态内容的末尾只使用一个缓存断点，系统将自动找到最长的匹配前缀。 **三个核心原则：** 1. **缓存内容是累积的**：当您使用 `cache_control` 标记一个块时，缓存内容是从所有先前的块按顺序生成的。这意味着每个缓存都依赖于它之前的所有内容。 2. **向前顺序检查**：系统通过从显式 Cache 断点向前来检查缓存命中，这确保了尽量命中最长的缓存。 3. **20 块回溯窗口**：系统在每个显式 Cache 断点之前最多检查 20 个块。如果检查 20 个块后未找到匹配项，将停止检查并移至上一个显式断点（如果有）。 **举例：** 如果在第30个块设置了 `cache_control`, 重复进行请求: 1. 若无任何块的内容被修改，则系统能命中 1\~30 块所有内容的缓存; 2. 若第 25 个块内容被修改，则系统从第 30 块往前找，直到第 24 块可以匹配缓存，那么 1\~24 块内容将会命中缓存; 3. 若第 5 个块内容被修改，则系统从第 30 块往前找，找到第 11 块仍未匹配缓存，本次缓存失效; ### 可被缓存的内容 请求中的大多数块都可以使用 `cache_control` 指定进行缓存，包括： * **工具**：`tools` 数组中的工具定义 * **系统消息**：`system` 数组中的内容块 * **文本消息**：`messages.content` 数组中的内容块，适用 user 和 assistant 的轮次 * **工具使用和工具结果**：`messages.content` 数组中的内容块中的 tool\_use 和 tool\_result 类型，适用 user 和 assistant 的轮次 使用 `cache_control` 标记任何这些元素以启用该部分请求的缓存。 ### 缓存失效 对缓存内容的修改可能会使部分或全部缓存失效。 如 [构建 prompt](#构建-prompt) 中所述，缓存遵循层次结构：`tools` → `system` → `messages`。每个级别的更改都会使该级别及所有后续级别失效。 ### 缓存性能 使用 `usage` 对象中的以下 API 响应字段监控缓存性能（或在流式传输)时的 `message_start` 事件中）： * `cache_creation_input_tokens`：创建新缓存条目时写入缓存的 token 数量。 * `cache_read_input_tokens`：此请求从缓存中检索的 token 数量。 * `input_tokens`：未从缓存读取或用于创建缓存的输入 token 数量（即最后一个缓存断点之后的 token）。 **了解 token 构成** 计算总输入 token： ``` total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens ``` **按位置分解：** * `cache_read_input_tokens`：断点之前的 token，已缓存（读取） * `cache_creation_input_tokens`：断点之前的 token，正在缓存（写入） * `input_tokens`：最后一个断点之后的 token（不符合缓存条件） **示例：** 一个包含 100,000 个已缓存内容 token（从缓存读取）、0 个正在缓存的新内容 token 和 50 个用户消息 token（缓存断点之后）的请求： * `cache_read_input_tokens`：100,000 * `cache_creation_input_tokens`：0 * `input_tokens`：50 * **总输入 token**：100,050 个 token 这对于理解成本和速率限制都很重要。有效使用缓存时，`input_tokens` 通常会比您的总输入小得多。 ### 常见问题 如果您遇到不符合预期的缓存行为： * **内容一致性**：验证缓存部分在多次调用中是相同的，并且在相同位置使用 `cache_control` 标记 * **缓存过期时间**：确认调用在缓存生命周期内进行（5 分钟） * **块数量的限制**：若一次调用有超过 20 个内容块的 prompt，可添加额外的 `cache_control` 参数以确保所有内容都可以被缓存（系统自动检查每个断点之前的约 20 个块） * **未生效的缓存断点**：一次调用最多支持 4 个 `cache_control` 参数，若超过 4 个，只取从后向前最近的 4 个 *** ## 更多示例 以下代码示例展示了各种 prompt 缓存模式，并演示了如何在不同场景中实现缓存： ```Python Python theme={null} theme={null} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="MiniMax-M2.7", max_tokens=1024, system=[ { "type": "text", "text": "You are an AI assistant tasked with analyzing legal documents." }, { "type": "text", "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", "cache_control": {"type": "ephemeral"} } ], messages=[ { "role": "user", "content": "What are the key terms and conditions in this agreement?" } ] ) print(response.model_dump_json()) ``` 此示例演示了基本的 prompt 缓存，通过缓存法律协议的完整文本，同时保持用户指令不缓存。 **首次请求：** * `input_tokens`：仅用户消息中的 token * `cache_creation_input_tokens`：整个系统消息中的 token，包括法律文档 * `cache_read_input_tokens`：0（首次请求无缓存命中） **缓存生命周期内的后续请求：** * `input_tokens`：仅用户消息中的 token * `cache_creation_input_tokens`：0（无新缓存创建） * `cache_read_input_tokens`：整个缓存系统消息中的 token ```Python Python theme={null} theme={null} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="MiniMax-M2.7", max_tokens=1024, tools=[ { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature, either 'celsius' or 'fahrenheit'" } }, "required": ["location"] }, }, # 更多工具 { "name": "get_time", "description": "Get the current time in a given time zone", "input_schema": { "type": "object", "properties": { "timezone": { "type": "string", "description": "The IANA time zone name, e.g. America/Los_Angeles" } }, "required": ["timezone"] }, "cache_control": {"type": "ephemeral"} } ], messages=[ { "role": "user", "content": "What's the weather and time in New York?" } ] ) print(response.model_dump_json()) ``` 此示例演示了缓存工具定义。 `cache_control` 参数放置在最后一个工具（`get_time`）上，以将所有工具指定为静态前缀的一部分。 所有工具定义，包括 `get_weather` 和 `get_time` 之前定义的任何其他工具，都将作为单个前缀缓存。 当您有一组一致的工具要在多个请求中复用而无需每次都重新处理时，此方法非常理想。 **首次请求：** * `input_tokens`：用户消息中的 token * `cache_creation_input_tokens`：所有工具定义和系统提示中的 token * `cache_read_input_tokens`：0（首次请求无缓存命中） **缓存生命周期内的后续请求：** * `input_tokens`：用户消息中的 token * `cache_creation_input_tokens`：0（无新缓存创建） * `cache_read_input_tokens`：所有缓存工具定义和系统提示中的 token ```Python Python theme={null} theme={null} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="MiniMax-M2.7", max_tokens=1024, system=[ { "type": "text", "text": "...长系统提示", "cache_control": {"type": "ephemeral"} } ], messages=[ # ...到目前为止的长对话 { "role": "user", "content": [ { "type": "text", "text": "Hello, can you tell me more about the solar system?", } ] }, { "role": "assistant", "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?" }, { "role": "user", "content": [ { "type": "text", "text": "Good to know." }, { "type": "text", "text": "Tell me more about Mars.", "cache_control": {"type": "ephemeral"} } ] } ] ) print(response.model_dump_json()) ``` 此示例演示了在多轮对话中的 prompt 缓存。 在每一轮中，我们使用 `cache_control` 标记最终消息的最后一个块，以启用对话的增量缓存。系统会自动查找并使用最长的先前缓存前缀进行后续消息。之前使用 `cache_control` 标记的块不需要再次标记——如果在 5 分钟内访问，它们仍然会导致缓存命中（和缓存刷新）。 请注意，`cache_control` 也放置在系统消息上。这确保了如果它从缓存中被驱逐（超过 5 分钟未使用后），它将在下一个请求时重新缓存。 这种方法非常适合在持续对话中保持上下文，而无需重复处理相同的信息。 正确设置后，您应该在每个请求的使用响应中看到以下内容： * `input_tokens`：新用户消息中的 token（通常很少） * `cache_creation_input_tokens`：新助手和用户轮次中的 token * `cache_read_input_tokens`：对话中直到前一轮的 token ```Python Python theme={null} theme={null} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="MiniMax-M2.7", max_tokens=1024, tools=[ { "name": "search_documents", "description": "Search through the knowledge base", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query" } }, "required": ["query"] } }, { "name": "get_document", "description": "Retrieve a specific document by ID", "input_schema": { "type": "object", "properties": { "doc_id": { "type": "string", "description": "Document ID" } }, "required": ["doc_id"] }, "cache_control": {"type": "ephemeral"} } ], system=[ { "type": "text", "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", "cache_control": {"type": "ephemeral"} }, { "type": "text", "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", "cache_control": {"type": "ephemeral"} } ], messages=[ { "role": "user", "content": "Can you search for information about Mars rovers?" }, { "role": "assistant", "content": [ { "type": "tool_use", "id": "tool_1", "name": "search_documents", "input": {"query": "Mars rovers"} } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "tool_1", "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)" } ] }, { "role": "assistant", "content": [ { "type": "text", "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document." } ] }, { "role": "user", "content": [ { "type": "text", "text": "Yes, please tell me about the Perseverance rover specifically.", "cache_control": {"type": "ephemeral"} } ] } ] ) print(response.model_dump_json()) ``` 这个综合示例演示了如何使用所有 4 个可用的缓存断点来优化 prompt 的不同部分： 此模式特别适用于： * 具有大型文档上下文的 RAG 应用程序 * 使用多个工具的 Agent 系统 * 保持上下文的长时间对话 * 需要独立优化 prompt 不同部分的应用程序 # 接口概览 Source: https://platform.minimaxi.com/docs/api-reference/api-overview MiniMax 开放平台 API 接口能力概览，包括语言、视频、语音、图像、音乐和文件管理等多模态能力。 ## 获取 API Key * **按量付费**：通过 [接口密钥 > 创建新的 API Key](https://platform.minimaxi.com/user-center/basic-information/interface-key)，获取 **API Key** 按量付费支持使用所有模态模型，包括语言、视频、语音、图像等 * **Token Plan**：通过 [订阅管理 > Token Plan](https://platform.minimaxi.com/user-center/payment/token-plan)，查看 **订阅 Key** 订阅 Key 用于 Token Plan 订阅套餐和已购积分，并与按量计费 API Key 相互独立。详情见 [Token Plan 概要](/docs/token-plan/intro) *** ## 语言模型 语言模型接口使用 **MiniMax M3**，**MiniMax M2.7**，**MiniMax M2.7-highspeed**，**MiniMax M2.5**，**MiniMax M2.5-highspeed**，**MiniMax M2.1**，**MiniMax M2.1-highspeed**，**MiniMax M2** 根据输入的上下文，让模型生成对话内容、工具调用。 可通过 **HTTP** 请求、**Anthropic SDK**（推荐） 或 **OpenAI SDK** 接入。 **支持模型** | 模型名称 | 输入输出总 token | 模型介绍 | | :--------------------- | :---------: | :---------------------------------------------------------- | | MiniMax-M3 | 1,000,000 | **最新 M 系列语言模型，适用于 Agent 推理、工具调用、代码和长上下文任务**（输出速度约 100+ TPS） | | MiniMax-M2.7 | 204800 | **开启模型的自我迭代 (输出速度约60tps)** | | MiniMax-M2.7-highspeed | 204800 | **M2.7 极速版：效果不变，更快，更敏捷 (输出速度约100tps)** | | MiniMax-M2.5 | 204800 | **顶尖性能与极致性价比，轻松驾驭复杂任务 (输出速度约60tps)** | | MiniMax-M2.5-highspeed | 204800 | **M2.5 极速版：效果不变，更快，更敏捷 (输出速度约100tps)** | | MiniMax-M2.1 | 204800 | **强大多语言编程能力，全面升级编程体验 (输出速度约60tps)** | | MiniMax-M2.1-highspeed | 204800 | **M2.1 极速版：效果不变，更快，更敏捷 (输出速度约100tps)** | | MiniMax-M2 | 204800 | **专为高效编码与Agent工作流而生** | 如果在使用模型过程中遇到任何问题： * 通过邮箱 [Model@minimaxi.com](mailto:Model@minimaxi.com) 等官方渠道联系我们的技术支持团队 * 在我们的 [Github](https://github.com/MiniMax-AI/MiniMax-M2/issues) 仓库提交Issue 通过 Anthropic SDK 调用 MiniMax 模型 通过 OpenAI SDK 调用 MiniMax 模型 *** ## 视频模型 本接口支持文本、图片、视频、音频等多模态输入进行视频生成，覆盖文生视频、图生视频、首尾帧生成视频、多模态参考生视频等场景。 **支持模型** | 模型 | 功能 | | :------------- | :----------------------------------------------------------------- | | MiniMax-H3 | 多模态视频生成模型，支持文生 / 图生 / 首尾帧 / 多模态参考，768P / 2K 分辨率，4–15s 时长 | | MiniMax-H3-Max | 极速生成模型，仅支持文生 / 图生（首帧、尾帧），不支持多模态参考；480P / 768P 分辨率（不支持 2K），5–15s 时长 | **接口说明** 两个模型共用同一套 `content[]` 请求协议与查询接口，切换模型只需改 `model` 字段。MiniMax-H3 任务采用异步方式，提供**创建视频生成任务**、**创建 H3-Context-IR 任务**和**创建视频再生成任务**三个创建入口，并共用查询、列表以及取消或删除接口；MiniMax-H3-Max 仅支持**创建视频生成任务**入口。使用步骤如下： 1. 根据场景创建视频生成任务，使用相同的多模态输入创建 H3-Context-IR 任务，或对符合 MiniMax-H3 768P 输出规格的源视频创建视频再生成任务；再生成请求必须且只能包含一个 `role=base_video` 的源视频项。成功后均返回 `task_id`。 2. 使用**查询任务**接口按 `task_id` 获取状态与结果；视频任务成功后从 `content.url` 获取成片地址，H3-Context-IR 任务成功后从 `content.prompt` 获取增强提示词。也可以使用**查询任务列表**接口批量查看，并通过 `task_type` 区分 `generation`、`h3_context_ir` 与 `regeneration`。 3. 对排队中的任务，可使用**取消或删除任务**接口取消；对成功或失败的任务，可使用同一接口删除任务记录。 基于多模态 content 输入创建视频生成任务 深度理解视频生成的多模态上下文并生成结构化增强提示词 将符合 MiniMax-H3 768P 输出规格的视频再生成为 2K 视频 按 task\_id 查询任务状态并获取成片下载地址 分页查询最近 7 天内的任务并按任务类型过滤 取消排队中的任务，或删除成功和失败的任务记录 *** ## 语音模型 语音模型提供**语音合成**、**音色复刻**与**音色设计**能力，支持 40 种语言、300+ 系统音色，可按需选择同步或异步方式生成。 接口均为无状态设计：单次调用仅处理传入内容，不存储用户数据，不涉及业务逻辑状态。 **支持模型** | 模型 | 特性 | | :--------------- | :----------------------------- | | speech-2.8-hd | 最新的 HD 模型，情绪渲染融合语气词，重塑自然听感 | | speech-2.8-turbo | 最新的 Turbo 模型，极致生成速度，更自然逼真的音频效果 | | speech-2.6-hd | HD 模型，韵律表现出色，极致音质与韵律表现，生成更快更自然 | | speech-2.6-turbo | Turbo 模型，音质优异，超低时延，响应更灵敏 | | speech-02-hd | 拥有出色的韵律、稳定性和复刻相似度，音质表现突出 | | speech-02-turbo | 拥有出色的韵律和稳定性，小语种能力加强，性能表现出色 | **接口说明** 四类能力共用上述模型： 1. **同步语音合成**：文本实时转语音，单次最长 **10,000 字符**；支持 300+ 系统音色与复刻音色、音量/语调/语速调整、按比例混音、流式输出，输出格式含 mp3、pcm、flac、wav。提供 **HTTP** 与 **WebSocket** 两种接入方式。 2. **异步长文本语音合成**：单次最长 **100 万字符**，适合整本书籍等长文本；支持句级时间戳（字幕）。创建任务得到 `task_id`，查询成功后用返回的 `file_id` 经文件接口下载（下载 URL 自返回起 **9 小时**内有效）。 3. **音色快速复刻**：上传待复刻音频获取 `file_id`（可选再上传示例音频增强效果），再调用快速复刻生成自定义 `voice_id`。需先完成个人或企业认证。 4. **音色设计**：基于声音描述 prompt 生成个性化音色，产出的 `voice_id` 可直接用于上述合成接口。 音色复刻与音色设计产出的均为**临时音色**：费用在首次用于语音合成时才收取（不含接口内试听）；若 \*\*168 小时（7 天）\*\*内未在任意语音合成接口中使用，该音色将被删除。 | 支持语种 | | | | :------------------ | :------------------- | :-------------------- | | 1. 中文（Chinese） | 15. 土耳其语（Turkish） | 28. 马来语（Malay） | | 2. 粤语（Cantonese） | 16. 荷兰语（Dutch） | 29. 波斯语（Persian） | | 3. 英语（English） | 17. 乌克兰语（Ukrainian） | 30. 斯洛伐克语（Slovak） | | 4. 西班牙语（Spanish） | 18. 泰语（Thai） | 31. 瑞典语（Swedish） | | 5. 法语（French） | 19. 波兰语（Polish） | 32. 克罗地亚语（Croatian） | | 6. 俄语（Russian） | 20. 罗马尼亚语（Romanian） | 33. 菲律宾语（Filipino） | | 7. 德语（German） | 21. 希腊语（Greek） | 34. 匈牙利语（Hungarian） | | 8. 葡萄牙语（Portuguese） | 22. 捷克语（Czech） | 35. 挪威语（Norwegian） | | 9. 阿拉伯语（Arabic） | 23. 芬兰语（Finnish） | 36. 斯洛文尼亚语（Slovenian） | | 10. 意大利语（Italian） | 24. 印地语（Hindi） | 37. 加泰罗尼亚语（Catalan） | | 11. 日语（Japanese） | 25. 保加利亚语（Bulgarian） | 38. 尼诺斯克语（Nynorsk） | | 12. 韩语（Korean） | 26. 丹麦语（Danish） | 39. 泰米尔语（Tamil） | | 13. 印尼语（Indonesian） | 27. 希伯来语（Hebrew） | 40. 阿非利卡语（Afrikaans） | | 14. 越南语（Vietnamese） | | | 通过 HTTP 请求进行语音合成 通过 WebSocket 进行流式语音合成 创建长文本语音生成任务 查询语音生成任务状态 上传待克隆的音频文件 执行音色克隆 基于描述生成个性化音色 *** ## 图片生成 本接口支持基于用户提供的文本或参考图片，进行创意图像生成。支持设置不同图片比例和长宽像素设置，满足不同场景下图像需求。 **接口说明** 通过创建图片生成任务接口，使用文本描述和参考图片，进行图像生成。 **模型列表** | 模型名称 | 简介 | | :------------ | :------------------------------ | | image-01 | 图像生成模型，画面表现细腻，支持文生图、图生图（人物主体参考） | | image-01-live | 图像生成模型，在 image-01 基础上额外支持多种画风设置 | 基于文本描述生成图像 基于参考图片生成图像 *** ## 音乐生成 自 2026 年 8 月 20 日起，付费接口（音乐生成、歌词生成）不再面向新用户提供服务，历史付费用户可继续使用现有 API 服务；免费音乐生成接口（Music-3.0-free、Music-2.6-free、music-cover-free）停止服务。 如需体验或使用音乐生成能力，可前往 [MiniMax Audio](https://www.minimaxi.com/audio)，或使用已发布在 [Hugging Face](https://huggingface.co/MiniMaxAI/MiniMax-Music3) 和 [魔搭 ModelScope](https://modelscope.cn/models/MiniMax/MiniMax-Music3) 的 MiniMax Music 3 开源模型。 本接口根据歌曲描述（prompt）和歌词（lyrics），生成一首人声的歌曲。 **支持模型** | 模型名称 | 使用方法 | | :-------- | :------------------------------ | | music-3.0 | 最新音乐生成模型，支持用户输入音乐灵感和歌词，生成 AI 音乐 | 根据描述和歌词生成音乐 *** ## 文件管理 本接口是作为文件管理接口，配合 MiniMax 开放平台的其他接口使用。 **接口说明** 本接口是作为文件管理接口，配合其他接口使用。共包含 5 个接口：**上传**、**列出**、**检索**、**下载**、**删除**。 文件的支持格式、容量及大小限制以**上传文件**接口文档为准，详见 [上传文件](/docs/api-reference/file-management-upload)。 上传文件到平台 获取已上传的文件列表 *** ## 工具 **Web Search** `web_search` 是由 MiniMax 在服务端托管和执行的联网搜索工具。模型可在生成回复时自动检索实时信息，并基于搜索结果作答；支持通过 Anthropic Messages API 和 OpenAI Responses API 调用。接口说明与示例详见 [Web Search](/docs/guides/server-tools#web_search)。 **官方 MCP** MiniMax 提供官方的 [Python 版本](https://github.com/MiniMax-AI/MiniMax-MCP) 和 [JavaScript 版本](https://github.com/MiniMax-AI/MiniMax-MCP-JS) 模型上下文协议（MCP）服务器实现代码，支持语音合成、音色克隆、视频生成、音乐生成等功能，详细说明请参考 [MiniMax MCP 使用指南](/docs/guides/mcp-guide) **语音调试台** # 错误码查询 Source: https://platform.minimaxi.com/docs/api-reference/errorcode 本文档汇总 MiniMax 接口常见错误码及对应解决方案，帮助开发者快速排查并解决调用问题。 如需反馈问题，请提供 Header 中的 trace\_id，以便我们为您排查。 | 错误码 | 含义 | 解决方法 | | :---- | :---------------------- | :---------------------------------------------------------------------- | | 1000 | 未知错误/系统默认错误 | 请稍后再试 | | 1001 | 请求超时 | 请稍后再试 | | 1002 | 请求频率超限 | 请稍后再试 | | 1004 | 未授权/Token 不匹配/Cookie 缺失 | 请检查 API Key | | 1008 | 余额不足 | 请检查您的账户余额 | | 1024 | 内部错误 | 请稍后再试 | | 1026 | 输入内容涉敏 | 请调整输入内容 | | 1027 | 输出内容涉敏 | 请调整输入内容 | | 1033 | 系统错误/下游服务错误 | 请稍后再试 | | 1039 | Token 限制 | 请调整 max\_tokens | | 1041 | 连接数限制 | 请联系我们 | | 1042 | 不可见字符比例超限/非法字符超过 10% | 请检查输入内容，是否包含不可见字符或非法字符 | | 1043 | ASR 相似度检查失败 | 请检查 file\_id 与 text\_validation 匹配度 | | 1044 | 克隆提示词相似度检查失败 | 请检查克隆提示音频和提示词 | | 2013 | 参数错误 | 请检查请求参数 | | 20132 | 语音克隆样本或 voice\_id 参数错误 | 请检查 Voice Cloning 接口下的 file\_id 和 T2A v2，T2A Large v2 接口下的 voice\_id 参数 | | 2037 | 语音时长不符合要求(太长或太短) | 请检查 voice\_clone file\_id 文件时长，最少应不低于 10 秒，最长应不超过 5 分钟 | | 2038 | 用户语音克隆功能被禁用 | 使用语音克隆功能需要完成账户身份认证，请根据您的使用需求在账户系管理》账户信息中进行个人或企业认证 | | 2039 | 语音克隆 voice\_id 重复 | 请修改 voice\_id，确保未和已有 voice\_id 重复 | | 2042 | 无权访问该 voice\_id | 请确认是否为该 voice\_id 创建者 | | 2045 | 请求频率增长超限 | 请避免请求骤增骤减情况 | | 2048 | 语音克隆提示音频太长 | 请调整 prompt\_audio 音频文件时长（＜ 8s） | | 2049 | 无效的 API Key | 请检查 API Key | | 2056 | 超出Token Plan资源限制 | 请等待下一个时间段资源释放后，再次尝试 | 如有其他疑问，请联系我们 [api@minimaxi.com](mailto:api@minimaxi.com)。 # 文件删除 Source: https://platform.minimaxi.com/docs/api-reference/file-management-delete api-reference/file/management/api/openapi.json POST /v1/files/delete 使用本接口，删除 MiniMax 开放平台上的相关文件。 # 文件列出 Source: https://platform.minimaxi.com/docs/api-reference/file-management-list api-reference/file/management/api/openapi.json GET /v1/files/list 使用本接口，列出不同分类下的文件。 # 文件检索 Source: https://platform.minimaxi.com/docs/api-reference/file-management-retrieve api-reference/file/management/api/openapi.json GET /v1/files/retrieve 使用本接口，检索 MiniMax 开放平台上的文件。 # 文件下载 Source: https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content api-reference/file/management/api/openapi.json GET /v1/files/retrieve_content 使用本接口，下载模型生成的文件。 # 文件上传 Source: https://platform.minimaxi.com/docs/api-reference/file-management-upload api-reference/file/management/api/openapi.json POST /v1/files/upload 使用本接口，在 MiniMax 开放平台，上传所需文件。 # 图生图 Source: https://platform.minimaxi.com/docs/api-reference/image-generation-i2i api-reference/image/generation/api/image-to-image.json POST /v1/image_generation 使用本接口，上传图片内容，进行图片生成。 # 文生图 Source: https://platform.minimaxi.com/docs/api-reference/image-generation-t2i api-reference/image/generation/api/text-to-image.json POST /v1/image_generation 使用本接口，输出文本内容，进行图片生成。 # 歌词生成 (Lyrics Generation) Source: https://platform.minimaxi.com/docs/api-reference/lyrics-generation api-reference/music/lyrics/api/openapi.json POST /v1/lyrics_generation 使用本接口生成歌词，支持完整歌曲创作和歌词编辑/续写。 自 2026 年 8 月 20 日起，付费接口（音乐生成、歌词生成）不再面向新用户提供服务，历史付费用户可继续使用现有 API 服务；免费音乐生成接口（Music-3.0-free、Music-2.6-free、music-cover-free）停止服务。 如需体验或使用音乐生成能力，可前往 [MiniMax Audio](https://www.minimaxi.com/audio)，或使用已发布在 [Hugging Face](https://huggingface.co/MiniMaxAI/MiniMax-Music3) 和 [魔搭 ModelScope](https://modelscope.cn/models/MiniMax/MiniMax-Music3) 的 MiniMax Music 3 开源模型。 # 获取模型列表 Source: https://platform.minimaxi.com/docs/api-reference/models/anthropic/list-models api-reference/models/anthropic/api/list-models.json GET /anthropic/v1/models 获取平台支持的所有模型列表，兼容 Anthropic API 规范。 # 获取单个模型详情 Source: https://platform.minimaxi.com/docs/api-reference/models/anthropic/retrieve-model api-reference/models/anthropic/api/retrieve-model.json GET /anthropic/v1/models/{model_id} 获取指定模型的详细信息，兼容 Anthropic API 规范。 # 获取模型列表 Source: https://platform.minimaxi.com/docs/api-reference/models/openai/list-models api-reference/models/openai/api/list-models.json GET /v1/models 获取平台支持的所有模型列表，兼容 OpenAI API 规范 # 获取单个模型详情 Source: https://platform.minimaxi.com/docs/api-reference/models/openai/retrieve-model api-reference/models/openai/api/retrieve-model.json GET /v1/models/{model_id} 获取指定模型的详细信息，兼容 OpenAI API 规范。 # 翻唱前处理 (Music Cover Preprocess) Source: https://platform.minimaxi.com/docs/api-reference/music-cover-preprocess api-reference/music/api/openapi.json POST /v1/music_cover_preprocess 对参考音频进行预处理，提取音频特征和歌词，用于两步翻唱流程。 自 2026 年 8 月 20 日起，付费接口（音乐生成、歌词生成）不再面向新用户提供服务，历史付费用户可继续使用现有 API 服务；免费音乐生成接口（Music-3.0-free、Music-2.6-free、music-cover-free）停止服务。 如需体验或使用音乐生成能力，可前往 [MiniMax Audio](https://www.minimaxi.com/audio)，或使用已发布在 [Hugging Face](https://huggingface.co/MiniMaxAI/MiniMax-Music3) 和 [魔搭 ModelScope](https://modelscope.cn/models/MiniMax/MiniMax-Music3) 的 MiniMax Music 3 开源模型。 # 音乐生成 (Music Generation) Source: https://platform.minimaxi.com/docs/api-reference/music-generation api-reference/music/api/openapi.json POST /v1/music_generation 使用本接口，输入歌词和歌曲描述，进行歌曲生成。 自 2026 年 8 月 20 日起，付费接口（音乐生成、歌词生成）不再面向新用户提供服务，历史付费用户可继续使用现有 API 服务；免费音乐生成接口（Music-3.0-free、Music-2.6-free、music-cover-free）停止服务。 如需体验或使用音乐生成能力，可前往 [MiniMax Audio](https://www.minimaxi.com/audio)，或使用已发布在 [Hugging Face](https://huggingface.co/MiniMaxAI/MiniMax-Music3) 和 [魔搭 ModelScope](https://modelscope.cn/models/MiniMax/MiniMax-Music3) 的 MiniMax Music 3 开源模型。 # 对话生成 Source: https://platform.minimaxi.com/docs/api-reference/responses-create api-reference/text/api/openapi-responses.json POST /v1/responses OpenAI Responses API 兼容的主接口调用MiniMax 模型，生成模型回复，支持流式与非流式。 ## 推理控制 对于 `MiniMax-M3`，`reasoning` 字段用于控制响应是否包含推理输出。 * 如果省略 `reasoning`，默认关闭推理，响应不会包含 `type: "reasoning"` 的输出项。 * `reasoning: {"effort": "none"}` 是默认行为，可关闭 `MiniMax-M3` 的推理输出。 * `minimal`、`low`、`medium` 和 `high` 这些取值会被兼容接收并开启推理输出，但不会调节 MiniMax-M3 的推理深度。 * 对于 M2.x 模型，推理无法关闭；即使传入 `reasoning: {"effort": "none"}`，推理仍会保持开启。 ```json theme={null} { "model": "MiniMax-M3", "input": "9.11 和 9.9 哪个更大？" } ``` ```json theme={null} { "model": "MiniMax-M3", "input": "9.11 和 9.9 哪个更大？", "reasoning": { "effort": "minimal" } } ``` # Token 估算 Source: https://platform.minimaxi.com/docs/api-reference/responses-input-tokens api-reference/text/api/openapi-responses.json POST /v1/responses/input_tokens 估算请求的输入 token 数，不真正调用模型生成。常用于在调用主接口前评估请求成本与是否触发上下文长度上限。 # 创建异步语音合成任务 Source: https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create api-reference/speech/t2a-async/api/openapi.json POST /v1/t2a_async_v2 使用本接口，创建异步语音合成任务。 ### 返回文件信息 #### txt 文件 输出文件如下所示 * 音频文件：文件格式遵从请求体设置 * 字幕文件：精确到句的字幕信息 * 额外信息 JSON 文件：音频文件相关的附加信息 #### json 文件 * `title`，若该字段为空，则不输出该字段的文件 * 音频文件：文件格式遵从请求体设置 * 字幕文件：精确到句的字幕信息 * 额外信息 JSON 文件：音频文件相关的附加信息 * `content`，若该字段为空，则不输出该字段的文件 * 音频文件：文件格式遵从请求体设置 * 字幕文件：精确到句的字幕信息 * 额外信息 JSON 文件：音频文件相关的附加信息 * `extra`，若该字段为空，则不输出该字段的文件 * 音频文件：文件格式遵从请求体设置 * 字幕文件：精确到句的字幕信息 * 额外信息 JSON 文件：音频文件相关的附加信息 # 查询语音生成任务状态 Source: https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query api-reference/speech/t2a-async/api/openapi.json GET /v1/query/t2a_async_query_v2 使用本接口，查询异步语音合成任务状态。 **注：该 API 限制每秒最多查询 10 次。** # 同步语音合成 HTTP Source: https://platform.minimaxi.com/docs/api-reference/speech-t2a-http api-reference/speech/t2a/api/openapi.json POST /v1/t2a_v2 使用本接口，在HTTP网络通信协议下进行同步语音合成。 备用接口地址 `https://api-bj.minimaxi.com/v1/t2a_v2` # 同步语音合成 WebSocket Source: https://platform.minimaxi.com/docs/api-reference/speech-t2a-websocket 使用本接口，在WebSocket网络通信协议下进行同步语音合成。 # 同步语音合成 WebSocket（双向流式） Source: https://platform.minimaxi.com/docs/api-reference/speech-t2a-websocket-bidi 支持文本流式输入的 WebSocket 语音合成接口，客户端可逐字发送文本，由服务端自动攒句合成。 ## 与 `/ws/v1/t2a_v2` 的区别 本接口面向**文本流式输入**场景：把大模型的流式输出直接逐 token 转成语音。 | | [`/ws/v1/t2a_v2`](/docs/api-reference/speech-t2a-websocket) | `/ws/v1/t2a_v2_bidi`（本接口） | | ------------- | ----------------------------------------------------------- | --------------------------------- | | 攒句责任 | **客户端**自行判断句子边界 | **服务端**自动攒句 | | 逐字发送文本 | 每个字触发一次合成，音频碎裂 | 攒成完整句子后再合成 | | 打断 | 不支持，只能断开连接 | `task_cancel`，打断后可继续 | | 句边界事件 | 无 | `sentence_start` / `sentence_end` | | `task_finish` | 立即关闭连接 | 先合成缓冲区残留再关闭 | | 催出残留但不结束会话 | 无 | `task_flush` | `task_start` 的音色、音频、发音字典等参数与 `/ws/v1/t2a_v2` **完全一致**，已有接入可直接复用。 ## 事件流程 1. 建立连接，收到 `connected_success` 2. 发送 `task_start`，收到 `task_started` 3. 发送 `task_continue`（**可按任意粒度，包括单个字符**），服务端攒句后开始合成 * 每句合成开始返回 `sentence_start` * 音频通过 `task_continued` 分块返回 * 该句结束返回 `sentence_end` 4. 需要打断时发送 `task_cancel`，收到 `task_canceled` 后可继续发送 `task_continue` 5. 一轮说完、希望立刻拿到尾句音频时发送 `task_flush`，收到 `task_flushed` 后会话继续 6. 发送 `task_finish`，服务端合成完残留文本后返回 `task_finished` 并关闭连接 三层结束语义不要混用：`is_final` 表示本次请求的音频结束，`sentence_end` 表示当前句结束，`task_finished` 表示整个会话结束。 一条连接同时只能有一个合成会话。任务已开始后重复发送 `task_start` 会返回 `2206`（事件顺序非法）并关闭连接。 ## 攒句与延迟 服务端按标点判断句子边界，因此**你发送的文本中的标点会直接影响音频的自然度**： | 文本情况 | 服务端行为 | | ---------------------- | ---------------------------- | | 以句末标点（`。！？…!?.` 及换行）结尾 | **立即**送去合成，不引入额外延迟 | | 出现次级标点（`，、；：,;:`） | 已攒文本达到一定长度才切句，避免切出过短的碎片 | | 长文本完全没有标点 | 达到长度上限时强制切断，此时句边界与语义无关，听感会断裂 | | 尾部不带标点，但已攒够长度 | 等待一个短暂的静默窗口后兜底送出 | | 尾部不带标点且很短 | **继续等待**，不会为了低延迟把半个词送去合成 | 最后一条对多轮对话场景有实际影响。 如果一轮说完时残留的文本既很短、又不带句末标点，它不会被那个短静默窗口立刻送出，而要等一个更长的兜底窗口。有两个办法避免这段等待：**给最后一片文本补上句末标点**，或者**发送 `task_flush`** 主动催出。 注意不能用 `task_finish` 代替——它会关闭连接，在一条连接上跑多轮对话时用不了。 如果你的程序在转发大模型输出前会清洗文本，**请保留原始标点**。缺少标点会让服务端退化为按长度机械切分，停顿位置与语义不符，音频明显不自然。 上游（如大模型）出现较长停顿时，音频中会出现相应的空白，这无法避免。服务端不会为了填补空白而把攒了一半的句子提前送出——那样只会让听众先听到半个词再等待。 ## 连接保活 连接空闲超过约 120 秒会被服务端关闭并返回 `2201`。「空闲」指服务端既没有收到上行事件，也没有在下发音频。 服务端**不会主动发送** WebSocket ping 帧。如果你的会话存在较长静默期（例如等待用户说话），请由客户端定期发送 ping —— 服务端会回复 pong 并刷新活跃时间。仅靠 TCP 连接存活不足以避免 `2201`。 ## 发送速率与重试 收到 `2205` 表示服务端排队待合成的文本过多，通常是发送速度超过了合成速度。 `2205` **不是配额限流**，也是软失败：连接和会话都不会关闭。稍后重新发送该条 `task_continue` 即可，**不需要重连、也不需要重新 `task_start`**。 单条 `task_continue` 文本超过 10,000 字符会返回 `2204`，该条被跳过，连接与会话同样保持。 # 语音识别 Source: https://platform.minimaxi.com/docs/api-reference/speech-to-text api-reference/speech/speech-to-text/api/openapi.json POST /v1/speech_to_text 使用本接口，将音频文件转写为文本，支持流式返回、说话人分离与字幕导出。 # AI SDK Source: https://platform.minimaxi.com/docs/api-reference/text-ai-sdk 通过 AI SDK 调用 MiniMax 模型 为了满足开发者对 [AI SDK](https://ai-sdk.dev) 生态的使用需求，MiniMax 提供了官方社区 Provider。通过简单的配置，即可将 MiniMax 的能力接入到 AI SDK 生态中。 ## 快速开始 ### 1. 安装 AI SDK 和 MiniMax Provider ```bash npm theme={null} npm install ai vercel-minimax-ai-provider ``` ```bash pnpm theme={null} pnpm add ai vercel-minimax-ai-provider ``` ### 2. 配置环境变量 ```bash theme={null} export MINIMAX_API_KEY=${YOUR_API_KEY} ``` ### 3. 调用 API ```typescript TypeScript theme={null} import { minimax } from 'vercel-minimax-ai-provider'; import { generateText } from 'ai'; const { text, reasoning } = await generateText({ model: minimax('MiniMax-M3'), system: 'You are a helpful assistant.', prompt: 'Hi, how are you?', }); if (reasoning) { console.log(`Thinking:\n${reasoning}\n`); } console.log(`Text:\n${text}\n`); ``` ### 4. 特别注意 在多轮 Function Call 对话中，必须将完整的模型返回（即 assistant 消息）添加到对话历史，以保持思维链的连续性： * 将完整的 `result.response.messages` 添加到消息历史（包含所有 assistant 和 tool 消息） ## 支持的模型 使用 AI SDK 时，支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型： | 模型名称 | 上下文窗口 | 模型介绍 | | :--------------------- | :-------: | :------------------------------------------ | | MiniMax-M3 | 1,000,000 | **最新 M 系列语言模型，适用于 Agent 推理、工具调用、代码和长上下文任务** | | MiniMax-M2.7 | 204,800 | **开启模型的自我迭代**（输出速度约 60 TPS） | | MiniMax-M2.7-highspeed | 204,800 | **M2.7 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.5 | 204,800 | **顶尖性能与极致性价比，轻松驾驭复杂任务**（输出速度约 60 TPS） | | MiniMax-M2.5-highspeed | 204,800 | **M2.5 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.1 | 204,800 | **强大多语言编程能力，全面升级编程体验**（输出速度约 60 TPS） | | MiniMax-M2.1-highspeed | 204,800 | **M2.1 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2 | 204,800 | **专为高效编码与 Agent 工作流而生** | TPS（Tokens Per Second）的计算方式详见[常见问题 > 接口相关](/docs/faq/about-apis#%E9%97%AE%E6%96%87%E6%9C%AC%E6%A8%A1%E5%9E%8B%E7%9A%84-tpstokens-per-second%E6%98%AF%E5%A6%82%E4%BD%95%E8%AE%A1%E7%AE%97%E7%9A%84)。 AI SDK 兼容接口支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型。如需使用其他模型，请使用标准的 MiniMax API 接口。 ## 兼容性说明 ### 支持的参数 在使用 AI SDK 接入时，我们支持以下输入参数： | 参数 | 支持状态 | 说明 | | :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | `model` | 完全支持 | 支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型 | | `messages` | 部分支持 | 支持文本和工具调用，不支持图像和文档输入 | | `maxTokens` | 完全支持 | 最大生成 token 数 | | `system` | 完全支持 | 系统提示词 | | `temperature` | 完全支持 | 取值范围 \[0, 2]，控制输出随机性，建议取值 1 | | `toolChoice` | 完全支持 | 工具选择策略 | | `tools` | 完全支持 | 工具定义 | | `topP` | 完全支持 | 核采样参数，取值范围 \[0, 1]，`MiniMax-M3` 默认值 0.95，`MiniMax-M2.x` 系列默认值 0.9 | ### Messages 字段支持 | 字段类型 | 支持状态 | 说明 | | :------------------- | :--- | :------- | | `role="user"` | 完全支持 | 用户文本消息 | | `role="assistant"` | 完全支持 | 助手响应 | | `role="tool"` | 完全支持 | 工具调用结果 | | `type="text"` | 完全支持 | 文本内容 | | `type="tool-call"` | 完全支持 | 工具调用 | | `type="tool-result"` | 完全支持 | 工具调用结果 | | `type="image"` | 不支持 | 暂不支持图像输入 | | `type="file"` | 不支持 | 暂不支持文件输入 | ## 示例代码 ### 流式响应 ```typescript TypeScript theme={null} import { minimax } from 'vercel-minimax-ai-provider'; import { streamText } from 'ai'; console.log("Starting stream response...\n"); console.log("=".repeat(60)); console.log("Thinking Process:"); console.log("=".repeat(60)); const result = streamText({ model: minimax('MiniMax-M3'), system: 'You are a helpful assistant.', prompt: 'Hi, how are you?', onError({ error }) { console.error(error); }, }); let inText = false; for await (const part of result.fullStream) { if (part.type === 'reasoning') { // 流式输出思考过程 process.stdout.write(part.text); } else if (part.type === 'text') { if (!inText) { inText = true; console.log("\n" + "=".repeat(60)); console.log("Response Content:"); console.log("=".repeat(60)); } // 流式输出文本内容 process.stdout.write(part.text); } } console.log("\n"); ``` ## 注意事项 1. AI SDK 兼容接口目前支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型 2. `temperature` 参数取值范围为 \[0, 2]，超出范围会返回错误 3. 当前不支持图像和文档类型的输入 4. 默认的 `minimax` Provider 实例使用 Anthropic 兼容 API 格式。如需使用 OpenAI 兼容格式，请使用 `minimaxOpenAI`。 5. 更多信息请参阅 [MiniMax AI Provider on AI SDK](https://ai-sdk.dev/providers/community-providers/minimax) 和 [GitHub 仓库](https://github.com/MiniMax-AI/vercel-minimax-ai-provider) # Anthropic SDK Source: https://platform.minimaxi.com/docs/api-reference/text-anthropic-api 通过 Anthropic SDK 调用 MiniMax 模型 为了满足开发者对 Anthropic API 生态的使用需求，我们的 API 新增了对 Anthropic API 格式的支持。通过简单的配置，即可将 MiniMax 的能力接入到 Anthropic API 生态中。 ## 快速开始 ### 1. 安装 Anthropic SDK ```bash Python theme={null} pip install anthropic ``` ```bash Node.js theme={null} npm install @anthropic-ai/sdk ``` ### 2. 配置环境变量 ```bash theme={null} export ANTHROPIC_BASE_URL=https://api.minimax.cn/anthropic export ANTHROPIC_API_KEY=${YOUR_API_KEY} ``` ### 3. 调用 API ```python Python theme={null} import anthropic client = anthropic.Anthropic() message = client.messages.create( model="MiniMax-M3", max_tokens=1000, system="You are a helpful assistant.", messages=[ { "role": "user", "content": [ { "type": "text", "text": "Hi, how are you?" } ] } ] ) for block in message.content: if block.type == "thinking": print(f"Thinking:\n{block.thinking}\n") elif block.type == "text": print(f"Text:\n{block.text}\n") ``` ### 4. 特别注意 在多轮 Function Call 对话中，必须将完整的模型返回（即 assistant 消息）添加到对话历史，以保持思维链的连续性： * 将完整的 `response.content`（包含 thinking/text/tool\_use 等所有块）添加到消息历史 * `response.content` 是一个列表，包含多种类型的内容块，必须完整回传 ## 支持的模型 使用 Anthropic SDK 时，支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型： | 模型名称 | 上下文窗口 | 模型介绍 | | :--------------------- | :-------: | :------------------------------------------ | | MiniMax-M3 | 1,000,000 | **最新 M 系列语言模型，适用于 Agent 推理、工具调用、代码和长上下文任务** | | MiniMax-M2.7 | 204,800 | **开启模型的自我迭代**（输出速度约 60 TPS） | | MiniMax-M2.7-highspeed | 204,800 | **M2.7 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.5 | 204,800 | **顶尖性能与极致性价比，轻松驾驭复杂任务**（输出速度约 60 TPS） | | MiniMax-M2.5-highspeed | 204,800 | **M2.5 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.1 | 204,800 | **强大多语言编程能力，全面升级编程体验**（输出速度约 60 TPS） | | MiniMax-M2.1-highspeed | 204,800 | **M2.1 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2 | 204,800 | **专为高效编码与 Agent 工作流而生** | TPS（Tokens Per Second）的计算方式详见[常见问题 > 接口相关](/docs/faq/about-apis#%E9%97%AE%E6%96%87%E6%9C%AC%E6%A8%A1%E5%9E%8B%E7%9A%84-tpstokens-per-second%E6%98%AF%E5%A6%82%E4%BD%95%E8%AE%A1%E7%AE%97%E7%9A%84)。 Anthropic API 兼容接口支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型。如需使用其他模型，请使用标准的 MiniMax API 接口。 ## 兼容性说明 ### 支持的参数 在使用 Anthropic SDK 接入时，我们支持以下输入参数： | 参数 | 支持状态 | 说明 | | :------------------- | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | 完全支持 | 支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型 | | `messages` | 部分支持 | `MiniMax-M3` 支持文本、图片、视频、工具调用、工具结果和 thinking 内容块。M2.7、M2.5、M2.1 和 M2 系列仅支持文本与工具调用相关内容块，不支持图片和视频输入 | | `max_tokens` | 完全支持 | 最大生成 token 数 | | `stream` | 完全支持 | 流式响应 | | `system` | 完全支持 | 系统提示词 | | `temperature` | 完全支持 | 取值范围 \[0, 2]，控制输出随机性，建议取值 1 | | `tool_choice` | 完全支持 | 工具选择策略 | | `tools` | 完全支持 | 工具定义 | | `top_p` | 完全支持 | 核采样参数，取值范围 \[0, 1]，`MiniMax-M3` 默认值 0.95，M2.x 系列默认值 0.9 | | `thinking` | 完全支持 | MiniMax-M3 默认关闭 thinking，可通过 `adaptive` 开启。M2.x 模型的 thinking 无法关闭。 | | `metadata` | 完全支持 | 元信息 | | `service_tier` | 完全支持 | 请求准入服务层级。支持的取值为 `standard` 和 `priority`；省略时默认使用 `standard`。`priority` 的[价格](/docs/guides/pricing-paygo)为 `standard` 的 1.5 倍，并会确保请求获得优先准入，使其排在其他请求之前处理，从而带来更快响应并减少失败。 | | `top_k` | 忽略 | 该参数会被忽略 | | `stop_sequences` | 忽略 | 该参数会被忽略 | | `mcp_servers` | 忽略 | 该参数会被忽略 | | `context_management` | 忽略 | 该参数会被忽略 | | `container` | 忽略 | 该参数会被忽略 | ### Thinking 控制 对于 `MiniMax-M3`，`thinking` 参数用于控制模型是否可以输出 `thinking` 内容块。 * 如果省略 `thinking`，默认关闭 thinking，响应不会包含 `thinking` 内容块。 * 设置 `thinking: {"type": "adaptive"}` 可显式开启 thinking。对于 MiniMax-M3，`adaptive` 等同于开启 thinking。 * 设置 `thinking: {"type": "disabled"}` 可显式保持 MiniMax-M3 的 thinking 输出关闭。 * 对于 M2.x 模型，thinking 无法关闭；即使传入 `thinking: {"type": "disabled"}`，thinking 仍会保持开启。 当响应包含 `thinking` 内容块时，后续轮次中应原样保留这些内容块，尤其是在工具调用对话中。 ### Messages 字段支持 | 字段类型 | 支持状态 | 说明 | | :------------------- | :--- | :------------------------------------------------------------ | | `type="text"` | 完全支持 | 文本消息 | | `type="image"` | 仅 M3 | 通过 URL 或 base64 输入图片，支持 JPEG、PNG、GIF、WEBP | | `type="video"` | 仅 M3 | 通过 URL、base64 或 `mm_file://{file_id}` 输入视频，支持 MP4、AVI、MOV、MKV | | `type="tool_use"` | 完全支持 | 工具调用 | | `type="tool_result"` | 完全支持 | 工具调用结果 | | `type="thinking"` | 完全支持 | 推理内容。多轮 thinking 对话中需要原样回带 | 对 `MiniMax-M3`，URL 或 base64 视频最大 50 MB，图片最大 10 MB，请求体最大 64 MB。更大的视频请通过 Files API 上传后传入 `mm_file://{file_id}`，Files API 视频最大 512 MB。 图片 token 用量会随图片尺寸和内容变化。以下是单张图片的粗略估算；准确用量以 `POST /anthropic/v1/messages/count_tokens` 或响应中的 `usage` 为准： | `detail` | 单张图片粗略 token 用量 | | :-------- | :--------------------- | | `low` | 通常为几百 token，最高约 600 | | `default` | 通常约 1k-3k token，最高约 5k | | `high` | 通常为数千 token，最高约 15k+ | Anthropic API 兼容接口也支持 `POST /anthropic/v1/messages/count_tokens`，可用于 `MiniMax-M3` 调用前预估输入 token 用量，不会生成模型输出。 ## 示例代码 ### 流式响应 ```python Python theme={null} import anthropic client = anthropic.Anthropic() print("Starting stream response...\n") print("=" * 60) print("Thinking Process:") print("=" * 60) stream = client.messages.create( model="MiniMax-M3", max_tokens=1000, system="You are a helpful assistant.", messages=[ {"role": "user", "content": [{"type": "text", "text": "Hi, how are you?"}]} ], stream=True, ) reasoning_buffer = "" text_buffer = "" for chunk in stream: if chunk.type == "content_block_start": if hasattr(chunk, "content_block") and chunk.content_block: if chunk.content_block.type == "text": print("\n" + "=" * 60) print("Response Content:") print("=" * 60) elif chunk.type == "content_block_delta": if hasattr(chunk, "delta") and chunk.delta: if chunk.delta.type == "thinking_delta": # 流式输出 thinking 过程 new_thinking = chunk.delta.thinking if new_thinking: print(new_thinking, end="", flush=True) reasoning_buffer += new_thinking elif chunk.delta.type == "text_delta": # 流式输出文本内容 new_text = chunk.delta.text if new_text: print(new_text, end="", flush=True) text_buffer += new_text print("\n") ``` ## 注意事项 如果在使用模型过程中遇到任何问题： * 通过邮箱 [Model@minimaxi.com](mailto:Model@minimaxi.com) 等官方渠道联系我们的技术支持团队 * 在我们的 [Github](https://github.com/MiniMax-AI/MiniMax-M2/issues) 仓库提交Issue 1. Anthropic API 兼容接口目前支持 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型 2. `temperature` 参数取值范围为 \[0, 2]，推荐使用1.0，超出范围会返回错误 3. 部分 Anthropic 参数（如 `top_k`、`stop_sequences`、`mcp_servers`、`context_management`、`container`）会被忽略 4. `MiniMax-M3` 支持通过 Anthropic 兼容内容块输入图片和视频；M2.7、M2.5、M2.1 和 M2 系列仅支持文本与工具调用相关内容块 # Messages API Source: https://platform.minimaxi.com/docs/api-reference/text-chat-anthropic api-reference/text/api/openapi-chat-anthropic.json POST /anthropic/v1/messages 使用 Anthropic API 兼容 Messages 格式调用 MiniMax 模型。 ✨ **全新模型 `MiniMax-M3`** **核心能力**：**Coding/Agentic SOTA**、**1M 超长上下文**、**多模态**。 **`MiniMax-M3` 新特性：** 1. 支持图片、视频理解，可参考右方示例代码 2. 支持通过 `thinking` 参数控制思考 # Chat Completions API Source: https://platform.minimaxi.com/docs/api-reference/text-chat-openai api-reference/text/api/openapi-chat-openai.json POST /v1/chat/completions 使用 OpenAI API 兼容 Chat Completions 格式调用 MiniMax 模型。 ✨ **全新模型 `MiniMax-M3`** **核心能力**：**Coding/Agentic SOTA**、**1M 超长上下文**、**多模态**。 **`MiniMax-M3` 新特性：** 1. 支持图片、视频理解，可参考右方示例代码 2. 支持通过 `thinking` 参数控制思考 # OpenAI SDK Source: https://platform.minimaxi.com/docs/api-reference/text-openai-api 通过 OpenAI SDK 调用 MiniMax 模型 为了满足开发者对 OpenAI API 生态的使用需求，我们的 API 新增了对 OpenAI API 格式的支持。通过简单的配置，即可将 MiniMax 的能力接入到 OpenAI API 生态中。 ## 快速开始 ### 1. 安装 OpenAI SDK ```bash Python theme={null} pip install openai ``` ```bash Node.js theme={null} npm install openai ``` ### 2. 配置环境变量 ```bash theme={null} export OPENAI_BASE_URL=https://api.minimax.cn/v1 export OPENAI_API_KEY=${YOUR_API_KEY} ``` ### 3. 调用 API ```python Python theme={null} from openai import OpenAI client = OpenAI() response = client.chat.completions.create( model="MiniMax-M3", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hi, how are you?"}, ], # 设置 reasoning_split=True 将思考内容分离到 reasoning_details 字段 extra_body={"reasoning_split": True}, ) print(f"Thinking:\n{response.choices[0].message.reasoning_details[0]['text']}\n") print(f"Text:\n{response.choices[0].message.content}\n") ``` ### 4. 特别注意 在多轮 Function Call 对话中，必须将完整的模型返回（即 assistant 消息）添加到对话历史，以保持思维链的连续性： * 将完整的 `response_message` 对象（包含 `tool_calls` 字段）添加到消息历史 * 原生的OpenAI API 的 `MiniMax-M3` `MiniMax-M2.7` `MiniMax-M2.7-highspeed` `MiniMax-M2.5` `MiniMax-M2.5-highspeed` `MiniMax-M2.1` `MiniMax-M2.1-highspeed` `MiniMax-M2` 模型 `content` 字段会包含 `` 标签内容，需要完整保留 * 在 Interleaved Thinking 友好格式中，通过启用额外的参数(`reasoning_split=True`)，模型思考内容通过 `reasoning_details` 字段单独提供，同样需要完整保留 ## 支持的模型 使用 OpenAI SDK 时，支持以下 MiniMax 模型： | 模型名称 | 上下文窗口 | 模型介绍 | | :--------------------- | :-------: | :------------------------------------------ | | MiniMax-M3 | 1,000,000 | **最新 M 系列语言模型，适用于 Agent 推理、工具调用、代码和长上下文任务** | | MiniMax-M2.7 | 204,800 | **开启模型的自我迭代**（输出速度约 60 TPS） | | MiniMax-M2.7-highspeed | 204,800 | **M2.7 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.5 | 204,800 | **顶尖性能与极致性价比，轻松驾驭复杂任务**（输出速度约 60 TPS） | | MiniMax-M2.5-highspeed | 204,800 | **M2.5 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2.1 | 204,800 | **强大多语言编程能力，全面升级编程体验**（输出速度约 60 TPS） | | MiniMax-M2.1-highspeed | 204,800 | **M2.1 极速版：效果不变，更快，更敏捷**（输出速度约 100 TPS） | | MiniMax-M2 | 204,800 | **专为高效编码与 Agent 工作流而生** | TPS（Tokens Per Second）的计算方式详见[常见问题 > 接口相关](/docs/faq/about-apis#%E9%97%AE%E6%96%87%E6%9C%AC%E6%A8%A1%E5%9E%8B%E7%9A%84-tpstokens-per-second%E6%98%AF%E5%A6%82%E4%BD%95%E8%AE%A1%E7%AE%97%E7%9A%84)。 更多模型信息请参考标准的 MiniMax API 接口文档。 ## 多模态输入 OpenAI API 兼容的 Chat Completions 支持在 `MiniMax-M3` 中输入文本、图片和视频。 图片使用 `image_url` 内容块，视频使用 `video_url` 内容块。`detail` 字段可取 `low`、`default`、`high`，默认值为 `default`；可通过 `max_long_side_pixel` 控制最长边。图片支持 JPEG、PNG、GIF、WEBP。视频支持 MP4、AVI、MOV、MKV；`fps` 默认值为 1，支持 0.2 到 5。URL 或 base64 视频最大 50 MB，图片最大 10 MB，请求体最大 64 MB。更大的视频请通过 Files API 上传后传入 `mm_file://{file_id}`，Files API 视频最大 512 MB。 图片 token 用量会随图片尺寸和内容变化。以下是单张图片的粗略估算；准确用量以响应中的 `usage` 或可用的 token 计数接口为准： | `detail` | 单张图片粗略 token 用量 | | :-------- | :--------------------- | | `low` | 通常为几百 token，最高约 600 | | `default` | 通常约 1k-3k token，最高约 5k | | `high` | 通常为数千 token，最高约 15k+ | ```python Python theme={null} response = client.chat.completions.create( model="MiniMax-M3", messages=[ { "role": "user", "content": [ {"type": "text", "text": "Summarize what is happening here."}, { "type": "image_url", "image_url": { "url": "https://example.com/image.png", "detail": "default", }, }, { "type": "video_url", "video_url": { "url": "mm_file://file_id", "detail": "default", }, }, ], } ], ) ``` ## MiniMax-M3 请求参数 `MiniMax-M3` 在 OpenAI API 兼容接口中支持以下额外的 Chat Completions 参数： | 参数 | 说明 | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `thinking` | 控制 MiniMax-M3 thinking。`type` 可取 `disabled` 或 `adaptive`；省略时默认开启 thinking。对于 M2.x 模型，thinking 无法关闭。 | | `stream_options.include_usage` | 流式调用时，设为 `true` 可在流中返回 token 用量。 | | `max_tokens` | 旧版生成长度限制参数。 | | `max_completion_tokens` | 生成长度限制参数，新接入建议使用此字段。 | | `temperature` | 采样温度。范围 `[0, 2]`，默认值 `1`。 | | `top_p` | 核采样参数。范围 `[0, 1]`，`MiniMax-M3` 默认值 `0.95`，M2.x 系列默认值 `0.9`。 | | `tools` | 函数工具定义。 | | `reasoning_split` | 输出格式开关。启用后将 thinking 内容拆分到 `reasoning_content` 和 `reasoning_details`。 | | `service_tier` | 请求准入服务层级。支持的取值为 `standard` 和 `priority`；省略时默认使用 `standard`。`priority` 的[价格](/docs/guides/pricing-paygo)为 `standard` 的 1.5 倍，并会确保请求获得优先准入，使其排在其他请求之前处理，从而带来更快响应并减少失败。 | ### Thinking 控制 对于 `MiniMax-M3`，`thinking` 参数用于控制模型是否可以输出 thinking 内容。 * 如果省略 `thinking`，默认开启 thinking，响应会包含 thinking 内容。 * 设置 `thinking: {"type": "adaptive"}` 可显式保持 thinking 开启。对于 MiniMax-M3，`adaptive` 等同于开启 thinking。 * 设置 `thinking: {"type": "disabled"}` 可跳过 thinking 并直接回答。 * 对于 M2.x 模型，thinking 无法关闭；即使传入 `thinking: {"type": "disabled"}`，thinking 仍会保持开启。 `reasoning_split` 不会开启或关闭 thinking。它只控制 thinking 内容的返回方式：为 `true` 时，thinking 会通过 `reasoning_content` 和 `reasoning_details` 返回；为 `false` 时，原生 Chat Completions 响应会将 thinking 保留在 `content` 字段中的 `...` 标签内。 ```python Python theme={null} response = client.chat.completions.create( model="MiniMax-M3", messages=[{"role": "user", "content": "Hi, how are you?"}], extra_body={ "thinking": {"type": "adaptive"}, }, ) ``` ## 示例代码 ### 流式响应 ```python Python theme={null} from openai import OpenAI client = OpenAI() print("Starting stream response...\n") print("=" * 60) print("Thinking Process:") print("=" * 60) stream = client.chat.completions.create( model="MiniMax-M3", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hi, how are you?"}, ], # 设置 reasoning_split=True 将思考内容分离到 reasoning_details 字段 extra_body={"reasoning_split": True}, stream=True, ) reasoning_buffer = "" text_buffer = "" for chunk in stream: if ( hasattr(chunk.choices[0].delta, "reasoning_details") and chunk.choices[0].delta.reasoning_details ): for detail in chunk.choices[0].delta.reasoning_details: if "text" in detail: reasoning_text = detail["text"] new_reasoning = reasoning_text[len(reasoning_buffer) :] if new_reasoning: print(new_reasoning, end="", flush=True) reasoning_buffer = reasoning_text if chunk.choices[0].delta.content: content_text = chunk.choices[0].delta.content new_text = content_text[len(text_buffer) :] if text_buffer else content_text if new_text: print(new_text, end="", flush=True) text_buffer = content_text print("\n" + "=" * 60) print("Response Content:") print("=" * 60) print(f"{text_buffer}\n") ``` ### Tool Use & Interleaved Thinking 了解如何通过 OpenAI SDK 使用 M3 Tool Use 和 Interleaved Thinking 能力，请参考以下文档。 了解如何利用 MiniMax-M3 工具调用和 Interleaved Thinking 能力，提升复杂任务中的表现。 ## 注意事项 如果在使用MiniMax模型过程中遇到任何问题： * 通过邮箱 [Model@minimaxi.com](mailto:Model@minimaxi.com) 等官方渠道联系我们的技术支持团队 * 在我们的 [Github](https://github.com/MiniMax-AI/MiniMax-M2/issues) 仓库提交Issue 1. `temperature` 参数取值范围为 \[0, 2]，推荐使用 1.0，超出范围会返回错误 2. 部分 OpenAI 参数（如`presence_penalty`、`frequency_penalty`、`logit_bias` 等）会被忽略 3. `MiniMax-M3` 可通过 OpenAI 兼容消息内容块输入图片和视频；当前不支持音频输入 4. `n` 参数仅支持值为 1 5. 旧版的`function_call` 已废弃，请使用 `tools` 参数 # Prompt 缓存 Source: https://platform.minimaxi.com/docs/api-reference/text-prompt-caching 通过 Prompt 缓存，可以有效降低延迟和成本。 # 功能特性 * **自动缓存**：被动缓存，自动识别重复的上下文内容，无需更改接口调用方式 （*相对的，在 anthropic API 中使用的需要显式设置参数的缓存模式，我们称之为「主动缓存」，详见[Anthropic 主动缓存](/docs/api-reference/anthropic-api-compatible-cache)*） * **降低成本**：命中缓存的输入 Token 以更低价格计费，大幅节省成本 * **提升速度**：减少重复内容的处理时间，加快模型响应 这种机制特别适用于以下场景： * 系统提示词复用：在多轮对话中，系统提示词通常保持不变； * 固定的工具清单：在一类任务中使用的工具往往是固定的； * 多轮对话历史：在复杂的对话中，历史消息往往包含大量重复信息； 满足以上条件的场景，均可利用缓存机制有效节约 tokens 消耗，加快响应速度。 # 代码示例 **安装 SDK** ```bash theme={null} theme={null} pip install anthropic ``` **环境变量设置** 国内用户使用 `https://api.minimax.cn/v1`，国际用户使用 `https://api.minimax.io/v1` ```bash theme={null} theme={null} export ANTHROPIC_BASE_URL=https://api.minimax.cn/anthropic export ANTHROPIC_API_KEY=${YOUR_API_KEY} ``` **第一次请求 - 建立缓存** ```python theme={null} theme={null} import anthropic client = anthropic.Anthropic() response1 = client.messages.create( model="MiniMax-M3", system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n", messages=[ { "role": "user", "content": [ { "type": "text", "text": "" } ] }, ], max_tokens=10240, ) print("第一次请求结果:") for block in response1.content: if block.type == "thinking": print(f"思考:\n{block.thinking}\n") elif block.type == "text": print(f"输出:\n{block.text}\n") print(f"输入 Token: {response1.usage.input_tokens}") print(f"输出 Token: {response1.usage.output_tokens}") print(f"命中缓存 Token: {response1.usage.cache_read_input_tokens}") ``` **第二次请求 - 复用缓存** ```python theme={null} theme={null} response2 = client.messages.create( model="MiniMax-M3", system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n", messages=[ { "role": "user", "content": [ { "type": "text", "text": "" } ] }, ], max_tokens=10240, ) print("\n第二次请求结果:") for block in response2.content: if block.type == "thinking": print(f"思考:\n{block.thinking}\n") elif block.type == "text": print(f"输出:\n{block.text}\n") print(f"输入 Token: {response2.usage.input_tokens}") print(f"输出 Token: {response2.usage.output_tokens}") print(f"命中缓存 Token: {response2.usage.cache_read_input_tokens}") ``` **响应包含上下文缓存的 Token 使用信息：** ```json theme={null} theme={null} { "usage": { "input_tokens": 108, "output_tokens": 91, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 14813 } } ``` **安装 SDK** ```bash theme={null} theme={null} pip install openai ``` **环境变量设置** 国内用户使用 `https://api.minimax.cn/v1`，国际用户使用 `https://api.minimax.io/v1` ```bash theme={null} theme={null} export OPENAI_BASE_URL=https://api.minimax.cn/v1 export OPENAI_API_KEY=${YOUR_API_KEY} ``` **第一次请求 - 建立缓存** ```python theme={null} theme={null} from openai import OpenAI client = OpenAI() response1 = client.chat.completions.create( model="MiniMax-M3", messages=[ {"role": "system", "content": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"}, {"role": "user", "content": ""}, ], # 设置 reasoning_split=True 将思考内容分离到 reasoning_details 字段 extra_body={"reasoning_split": True}, ) print("第一次请求结果:") print(f"回复: {response1.choices[0].message.content}") print(f"总 Token: {response1.usage.total_tokens}") print(f"缓存 Token: {response1.usage.prompt_tokens_details.cached_tokens if hasattr(response1.usage, 'prompt_tokens_details') else 0}") ``` **第二次请求 - 复用缓存** ```python theme={null} theme={null} response2 = client.chat.completions.create( model="MiniMax-M3", messages=[ {"role": "system", "content": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"}, {"role": "user", "content": ""}, ], # 设置 reasoning_split=True 将思考内容分离到 reasoning_details 字段 extra_body={"reasoning_split": True}, ) print("\n第二次请求结果:") print(f"回复: {response2.choices[0].message.content}") print(f"总 Token: {response2.usage.total_tokens}") print(f"缓存 Token: {response2.usage.prompt_tokens_details.cached_tokens if hasattr(response2.usage, 'prompt_tokens_details') else 0}") ``` **响应包含上下文缓存的 Token 使用信息：** ```json theme={null} theme={null} { "usage": { "prompt_tokens": 1200, "completion_tokens": 300, "total_tokens": 1500, "prompt_tokens_details": { "cached_tokens": 800 } } } ``` # 注意事项 * 缓存适用于包含 512 个及以上的输入 token 数量的 API 调用； * 缓存采用前缀匹配的方式，以「工具定义-系统提示词-历史对话内容」为顺序构建，任意模块内容的变更，都可能会影响缓存的效果； # 最佳实践 * 在对话的开头部分放置静态的或重复的内容（包括工具定义、系统提示词，历史对话内容 ），将动态的用户信息放在对话的最后，以最大程度利用 cache; * 通过API返回的 usage tokens 数量，来监测缓存性能，定期分析以优化你的使用策略； # 计费说明 prompt 缓存采用差异化的计费策略： * 缓存命中 Token：按优惠价格计费 * 新增的输入 Token: 按标准输入价格计费 * 输出 Token：按标准输出价格计费 > 详见 [按量计费价格页](/docs/guides/pricing-paygo) 计费示例： ``` 假设使用 MiniMax-M3 输入 ≤512k tokens 的标准价格：输入 4.20 元/1M tokens，输出 16.80 元/1M tokens，缓存命中 0.84 元/1M tokens： 单次请求 token 用量详情： - 总输入 Token： 50000 - 缓存命中 Token： 45000 - 新增输入内容 Token： 5000 - 输出 Token： 1000 计费计算： - 新增输入内容费用： 5000 × 4.20/1000000 = 0.021 元 - 缓存费用： 45000 × 0.84/1000000 = 0.0378 元 - 输出费用： 1000 × 16.80/1000000 = 0.0168 元 - 总费用：0.021+0.0378+0.0168 = 0.0756 元 相比无缓存 （50000 × 4.20/1000000 + 1000 × 16.80/1000000 = 0.2268 元），节省约 66.7% ``` 对 MiniMax-M3，请求输入 tokens 大于 512k 时适用长上下文价格，输入 tokens 包含缓存命中 tokens。 # Cache 对比 | | Prompt 缓存（被动缓存） | Anthropic 主动缓存 | | :--- | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------- | | 使用方式 | 自动识别重复内容并缓存 | 在API中显式设置 cache\_control | | 计费方式 | 命中缓存的token以优惠价格进行计费
写入缓存的部分无额外计费 | 命中缓存的token以优惠价格进行计费
首次写入缓存的token需要额外计费 | | 缓存过期 | 根据系统负载自动调整过期时间 | 5min过期时间，持续使用会自动续期 | | 支持模型 | MiniMax-M3
MiniMax-M2.7 系列
MiniMax-M2.5 系列
MiniMax-M2.1 系列 | MiniMax-M2.7 系列
MiniMax-M2.5 系列
MiniMax-M2.1 系列
MiniMax-M2 系列 | # 更多阅读 # 视频下载 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-download api-reference/video/generation/api/openapi.json GET /v1/files/retrieve 通过本接口进行生成视频文件下载。 # 首尾帧生成视频 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-fl2v api-reference/video/generation/api/start-end-to-video.json POST /v1/video_generation 使用本接口上传首尾帧图片及文本内容，创建视频生成任务。 # 图生视频任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-i2v api-reference/video/generation/api/image-to-video.json POST /v1/video_generation 使用本接口输入图片及文本内容，创建视频生成任务。 # 查询视频生成任务状态 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-query api-reference/video/generation/api/openapi.json GET /v1/query/video_generation 使用本接口查询视频生成的任务状态。 # 主体参考视频生成任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-s2v api-reference/video/generation/api/subject-reference-to-video.json POST /v1/video_generation 使用本接口上传人物主体图片及文本内容，创建视频生成任务。 # 文生视频生成任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-t2v api-reference/video/generation/api/text-to-video.json POST /v1/video_generation 使用本接口输入文本内容，创建视频生成任务。 # 创建视频生成任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create api-reference/video/generation/api/v2-video-generation.json POST /v2/video_generation 视频生成 V2 接口，通过多模态 content 数组输入（文本 / 图片 / 视频 / 音频），可通过 `model` 字段切换 MiniMax H3 与 MiniMax H3 Max，覆盖文生视频、图生视频（首尾帧）、多模态参考生视频，最高 2K 输出。

提示：若需要使用 MiniMax H3 或 MiniMax H3 Max，请点击 [按量购买 API](/docs/guides/pricing-paygo#%E8%A7%86%E9%A2%91)。 # 取消或删除任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-delete api-reference/video/generation/api/v2-video-generation.json DELETE /v2/video_generation/{task_id} 按任务当前状态取消排队中的任务，或删除成功和失败的视频生成、H3-Context-IR 及视频再生成任务记录。 本接口会根据任务的**当前状态**自动执行取消或删除，行为如下： | 任务状态 | 执行操作（action） | 说明 | | :--------------- | :----------- | :----------------- | | `queued`（排队中） | `cancelled` | 取消任务，任务尚未开始处理，无扣费 | | `succeeded`（成功） | `deleted` | 删除任务记录 | | `failed`（失败） | `deleted` | 删除任务记录 | | `running`（运行中） | — | 不可操作，返回错误（处理中无法取消） | | `cancelled`（已取消） | — | 不可操作，返回错误 | # 创建 H3-Context-IR 任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-h3-context-ir api-reference/video/generation/api/v2-video-generation.json POST /v2/h3_context_ir 深度理解多模态上下文，并生成结构化、语义更丰富的视频提示词。 本接口只返回增强后的视频提示词，不会创建视频生成任务。 H3-Context-IR 对文本、图像、音频和视频等多模态上下文进行深度理解，分析素材之间以及素材与目标生成结果之间的关系，并进行复杂逻辑推理。系统会将理解结果转换为结构化表达，在尽量保持用户原始意图的前提下丰富语义细节。 H3-Context-IR 是一个复杂系统，暂不提供开源实现；本 API 既可用于验证 Full 2K-Workflow 的官方效果，也可集成到生产工作流中。 创建成功后，使用[查询任务](/docs/api-reference/video-generation-v2-query)或[查询任务列表](/docs/api-reference/video-generation-v2-list)接口查询。H3-Context-IR 任务的 `task_type` 为 `h3_context_ir`；任务成功后，从 `content.prompt` 获取增强提示词。 # 查询任务列表 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-list api-reference/video/generation/api/v2-video-generation.json GET /v2/query/video_generation 分页查询最近 7 天内的任务列表，支持按状态、任务 ID、模型和任务类型过滤。 # 查询任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-query api-reference/video/generation/api/v2-video-generation.json GET /v2/query/video_generation/{task_id} 按 task_id 查询最近 7 天内单个视频生成、H3-Context-IR 或视频再生成任务的状态与结果。 # 创建视频再生成任务 Source: https://platform.minimaxi.com/docs/api-reference/video-generation-v2-regeneration api-reference/video/generation/api/v2-video-generation.json POST /v2/video_regeneration 对符合 MiniMax-H3 768P 输出规格的源视频再生成为 2K 视频。 支持两种方式（二选一）： * **按任务 ID**：传已有生成任务的 `source_task_id` * **按源视频**：在 `content` 中传 `base_video` 本接口仅支持对符合 MiniMax-H3 768P 输出规格的生成视频进行再生成并输出 2K，不支持任意视频的通用处理。 再生成任务的 `task_type` 为 `regeneration`，可通过 H3 共用的[查询任务](/docs/api-reference/video-generation-v2-query)、[查询任务列表](/docs/api-reference/video-generation-v2-list)和[取消或删除任务](/docs/api-reference/video-generation-v2-delete)接口管理。 # 音色快速复刻 Source: https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone api-reference/speech/voice-cloning/api/openapi.json POST /v1/voice_clone 使用本接口进行音色快速复刻。 复刻得到的音色若 7 天内未正式调用，则系统会删除该音色。 调用本接口前，请先完成个人或企业认证。 # 上传复刻音频 Source: https://platform.minimaxi.com/docs/api-reference/voice-cloning-uploadcloneaudio api-reference/speech/voice-cloning/api/upload-file.json POST /v1/files/upload 使用本接口上传用于复刻的音频文件。 # 上传示例音频 Source: https://platform.minimaxi.com/docs/api-reference/voice-cloning-uploadprompt api-reference/speech/voice-cloning/api/upload-prompt.json POST /v1/files/upload 使用本接口上传示例音频文件，使用示例音频将有助于增强语音合成的音色相似度和稳定性。 # 音色设计 Source: https://platform.minimaxi.com/docs/api-reference/voice-design-design api-reference/speech/voice-design/api/openapi.json POST /v1/voice_design 使用本接口，输入文本内容，进行音色设计。 # 删除音色 Source: https://platform.minimaxi.com/docs/api-reference/voice-management-delete api-reference/speech/voice-management/api/openapi.json POST /v1/delete_voice 使用本接口，对于生成的部分音色进行删除。 该 API 用于删除指定 voice\_id 的音色，删除范围为通过 [Voice Cloning API](/docs/api-reference/voice-cloning-clone) 和 [Voice Generation API](/docs/api-reference/voice-design-design) 生成的音色的 voice\_id。 ⚠️ 注意：删除后，该 voice\_id 将无法再次使用。 # 查询可用音色ID Source: https://platform.minimaxi.com/docs/api-reference/voice-management-get api-reference/speech/voice-management/api/openapi.json POST /v1/get_voice 使用本接口支持查询不同分类下的音色信息。 该 API 支持查询**当前账号**下可调用的**全部音色 ID**（voice\_id）。 包括系统音色、快速克隆音色、文生音色接口生成的音色、音乐生成接口的人声音色以及伴奏音色。 快速复刻得到的音色为未激活状态，需正式调用一次才可在本接口查询到 # 账户相关 Source: https://platform.minimaxi.com/docs/faq/about-account 本文档解答MiniMax开放平台账户相关的常见问题，包括充值方式、发票申请、余额预警及资源包管理等关键内容。 ### 问：MiniMax 开放平台，支持哪些充值方式？ **答：** MiniMax 开放平台支持 **在线充值** 和 **对公汇款** 两种充值方式。 * 在线充值：登陆 MiniMax 开放平台，前往[账户管理->余额](https://platform.minimaxi.com/user-center/payment/balance)，点击 **立即充值** 按钮，在充值页使用微信进行在线充值。您可以在账单页查询充值结果。 * 对公汇款：对公汇款仅支持企业用户。支持采用对公汇款的方式向 MiniMax 开放平台账户进行充值。**请确保汇款方开户名称与开放平台实名认证主体名称一致。** 您可联系商务获得具体账户信息。我方银行账户到账后，汇款金额将在 10 分钟- 1 小时左右转入您对应的开放平台账户，如未及时收到，请联系我们。 ### 问：如何获取账号的GroupId **答：** MiniMax开放平台GroupId可以在[账户管理->账户信息 ](https://platform.minimaxi.com/user-center/basic-information)中复制。 ### 问：如何获取发票 **答：** 在 MiniMax 开放平台申请开票时，发票的抬头需与实名认证主体名称一致。 请注意，个人账号无法开具企业抬头发票。若需要修改为企业抬头，需前往[账户管理->账户信息 ](https://platform.minimaxi.com/user-center/basic-information)将您的个人认证变更为企业认证。如在认证过程中有任务问题，您可联系商务获得帮助。 您可填写下列表单，进行发票申请： [MiniMax 开放平台发票申请表](https://biaodan.info/web/formview/6503f8ba75a03c4a8388a91a) 请注意：我们并非根据充值金额进行开票。目前的开票模式是：可开票金额=已消耗金额-已开票金额。 ### 问：是否支持余额预警 **答：** 为避免因账户余额不足影响您的业务，我们建议您开启余额预警功能。您可前往[账户管理->余额](https://platform.minimaxi.com/user-center/payment/balance)，设置余额预警金额。当账户余额低于预警值时，MiniMax 开放平台将以邮件、短信、站内信等形式通知您，请注意查收，并及时充值。 ### 问：资源包及有效期 **答：** MiniMax 开放平台，目前提供视频及语音资源包的购买，具体套餐内容，您可前往[账户管理->API 资源包](https://platform.minimaxi.com/user-center/payment/subscription)了解详细内容，并选择合适您的套餐。 提示：您所购买的资源包，余量不继承，过期将自动清零。请关注所购买的资源包的有效期，及时使用。 # 接口相关 Source: https://platform.minimaxi.com/docs/faq/about-apis 本文档解答 MiniMax 开放平台接口使用的核心问题，包括 API Key 获取与管理、资源保障提升方案及声音复刻服务使用条件。帮助开发者高效集成与调用平台API服务。 ### 问：如何获取 API Key **答：** 您可前往[账户管理 > 接口密钥](https://platform.minimaxi.com/user-center/basic-information/interface-key)创建并管理自己的 **按量计费 API Key**。前往[订阅管理 > Token Plan](https://platform.minimaxi.com/user-center/payment/token-plan)查看您的 **订阅 Key**，它用于 Token Plan 订阅套餐和已购积分。请注意，API Key 是您调用接口的重要凭证，请不要与他人共享您的 API Key，或将其暴露在浏览器或其他客户端代码中。 ### 问：如何提高速率限制 **答：** MiniMax 开放平台为您提供不同的资源保障方案，可前往[速率限制](/docs/guides/rate-limits)页面查看具体内容。如您需要获得更高的资源保障，您可通过[api@minimaxi.com](mailto:api@minimaxi.com)与我们的商务获得联系。 ### 问：语言模型的 TPS（Tokens Per Second）是如何计算的 **答：** TPS 表示模型每秒生成的 token 数量，用于衡量模型的推理输出速度。计算公式为： $$ \text{TPS} = \frac{\text{输出 token 数量}}{\text{最后一个 token 的生成时间} - \text{第一个 token 的生成时间}} $$ 即从模型输出第一个 token 开始计时，到最后一个 token 输出完成为止，期间生成的 token 总数除以这段时间（秒）。 TPS 在实际使用中可能存在波动，各模型页面标注的 TPS 为参考值。 ### 问：如何才能使用声音复刻服务 **答：** 基于法律法规的要求，如您需要使用声音克隆服务，请先前往[账户管理 > 账户信息](https://platform.minimaxi.com/user-center/basic-information)中的认证信息中，完成**个人实名认证**或者**企业认证**完成认证后，即刻可以通过 [API 调试台 > Voice Cloning](https://platform.minimaxi.com/examination-center/voice-experience-center/voiceCloning) 页面，或者通过快速复刻接口使用声音复刻服务。 # 联系我们 Source: https://platform.minimaxi.com/docs/faq/contact-us 本页面提供 MiniMax 官方联系方式，涵盖微信、飞书渠道与邮件支持，方便您快速获取技术协助与业务咨询。 **1、开放平台用户交流群**——使用问题咨询、故障排查协助 **2、技术交流共创群**——分享实战心得，在交流中共同进阶 **3、商务合作咨询**
### 品牌资源 **Logo 与品牌标识：** [点击下载 MiniMax 品牌资源包](https://filecdn.minimax.chat/public/MiniMax%20Logo.zip) 包含平台 Logo、图标等品牌素材，请遵循品牌使用规范使用。 *** ### 邮件联系 **邮件联系：** 商务合作、开票、退款——[api@minimaxi.com](mailto:api@minimaxi.com) # 系统音色列表 Source: https://platform.minimaxi.com/docs/faq/system-voice-id 本文档列举了MiniMax开放平台全部的系统音色，为您提供语音合成选择。参考以下表格的内容，可查阅目前全部的系统音色的ID(Voice ID)、名称及支持语言，方便开发者快速查询与调用。 参考以下表格的内容，可查阅目前全部的系统音色。 | 序号 | 语言 | 音色 ID (Voice ID) | 音色名称 (Voice Name) | | :-- | :------- | :------------------------------------------ | :------------------------ | | 1 | 中文 (普通话) | `male-qn-qingse` | 青涩青年音色 | | 2 | 中文 (普通话) | `male-qn-jingying` | 精英青年音色 | | 3 | 中文 (普通话) | `male-qn-badao` | 霸道青年音色 | | 4 | 中文 (普通话) | `male-qn-daxuesheng` | 青年大学生音色 | | 5 | 中文 (普通话) | `female-shaonv` | 少女音色 | | 6 | 中文 (普通话) | `female-yujie` | 御姐音色 | | 7 | 中文 (普通话) | `female-chengshu` | 成熟女性音色 | | 8 | 中文 (普通话) | `female-tianmei` | 甜美女性音色 | | 9 | 中文 (普通话) | `male-qn-qingse-jingpin` | 青涩青年音色-beta | | 10 | 中文 (普通话) | `male-qn-jingying-jingpin` | 精英青年音色-beta | | 11 | 中文 (普通话) | `male-qn-badao-jingpin` | 霸道青年音色-beta | | 12 | 中文 (普通话) | `male-qn-daxuesheng-jingpin` | 青年大学生音色-beta | | 13 | 中文 (普通话) | `female-shaonv-jingpin` | 少女音色-beta | | 14 | 中文 (普通话) | `female-yujie-jingpin` | 御姐音色-beta | | 15 | 中文 (普通话) | `female-chengshu-jingpin` | 成熟女性音色-beta | | 16 | 中文 (普通话) | `female-tianmei-jingpin` | 甜美女性音色-beta | | 17 | 中文 (普通话) | `clever_boy` | 聪明男童 | | 18 | 中文 (普通话) | `cute_boy` | 可爱男童 | | 19 | 中文 (普通话) | `lovely_girl` | 萌萌女童 | | 20 | 中文 (普通话) | `cartoon_pig` | 卡通猪小琪 | | 21 | 中文 (普通话) | `bingjiao_didi` | 病娇弟弟 | | 22 | 中文 (普通话) | `junlang_nanyou` | 俊朗男友 | | 23 | 中文 (普通话) | `chunzhen_xuedi` | 纯真学弟 | | 24 | 中文 (普通话) | `lengdan_xiongzhang` | 冷淡学长 | | 25 | 中文 (普通话) | `badao_shaoye` | 霸道少爷 | | 26 | 中文 (普通话) | `tianxin_xiaoling` | 甜心小玲 | | 27 | 中文 (普通话) | `qiaopi_mengmei` | 俏皮萌妹 | | 28 | 中文 (普通话) | `wumei_yujie` | 妩媚御姐 | | 29 | 中文 (普通话) | `diadia_xuemei` | 嗲嗲学妹 | | 30 | 中文 (普通话) | `danya_xuejie` | 淡雅学姐 | | 31 | 中文 (普通话) | `Chinese (Mandarin)_Reliable_Executive` | 沉稳高管 | | 32 | 中文 (普通话) | `Chinese (Mandarin)_News_Anchor` | 新闻女声 | | 33 | 中文 (普通话) | `Chinese (Mandarin)_Mature_Woman` | 傲娇御姐 | | 34 | 中文 (普通话) | `Chinese (Mandarin)_Unrestrained_Young_Man` | 不羁青年 | | 35 | 中文 (普通话) | `Arrogant_Miss` | 嚣张小姐 | | 36 | 中文 (普通话) | `Robot_Armor` | 机械战甲 | | 37 | 中文 (普通话) | `Chinese (Mandarin)_Kind-hearted_Antie` | 热心大婶 | | 38 | 中文 (普通话) | `Chinese (Mandarin)_HK_Flight_Attendant` | 港普空姐 | | 39 | 中文 (普通话) | `Chinese (Mandarin)_Humorous_Elder` | 搞笑大爷 | | 40 | 中文 (普通话) | `Chinese (Mandarin)_Gentleman` | 温润男声 | | 41 | 中文 (普通话) | `Chinese (Mandarin)_Warm_Bestie` | 温暖闺蜜 | | 42 | 中文 (普通话) | `Chinese (Mandarin)_Male_Announcer` | 播报男声 | | 43 | 中文 (普通话) | `Chinese (Mandarin)_Sweet_Lady` | 甜美女声 | | 44 | 中文 (普通话) | `Chinese (Mandarin)_Southern_Young_Man` | 南方小哥 | | 45 | 中文 (普通话) | `Chinese (Mandarin)_Wise_Women` | 阅历姐姐 | | 46 | 中文 (普通话) | `Chinese (Mandarin)_Gentle_Youth` | 温润青年 | | 47 | 中文 (普通话) | `Chinese (Mandarin)_Warm_Girl` | 温暖少女 | | 48 | 中文 (普通话) | `Chinese (Mandarin)_Kind-hearted_Elder` | 花甲奶奶 | | 49 | 中文 (普通话) | `Chinese (Mandarin)_Cute_Spirit` | 憨憨萌兽 | | 50 | 中文 (普通话) | `Chinese (Mandarin)_Radio_Host` | 电台男主播 | | 51 | 中文 (普通话) | `Chinese (Mandarin)_Lyrical_Voice` | 抒情男声 | | 52 | 中文 (普通话) | `Chinese (Mandarin)_Straightforward_Boy` | 率真弟弟 | | 53 | 中文 (普通话) | `Chinese (Mandarin)_Sincere_Adult` | 真诚青年 | | 54 | 中文 (普通话) | `Chinese (Mandarin)_Gentle_Senior` | 温柔学姐 | | 55 | 中文 (普通话) | `Chinese (Mandarin)_Stubborn_Friend` | 嘴硬竹马 | | 56 | 中文 (普通话) | `Chinese (Mandarin)_Crisp_Girl` | 清脆少女 | | 57 | 中文 (普通话) | `Chinese (Mandarin)_Pure-hearted_Boy` | 清澈邻家弟弟 | | 58 | 中文 (普通话) | `Chinese (Mandarin)_Soft_Girl` | 柔和少女 | | 59 | 中文 (粤语) | `Cantonese_ProfessionalHost（F)` | 专业女主持 | | 60 | 中文 (粤语) | `Cantonese_GentleLady` | 温柔女声 | | 61 | 中文 (粤语) | `Cantonese_ProfessionalHost（M)` | 专业男主持 | | 62 | 中文 (粤语) | `Cantonese_PlayfulMan` | 活泼男声 | | 63 | 中文 (粤语) | `Cantonese_CuteGirl` | 可爱女孩 | | 64 | 中文 (粤语) | `Cantonese_KindWoman` | 善良女声 | | 65 | 英文 | `Santa_Claus ` | Santa Claus | | 66 | 英文 | `Grinch` | Grinch | | 67 | 英文 | `Rudolph` | Rudolph | | 68 | 英文 | `Arnold` | Arnold | | 69 | 英文 | `Charming_Santa` | Charming Santa | | 70 | 英文 | `Charming_Lady` | Charming Lady | | 71 | 英文 | `Sweet_Girl` | Sweet Girl | | 72 | 英文 | `Cute_Elf` | Cute Elf | | 73 | 英文 | `Attractive_Girl` | Attractive Girl | | 74 | 英文 | `Serene_Woman` | Serene Woman | | 75 | 英文 | `English_Trustworthy_Man` | Trustworthy Man | | 76 | 英文 | `English_Graceful_Lady` | Graceful Lady | | 77 | 英文 | `English_Aussie_Bloke` | Aussie Bloke | | 78 | 英文 | `English_Whispering_girl` | Whispering girl | | 79 | 英文 | `English_Diligent_Man` | Diligent Man | | 80 | 英文 | `English_Gentle-voiced_man` | Gentle-voiced man | | 81 | 日文 | `Japanese_IntellectualSenior` | Intellectual Senior | | 82 | 日文 | `Japanese_DecisivePrincess` | Decisive Princess | | 83 | 日文 | `Japanese_LoyalKnight` | Loyal Knight | | 84 | 日文 | `Japanese_DominantMan` | Dominant Man | | 85 | 日文 | `Japanese_SeriousCommander` | Serious Commander | | 86 | 日文 | `Japanese_ColdQueen` | Cold Queen | | 87 | 日文 | `Japanese_DependableWoman` | Dependable Woman | | 88 | 日文 | `Japanese_GentleButler` | Gentle Butler | | 89 | 日文 | `Japanese_KindLady` | Kind Lady | | 90 | 日文 | `Japanese_CalmLady` | Calm Lady | | 91 | 日文 | `Japanese_OptimisticYouth` | Optimistic Youth | | 92 | 日文 | `Japanese_GenerousIzakayaOwner` | Generous Izakaya Owner | | 93 | 日文 | `Japanese_SportyStudent` | Sporty Student | | 94 | 日文 | `Japanese_InnocentBoy` | Innocent Boy | | 95 | 日文 | `Japanese_GracefulMaiden` | Graceful Maiden | | 96 | 韩文 | `Korean_SweetGirl` | Sweet Girl | | 97 | 韩文 | `Korean_CheerfulBoyfriend` | Cheerful Boyfriend | | 98 | 韩文 | `Korean_EnchantingSister` | Enchanting Sister | | 99 | 韩文 | `Korean_ShyGirl` | Shy Girl | | 100 | 韩文 | `Korean_ReliableSister` | Reliable Sister | | 101 | 韩文 | `Korean_StrictBoss` | Strict Boss | | 102 | 韩文 | `Korean_SassyGirl` | Sassy Girl | | 103 | 韩文 | `Korean_ChildhoodFriendGirl` | Childhood Friend Girl | | 104 | 韩文 | `Korean_PlayboyCharmer` | Playboy Charmer | | 105 | 韩文 | `Korean_ElegantPrincess` | Elegant Princess | | 106 | 韩文 | `Korean_BraveFemaleWarrior` | Brave Female Warrior | | 107 | 韩文 | `Korean_BraveYouth` | Brave Youth | | 108 | 韩文 | `Korean_CalmLady` | Calm Lady | | 109 | 韩文 | `Korean_EnthusiasticTeen` | Enthusiastic Teen | | 110 | 韩文 | `Korean_SoothingLady` | Soothing Lady | | 111 | 韩文 | `Korean_IntellectualSenior` | Intellectual Senior | | 112 | 韩文 | `Korean_LonelyWarrior` | Lonely Warrior | | 113 | 韩文 | `Korean_MatureLady` | Mature Lady | | 114 | 韩文 | `Korean_InnocentBoy` | Innocent Boy | | 115 | 韩文 | `Korean_CharmingSister` | Charming Sister | | 116 | 韩文 | `Korean_AthleticStudent` | Athletic Student | | 117 | 韩文 | `Korean_BraveAdventurer` | Brave Adventurer | | 118 | 韩文 | `Korean_CalmGentleman` | Calm Gentleman | | 119 | 韩文 | `Korean_WiseElf` | Wise Elf | | 120 | 韩文 | `Korean_CheerfulCoolJunior` | Cheerful Cool Junior | | 121 | 韩文 | `Korean_DecisiveQueen` | Decisive Queen | | 122 | 韩文 | `Korean_ColdYoungMan` | Cold Young Man | | 123 | 韩文 | `Korean_MysteriousGirl` | Mysterious Girl | | 124 | 韩文 | `Korean_QuirkyGirl` | Quirky Girl | | 125 | 韩文 | `Korean_ConsiderateSenior` | Considerate Senior | | 126 | 韩文 | `Korean_CheerfulLittleSister` | Cheerful Little Sister | | 127 | 韩文 | `Korean_DominantMan` | Dominant Man | | 128 | 韩文 | `Korean_AirheadedGirl` | Airheaded Girl | | 129 | 韩文 | `Korean_ReliableYouth` | Reliable Youth | | 130 | 韩文 | `Korean_FriendlyBigSister` | Friendly Big Sister | | 131 | 韩文 | `Korean_GentleBoss` | Gentle Boss | | 132 | 韩文 | `Korean_ColdGirl` | Cold Girl | | 133 | 韩文 | `Korean_HaughtyLady` | Haughty Lady | | 134 | 韩文 | `Korean_CharmingElderSister` | Charming Elder Sister | | 135 | 韩文 | `Korean_IntellectualMan` | Intellectual Man | | 136 | 韩文 | `Korean_CaringWoman` | Caring Woman | | 137 | 韩文 | `Korean_WiseTeacher` | Wise Teacher | | 138 | 韩文 | `Korean_ConfidentBoss` | Confident Boss | | 139 | 韩文 | `Korean_AthleticGirl` | Athletic Girl | | 140 | 韩文 | `Korean_PossessiveMan` | Possessive Man | | 141 | 韩文 | `Korean_GentleWoman` | Gentle Woman | | 142 | 韩文 | `Korean_CockyGuy` | Cocky Guy | | 143 | 韩文 | `Korean_ThoughtfulWoman` | Thoughtful Woman | | 144 | 韩文 | `Korean_OptimisticYouth` | Optimistic Youth | | 145 | 西班牙文 | `Spanish_SereneWoman` | Serene Woman | | 146 | 西班牙文 | `Spanish_MaturePartner` | Mature Partner | | 147 | 西班牙文 | `Spanish_CaptivatingStoryteller` | Captivating Storyteller | | 148 | 西班牙文 | `Spanish_Narrator` | Narrator | | 149 | 西班牙文 | `Spanish_WiseScholar` | Wise Scholar | | 150 | 西班牙文 | `Spanish_Kind-heartedGirl` | Kind-hearted Girl | | 151 | 西班牙文 | `Spanish_DeterminedManager` | Determined Manager | | 152 | 西班牙文 | `Spanish_BossyLeader` | Bossy Leader | | 153 | 西班牙文 | `Spanish_ReservedYoungMan` | Reserved Young Man | | 154 | 西班牙文 | `Spanish_ConfidentWoman` | Confident Woman | | 155 | 西班牙文 | `Spanish_ThoughtfulMan` | Thoughtful Man | | 156 | 西班牙文 | `Spanish_Strong-WilledBoy` | Strong-willed Boy | | 157 | 西班牙文 | `Spanish_SophisticatedLady` | Sophisticated Lady | | 158 | 西班牙文 | `Spanish_RationalMan` | Rational Man | | 159 | 西班牙文 | `Spanish_AnimeCharacter` | Anime Character | | 160 | 西班牙文 | `Spanish_Deep-tonedMan` | Deep-toned Man | | 161 | 西班牙文 | `Spanish_Fussyhostess` | Fussy hostess | | 162 | 西班牙文 | `Spanish_SincereTeen` | Sincere Teen | | 163 | 西班牙文 | `Spanish_FrankLady` | Frank Lady | | 164 | 西班牙文 | `Spanish_Comedian` | Comedian | | 165 | 西班牙文 | `Spanish_Debator` | Debator | | 166 | 西班牙文 | `Spanish_ToughBoss` | Tough Boss | | 167 | 西班牙文 | `Spanish_Wiselady` | Wise Lady | | 168 | 西班牙文 | `Spanish_Steadymentor` | Steady Mentor | | 169 | 西班牙文 | `Spanish_Jovialman` | Jovial Man | | 170 | 西班牙文 | `Spanish_SantaClaus` | Santa Claus | | 171 | 西班牙文 | `Spanish_Rudolph` | Rudolph | | 172 | 西班牙文 | `Spanish_Intonategirl` | Intonate Girl | | 173 | 西班牙文 | `Spanish_Arnold` | Arnold | | 174 | 西班牙文 | `Spanish_Ghost` | Ghost | | 175 | 西班牙文 | `Spanish_HumorousElder` | Humorous Elder | | 176 | 西班牙文 | `Spanish_EnergeticBoy` | Energetic Boy | | 177 | 西班牙文 | `Spanish_WhimsicalGirl` | Whimsical Girl | | 178 | 西班牙文 | `Spanish_StrictBoss` | Strict Boss | | 179 | 西班牙文 | `Spanish_ReliableMan` | Reliable Man | | 180 | 西班牙文 | `Spanish_SereneElder` | Serene Elder | | 181 | 西班牙文 | `Spanish_AngryMan` | Angry Man | | 182 | 西班牙文 | `Spanish_AssertiveQueen` | Assertive Queen | | 183 | 西班牙文 | `Spanish_CaringGirlfriend` | Caring Girlfriend | | 184 | 西班牙文 | `Spanish_PowerfulSoldier` | Powerful Soldier | | 185 | 西班牙文 | `Spanish_PassionateWarrior` | Passionate Warrior | | 186 | 西班牙文 | `Spanish_ChattyGirl` | Chatty Girl | | 187 | 西班牙文 | `Spanish_RomanticHusband` | Romantic Husband | | 188 | 西班牙文 | `Spanish_CompellingGirl` | Compelling Girl | | 189 | 西班牙文 | `Spanish_PowerfulVeteran` | Powerful Veteran | | 190 | 西班牙文 | `Spanish_SensibleManager` | Sensible Manager | | 191 | 西班牙文 | `Spanish_ThoughtfulLady` | Thoughtful Lady | | 192 | 葡萄牙文 | `Portuguese_SentimentalLady` | Sentimental Lady | | 193 | 葡萄牙文 | `Portuguese_BossyLeader` | Bossy Leader | | 194 | 葡萄牙文 | `Portuguese_Wiselady` | Wise lady | | 195 | 葡萄牙文 | `Portuguese_Strong-WilledBoy` | Strong-willed Boy | | 196 | 葡萄牙文 | `Portuguese_Deep-VoicedGentleman` | Deep-voiced Gentleman | | 197 | 葡萄牙文 | `Portuguese_UpsetGirl` | Upset Girl | | 198 | 葡萄牙文 | `Portuguese_PassionateWarrior` | Passionate Warrior | | 199 | 葡萄牙文 | `Portuguese_AnimeCharacter` | Anime Character | | 200 | 葡萄牙文 | `Portuguese_ConfidentWoman` | Confident Woman | | 201 | 葡萄牙文 | `Portuguese_AngryMan` | Angry Man | | 202 | 葡萄牙文 | `Portuguese_CaptivatingStoryteller` | Captivating Storyteller | | 203 | 葡萄牙文 | `Portuguese_Godfather` | Godfather | | 204 | 葡萄牙文 | `Portuguese_ReservedYoungMan` | Reserved Young Man | | 205 | 葡萄牙文 | `Portuguese_SmartYoungGirl` | Smart Young Girl | | 206 | 葡萄牙文 | `Portuguese_Kind-heartedGirl` | Kind-hearted Girl | | 207 | 葡萄牙文 | `Portuguese_Pompouslady` | Pompous lady | | 208 | 葡萄牙文 | `Portuguese_Grinch` | Grinch | | 209 | 葡萄牙文 | `Portuguese_Debator` | Debator | | 210 | 葡萄牙文 | `Portuguese_SweetGirl` | Sweet Girl | | 211 | 葡萄牙文 | `Portuguese_AttractiveGirl` | Attractive Girl | | 212 | 葡萄牙文 | `Portuguese_ThoughtfulMan` | Thoughtful Man | | 213 | 葡萄牙文 | `Portuguese_PlayfulGirl` | Playful Girl | | 214 | 葡萄牙文 | `Portuguese_GorgeousLady` | Gorgeous Lady | | 215 | 葡萄牙文 | `Portuguese_LovelyLady` | Lovely Lady | | 216 | 葡萄牙文 | `Portuguese_SereneWoman` | Serene Woman | | 217 | 葡萄牙文 | `Portuguese_SadTeen` | Sad Teen | | 218 | 葡萄牙文 | `Portuguese_MaturePartner` | Mature Partner | | 219 | 葡萄牙文 | `Portuguese_Comedian` | Comedian | | 220 | 葡萄牙文 | `Portuguese_NaughtySchoolgirl` | Naughty Schoolgirl | | 221 | 葡萄牙文 | `Portuguese_Narrator` | Narrator | | 222 | 葡萄牙文 | `Portuguese_ToughBoss` | Tough Boss | | 223 | 葡萄牙文 | `Portuguese_Fussyhostess` | Fussy hostess | | 224 | 葡萄牙文 | `Portuguese_Dramatist` | Dramatist | | 225 | 葡萄牙文 | `Portuguese_Steadymentor` | Steady Mentor | | 226 | 葡萄牙文 | `Portuguese_Jovialman` | Jovial Man | | 227 | 葡萄牙文 | `Portuguese_CharmingQueen` | Charming Queen | | 228 | 葡萄牙文 | `Portuguese_SantaClaus` | Santa Claus | | 229 | 葡萄牙文 | `Portuguese_Rudolph` | Rudolph | | 230 | 葡萄牙文 | `Portuguese_Arnold` | Arnold | | 231 | 葡萄牙文 | `Portuguese_CharmingSanta` | Charming Santa | | 232 | 葡萄牙文 | `Portuguese_CharmingLady` | Charming Lady | | 233 | 葡萄牙文 | `Portuguese_Ghost` | Ghost | | 234 | 葡萄牙文 | `Portuguese_HumorousElder` | Humorous Elder | | 235 | 葡萄牙文 | `Portuguese_CalmLeader` | Calm Leader | | 236 | 葡萄牙文 | `Portuguese_GentleTeacher` | Gentle Teacher | | 237 | 葡萄牙文 | `Portuguese_EnergeticBoy` | Energetic Boy | | 238 | 葡萄牙文 | `Portuguese_ReliableMan` | Reliable Man | | 239 | 葡萄牙文 | `Portuguese_SereneElder` | Serene Elder | | 240 | 葡萄牙文 | `Portuguese_GrimReaper` | Grim Reaper | | 241 | 葡萄牙文 | `Portuguese_AssertiveQueen` | Assertive Queen | | 242 | 葡萄牙文 | `Portuguese_WhimsicalGirl` | Whimsical Girl | | 243 | 葡萄牙文 | `Portuguese_StressedLady` | Stressed Lady | | 244 | 葡萄牙文 | `Portuguese_FriendlyNeighbor` | Friendly Neighbor | | 245 | 葡萄牙文 | `Portuguese_CaringGirlfriend` | Caring Girlfriend | | 246 | 葡萄牙文 | `Portuguese_PowerfulSoldier` | Powerful Soldier | | 247 | 葡萄牙文 | `Portuguese_FascinatingBoy` | Fascinating Boy | | 248 | 葡萄牙文 | `Portuguese_RomanticHusband` | Romantic Husband | | 249 | 葡萄牙文 | `Portuguese_StrictBoss` | Strict Boss | | 250 | 葡萄牙文 | `Portuguese_InspiringLady` | Inspiring Lady | | 251 | 葡萄牙文 | `Portuguese_PlayfulSpirit` | Playful Spirit | | 252 | 葡萄牙文 | `Portuguese_ElegantGirl` | Elegant Girl | | 253 | 葡萄牙文 | `Portuguese_CompellingGirl` | Compelling Girl | | 254 | 葡萄牙文 | `Portuguese_PowerfulVeteran` | Powerful Veteran | | 255 | 葡萄牙文 | `Portuguese_SensibleManager` | Sensible Manager | | 256 | 葡萄牙文 | `Portuguese_ThoughtfulLady` | Thoughtful Lady | | 257 | 葡萄牙文 | `Portuguese_TheatricalActor` | Theatrical Actor | | 258 | 葡萄牙文 | `Portuguese_FragileBoy` | Fragile Boy | | 259 | 葡萄牙文 | `Portuguese_ChattyGirl` | Chatty Girl | | 260 | 葡萄牙文 | `Portuguese_Conscientiousinstructor` | Conscientious Instructor | | 261 | 葡萄牙文 | `Portuguese_RationalMan` | Rational Man | | 262 | 葡萄牙文 | `Portuguese_WiseScholar` | Wise Scholar | | 263 | 葡萄牙文 | `Portuguese_FrankLady` | Frank Lady | | 264 | 葡萄牙文 | `Portuguese_DeterminedManager` | Determined Manager | | 265 | 法文 | `French_Male_Speech_New` | Level-Headed Man | | 266 | 法文 | `French_Female_News Anchor` | Patient Female Presenter | | 267 | 法文 | `French_CasualMan` | Casual Man | | 268 | 法文 | `French_MovieLeadFemale` | Movie Lead Female | | 269 | 法文 | `French_FemaleAnchor` | Female Anchor | | 270 | 法文 | `French_MaleNarrator` | Male Narrator | | 271 | 印尼文 | `Indonesian_SweetGirl` | Sweet Girl | | 272 | 印尼文 | `Indonesian_ReservedYoungMan` | Reserved Young Man | | 273 | 印尼文 | `Indonesian_CharmingGirl` | Charming Girl | | 274 | 印尼文 | `Indonesian_CalmWoman` | Calm Woman | | 275 | 印尼文 | `Indonesian_ConfidentWoman` | Confident Woman | | 276 | 印尼文 | `Indonesian_CaringMan` | Caring Man | | 277 | 印尼文 | `Indonesian_BossyLeader` | Bossy Leader | | 278 | 印尼文 | `Indonesian_DeterminedBoy` | Determined Boy | | 279 | 印尼文 | `Indonesian_GentleGirl` | Gentle Girl | | 280 | 德文 | `German_FriendlyMan` | Friendly Man | | 281 | 德文 | `German_SweetLady` | Sweet Lady | | 282 | 德文 | `German_PlayfulMan` | Playful Man | | 283 | 俄文 | `Russian_HandsomeChildhoodFriend` | Handsome Childhood Friend | | 284 | 俄文 | `Russian_BrightHeroine` | Bright Queen | | 285 | 俄文 | `Russian_AmbitiousWoman` | Ambitious Woman | | 286 | 俄文 | `Russian_ReliableMan` | Reliable Man | | 287 | 俄文 | `Russian_CrazyQueen` | Crazy Girl | | 288 | 俄文 | `Russian_PessimisticGirl` | Pessimistic Girl | | 289 | 俄文 | `Russian_AttractiveGuy` | Attractive Guy | | 290 | 俄文 | `Russian_Bad-temperedBoy` | Bad-tempered Boy | | 291 | 意大利文 | `Italian_BraveHeroine` | Brave Heroine | | 292 | 意大利文 | `Italian_Narrator` | Narrator | | 293 | 意大利文 | `Italian_WanderingSorcerer` | Wandering Sorcerer | | 294 | 意大利文 | `Italian_DiligentLeader` | Diligent Leader | | 295 | 阿拉伯文 | `Arabic_CalmWoman` | Calm Woman | | 296 | 阿拉伯文 | `Arabic_FriendlyGuy` | Friendly Guy | | 297 | 土耳其文 | `Turkish_CalmWoman` | Calm Woman | | 298 | 土耳其文 | `Turkish_Trustworthyman` | Trustworthy man | | 299 | 乌克兰文 | `Ukrainian_CalmWoman` | Calm Woman | | 300 | 乌克兰文 | `Ukrainian_WiseScholar` | Wise Scholar | | 301 | 荷兰文 | `Dutch_kindhearted_girl` | Kind-hearted girl | | 302 | 荷兰文 | `Dutch_bossy_leader` | Bossy leader | | 303 | 越南文 | `Vietnamese_kindhearted_girl` | Kind-hearted girl | | 304 | 泰文 | `Thai_male_1_sample8` | Serene Man | | 305 | 泰文 | `Thai_male_2_sample2` | Friendly Man | | 306 | 泰文 | `Thai_female_1_sample1` | Confident Woman | | 307 | 泰文 | `Thai_female_2_sample2` | Energetic Woman | | 308 | 波兰文 | `Polish_male_1_sample4` | Male Narrator | | 309 | 波兰文 | `Polish_male_2_sample3` | Male Anchor | | 310 | 波兰文 | `Polish_female_1_sample1` | Calm Woman | | 311 | 波兰文 | `Polish_female_2_sample3` | Casual Woman | | 312 | 罗马尼亚文 | `Romanian_male_1_sample2` | Reliable Man | | 313 | 罗马尼亚文 | `Romanian_male_2_sample1` | Energetic Youth | | 314 | 罗马尼亚文 | `Romanian_female_1_sample4` | Optimistic Youth | | 315 | 罗马尼亚文 | `Romanian_female_2_sample1` | Gentle Woman | | 316 | 希腊文 | `greek_male_1a_v1` | Thoughtful Mentor | | 317 | 希腊文 | `Greek_female_1_sample1` | Gentle Lady | | 318 | 希腊文 | `Greek_female_2_sample3` | Girl Next Door | | 319 | 捷克文 | `czech_male_1_v1` | Assured Presenter | | 320 | 捷克文 | `czech_female_5_v7` | Steadfast Narrator | | 321 | 捷克文 | `czech_female_2_v2` | Elegant Lady | | 322 | 芬兰文 | `finnish_male_3_v1` | Upbeat Man | | 323 | 芬兰文 | `finnish_male_1_v2` | Friendly Boy | | 324 | 芬兰文 | `finnish_female_4_v1` | Assetive Woman | | 325 | 印地文 | `hindi_male_1_v2` | Trustworthy Advisor | | 326 | 印地文 | `hindi_female_2_v1` | Tranquil Woman | | 327 | 印地文 | `hindi_female_1_v2` | News Anchor | # 图片生成 Source: https://platform.minimaxi.com/docs/guides/image-generation 图片生成服务提供文生图（text-to-image）与图生图（image-to-image）两种核心功能。 ## 根据文本生成图片 根据详尽的文本描述（prompt），直接生成与之匹配的图片。 ```python 请求示例 theme={null} import base64 import requests import os url = "https://api.minimax.cn/v1/image_generation" api_key = os.environ.get("MINIMAX_API_KEY") headers = {"Authorization": f"Bearer {api_key}"} payload = { "model": "image-01", "prompt": "men Dressing in white t shirt, full-body stand front view image :25, outdoor, Venice beach sign, full-body image, Los Angeles, Fashion photography of 90s, documentary, Film grain, photorealistic", "aspect_ratio": "16:9", "response_format": "base64", } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() images = response.json()["data"]["image_base64"] for i in range(len(images)): with open(f"output-{i}.jpeg", "wb") as f: f.write(base64.b64decode(images[i])) ``` 生成结果： ![图片描述](https://filecdn.minimax.chat/public/5d969bc8-047c-424d-b7f8-87ece21e8f13.jpeg) ## 结合参考图生成图片 此功能允许提供一张包含清晰主体的参考图（支持网络图片链接），并结合 prompt 描述，生成一张保留了主体特征的新图片。当前每次请求仅支持传入一张参考图。该功能尤其适用于需要保持人物形象一致性的场景，例如为同一个虚拟角色生成不同情境下的图片。 ```python 请求示例 theme={null} import base64 import requests import os url = "https://api.minimax.cn/v1/image_generation" api_key = os.environ.get("MINIMAX_API_KEY") headers = {"Authorization": f"Bearer {api_key}"} payload = { "model": "image-01", "prompt": "女孩在图书馆的窗户前，看向远方", "aspect_ratio": "16:9", "subject_reference": [ { "type": "character", "image_file": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/1754990600020238321-411603868533342214-cover.jpg", } ], "response_format": "base64", } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() images = response.json()["data"]["image_base64"] for i in range(len(images)): with open(f"output-{i}.jpeg", "wb") as f: f.write(base64.b64decode(images[i])) ``` 生成结果： ![图片描述](https://filecdn.minimax.chat/public/0a70cf90-9ae2-4593-b4a3-84ec9ab3429a.jpeg) ## 推荐阅读 使用 API 接口，输入文本描述，进行图片生成。 使用 API 接口，输入图片内容，进行图片生成。 各模型的定价说明、计费方式及使用限制。 为保证资源的高效使用，引入速率限制，以确保服务的可用性、稳定性。 # 本地运行与自托管部署 MiniMax 开放模型 Source: https://platform.minimaxi.com/docs/guides/local-deploy 为 MiniMax-M3、MiniMax-M2.7、MiniMax Music 3 和 MiniMax H3 选择本地运行或自托管路径。 MiniMax 提供语言、多模态理解、音乐生成和音视频生成模型的开放权重。本指南汇总官方部署基线，并链接到每个模型的端到端部署流程。 本栏目以服务器或集群上的**自托管部署**为主，H3 页面还提供 ComfyUI 本地工作流路径。你需要自行准备硬件、运行推理环境、按需配置访问控制并实施内容安全措施。需要托管服务、弹性扩缩容或 MiniMax 平台完整能力时，请使用 [MiniMax API](/docs/guides/quickstart-preparation)。 ## 选择模型 | 模型 | 任务 | 模型原生能力 | 本部署指南覆盖范围 | 参考配置 | 状态 | | :--------------------------------------------------- | :---------------------- | :------------------ | :------------------------------------------------------------------------------- | :-------------------------------------------------------- | :--------------------------------- | | [MiniMax-M3](/docs/guides/local-deploy-m3) | Agent、Coding、长上下文和多模态理解 | 文本、图片和视频输入，文本输出 | SGLang OpenAI 兼容 Chat Completions；以模型页的已验证能力表为准 | 8 × B200、MXFP8 | Experimental | | [MiniMax-M2.7](/docs/guides/local-deploy-m2-7) | Agent、软件工程和现有 M2.7 工作流 | 文本输入和输出、思考、工具调用 | SGLang OpenAI 兼容 Chat Completions | 4 × 高显存 NVIDIA GPU、TP 4；官方尚未发布统一最低显存 | Preview | | [MiniMax Music 3](/docs/guides/local-deploy-music-3) | 根据歌词和音乐描述生成歌曲 | 歌词和音乐描述输入，立体声音频输出 | SGLang-Omni 非流式 Speech API | 1 × H200 参考样例；其他容量未验证 | Preview | | [MiniMax H3](/docs/guides/local-deploy-h3) | 文本、关键帧或参考素材驱动的音视频生成 | 文本、图片、视频和音频条件，音视频输出 | ComfyUI 原生 T2V/I2V/R2V 工作流与 SGLang H3-Base API；不包含 H3-Context-IR 和完整 2K Workflow | ComfyUI `0.30.0+`，最低显存未公布；SGLang 参考配置为 8 × B200、Ulysses 8 | ComfyUI 原生支持 / SGLang Experimental | 状态表示本文档部署基线的成熟度，不表示模型本身的产品生命周期： * **Stable**：使用固定版本的运行时，并提供可复现的参考命令。 * **Preview**：已有官方部署路径，但上游安装方式或部分能力仍在变化。 * **Experimental**：依赖预发布运行时，或部分硬件组合尚未完成端到端验证。 “开放权重”不代表所有模型采用相同许可证。部署、分发或商用前，请阅读对应模型页链接的完整 License 和 Acceptable Use Policy。推理框架支持不会额外授予模型使用权。 ## 自托管部署的边界 自托管后，模型权重、输入数据和推理服务运行在你控制的基础设施上，同时也意味着： * 你负责容量规划、扩缩容、监控、故障恢复和升级。 * 快速开始默认只监听本机；对外提供服务前，需要配置鉴权、TLS、网络隔离和远程媒体访问限制。 * 开放权重不包含 MiniMax 平台的托管文件、缓存、内容安全和平台专属工作流。 * 社区量化、转换权重和其他推理框架不属于本栏目已验证范围，除非模型页明确列出。 ## 部署前准备 1. 阅读目标模型的 License、开放范围和已验证能力。 2. 按模型页准备指定的 GPU、主机内存、磁盘、驱动和 CUDA 环境。 3. 固定模型 revision、推理框架版本或镜像 digest，不要在生产环境跟随 `main`、`dev` 或 `latest` 漂移。 4. 准备 Hugging Face 缓存或离线权重；使用中国大陆镜像时，以模型页列出的官方入口为准。 5. 先完成健康检查和最小请求，再进行量化、并行、卸载或吞吐优化。 对应模型页提供 MiniMax 文档采用的参考基线。SGLang Cookbook 配置器可生成更多硬件、量化和拓扑组合，但生成结果可能处于 Unverified 状态；不要把其他硬件的参数直接套用到当前环境。 ## 支持与验证范围 每个模型页都会标明模型 revision、运行时版本、参考硬件、已验证能力和最后验证日期。缺少官方实测的数据会明确写为“未提供”或“未验证”，不使用相邻模型或社区结果估算。 # 本地运行与自托管部署 MiniMax H3 Source: https://platform.minimaxi.com/docs/guides/local-deploy-h3 使用 ComfyUI 本地运行 MiniMax H3，或通过 SGLang 部署可复现的 H3-Base 服务。 MiniMax H3 受 [MiniMax H3 Community License Agreement](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE) 约束。截至 2026 年 8 月 26 日审阅的 License 版本，美国、欧盟、英国和韩国属于 Excluded Territories，需要另行获得许可。下载、部署或提供托管服务前，请阅读最新协议。 MiniMax H3-Base 联合生成 768p 视频与同步立体声音频。本页提供两条不同路径：使用 ComfyUI 的本地可视化工作流，以及在 NVIDIA 数据中心 GPU 上使用 SGLang 部署自托管 API 服务。 ## 状态与范围 | 项目 | 固定基线 | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------ | | SGLang 部署状态 | **Preview** — H3 支持已随 SGLang v0.5.17 及以后版本在 PyPI 发布；本页为可复现性固定源码 commit，上游 diffusion 安装的依赖仍使用 `--prerelease=allow` | | vLLM-Omni 支持 | 社区维护的 recipe，基于 vLLM 0.26.0；见[使用 vLLM-Omni 自托管](#使用-vllm-omni-自托管) | | ComfyUI 支持 | ComfyUI `0.30.0` 及以上版本原生提供 T2V、I2V 和 R2V 模板；使用 Comfy-Org 转换权重 | | 最后审阅 | 2026 年 8 月 26 日 | | 模型 | [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3)，revision `42ed227ee7df40d41602854ae760620d6eb651fe` | | 推理框架 | SGLang 源码 commit `2511743bd784e69e5a81ca3d926a000711dae4ab` | | SGLang Quickstart checkpoint | FL2VA，官方混合 BF16/FP32 权重 | | SGLang Quickstart 硬件 | 单节点 8 × NVIDIA B200、Ulysses degree 8、组件常驻 | | 上游配方验证的 API | 异步 `/v1/videos` 接口、短边 768 像素的 5 秒 T2VA | 固定 commit 可以提高命令的可复现性，但 H3 diffusion 服务尚不是稳定的 SGLang 发布契约。修改任一 revision 前应重新验证本页。 开放发布包含 H3-Base FL2VA 与 Ref2VA，不包含 H3-Context-IR 和 H3-Regenerate-2K。因此，自托管 H3-Base 不能复现 MiniMax 平台完整的 Context-IR 与 2K 工作流。 ## 选择部署路径 | 路径 | 适用场景 | 接口 | 权重 | 验证边界 | | :-------------------- | :---------------------------------------- | :--------------------- | :----------------------------------- | :---------------------------------------------------- | | **ComfyUI 本地工作流** | 交互创作、提示词迭代、关键帧和参考素材 | 可视化节点图与模板库 | Comfy-Org 发布的裁剪和量化转换权重 | ComfyUI 原生模板；数值基线不同于官方混合 BF16/FP32 checkpoint | | **SGLang 自托管 API** | 可复现的服务器部署与应用集成 | 异步 `/v1/videos` API | 官方 `MiniMaxAI/MiniMax-H3` checkpoint | 本文固定的 8 × B200 FL2VA 参考配置 | | **vLLM-Omni 自托管 API** | FL2VA + Ref2VA 合并服务、同步 MP4 响应、AMD ROCm 主机 | 同步与异步 `/v1/videos` API | 官方 `MiniMaxAI/MiniMax-H3` checkpoint | 社区维护的上游 recipe；见[使用 vLLM-Omni 自托管](#使用-vllm-omni-自托管) | 需要在本地工作站通过可视化方式创建和调整工作流时，选择 ComfyUI；需要 HTTP 服务、可复现服务器配置或应用集成时，选择 SGLang。 ## 使用 ComfyUI 本地运行 H3 ComfyUI 原生提供 MiniMax H3 节点和示例模板，无需先搭建推理 API，适合快速体验 T2V、I2V 和参考素材驱动工作流。 ComfyUI 模板使用 [`Comfy-Org/MiniMax-H3`](https://huggingface.co/Comfy-Org/MiniMax-H3) 发布的裁剪和量化文件，其中包含 INT8/NVFP4 组件。这些文件不同于 SGLang 基线使用的官方混合 BF16/FP32 H3 checkpoint，输出质量、显存占用和可复现性可能不同；不要混用两条路径的性能结论。 ### ComfyUI 基线 | 项目 | 基线 | | :-------------------------- | :--------------------------------------------------------------------------------------------------------- | | ComfyUI | `0.30.0` 或更高版本 | | 内置工作流 | MiniMax H3 T2V、I2V 和 R2V | | 本文核验的工作流模板 revision | [`3c1df78`](https://github.com/Comfy-Org/workflow_templates/tree/3c1df78dedcc66c94ec27e0ed8a809ed7742f863) | | 本文核验的 Comfy-Org 模型 revision | [`4cc1d817`](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/4cc1d817b6184899b41293954329f576cb5ae86b) | | 已公布最低显存与性能 | ComfyUI H3 指南未公布；请在实际硬件上验证所选工作流 | 以上版本和 revision 记录 2026 年 8 月 26 日核验的文档基线。此后 Template Library 可能继续更新。 ### 通过 Template Library 快速开始 1. 将 ComfyUI 更新到 `0.30.0` 或更高版本，并正常启动。 2. 打开 **Template Library** > **Video**。 3. 选择 **MiniMax H3 T2V**、**MiniMax H3 I2V** 或 **MiniMax H3 R2V**。 4. 按模型扫描弹窗下载所需文件。如果模型列表没有刷新，请重启 ComfyUI。 5. 设置提示词，以及需要的输入图片、视频或音频参考素材。 6. 在 **Resolution Selector** 中使用 `0.98` Megapixels 和 `32` 的倍数，或者为 16:9 原生画布直接设置 `1344 × 768`。不要选择 `1.0` Megapixels：它会得到 `1376 × 768`，超过 H3-Base 的 768 × 1344 像素面积上限。 7. 将工作流加入队列。正确结果应为包含 24 FPS 视频流和同步立体声音频的 MP4。 ### 选择工作流 | 工作流 | 输入与控制 | checkpoint 系列 | 原生节点 | 固定模板 | | :-- | :--------------------- | :------------ | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- | | T2V | 描述镜头、运镜、对白、音效和音乐的文本提示词 | FL2VA | 不连接关键帧的 `MiniMaxH3ImageToVideo` | [T2V JSON](https://github.com/Comfy-Org/workflow_templates/blob/3c1df78dedcc66c94ec27e0ed8a809ed7742f863/templates/video_minimax_h3_t2v.json) | | I2V | 输入图片；可选首帧和尾帧 | FL2VA | `MiniMaxH3ImageToVideo` | [I2V JSON](https://github.com/Comfy-Org/workflow_templates/blob/3c1df78dedcc66c94ec27e0ed8a809ed7742f863/templates/video_minimax_h3_i2v.json) | | R2V | 支持的图片、视频和音频参考素材组合 | Ref2VA | `MiniMaxH3ReferenceToVideo` | [R2V JSON](https://github.com/Comfy-Org/workflow_templates/blob/3c1df78dedcc66c94ec27e0ed8a809ed7742f863/templates/video_minimax_h3_r2v.json) | T2V 和 I2V 使用 FL2VA diffusion model；R2V 需要独立的 Ref2VA diffusion model，两者不能互换。在 R2V 提示词中，按连接顺序使用 ``、`