fetch-model-schemas.js

#!/usr/bin/env node

/**
 * Fetch FAL model schemas from OpenAPI and generate config files
 * Uses FAL's OpenAPI endpoint to get accurate parameter definitions
 */

import fs from 'fs-extra';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Models to fetch schemas for
const MODELS_TO_FETCH = [
  // Original models that need schema updates
  {
    id: 'fal-ai/flux-pro/kontext/max/text-to-image',
    name: 'FLUX Pro Kontext Max',
    category: 'Professional',
    costPerImage: 0.08,
    description: 'Advanced FLUX model with maximum context understanding',
    modelKey: 'flux-kontext-max'
  },
  {
    id: 'fal-ai/flux-pro/kontext/text-to-image',
    name: 'FLUX Pro Kontext',
    category: 'Professional',
    costPerImage: 0.04,
    description: 'Professional FLUX model with enhanced context understanding',
    modelKey: 'flux-kontext-pro'
  },
  {
    id: 'fal-ai/flux-pro/v1.1-ultra',
    name: 'FLUX Pro Ultra v1.1',
    category: 'Ultra Quality',
    costPerImage: 0.06,
    description: 'Latest FLUX Pro model with ultra-high quality output',
    modelKey: 'flux-pro-ultra'
  },
  {
    id: 'fal-ai/imagen4/preview/ultra',
    name: 'Imagen 4 Ultra (Preview)',
    category: 'Ultra Quality',
    costPerImage: 0.06,
    description: "Google's latest high-quality image generation model",
    modelKey: 'imagen4-ultra'
  },
  {
    id: 'fal-ai/qwen-image',
    name: 'Qwen Image',
    category: 'General Purpose',
    costPerImage: 0.05,
    description: 'High-quality text-to-image model with excellent text rendering',
    modelKey: 'qwen-image'
  },
  // New models added
  {
    id: 'fal-ai/gemini-25-flash-image',
    name: 'Gemini 2.5 Flash Image',
    category: 'Advanced',
    costPerImage: 0.03,
    description: 'Google Gemini 2.5 Flash for fast image generation',
    modelKey: 'gemini-25-flash-image'
  },
  {
    id: 'fal-ai/gemini-25-flash-image/edit',
    name: 'Gemini 2.5 Flash Edit',
    category: 'Image Editing',
    costPerImage: 0.03,
    description: 'Google Gemini 2.5 Flash for image editing',
    isEditModel: true,
    modelKey: 'gemini-25-flash-edit'
  },
  {
    id: 'fal-ai/gemini-flash-edit',
    name: 'Gemini Flash Edit',
    category: 'Image Editing',
    costPerImage: 0.04,
    description: 'Edit images using Google Gemini with natural language',
    isEditModel: true,
    modelKey: 'gemini-flash-edit'
  },
  {
    id: 'fal-ai/flux-pro/kontext',
    name: 'FLUX Pro Kontext Edit',
    category: 'Image Editing',
    costPerImage: 0.05,
    description: 'FLUX Pro model for image-to-image transformation',
    isEditModel: true,
    modelKey: 'flux-pro-kontext-edit'
  },
  {
    id: 'fal-ai/nano-banana',
    name: 'Nano Banana',
    category: 'Advanced',
    costPerImage: 0.04,
    description: "Google's state-of-the-art image generation model",
    modelKey: 'nano-banana'
  },
  {
    id: 'fal-ai/nano-banana/edit',
    name: 'Nano Banana Edit',
    category: 'Image Editing',
    costPerImage: 0.04,
    description: "Google's state-of-the-art image editing model",
    isEditModel: true,
    modelKey: 'nano-banana-edit'
  },
  {
    id: 'fal-ai/ideogram/character/edit',
    name: 'Ideogram Character Edit',
    category: 'Image Editing',
    costPerImage: 0.05,
    description: 'Modify consistent characters while preserving core identity',
    isEditModel: true,
    modelKey: 'ideogram-character-edit'
  },
  {
    id: 'fal-ai/qwen-image-edit-plus',
    name: 'Qwen Image Edit Plus',
    category: 'Image Editing',
    costPerImage: 0.04,
    description: 'Advanced image editing with Qwen model',
    isEditModel: true,
    modelKey: 'qwen-image-edit-plus'
  }
];

async function fetchModelSchema(modelId) {
  const url = `https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=${modelId}`;

  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return await response.json();
  } catch (error) {
    console.error(`Failed to fetch schema for ${modelId}:`, error.message);
    return null;
  }
}

