generate_image

Implementation Reference

• src/index.ts:1246-1430 (registration)

  MCP tool registration for 'generate_image' - defines the tool with its Zod schema for prompt, outputPath, and all optional generation parameters, then calls the generateImage service function.

  // Generate image tool - uses Replicate directly without Printify integration
  server.tool(
    "generate_image",
    {
      prompt: z.string().describe("Text prompt for image generation"),
      outputPath: z.string().describe("Full path where the generated image should be saved"),
  
      // Optional model override
      model: z.string().optional()
        .describe("Optional: Override the default model. Use get_defaults to see available models"),
  
      // Common parameters for both models
      width: z.number().optional().default(1024).describe("Image width in pixels"),
      height: z.number().optional().default(1024).describe("Image height in pixels"),
      aspectRatio: z.string().optional().describe("Aspect ratio (e.g., '16:9', '4:3', '1:1'). If provided, overrides width and height"),
      outputFormat: z.enum(["jpeg", "png", "webp"]).optional().default("png").describe("Output format"),
      safetyTolerance: z.number().optional().default(2).describe("Safety tolerance (0-6)"),
      seed: z.number().optional().describe("Random seed for reproducible generation"),
      numInferenceSteps: z.number().optional().default(25).describe("Number of inference steps"),
      guidanceScale: z.number().optional().default(7.5).describe("Guidance scale"),
      negativePrompt: z.string().optional().default("low quality, bad quality, sketches").describe("Negative prompt"),
  
      // Flux 1.1 Pro specific parameters
      promptUpsampling: z.boolean().optional()
        .describe("Enable prompt upsampling (Flux 1.1 Pro only)"),
      outputQuality: z.number().optional()
        .describe("Output quality 1-100 (Flux 1.1 Pro only)"),
  
      // Flux 1.1 Pro Ultra specific parameters
      raw: z.boolean().optional()
        .describe("Generate less processed, more natural-looking images (Flux 1.1 Pro Ultra only)"),
      imagePromptStrength: z.number().optional()
        .describe("Image prompt strength 0-1 (Flux 1.1 Pro Ultra only)")
    },
    async ({
      prompt, outputPath, model, width, height, aspectRatio, outputFormat, safetyTolerance,
      seed, numInferenceSteps, guidanceScale, negativePrompt, promptUpsampling, outputQuality,
      raw, imagePromptStrength
    }): Promise<{ content: any[], isError?: boolean }> => {
      // Import the services
      const { generateImage } = await import('./services/image-generator.js');
      const { formatSuccessResponse } = await import('./utils/error-handler.js');
      const fs = await import('fs');
      const path = await import('path');
  
      // Check if Replicate client is initialized
      if (!replicateClient) {
        return {
          content: [{
            type: "text",
            text: "Replicate API client is not initialized. The REPLICATE_API_TOKEN environment variable may not be set."
          }],
          isError: true
        };
      }
  
      // Extract filename from the output path
      const fileName = path.basename(outputPath);
  
      // Check if we're using the Ultra model which requires ImgBB
      // Determine which model to use (user-specified or default)
      const modelToUse = model || replicateClient.getDefaultModel();
  
      console.log(`Starting generate_image with prompt: ${prompt}`);
      console.log(`Using model: ${modelToUse}`);
      console.log(`Output path: ${outputPath}`);
  
      // Get default parameters first
      const defaults = replicateClient.getAllDefaults();
  
      // Generate the image with Replicate and process with Sharp
      // Start with defaults, then override with parameters from the tool call
      const generationResult = await generateImage(
        replicateClient,
        prompt,
        fileName,
        {
          // Start with defaults
          model: defaults.model,
          width: defaults.width,
          height: defaults.height,
          aspectRatio: defaults.aspectRatio,
          outputFormat: defaults.outputFormat,
          safetyTolerance: defaults.safetyTolerance,
          numInferenceSteps: defaults.numInferenceSteps,
          guidanceScale: defaults.guidanceScale,
          negativePrompt: defaults.negativePrompt,
          raw: defaults.raw,
          promptUpsampling: defaults.promptUpsampling,
          outputQuality: defaults.outputQuality,
  
          // Override with parameters from the tool call (if provided)
          ...(model !== undefined && { model }),
          ...(width !== undefined && { width }),
          ...(height !== undefined && { height }),
          ...(aspectRatio !== undefined && { aspectRatio }),
          ...(outputFormat !== undefined && { outputFormat }),
          ...(safetyTolerance !== undefined && { safetyTolerance }),
          ...(seed !== undefined && { seed }),
          ...(numInferenceSteps !== undefined && { numInferenceSteps }),
          ...(guidanceScale !== undefined && { guidanceScale }),
          ...(negativePrompt !== undefined && { negativePrompt }),
          ...(promptUpsampling !== undefined && { promptUpsampling }),
          ...(outputQuality !== undefined && { outputQuality }),
          ...(raw !== undefined && { raw }),
          ...(imagePromptStrength !== undefined && { imagePromptStrength })
        }
      );
  
      // If image generation failed, return the error
      if (!generationResult.success) {
        return generationResult.errorResponse as { content: any[], isError: boolean };
      }
  
      const imageBuffer = generationResult.buffer;
      const finalFileName = generationResult.fileName;
      const usingModel = generationResult.model;
      const dimensions = generationResult.dimensions;
  
      // Make sure we have valid image data
      if (!imageBuffer) {
        return {
          content: [{
            type: "text",
            text: "Failed to get valid image data from the image generator."
          }],
          isError: true
        };
      }
  
      try {
        // Create the directory if it doesn't exist
        const outputDir = path.dirname(outputPath);
        if (!fs.existsSync(outputDir)) {
          fs.mkdirSync(outputDir, { recursive: true });
        }
  
        // Save the buffer directly to the specified output path
        if (imageBuffer) {
          fs.writeFileSync(outputPath, imageBuffer);
        } else {
          throw new Error('No image data available to save');
        }
  
        // Return success response
        const response = formatSuccessResponse(
          'Image Generated Successfully',
          {
            Prompt: prompt,
            Model: usingModel.split('/')[1],
            'Output Path': outputPath,
            'File Name': finalFileName,
            'File Size': `${imageBuffer ? imageBuffer.length : 0} bytes`,
            'Dimensions': dimensions || `${width}x${height}`,
            'Format': outputFormat || 'png',
            'Generation Parameters': {
              // Use the actual dimensions from the generated image
              ...(generationResult.dimensions ? { 'Dimensions': generationResult.dimensions } : {}),
              // Show the aspect ratio that was actually used (from tool call or defaults)
              'Aspect Ratio': aspectRatio || defaults.aspectRatio || '1:1',
              'Inference Steps': numInferenceSteps || defaults.numInferenceSteps,
              'Guidance Scale': guidanceScale || defaults.guidanceScale,
              'Negative Prompt': negativePrompt || defaults.negativePrompt,
              ...(raw !== undefined ? { 'Raw Mode': raw } : {}),
              ...(promptUpsampling !== undefined ? { 'Prompt Upsampling': promptUpsampling } : {}),
              ...(outputQuality !== undefined ? { 'Output Quality': outputQuality } : {}),
              ...(imagePromptStrength !== undefined ? { 'Image Prompt Strength': imagePromptStrength } : {}),
              ...(seed !== undefined ? { 'Seed': seed } : {})
            }
          },
          `Image has been successfully generated and saved to: ${outputPath}`
        ) as { content: any[], isError?: boolean };
  
        return response;
      } catch (error: any) {
        return {
          content: [{
            type: "text",
            text: `Error saving image to ${outputPath}: ${error.message || String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• src/services/image-generator.ts:12-148 (handler)

  Main handler function 'generateImage' - accepts ReplicateClient, prompt, fileName, and options, builds model options, calls replicateClient.generateImage(), processes with Sharp, and returns buffer, mimeType, fileName, model, and dimensions.

  export async function generateImage(
    replicateClient: ReplicateClient,
    prompt: string,
    fileName: string,
    options: any = {}
  ) {
    // No need to track files anymore since we're keeping everything in memory
  
    try {
      // Prepare options with proper naming for the API
      const modelOptions: any = {};
  
      // Set aspect ratio or dimensions
      if (options.aspectRatio) {
        modelOptions.aspectRatio = options.aspectRatio;
      } else {
        // If no aspect ratio is provided, use width and height
        // These will be overridden by the defaults in the DefaultsManager if not provided
        modelOptions.width = options.width || 1024;
        modelOptions.height = options.height || 1024;
      }
  
      // Add common parameters
      if (options.numInferenceSteps) modelOptions.numInferenceSteps = options.numInferenceSteps;
      if (options.guidanceScale) modelOptions.guidanceScale = options.guidanceScale;
      if (options.negativePrompt) modelOptions.negativePrompt = options.negativePrompt;
      if (options.seed !== undefined) modelOptions.seed = options.seed;
      // Always set outputFormat, defaulting to png unless explicitly specified
      modelOptions.outputFormat = options.outputFormat || "png";
      if (options.safetyTolerance !== undefined) modelOptions.safetyTolerance = options.safetyTolerance;
  
      // Add model-specific parameters if provided
      if (options.promptUpsampling !== undefined) modelOptions.promptUpsampling = options.promptUpsampling;
      if (options.outputQuality !== undefined) modelOptions.outputQuality = options.outputQuality;
      if (options.raw !== undefined) modelOptions.raw = options.raw;
      if (options.imagePromptStrength !== undefined) modelOptions.imagePromptStrength = options.imagePromptStrength;
  
      // Add model override if provided
      if (options.model) modelOptions.model = options.model;
  
      // Get the current default model for informational purposes
      const defaultModel = replicateClient.getDefaultModel();
      const usingModel = options.model || defaultModel;
      console.log(`Using model: ${usingModel} (${options.model ? 'override' : 'default'})`);
      console.log(`Prompt: ${prompt}`);
  
      // STEP 1: Generate the image with Replicate
      console.log('Generating image with Replicate...');
      const imageBuffer = await replicateClient.generateImage(prompt, modelOptions);
      console.log(`Image generated successfully, buffer size: ${imageBuffer.length} bytes`);
  
      // STEP 2: Process the image with Sharp
      console.log('Processing image with Sharp...');
  
      // Get the output format from options (already defaulted to png earlier)
      const outputFormat = modelOptions.outputFormat;
      let mimeType: string;
  
      if (outputFormat === 'jpeg' || outputFormat === 'jpg') {
        mimeType = 'image/jpeg';
      } else if (outputFormat === 'webp') {
        mimeType = 'image/webp';
      } else {
        // Default to PNG
        mimeType = 'image/png';
      }
  
      // Process with Sharp and get buffer directly
      let sharpInstance = sharp(imageBuffer);
  
      // Apply format-specific options
      if (outputFormat === 'png') {
        sharpInstance = sharpInstance.png({ quality: 100 });
      } else if (outputFormat === 'jpeg' || outputFormat === 'jpg') {
        sharpInstance = sharpInstance.jpeg({ quality: 100 });
      } else if (outputFormat === 'webp') {
        sharpInstance = sharpInstance.webp({ quality: 100 });
      }
  
      // Get the processed image as a buffer
      const processedBuffer = await sharpInstance.toBuffer();
      console.log(`Image processed successfully, buffer size: ${processedBuffer.length} bytes`);
  
      // Determine the final filename with extension
      const fileExtension = outputFormat === 'jpeg' ? 'jpg' : outputFormat;
      const finalFileName = fileName.endsWith(`.${fileExtension}`) ? fileName : `${fileName}.${fileExtension}`;
  
      // No need to clean up files since we're keeping everything in memory
  
      // Get dimensions from the Sharp metadata
      const metadata = await sharpInstance.metadata();
      const dimensions = `${metadata.width}x${metadata.height}`;
  
      return {
        success: true,
        buffer: processedBuffer,
        mimeType,
        fileName: finalFileName,
        model: usingModel,
        dimensions
      };
    } catch (error: any) {
      console.error('Error generating or processing image:', error);
  
      // No need to clean up files since we're keeping everything in memory
  
      // Get the current default model for informational purposes
      const defaultModel = replicateClient.getDefaultModel();
      const usingModel = options.model || defaultModel;
  
      // Determine which step failed
      const errorStep = error.message.includes('Sharp') ? 'Image Processing' : 'Image Generation';
  
      return {
        success: false,
        error,
        errorResponse: formatErrorResponse(
          error,
          errorStep,
          {
            Prompt: prompt,
            Model: usingModel.split('/')[1],
            Step: errorStep
          },
          [
            'Check that your REPLICATE_API_TOKEN is valid',
            'Try a different model using set-model',
            'Try a more descriptive prompt',
            'Try a different aspect ratio',
            ...(errorStep === 'Image Processing' ? [
              'Make sure Sharp is properly installed'
            ] : [])
          ]
        )
      };
    }
  }

• src/replicate-client.ts:79-191 (helper)

  ReplicateClient.generateImage() - lower-level helper that converts camelCase options to snake_case, calls the Replicate API via defaultsManager.prepareModelInput, and handles various output types (URL strings, Buffer, Uint8Array, FileOutput objects).

  async generateImage(prompt: string, options: any = {}, modelId?: string): Promise<Buffer> {
    try {
      // Convert camelCase options to snake_case for the API
      const apiOptions: any = {};
  
      // Map common options
      if (options.aspectRatio) apiOptions.aspect_ratio = options.aspectRatio;
      if (options.width) apiOptions.width = options.width;
      if (options.height) apiOptions.height = options.height;
      if (options.seed !== undefined) apiOptions.seed = options.seed;
      if (options.numInferenceSteps) apiOptions.num_inference_steps = options.numInferenceSteps;
      if (options.guidanceScale) apiOptions.guidance_scale = options.guidanceScale;
      if (options.negativePrompt) apiOptions.negative_prompt = options.negativePrompt;
      // Always set output_format, defaulting to png unless explicitly specified
      apiOptions.output_format = options.outputFormat || "png";
      if (options.safetyTolerance !== undefined) apiOptions.safety_tolerance = options.safetyTolerance;
  
      // Map model-specific options
      if (options.promptUpsampling !== undefined) apiOptions.prompt_upsampling = options.promptUpsampling;
      if (options.outputQuality !== undefined) apiOptions.output_quality = options.outputQuality;
      if (options.raw !== undefined) apiOptions.raw = options.raw;
      if (options.imagePromptStrength !== undefined) apiOptions.image_prompt_strength = options.imagePromptStrength;
  
      // Use the defaults manager to prepare the input with merged options
      const mergedOptions = { ...options, ...apiOptions };
      const { modelId: selectedModelId, input } = this.defaultsManager.prepareModelInput(prompt, mergedOptions);
  
      console.log(`Using model: ${selectedModelId}`);
      console.log(`Input parameters: ${JSON.stringify(input, null, 2)}`);
  
      // Run the model using the Replicate client
      const output = await this.client.run(selectedModelId as any, { input });
  
      console.log('Replicate output type:', output ? (output.constructor ? output.constructor.name : typeof output) : 'null');
  
      // Handle different output types from Replicate
      let imageData: Buffer;
  
      if (output === null || output === undefined) {
        throw new Error('Replicate returned null or undefined output');
      } else if (typeof output === 'string') {
        // If output is a URL, download the image
        console.log('Replicate returned a string (URL):', output);
        const response = await axios.get(output, { responseType: 'arraybuffer' });
        imageData = Buffer.from(response.data);
      } else if (Buffer.isBuffer(output)) {
        // If output is already a Buffer
        console.log('Replicate returned a Buffer');
        imageData = output;
      } else if (output instanceof Uint8Array || output instanceof ArrayBuffer) {
        // If output is a Uint8Array or ArrayBuffer
        console.log('Replicate returned a Uint8Array or ArrayBuffer');
        imageData = Buffer.from(output);
      } else if (typeof output === 'object' && output !== null) {
        // If output is a FileOutput object or similar
        console.log('Replicate returned an object:', Object.keys(output));
  
        // Try to get the file content
        if ('file' in output && output.file) {
          console.log('Object has a file property');
          // Use type assertion to handle FileOutput object
          const fileContent = await (output.file as any).arrayBuffer();
          imageData = Buffer.from(fileContent);
        } else if ('arrayBuffer' in output && typeof output.arrayBuffer === 'function') {
          console.log('Object has an arrayBuffer method');
          // Use type assertion for the arrayBuffer method
          const arrayBuffer = await (output as any).arrayBuffer();
          imageData = Buffer.from(arrayBuffer);
        } else if ('blob' in output && typeof output.blob === 'function') {
          console.log('Object has a blob method');
          // Use type assertion for the blob method
          const blob = await (output as any).blob();
          const arrayBuffer = await (blob as any).arrayBuffer();
          imageData = Buffer.from(arrayBuffer);
        } else if ('text' in output && typeof output.text === 'function') {
          console.log('Object has a text method');
          // Use type assertion for the text method
          const text = await (output as any).text();
          // If the text is a URL, download the image
          if (text.startsWith('http')) {
            const response = await axios.get(text, { responseType: 'arraybuffer' });
            imageData = Buffer.from(response.data);
          } else {
            imageData = Buffer.from(text);
          }
        } else {
          // Last resort: try to stringify the object and see if it's a URL
          const str = output.toString();
          console.log('Object toString():', str);
          if (str.startsWith('http')) {
            const response = await axios.get(str, { responseType: 'arraybuffer' });
            imageData = Buffer.from(response.data);
          } else {
            throw new Error(`Unsupported Replicate output type: ${output.constructor ? output.constructor.name : typeof output}`);
          }
        }
      } else {
        throw new Error(`Unsupported Replicate output type: ${typeof output}`);
      }
  
      return imageData;
    } catch (error: any) {
      // Provide detailed error information
      const errorDetails = {
        message: error.message,
        prompt: prompt,
        options: JSON.stringify(options),
        modelId: modelId || this.getDefault('model')
      };
  
      throw new Error(`Replicate API error: ${error.message}\nDetails: ${JSON.stringify(errorDetails, null, 2)}`);
    }
  }

• src/model-manager.ts:169-230 (schema)

  DefaultsManager.prepareModelInput() - prepares and validates input parameters for the selected model (Flux 1.1 Pro or Pro Ultra), applying default values and mapping options to API parameters.

    prepareModelInput(prompt: string, options: any = {}): { modelId: string, input: any } {
      // Get the model to use (user-specified or default)
      const selectedModelId = options.model || this.defaults.model;
  
      // Set up the appropriate input parameters based on model
      let input: any = { prompt };
  
      // Apply defaults first, then override with user-specified options
      if (selectedModelId === "black-forest-labs/flux-1.1-pro-ultra") {
        // Ultra-specific parameters
        input.raw = options.raw !== undefined ? options.raw : this.defaults.raw;
  
        if (options.imagePromptStrength !== undefined) {
          input.image_prompt_strength = options.imagePromptStrength;
        }
      } else {
        // Pro-specific parameters
        input.prompt_upsampling = options.promptUpsampling !== undefined ?
          options.promptUpsampling : this.defaults.promptUpsampling;
  
        input.output_quality = options.outputQuality !== undefined ?
          options.outputQuality : this.defaults.outputQuality;
      }
  
      // Common parameters for both models - apply defaults then override with options
  
      // Handle aspect ratio or dimensions - only set one or the other, never both
      if (options.aspectRatio) {
        // If aspect ratio is explicitly provided, use it and don't set width/height
        input.aspect_ratio = options.aspectRatio;
      } else if (options.width && options.height) {
        // If width and height are explicitly provided, use them and don't set aspect ratio
        input.width = options.width;
        input.height = options.height;
      } else if (this.defaults.aspectRatio) {
        // If no explicit dimensions are provided but we have a default aspect ratio, use it
        input.aspect_ratio = this.defaults.aspectRatio;
      } else if (this.defaults.width && this.defaults.height) {
        // Last resort: use default width and height if they exist
        input.width = this.defaults.width;
        input.height = this.defaults.height;
      } else {
        // Absolute fallback: use 1:1 aspect ratio
        input.aspect_ratio = "1:1";
      }
  
      // Other common parameters
      if (options.seed !== undefined) input.seed = options.seed;
  
      input.num_inference_steps = options.numInferenceSteps || this.defaults.numInferenceSteps;
      input.guidance_scale = options.guidanceScale || this.defaults.guidanceScale;
      input.negative_prompt = options.negativePrompt || this.defaults.negativePrompt;
  
      // Always set output_format, defaulting to png unless explicitly specified
      input.output_format = options.outputFormat || this.defaults.outputFormat;
  
      input.safety_tolerance = options.safetyTolerance !== undefined ?
        options.safetyTolerance : this.defaults.safetyTolerance;
  
      return { modelId: selectedModelId, input };
    }
  }

• src/utils/error-handler.ts:80-106 (helper)

  formatSuccessResponse() - helper used by the generate_image handler to format successful responses with title, data key-value pairs, and additional text.

  export function formatSuccessResponse(
    title: string,
    data: Record<string, any> = {},
    additionalText: string = ''
  ) {
    let text = `✅ **${title}**\n\n`;
    
    // Add data information
    Object.entries(data).forEach(([key, value]) => {
      if (typeof value === 'string' && value.includes('"')) {
        text += `- **${key}**: ${value}\n`;
      } else if (typeof value === 'object') {
        text += `- **${key}**: ${JSON.stringify(value)}\n`;
      } else {
        text += `- **${key}**: "${value}"\n`;
      }
    });
    
    // Add additional text if provided
    if (additionalText) {
      text += `\n${additionalText}`;
    }
    
    return {
      content: [{ type: "text", text }]
    };
  }