MiniMax MCP JS

Instructions

Implementation Reference

• src/mcp-server.ts:555-631 (registration)

  Registration of the 'image_to_video' MCP tool including input schema (Zod) and execution handler that calls VideoAPI.generateVideo

  private registerImageToVideoTool(): void {
    this.server.tool(
      'image_to_video',
      'Generate a video based on an image.\n\nNote: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.',
      {
        model: z
          .string()
          .optional()
          .default('I2V-01')
          .describe('Model to use, values: ["I2V-01", "I2V-01-Director", "I2V-01-live"]'),
        prompt: z.string().describe('Text prompt for video generation'),
        firstFrameImage: z.string().describe('Path to the first frame image'),
        outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory,
        outputFile: z
          .string()
          .optional()
          .describe('Path to save the generated video file, automatically generated if not provided'),
        asyncMode: z
          .boolean()
          .optional()
          .default(false)
          .describe('Whether to use async mode. Defaults to False. If True, the video generation task will be submitted asynchronously and the response will return a task_id. Should use `query_video_generation` tool to check the status of the task and get the result.'),
      },
      async (params) => {
        try {
          // If no output filename is provided, generate one automatically
          if (!params.outputFile) {
            const promptPrefix = params.prompt.substring(0, 20).replace(/[^\w]/g, '_');
            params.outputFile = `i2v_${promptPrefix}_${Date.now()}`;
          }
  
          const result = await this.videoApi.generateVideo(params);
  
          if (params.asyncMode) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Success. Video generation task submitted: Task ID: ${result.task_id}. Please use \`query_video_generation\` tool to check the status of the task and get the result.`,
                },
              ],
            };
          }
  
          // Handle different output formats
          if (this.config.resourceMode === RESOURCE_MODE_URL) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Success. Video URL: ${result.video_url}`,
                },
              ],
            };
          } else {
            return {
              content: [
                {
                  type: 'text',
                  text: `Video saved: ${result.video_path}`,
                },
              ],
            };
          }
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to generate video: ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
          };
        }
      }
    );
  }

• src/mcp-rest-server.ts:353-375 (schema)

  JSON schema definition for 'image_to_video' tool in REST server's listTools handler

    name: 'image_to_video',
    description: 'Generate video based on image',
    arguments: [
      { name: 'prompt', description: 'Text prompt for video generation', required: true },
      { name: 'firstFrameImage', description: 'Path to first frame image', required: true },
      { name: 'model', description: 'Model to use, values: ["I2V-01", "I2V-01-Director", "I2V-01-live"]', required: false },
      { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false },
      { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false },
      { name: 'async_mode', description: 'Whether to use async mode. Defaults to False. If True, the video generation task will be submitted asynchronously and the response will return a task_id. Should use `query_video_generation` tool to check the status of the task and get the result', required: false }
    ],
    inputSchema: {
      type: 'object',
      properties: {
        prompt: { type: 'string' },
        firstFrameImage: { type: 'string' },
        model: { type: 'string' },
        outputDirectory: { type: 'string' },
        outputFile: { type: 'string' },
        async_mode: { type: 'boolean' }
      },
      required: ['prompt', 'firstFrameImage']
    }
  },

• src/mcp-rest-server.ts:622-652 (handler)

  Handler method for 'image_to_video' tool in REST server that validates params and delegates to MediaService.generateVideo with retry logic

  private async handleImageToVideo(args: any, api: MiniMaxAPI, mediaService: MediaService, attempt = 1): Promise<any> {
    try {
      // Ensure model is suitable for image to video conversion
      if (!args.model) {
        args.model = 'I2V-01';
      }
  
      // Ensure firstFrameImage parameter exists
      if (!args.firstFrameImage) {
        throw new Error('Missing required parameter: firstFrameImage');
      }
  
      // Auto-generate output filename if not provided
      if (!args.outputFile) {
        const promptPrefix = args.prompt.substring(0, 20).replace(/[^\w]/g, '_');
        args.outputFile = `i2v_${promptPrefix}_${Date.now()}`;
      }
  
      // Call media service to handle request
      const result = await mediaService.generateVideo(args);
      return result;
    } catch (error) {
      if (attempt < MAX_RETRY_ATTEMPTS) {
        // console.warn(`[${new Date().toISOString()}] Failed to generate video, attempting retry (${attempt}/${MAX_RETRY_ATTEMPTS})`, error);
        // Delay retry
        await new Promise(resolve => setTimeout(resolve, RETRY_DELAY * Math.pow(2, attempt - 1)));
        return this.handleImageToVideo(args, api, mediaService, attempt + 1);
      }
      throw this.wrapError('Failed to generate video', error);
    }
  }

• src/services/media-service.ts:137-179 (helper)

  MediaService.generateVideo helper method used by image_to_video handlers, formats response and calls VideoAPI

  public async generateVideo(params: any): Promise<any> {
    this.checkInitialized();
    try {
      // Auto-generate output filename if not provided
      if (!params.outputFile) {
        const promptPrefix = params.prompt.substring(0, 20).replace(/[^\w]/g, '_');
        params.outputFile = `video_${promptPrefix}_${Date.now()}`;
      }
  
      const result = await this.videoApi.generateVideo(params);
      if (params.async_mode) {
        return {
          content: [
            {
              type: 'text',
              text: `Success. Video generation task submitted: Task ID: ${result.task_id}. Please use \`query_video_generation\` tool to check the status of the task and get the result.`,
            },
          ],
        };
      } else if (this.config.resourceMode === RESOURCE_MODE_URL) {
        return {
          content: [
            {
              type: 'text',
              text: `Success. Video URL: ${result.video_url}`,
            },
          ],
        };
      } else {
        return {
          content: [
            {
              type: 'text',
              text: `Success. Video saved as: ${result.video_path}`,
            },
          ],
        };
      }
    } catch (error) {
      // console.error(`[${new Date().toISOString()}] Failed to generate video:`, error);
      throw this.wrapError('Failed to generate video', error);
    }
  }

