Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
755 lines (653 loc) · 14.7 KB

API_DOCUMENTATION.md

File metadata and controls

755 lines (653 loc) · 14.7 KB
Raw

Vahini Book Builder - API Documentation

Overview

This document describes the Flask API endpoints for the Vahini Book Builder application, including the new multi-model image generation, printing options, and courier integration features.

Base URL

http://localhost:5000

Authentication

Currently using session-based authentication. API keys can be added for programmatic access.

Response Format

All API responses are JSON with the following standard format:

Success Response

{
  "success": true,
  "data": {...},
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": "Error description",
  "error_code": "ERROR_CODE",
  "timestamp": "2024-01-15T10:30:00Z"
}

Image Generation API

GET /api/image-models

Get list of available image generation models.

Response:

{
  "success": true,
  "data": {
    "models": [
      {
        "code": "dalle-3",
        "name": "DALL-E 3",
        "provider": "OpenAI",
        "description": "Advanced image generation by OpenAI",
        "capabilities": ["High-quality image generation", "..."],
        "pricing": "Per image - Standard: $0.04, HD: $0.08",
        "best_for": ["detailed illustrations", "..."],
        "requires_api_key": true,
        "api_key_env": "OPENAI_API_KEY"
      },
      {
        "code": "gpt4-vision",
        "name": "GPT-4 Vision",
        "provider": "OpenAI",
        "description": "Advanced language model with vision capabilities",
        ...
      }
    ]
  }
}

POST /api/generate-image

Generate an image from a text prompt.

Request Body:

{
  "prompt": "A cute cartoon turtle learning to write alphabet",
  "model": "dalle-3",
  "size": "1024x1024",
  "quality": "standard",
  "style": "natural"
}

Parameters:

  • prompt (required): Text description of image
  • model (optional): Image model to use (default: "mock")
    • Options: dalle-3, gpt4-vision, stable-diffusion, midjourney, mock
  • size (optional): Image size (DALL-E 3)
    • Options: 1024x1024, 1792x1024, 1024x1792
  • quality (optional): Image quality (DALL-E 3)
    • Options: standard, hd
  • style (optional): Image style (DALL-E 3)
    • Options: natural, vivid

Response (DALL-E 3):