function extractParametersFromSchema(openApiSchema, modelInfo) {
  // Default structure
  const config = {
    id: modelInfo.id,
    name: modelInfo.name,
    description: modelInfo.description,
    category: modelInfo.category,
    costPerImage: modelInfo.costPerImage,
    type: modelInfo.isEditModel ? 'image-edit' : 'text-to-image',
    defaultParams: {},
    supportedAspectRatios: [],
    supportedFormats: ['jpeg', 'png'],
    maxImages: 4,
    parameters: {}
  };

  try {
    // Look for main endpoint path
    const paths = openApiSchema.paths || {};
    const mainPath = `/fal-ai/${modelInfo.id.replace('fal-ai/', '')}`;

    let inputSchema = null;

    // Try to find the input schema
    if (paths[mainPath]?.post?.requestBody?.content?.['application/json']?.schema) {
      const schema = paths[mainPath].post.requestBody.content['application/json'].schema;

      // Handle $ref to components
      if (schema.$ref) {
        const refName = schema.$ref.split('/').pop();
        if (openApiSchema.components?.schemas?.[refName]) {
          inputSchema = openApiSchema.components.schemas[refName];
        }
      } else {
        inputSchema = schema;
      }
    }

    // Fallback: look for input schema in components
    if (!inputSchema && openApiSchema.components?.schemas) {
      const inputSchemaName = Object.keys(openApiSchema.components.schemas).find(name =>
        name.toLowerCase().includes('input') || name.toLowerCase().includes('request')
      );
      if (inputSchemaName) {
        inputSchema = openApiSchema.components.schemas[inputSchemaName];
      }
    }

    // Parse the schema if found
    if (inputSchema) {
      const properties = inputSchema.properties || {};
      const required = inputSchema.required || [];

      // Extract parameters
      for (const [key, value] of Object.entries(properties)) {
        config.parameters[key] = {
          type: value.type,
          required: required.includes(key),
          description: value.description || '',
          default: value.default,
          enum: value.enum,
          minimum: value.minimum,
          maximum: value.maximum
        };

        // Set defaults
        if (value.default !== undefined) {
          config.defaultParams[key] = value.default;
        }

        // Extract enums for aspect ratios
        if (key === 'aspect_ratio' && value.enum) {
          config.supportedAspectRatios = value.enum;
        }

        // Extract supported formats
        if (key === 'output_format' && value.enum) {
          config.supportedFormats = value.enum;
        }

        // Extract max images
        if (key === 'num_images' && value.maximum) {
          config.maxImages = value.maximum;
        }
      }
    }

    // For edit models, ensure we have image_url parameter
    if (modelInfo.isEditModel) {
      config.parameters.image_url = {
        type: 'string',
        required: true,
        description: 'URL of the image to edit'
      };
      config.parameters.prompt = {
        type: 'string',
        required: true,
        description: 'Description of the edit to make'
      };
    }

    // Set reasonable defaults if not found
    if (!config.defaultParams.num_images) {
      config.defaultParams.num_images = 1;
    }

    if (config.supportedAspectRatios.length === 0) {
      config.supportedAspectRatios = ['1:1', '16:9', '9:16', '4:3', '3:4'];
    }

  } catch (error) {
    console.warn(`Warning: Could not fully parse schema for ${modelInfo.id}:`, error.message);
  }

  return config;
}

async function generateModelConfigs() {
  console.log('🔍 Fetching model schemas from FAL OpenAPI...\n');

  const modelsDir = path.join(__dirname, 'models');
  await fs.ensureDir(modelsDir);

  let successCount = 0;
  let failCount = 0;

  for (const modelInfo of MODELS_TO_FETCH) {
    console.log(`📥 Fetching schema for ${modelInfo.name}...`);

    const schema = await fetchModelSchema(modelInfo.id);

    if (schema) {
      const config = extractParametersFromSchema(schema, modelInfo);

      // Generate filename from model ID (or use custom key)
      const filename = (modelInfo.modelKey || modelInfo.id
        .replace('fal-ai/', '')
        .replace(/\//g, '-')
        .replace(/[^a-z0-9-]/gi, '-')
        .toLowerCase()) + '.json';

      const filepath = path.join(modelsDir, filename);

      // Add optimization prompt based on model type
      if (modelInfo.isEditModel) {
        config.optimization_system_prompt = `You are optimizing edit instructions for ${modelInfo.name}. This model excels at precise image modifications while preserving the original image's structure and quality. Focus on: 1) Clear, specific edit instructions that describe exactly what to change. 2) Preserve elements that should remain unchanged by explicitly mentioning what to keep. 3) Use directional and positional language for spatial edits. 4) For style changes, describe the target style in detail. Example: 'change color to red' → 'Change the car's color from blue to bright cherry red while preserving all reflections, shadows, and environmental lighting'`;
      } else {
        config.optimization_system_prompt = `You are optimizing prompts for ${modelInfo.name}. Focus on detailed visual descriptions, artistic style, composition, and technical aspects that enhance image quality. Be specific about lighting, colors, textures, and spatial relationships.`;
      }

      await fs.writeJson(filepath, config, { spaces: 2 });
      console.log(`✅ Created ${filename}`);
      successCount++;
    } else {
      console.log(`❌ Failed to fetch schema for ${modelInfo.id}`);

      // Create basic config anyway
      const filename = (modelInfo.modelKey || modelInfo.id
        .replace('fal-ai/', '')
        .replace(/\//g, '-')
        .replace(/[^a-z0-9-]/gi, '-')
        .toLowerCase()) + '.json';

      const basicConfig = {
        id: modelInfo.id,
        name: modelInfo.name,
        description: modelInfo.description,
        category: modelInfo.category,
        costPerImage: modelInfo.costPerImage,
        type: modelInfo.isEditModel ? 'image-edit' : 'text-to-image',
        defaultParams: {
          num_images: 1
        },
        supportedAspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
        supportedFormats: ['jpeg', 'png'],
        maxImages: modelInfo.isEditModel ? 1 : 4,
        parameters: modelInfo.isEditModel ? {
          prompt: { type: 'string', required: true },
          image_url: { type: 'string', required: true }
        } : {
          prompt: { type: 'string', required: true },
          num_images: { type: 'integer', required: false }
        }
      };

      const filepath = path.join(modelsDir, filename);
      await fs.writeJson(filepath, basicConfig, { spaces: 2 });
      console.log(`⚠️  Created basic config for ${filename} (schema fetch failed)`);
      failCount++;
    }
  }

  console.log(`\n✨ Done! Created ${successCount} configs from schemas, ${failCount} basic configs`);
  console.log(`📁 Model configs saved to: ${modelsDir}`);
}

// Run if called directly
if (import.meta.url === `file://${process.argv[1]}`) {
  generateModelConfigs().catch(console.error);
}

export { fetchModelSchema, extractParametersFromSchema, generateModelConfigs };