voice_design
Generate custom voices using description prompts and preview text with MiniMax MCP JS. Save outputs to specified directories for text-to-speech applications.
Instructions
Generate a voice based on description prompts.
Note: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| outputDirectory | No | The directory to save the output file. `outputDirectory` is relative to `MINIMAX_MCP_BASE_PATH` (or `basePath` in config). The final save path is `${basePath}/${outputDirectory}`. For example, if `MINIMAX_MCP_BASE_PATH=~/Desktop` and `outputDirectory=workspace`, the output will be saved to `~/Desktop/workspace/` | |
| previewText | Yes | The text to preview the voice | |
| prompt | Yes | The prompt to generate the voice from | |
| voiceId | No | The id of the voice to use. For example, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"... |
Implementation Reference
- src/api/voice-design.ts:16-73 (handler)Core handler implementing the voice_design tool logic: validates inputs, calls MiniMax /v1/voice_design API, decodes hex audio response, saves MP3 preview file, returns voiceId and outputFile.async voiceDesign(request: VoiceDesignRequest): Promise<any> { // Validate required parameters if (!request.prompt || request.prompt.trim() === '') { throw new MinimaxRequestError(ERROR_PROMPT_REQUIRED); } if (!request.previewText || request.previewText.trim() === '') { throw new MinimaxRequestError(ERROR_PREVIEW_TEXT_REQUIRED); } // Process output file const textPrefix = request.prompt.substring(0, 20).replace(/[^\w]/g, '_'); const fileName = `voice_design_${textPrefix}_${Date.now()}`; const outputFile = buildOutputFile(fileName, request.outputDirectory, 'mp3'); // Prepare request data const requestData: Record<string, any> = { prompt: request.prompt, preview_text: request.previewText, voice_id: request.voiceId, }; try { // Send request const response = await this.api.post<any>('/v1/voice_design', requestData); // Process response const trialAudioData = response?.trial_audio; const voiceId = response?.voice_id; if (!trialAudioData) { throw new MinimaxRequestError('Could not get audio data from response'); } // decode and save file try { // Convert hex string to binary const audioBuffer = Buffer.from(trialAudioData, 'hex'); // Ensure output directory exists const outputDir = path.dirname(outputFile); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } // Write to file fs.writeFileSync(outputFile, audioBuffer); return { voiceId, outputFile, }; } catch (error) { throw new MinimaxRequestError(`Failed to save audio file: ${String(error)}`); } } catch (err) { throw err; } }
- src/mcp-server.ts:775-829 (registration)Registers the 'voice_design' MCP tool with name, description, Zod input schema (prompt, previewText, voiceId?, outputDirectory?), and async handler that calls VoiceDesignAPI and formats response.private registerVoiceDesignTool(): void { this.server.tool( 'voice_design', 'Generate a voice based on description prompts.\n\nNote: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.', { prompt: z .string() .describe('The prompt to generate the voice from'), previewText: z .string() .describe('The text to preview the voice'), voiceId: z .string() .optional() .describe('The id of the voice to use. For example, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"...'), outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory, }, async (params) => { try { // No need to update configuration from request parameters in stdio mode const { voiceId, outputFile } = await this.voiceDesignApi.voiceDesign(params); // Handle different output formats if (this.config.resourceMode === RESOURCE_MODE_URL) { return { content: [ { type: 'text', text: `Success. Voice ID: ${voiceId}. Voice URL: ${outputFile}`, }, ], }; } else { return { content: [ { type: 'text', text: `Success. Voice ID: ${voiceId}. Voice saved as: ${outputFile}`, }, ], }; } } catch (error) { return { content: [ { type: 'text', text: `Failed to design voice: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }, ); }
- src/types/index.ts:79-83 (schema)TypeScript interface defining the structure of VoiceDesignRequest: prompt (required), previewText (required), voiceId (optional), inherits outputDirectory from BaseToolRequest.export interface VoiceDesignRequest extends BaseToolRequest { prompt: string; previewText: string; voiceId?: string; }
- Thin wrapper in MediaService that initializes and delegates to VoiceDesignAPI.voiceDesign, used by REST server handler.public async designVoice(params: any): Promise<any> { this.checkInitialized(); try { return await this.voiceDesignApi.voiceDesign(params); } catch (error) { throw this.wrapError('Failed to design voice', error); } }
- src/mcp-rest-server.ts:401-419 (registration)Tool definition/schema for 'voice_design' in REST server's listTools handler, including arguments and inputSchema for protocol compliance.name: 'voice_design', description: 'Generate a voice based on description prompts', arguments: [ { name: 'prompt', description: 'The prompt to generate the voice from', required: true }, { name: 'previewText', description: 'The text to preview the voice', required: true }, { name: 'voiceId', description: 'The id of the voice to use', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false } ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, previewText: { type: 'string' }, voiceId: { type: 'string' }, outputDirectory: { type: 'string' } }, required: ['prompt', 'previewText'] } }