{
  "success": true,
  "data": {
    "model": "dalle-3",
    "image_url": "https://oaidalleapiprodscus.blob.core.windows.net/...",
    "revised_prompt": "A cute cartoon turtle in a classroom setting...",
    "size": "1024x1024",
    "quality": "standard",
    "style": "natural",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Response (Mock):

{
  "success": true,
  "data": {
    "model": "mock",
    "image_url": "https://via.placeholder.com/1024x1024",
    "prompt": "A cute cartoon turtle learning to write alphabet",
    "created_at": "2024-01-15T10:30:00Z",
    "note": "This is a mock image for testing purposes"
  }
}

Printing Options API

GET /api/printing-options

Get all available printing options.

Response:

{
  "success": true,
  "data": {
    "paper_types": [
      {
        "code": "standard",
        "name": "Standard White",
        "gsm": 80,
        "description": "80 GSM white paper - economical choice",
        "price_per_page": 2.0,
        "finish": "matte"
      },
      {
        "code": "glossy",
        "name": "Glossy Coated",
        "gsm": 135,
        "description": "135 GSM glossy coated paper",
        "price_per_page": 5.0,
        "finish": "glossy"
      }
    ],
    "paper_sizes": [
      {
        "code": "a4",
        "name": "A4",
        "description": "Standard Letter Size (210x297mm)",
        "width_mm": 210,
        "height_mm": 297,
        "multiplier": 1.0
      }
    ],
    "print_colors": [
      {
        "code": "bw",
        "name": "Black & White",
        "description": "Black and white printing",
        "price_per_page": 1.0
      },
      {
        "code": "color",
        "name": "Full Color",
        "description": "Full color CMYK printing",
        "price_per_page": 4.0
      }
    ],
    "binding_options": [
      {
        "code": "perfect",
        "name": "Perfect Binding",
        "description": "Professional glued spine",
        "price": 50,
        "min_pages": 20,
        "durability": "medium"
      }
    ],
    "cover_options": [
      {
        "code": "standard",
        "name": "Standard Cover",
        "description": "Same paper as pages",
        "price": 20
      }
    ]
  }
}

POST /api/calculate-printing-cost

Calculate printing cost for given options.

Request Body:

{
  "num_pages": 48,
  "copies": 10,
  "paper_type": "glossy",
  "paper_size": "a4",
  "print_color": "color",
  "binding_type": "perfect",
  "cover_type": "premium"
}

Parameters:

  • num_pages (required): Number of pages
  • copies (required): Number of copies
  • paper_type (optional): Paper type code (default: "standard")
  • paper_size (optional): Paper size code (default: "a4")
  • print_color (optional): Print color code (default: "bw")
  • binding_type (optional): Binding type code (default: "perfect")
  • cover_type (optional): Cover type code (default: "standard")

Response:

{
  "success": true,
  "data": {
    "num_pages": 48,
    "copies": 10,
    "options": {
      "paper": {
        "type": "glossy",
        "name": "Glossy Coated",
        "size": "a4"
      },
      "color": {
        "type": "color",
        "name": "Full Color"
      },
      "binding": {
        "type": "perfect",
        "name": "Perfect Binding"
      },
      "cover": {
        "type": "premium",
        "name": "Premium Cover"
      }
    },
    "cost_breakdown": {
      "pages": 2400.00,
      "binding": 52.50,
      "cover": 84.00,
      "per_book": 2536.50
    },
    "totals": {
      "subtotal": 25365.00,
      "discount_percent": 10,
      "discount_amount": 2536.50,
      "total": 22828.50,
      "currency": "INR"
    },
    "per_copy_cost": 2282.85
  }
}

Courier Service API

GET /api/couriers

Get list of all available courier services.

Response:

{
  "success": true,
  "data": {
    "couriers": [
      {
        "code": "delhivery",
        "name": "Delhivery",
        "full_name": "Delhivery Limited",
        "website": "https://www.delhivery.com",
        "features": ["tracking", "insurance", "cod"],
        "weight_limit": 25
      },
      {
        "code": "dtdc",
        "name": "DTDC",
        "full_name": "Day Tagg Courier Services",
        "website": "https://www.dtdc.in",
        "features": ["tracking", "insurance", "cod"],
        "weight_limit": 25
      }
    ]
  }
}

GET /api/couriers/:code

Get detailed information for a specific courier.

Parameters:

  • code (path): Courier code (e.g., "delhivery")

Response:

{
  "success": true,
  "data": {
    "name": "Delhivery",
    "full_name": "Delhivery Limited",
    "website": "https://www.delhivery.com",
    "base_rate": 40,
    "per_kg": 18,
    "weight_limit": 25,
    "regions": {
      "metro": {
        "multiplier": 1.0,
        "delivery_days": "1-2"
      },
      "tier1": {
        "multiplier": 1.15,
        "delivery_days": "2-3"
      }
    },
    "features": ["tracking", "insurance", "cod"]
  }
}

POST /api/calculate-shipping

Calculate shipping cost for given parameters.

Request Body:

{
  "weight_kg": 0.35,
  "destination_city": "Mumbai",
  "courier_name": "delhivery",
  "quantity": 10
}

Parameters:

  • weight_kg (required): Weight in kilograms
  • destination_city (required): Destination city name
  • courier_name (required): Courier service code
  • quantity (optional): Number of packages (default: 1)

Response:

{
  "success": true,
  "data": {
    "courier": "delhivery",
    "courier_name": "Delhivery",
    "weight_kg": 0.35,
    "quantity": 10,
    "region": "metro",
    "delivery_days": "1-2",
    "base_cost": 40,
    "per_kg_cost": 6.3,
    "region_multiplier": 1.0,
    "subtotal": 46.3,
    "gst": 2.32,
    "total": 48.62,
    "currency": "INR",
    "features": "tracking, insurance, cod"
  }
}

POST /api/compare-couriers

Compare shipping costs across all couriers.

Request Body:

{
  "weight_kg": 0.35,
  "destination_city": "Delhi",
  "quantity": 5
}

Response:

{
  "success": true,
  "data": [
    {
      "courier": "shiprocket",
      "courier_name": "Shiprocket",
      "total": 35.00,
      "delivery_days": "2-3",
      "estimated_delivery": "2024-01-17"
    },
    {
      "courier": "delhivery",
      "courier_name": "Delhivery",
      "total": 40.00,
      "delivery_days": "1-2",
      "estimated_delivery": "2024-01-16"
    }
  ]
}

GET /api/delivery-estimate

Get estimated delivery time for a destination.

Parameters:

  • city (query): Destination city
  • courier (query): Courier code

Response:

{
  "success": true,
  "data": {
    "courier": "delhivery",
    "destination": "Bangalore",
    "min_days": 2,
    "max_days": 3,
    "estimated_delivery_start": "2024-01-17",
    "estimated_delivery_end": "2024-01-18",
    "delivery_range": "2-3"
  }
}

POST /api/estimate-book-weight

Estimate the weight of a printed book.

Request Body:

{
  "num_pages": 48,
  "paper_type": "glossy"
}

Response:

{
  "success": true,
  "data": {
    "num_pages": 48,
    "paper_type": "glossy",
    "estimated_weight_kg": 0.35,
    "breakdown": {
      "pages_weight_grams": 360,
      "cover_weight_grams": 15,
      "binding_weight_grams": 5,
      "total_weight_grams": 380
    }
  }
}

Prompt Generation API

GET /api/prompt-templates

Get available prompt templates for books.

Response:

{
  "success": true,
  "data": {
    "book_types": [
      {
        "code": "pre_writing",
        "name": "Pre-Writing Skills",
        "description": "Fine motor development for writing",
        "age_range": "3-5",
        "pages": 48,
        "stages": 6
      },
      {
        "code": "coloring",
        "name": "Coloring Book",
        "description": "Color recognition and creativity",
        "age_range": "2-7",
        "pages": 40
      }
    ],
    "stages": [
      {
        "stage": 1,
        "name": "Straight Lines",
        "age_range": "3-3.5",
        "patterns": ["vertical", "horizontal", "diagonal"]
      }
    ],
    "characters": 15,
    "coloring_themes": 12
  }
}

POST /api/generate-worksheet-prompt

Generate a worksheet prompt for fine motor skills.

Request Body:

{
  "stage": 3,
  "pattern_index": 1,
  "character_index": 5,
  "num_pages": 10
}

Response:

{
  "success": true,
  "data": {
    "prompt": "Create 10 educational worksheet pages for fine motor skill development...",
    "stage": 3,
    "stage_name": "Wavy Lines",
    "character": "Rabbit",
    "pattern": "curved_waves",
    "design_specs": {
      "page_size": "A4",
      "margins": "2cm",
      "dpi": 300,
      "color_space": "CMYK"
    }
  }
}

POST /api/generate-coloring-prompt

Generate a coloring page prompt.

Request Body:

{
  "theme_index": 2,
  "color_index": 3,
  "num_pages": 10
}

Response:

{
  "success": true,
  "data": {
    "prompt": "Create 10 coloring pages with the Cat and Mouse theme...",
    "theme": "Cat and Mouse Adventures",
    "color_palette": "Ocean Blues and Greens",
    "layout": {
      "top_zone": "Colored reference image",
      "middle_zone": "B&W coloring subject",
      "bottom_zone": "Color palette guide"
    },
    "design_specs": {
      "page_size": "A4",
      "margins": "1.5cm",
      "dpi": 300,
      "color_space": "CMYK"
    }
  }
}

Combined Order API

POST /api/create-order

Create a complete book order with all options.

Request Body:

{
  "title": "Fine Motor Skills Book",
  "description": "Educational workbook for children",
  "age_range": "4-5",
  "num_pages": 48,
  "copies": 10,
  "book_type": "pre_writing",
  "image_model": "dalle-3",
  "printing_options": {
    "paper_type": "glossy",
    "paper_size": "a4",
    "print_color": "color",
    "binding_type": "perfect",
    "cover_type": "premium"
  },
  "shipping": {
    "courier": "delhivery",
    "destination_city": "Mumbai"
  }
}

Response:

{
  "success": true,
  "data": {
    "order_id": "ORD-2024-001",
    "status": "pending",
    "summary": {
      "title": "Fine Motor Skills Book",
      "copies": 10,
      "pages_per_copy": 48
    },
    "costs": {
      "printing": {
        "subtotal": 25365.00,
        "discount": 2536.50,
        "total": 22828.50
      },
      "shipping": {
        "weight_kg": 3.5,
        "cost": 48.62
      },
      "grand_total": 22877.12
    },
    "estimated_delivery": {
      "courier": "Delhivery",
      "estimated_date": "2024-01-18",
      "delivery_range": "1-2 days"
    }
  }
}

Error Codes

Code Status Description
INVALID_PARAM 400 Invalid request parameter
MISSING_PARAM 400 Required parameter missing
NOT_FOUND 404 Resource not found
API_KEY_MISSING 401 API key not configured
API_ERROR 500 External API error
DATABASE_ERROR 500 Database operation failed
CALCULATION_ERROR 500 Calculation failed

Rate Limiting

Currently no rate limiting is implemented. In production, implement:

  • 100 requests per minute per IP for public endpoints
  • 1000 requests per minute per API key for authenticated endpoints
  • 10 concurrent image generation requests

Examples

Complete Order Creation Flow

# 1. Get available options
curl http://localhost:5000/api/printing-options

# 2. Calculate printing cost
curl -X POST http://localhost:5000/api/calculate-printing-cost \
  -H "Content-Type: application/json" \
  -d '{
    "num_pages": 48,
    "copies": 10,
    "paper_type": "glossy",
    "print_color": "color",
    "binding_type": "perfect"
  }'

# 3. Compare couriers
curl -X POST http://localhost:5000/api/compare-couriers \
  -H "Content-Type: application/json" \
  -d '{
    "weight_kg": 0.35,
    "destination_city": "Mumbai",
    "quantity": 10
  }'

# 4. Generate image
curl -X POST http://localhost:5000/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cute cartoon turtle learning to write",
    "model": "dalle-3"
  }'

# 5. Create order
curl -X POST http://localhost:5000/api/create-order \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fine Motor Skills Book",
    "copies": 10,
    "book_type": "pre_writing",
    "printing_options": {...},
    "shipping": {...}
  }'

Version History

  • v1.0.0 (2024-01-15): Initial release with multi-model image generation, courier integration, and enhanced printing options