generate_image

Instructions

Implementation Reference

• src/tools/generateImageHandler.ts:5-69 (handler)

  Main handler function for the 'generate_image' MCP tool. Validates input, constructs Ideogram API parameters, invokes the client, and formats the response with image URLs and file paths.

  export async function generateImageHandler(ideogramClient: IdeogramClient, args: any) {
    if (!args || typeof args.prompt !== "string") {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Prompt is required and must be a string"
      );
    }
  
    // 保存先ディレクトリとファイル名のデフォルト設定
    const outputDir = typeof args.output_dir === "string" && args.output_dir.trim() !== ""
      ? args.output_dir
      : "docs";
    const baseFilename = typeof args.base_filename === "string" && args.base_filename.trim() !== ""
      ? args.base_filename
      : "ideogram-image";
  
    const params: IdeogramGenerateParams = {
      prompt: args.prompt,
      aspect_ratio: typeof args.aspect_ratio === "string" ? args.aspect_ratio : undefined,
      resolution: typeof args.resolution === "string" ? args.resolution : undefined,
      seed: typeof args.seed === "number" ? args.seed : undefined,
      magic_prompt: typeof args.magic_prompt === "string" && ["AUTO", "ON", "OFF"].includes(args.magic_prompt)
        ? args.magic_prompt as IdeogramGenerateParams["magic_prompt"]
        : undefined,
      rendering_speed: typeof args.rendering_speed === "string" && ["TURBO", "DEFAULT", "QUALITY"].includes(args.rendering_speed)
        ? args.rendering_speed as IdeogramGenerateParams["rendering_speed"]
        : undefined,
      style_codes: Array.isArray(args.style_codes) ? args.style_codes : undefined,
      style_type: typeof args.style_type === "string" ? args.style_type : undefined,
      negative_prompt: typeof args.negative_prompt === "string" ? args.negative_prompt : undefined,
      num_images: typeof args.num_images === "number" ? args.num_images : undefined,
    };
  
    // Ideogram 3.0用のスタイルリファレンス機能
    if (args.style_reference && typeof args.style_reference === "object") {
      const styleRef: IdeogramStyleReference = {};
      const styleRefObj = args.style_reference as any;
      if (styleRefObj.urls && Array.isArray(styleRefObj.urls)) {
        styleRef.urls = styleRefObj.urls.slice(0, 3);
      }
      if (typeof styleRefObj.style_code === "string") {
        styleRef.style_code = styleRefObj.style_code;
      }
      if (typeof styleRefObj.random_style === "boolean") {
        styleRef.random_style = styleRefObj.random_style;
      }
      params.style_reference = styleRef;
    }
  
    // blur_maskオプション受け取り
    const blurMask = args.blur_mask === true;
  
    const response = await ideogramClient.generateImage(params, outputDir, baseFilename, blurMask);
  
    return {
      content: [
        {
          type: "text",
          text: `Generated ${response.data.length} image(s):\n${response.data
            .map((img) => `URL: ${img.url}\nSaved to: ${(img.filepath ?? "").replace(/\\/g, "/")}`)
            .join("\n\n")}`
        }
      ]
    };
  }

• src/tools/generateImageSchema.ts:1-98 (schema)

  Input schema (JSON Schema) defining parameters for the generate_image tool, including prompt, aspect_ratio, style options, etc.

  export const generateImageInputSchema = {
    type: "object",
    properties: {
      prompt: {
        type: "string",
        description: "The prompt to use for generating the image (must be in English)"
      },
      aspect_ratio: {
        type: "string",
        description: "The aspect ratio for the generated image (see official docs for all 15 values)",
        enum: [
          "1x1", "4x3", "3x4", "16x9", "9x16",
          "2x3", "3x2", "5x4", "4x5", "21x9",
          "9x21", "3x1", "1x3", "2x1", "1x2"
        ]
      },
      resolution: {
        type: "string",
        description: "The resolution for the generated image (see official docs for all 69 values)",
      },
      seed: {
        type: "integer",
        description: "Random seed. Set for reproducible generation.",
        minimum: 0,
        maximum: 2147483647
      },
      magic_prompt: {
        type: "string",
        description: "Whether to use magic prompt",
        enum: ["AUTO", "ON", "OFF"]
      },
      rendering_speed: {
        type: "string",
        description: "Rendering speed for v3 (TURBO/DEFAULT/QUALITY)",
        enum: ["TURBO", "DEFAULT", "QUALITY"]
      },
      style_codes: {
        type: "array",
        description: "Array of 8-char style codes",
        items: { type: "string" }
      },
      style_type: {
        type: "string",
        description: "The style type for generation",
        enum: ["AUTO", "GENERAL", "REALISTIC", "DESIGN"]
      },
      style_reference_images: {
        type: "array",
        description: "A set of images to use as style references (max 10MB, JPEG/PNG/WebP)",
        items: { type: "string", format: "binary" }
      },
      negative_prompt: {
        type: "string",
        description: "Description of what to exclude from the image (must be in English)"
      },
      num_images: {
        type: "number",
        description: "Number of images to generate (1-8)",
        minimum: 1,
        maximum: 8
      },
      style_reference: {
        type: "object",
        description: "Style reference options for Ideogram 3.0",
        properties: {
          urls: {
            type: "array",
            description: "URLs to reference images for style (max 3)",
            items: {
              type: "string"
            },
            maxItems: 3
          },
          style_code: {
            type: "string",
            description: "Style code to apply (alternative to URLs)"
          },
          random_style: {
            type: "boolean",
            description: "Whether to use a random style from Ideogram's library"
          }
        }
      },
      output_dir: {
        type: "string",
        description: "Directory to save generated images (default: 'docs')."
      },
      base_filename: {
        type: "string",
        description: "Base filename for saved images (default: 'ideogram-image'). Timestamp and image ID will be appended automatically."
      },
      blur_mask: {
        type: "boolean",
        description: "Apply a blurred mask to the image edges (using a fixed mask image). If true, the output image will have blurred/feathered edges. (default: false)"
      }
    },
    required: ["prompt"]
  };