• src/api/video.ts:17-149 (handler)

  Core handler in VideoAPI for generating video from image+text (image_to_video). Submits to MiniMax API /v1/video_generation (supports first_frame_image), polls status, downloads/saves video file or returns URL.

  async generateVideo(request: VideoGenerationRequest): Promise<any> {
    // Validate required parameters
    if (!request.prompt || request.prompt.trim() === '') {
      throw new MinimaxRequestError(ERROR_PROMPT_REQUIRED);
    }
  
    try {
      // Ensure model is valid
      const model = this.ensureValidModel(request.model);
  
      // Prepare request data
      const requestData: Record<string, any> = {
        model: model,
        prompt: request.prompt
      };
  
      // Process first frame image
      if (request.firstFrameImage) {
        // Check if it's a URL or data URL
        if (!request.firstFrameImage.startsWith(('http://')) &&
            !request.firstFrameImage.startsWith(('https://')) &&
            !request.firstFrameImage.startsWith(('data:'))) {
          // If it's a local file, convert to data URL
          if (!fs.existsSync(request.firstFrameImage)) {
            throw new MinimaxRequestError(`First frame image file does not exist: ${request.firstFrameImage}`);
          }
  
          const imageData = fs.readFileSync(request.firstFrameImage);
          const base64Image = imageData.toString('base64');
          requestData.first_frame_image = `data:image/jpeg;base64,${base64Image}`;
        } else {
          requestData.first_frame_image = request.firstFrameImage;
        }
      }
  
      // Process resolution
      if (request.resolution) {
        requestData.resolution = request.resolution;
      }
  
      // Process duration
      if (request.duration) {
        requestData.duration = request.duration;
      }
  
      // Step 1: Submit video generation task
      const response = await this.api.post<any>('/v1/video_generation', requestData);
  
      // Get task ID
      const taskId = response?.task_id;
      if (!taskId) {
        throw new MinimaxRequestError('Unable to get task ID from response');
      }
  
      if (request.asyncMode) {
        return {
          task_id: taskId,
        }
      }
  
      // Step 2: Wait for video generation task to complete
      let fileId: string | null = null;
      const maxRetries = model === "MiniMax-Hailuo-02" ? 60 : 30; // Maximum 30 attempts, total duration 10 minutes (30 * 20 seconds). MiniMax-Hailuo-02 model has a longer processing time, so we need to wait for a longer time
      const retryInterval = 20; // 20 second interval
  
      for (let attempt = 0; attempt < maxRetries; attempt++) {
        // Query task status
        const statusResponse = await this.api.get<any>(`/v1/query/video_generation?task_id=${taskId}`);
        const status = statusResponse?.status;
  
        if (status === 'Fail') {
          throw new MinimaxRequestError(`Video generation task failed, task ID: ${taskId}`);
        } else if (status === 'Success') {
          fileId = statusResponse?.file_id;
          if (fileId) {
            break;
          }
          throw new MinimaxRequestError(`File ID missing in success response, task ID: ${taskId}`);
        }
  
        // Task still processing, wait and retry
        await new Promise(resolve => setTimeout(resolve, retryInterval * 1000));
      }
  
      if (!fileId) {
        throw new MinimaxRequestError(`Failed to get file ID, task ID: ${taskId}`);
      }
  
      // Step 3: Get video result
      const fileResponse = await this.api.get<any>(`/v1/files/retrieve?file_id=${fileId}`);
      const downloadUrl = fileResponse?.file?.download_url;
  
      if (!downloadUrl) {
        throw new MinimaxRequestError(`Unable to get download URL for file ID: ${fileId}`);
      }
  
      // If URL mode, return URL directly
      const resourceMode = this.api.getResourceMode();
      if (resourceMode === RESOURCE_MODE_URL) {
        return {
          video_url: downloadUrl,
          task_id: taskId,
        };
      }
  
      // Step 4: Download and save video
      const outputPath = buildOutputFile(`video_${taskId}`, request.outputDirectory, 'mp4', true);
  
      try {
        const videoResponse = await requests.default.get(downloadUrl, { responseType: 'arraybuffer' });
  
        // Ensure directory exists
        const dirPath = path.dirname(outputPath);
        if (!fs.existsSync(dirPath)) {
          fs.mkdirSync(dirPath, { recursive: true });
        }
  
        // Save file
        fs.writeFileSync(outputPath, Buffer.from(videoResponse.data));
        return {
          video_path: outputPath,
          task_id: taskId,
        }
      } catch (error) {
        throw new MinimaxRequestError(`Failed to download or save video: ${String(error)}`);
      }
    } catch (error) {
      if (error instanceof MinimaxRequestError) {
        throw error;
      }
      throw new MinimaxRequestError(`Unexpected error occurred during video generation: ${String(error)}`);
    }
  }