generate_image

Instructions

Implementation Reference

• src/index.ts:222-284 (handler)

  Main handler for the generate_image tool: parses input schema, calls fal.subscribe to generate images using the specified model and parameters, optionally downloads images locally using downloadImage helper, formats a detailed text response with image URLs and local paths.

  case "generate_image": {
    const params = GenerateImageSchema.parse(args);
    const result = await fal.subscribe(params.model, {
      input: {
        prompt: params.prompt,
        image_size: params.image_size,
        num_images: params.num_images,
        ...(params.seed && { seed: params.seed }),
      },
      logs: true,
      onQueueUpdate: (update: any) => {
        console.error(`Queue position: ${update.position || "processing"}`);
      },
    });
  
    // Format the response nicely
    const images = (result as any).images || [];
    let responseText = `✅ Generated ${images.length} image(s) successfully!\n\n`;
    
    // Download images locally if requested
    const downloadedPaths: string[] = [];
    const shouldDownload = params.download_images !== false;
    
    for (let idx = 0; idx < images.length; idx++) {
      const img = images[idx];
      responseText += `Image ${idx + 1}:\n`;
      
      if (shouldDownload) {
        try {
          const localPath = await downloadImage(img.url);
          downloadedPaths.push(localPath);
          responseText += `📁 Saved to: ${localPath}\n`;
        } catch (error: any) {
          responseText += `⚠️ Download failed: ${error.message}\n`;
        }
      }
      
      responseText += `🌐 URL: ${img.url}\n`;
      if (img.width && img.height) {
        responseText += `📐 Size: ${img.width}x${img.height}\n`;
      }
      responseText += `\n`;
    }
    
    if ((result as any).seed) {
      responseText += `🎲 Seed: ${(result as any).seed}\n`;
    }
    
    if (downloadedPaths.length > 0) {
      responseText += `\n📂 Images saved to: ${path.join(process.cwd(), "fal-images")}/\n`;
    } else if (shouldDownload && images.length > 0) {
      responseText += `\n💡 Tip: Images URLs are temporary. Save them soon if needed.\n`;
    }
    
    return {
      content: [
        {
          type: "text",
          text: responseText,
        },
      ],
    };
  }

• src/index.ts:62-69 (schema)

  Zod schema defining input parameters for generate_image tool, used for validation in the handler.

  const GenerateImageSchema = z.object({
    prompt: z.string().describe("Text description of the image to generate"),
    model: z.string().default("fal-ai/flux/schnell").describe("Model to use for generation"),
    image_size: z.enum(["square", "landscape_4_3", "portrait_3_4"]).default("landscape_4_3").optional(),
    num_images: z.number().min(1).max(4).default(1).optional(),
    seed: z.number().optional(),
    download_images: z.boolean().default(true).optional().describe("Whether to download images locally"),
  });

• src/index.ts:104-137 (registration)

  Tool registration in the ListToolsRequestHandler response, defining name, description, and JSON inputSchema matching the Zod schema.

  {
    name: "generate_image",
    description: "Generate an image using Fal.ai models like Flux or Stable Diffusion",
    inputSchema: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description: "Text description of the image to generate",
        },
        model: {
          type: "string",
          description: "Model to use (default: fal-ai/flux/schnell)",
          default: "fal-ai/flux/schnell",
        },
        image_size: {
          type: "string",
          enum: ["square", "landscape_4_3", "portrait_3_4"],
          description: "Image size preset",
          default: "landscape_4_3",
        },
        num_images: {
          type: "number",
          description: "Number of images to generate (1-4)",
          default: 1,
        },
        seed: {
          type: "number",
          description: "Seed for reproducible generation",
        },
      },
      required: ["prompt"],
    },
  },

• src/index.ts:19-51 (helper)

  Helper function to download generated image from URL to local fal-images directory, used optionally in the generate_image handler.

  async function downloadImage(url: string, outputDir: string = process.cwd()): Promise<string> {
    try {
      // Create images directory if it doesn't exist
      const imagesDir = path.join(outputDir, "fal-images");
      if (!fs.existsSync(imagesDir)) {
        fs.mkdirSync(imagesDir, { recursive: true });
      }
      
      // Generate filename from URL or timestamp
      const urlParts = url.split("/");
      const originalName = urlParts[urlParts.length - 1];
      const timestamp = new Date().getTime();
      const filename = `${timestamp}-${originalName}`;
      const filepath = path.join(imagesDir, filename);
      
      // Download the image using buffer approach
      const response = await fetch(url);
      if (!response.ok) throw new Error(`Failed to download: ${response.statusText}`);
      
      const buffer = await response.buffer();
      fs.writeFileSync(filepath, buffer);
      
      // Verify the file was created
      if (!fs.existsSync(filepath)) {
        throw new Error("File was not created successfully");
      }
      
      return filepath;
    } catch (error) {
      console.error(`Failed to download image: ${error}`);
      throw error;
    }
  }