• src/server.ts:28-38 (registration)

  Registers the 'generate_image' tool in the MCP ListTools response, providing name, description, and input schema.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "generate_image",
          description: "Generate an image using Ideogram AI",
          inputSchema: generateImageInputSchema
        }
      ]
    };
  });

• src/server.ts:40-47 (registration)

  Dispatches MCP CallTool requests for 'generate_image' to the generateImageHandler function.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    switch (request.params.name) {
      case "generate_image":
        return await generateImageHandler(ideogramClient, request.params.arguments);
      default:
        throw new McpError(ErrorCode.MethodNotFound, "Unknown tool");
    }
  });

• src/ideogram-client.ts:27-147 (helper)

  Core IdeogramClient.generateImage method called by the handler; handles API call, image download, optional blurring, and local saving.

  async generateImage(
    params: IdeogramGenerateParams,
    outputDir?: string,
    baseFilename?: string,
    blurMask?: boolean
  ): Promise<IdeogramResponse> {
     // デフォルト値を補完（未指定なら 1x1）
     if (!params.aspect_ratio) {
       params.aspect_ratio = '1x1';
     }
     // MagicPrompt 統合 & デフォルト AUTO
     if (params.magic_prompt_option && !params.magic_prompt) {
       params.magic_prompt = params.magic_prompt_option;
       delete (params as any).magic_prompt_option;
     }
     if (!params.magic_prompt) {
       params.magic_prompt = 'AUTO';
     }
  
     // v3: rendering_speed を優先。model が指定されている場合は後方互換マッピング
     let rendering_speed: 'TURBO' | 'DEFAULT' | 'QUALITY' = params.rendering_speed ?? 'DEFAULT';
     if (params.model) {
       switch (params.model) {
         case 'V_3_TURBO':
         case 'V_2_TURBO':
         case 'V_1_TURBO':
           rendering_speed = 'TURBO';
           break;
         case 'V_3_QUALITY':
           rendering_speed = 'QUALITY';
           break;
         // V_3, V_2, V_1 などは DEFAULT
         default:
           rendering_speed = 'DEFAULT';
       }
       // API には model を送らない
       delete (params as any).model;
     }
     // request payload に rendering_speed を明示
     (params as any).rendering_speed = rendering_speed;
     // クライアント内で model / rendering_speed の重複を排除
     delete (params as any).model;
     delete (params as any).rendering_speed_option; // 念のため
  
     try {
       // 参照画像がURLとして提供されている場合
       let formData: any = undefined;
      let requestConfig: any = {
        headers: {
          'Api-Key': this.apiKey,
          'Content-Type': 'application/json',
        },
      };
      
      // style_referenceでurlsが指定されている場合はマルチパートフォームデータを使用
      if (params.style_reference?.urls && params.style_reference.urls.length > 0) {
        formData = new FormData();
        
        // 参照画像をダウンロードしてFormDataに追加
        for (let i = 0; i < params.style_reference.urls.length; i++) {
          const url = params.style_reference.urls[i];
          try {
            const response = await axios.get(url, { responseType: 'arraybuffer' });
            const buffer = Buffer.from(response.data, 'binary');
            formData.append(`reference_image_${i+1}`, buffer, `reference_${i+1}.jpg`);
          } catch (error) {
            console.error(`Failed to download reference image from ${url}:`, error);
          }
        }
        
        // その他のパラメータをJSON文字列としてFormDataに追加
        const paramsWithoutStyleReferenceUrls = {
          ...params,
          style_reference: {
            ...params.style_reference,
            urls: undefined // URLsを無効化して重複を避ける
          }
        };
        formData.append('image_request', JSON.stringify(paramsWithoutStyleReferenceUrls));
        
        // FormDataを使用するためのヘッダー設定
        requestConfig.headers['Content-Type'] = 'multipart/form-data';
      }
      
      // 通常のJSONリクエストまたはFormDataリクエストを送信
      const response = await axios.post(
        `${this.baseUrl}/v1/ideogram-v3/generate`,
        formData || params,
        requestConfig
      );
  
      // 画像を自動保存
      const downloadPromises = response.data.data.map(async (img: { url: string; id: string }) => {
        const filepath = await downloadAndBlurMaskImage(
          img.url,
          img.id,
          outputDir,
          baseFilename,
          blurMask // 追加
        );
        return { ...img, filepath };
      });
  
      const updatedData = await Promise.all(downloadPromises);
      response.data.data = updatedData;
  
      const result: IdeogramResponse = {
        ...response.data,
        request: { ...params }
      };
      return result;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const detail = typeof error.response?.data === 'string'
          ? error.response.data
          : JSON.stringify(error.response?.data, null, 2);
        throw new Error(`Ideogram API error (${error.response?.status}): ${detail || error.message}`);
      }
      throw error;
    }
  }