Vertical AI Model Providers Integration Guide

🎯 Introduction

Welcome to the SmartBe Vertical AI Models Integration Program! This guide is specifically for Vertical AI Model Providers who want to integrate their specialized medical AI models into the SmartBe platform.

About SmartBe Platform

SmartBe is a comprehensive health platform that connects users (our clients) with three types of providers:

• Vertical AI Model Providers (this guide): Specialized AI models for medical tasks like analyzing MRI scans, interpreting ECG readings, or detecting diseases from pathology images
• Medical Advisors: Licensed medical professionals who provide consultations and expert health guidance
• Caregivers: Dedicated care providers who offer daily health support, medication management, and personalized assistance

What is a Vertical AI Model Provider?

A Vertical AI Model Provider is an organization or individual that offers specialized artificial intelligence models designed for specific medical tasks, such as analyzing MRI scans, interpreting ECG readings, or detecting diseases from pathology images. These models are accessed programmatically via API endpoints.

Benefits of Integration

• Increased Reach: Access to SmartBe's growing user base
• Automated Discovery: SmartBe's system automatically selects the best model for each user's specific health needs
• Performance Tracking: Real-time metrics on usage, success rate, and response time
• Revenue Opportunities: Monetize your AI models through our platform
• Platform Integration: Seamlessly integrate with other providers (medical advisors and caregivers) to offer comprehensive health solutions

✅ Prerequisites

Before you begin, ensure you have:

1. A SmartBe User Account
   • Sign up at: https://app.howbetech.com/signup
   • Verify your email address
   • Note: You'll register as a provider, not a regular user/client
2. A Hosted AI Model
   • Your AI model must be hosted and accessible via a REST API endpoint
   • Recommended hosting platforms:
     • AWS SageMaker
     • Google Cloud AI Platform
     • Azure ML
     • Hugging Face Inference Endpoints
     • Custom server (ensure 99.9% uptime)
3. API Endpoint Requirements
   • HTTPS endpoint (HTTP not supported for security)
   • API key authentication
   • JSON request/response format
   • Response time < 30 seconds (recommended)
4. Contact Information
   • Business email address
   • Organization/company name
   • Optional: Phone number, website

🏥 Supported Model Types

SmartBe supports 14 categories of medical AI models that Vertical AI Model Providers can integrate:

Medical Imaging Analysis

Model Type	Description	Use Cases
mri_analysis	MRI scan interpretation	Brain, spine, joint, organ imaging
ct_scan_analysis	CT scan analysis	Tumor detection, organ assessment
xray_analysis	X-ray image interpretation	Chest X-rays, bone fractures
radiology_general	General radiology AI	Multi-modality imaging support
medical_image_segmentation	Image segmentation & annotation	Organ/tissue boundary detection

Specialized Diagnostics

Model Type	Description	Use Cases
pathology_analysis	Digital pathology analysis	Tissue sample analysis, cancer detection
dermatology_analysis	Skin condition analysis	Melanoma detection, rash classification
ophthalmology_analysis	Eye imaging analysis	Retinopathy, glaucoma detection
ecg_analysis	Electrocardiogram interpretation	Arrhythmia, heart condition detection

Advanced Medical AI

Model Type	Description	Use Cases
genomics_analysis	Genomic data analysis	Genetic variant interpretation
lab_results_analysis	Laboratory results interpretation	Blood work, biomarker analysis
disease_classification	Disease prediction & classification	Multi-disease risk assessment
drug_discovery	Drug-target interaction	Molecular screening, compound analysis
clinical_decision_support	Clinical decision assistance	Treatment recommendations, diagnosis support

🚀 Integration Steps

Step 1: Prepare Your API Endpoint

Your API endpoint should accept POST requests with the following structure:

POST https://your-api-endpoint.com/v1/analyze
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "model_type": "mri_analysis",
  "input_data": {
    "scan_type": "brain",
    "sequence": "T1-weighted",
    "clinical_history": "Patient complains of headaches"
  },
  "image_url": "https://storage.howbetech.com/scans/image-123.dcm",
  "text_input": "Additional context or instructions"
}

Your API should return:

{
  "success": true,
  "result": {
    "diagnosis": "No significant abnormalities detected",
    "findings": [
      "Normal brain parenchyma",
      "No mass lesions identified"
    ],
    "confidence_score": 0.95,
    "additional_data": {}
  },
  "processing_time_ms": 2500
}

Error Response:

{
  "success": false,
  "error": "Invalid image format",
  "error_code": "INVALID_INPUT"
}

Step 2: Register as a Provider

Option A: Via API (Recommended for Automation)

curl -X POST https://api.howbetech.com/api/vertical-models/providers \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "provider_name": "RadiologyAI Pro",
    "organization_name": "MedTech Solutions Inc.",
    "website_url": "https://www.medtechsolutions.com",
    "api_endpoint": "https://api.medtechsolutions.com/v1/analyze",
    "api_key": "your_encrypted_api_key_here",
    "contact_email": "contact@medtechsolutions.com",
    "contact_phone": "+1-555-0123",
    "model_types": ["mri_analysis", "ct_scan_analysis"],
    "description": "Advanced radiology AI with 98% accuracy on brain MRI analysis",
    "capabilities": {
      "max_image_size_mb": 50,
      "supported_formats": ["DICOM", "NIFTI", "PNG", "JPEG"],
      "average_processing_time_seconds": 3,
      "batch_processing": false,
      "real_time": true,
      "accuracy_score": 0.98,
      "fda_approved": true,
      "certifications": ["CE Mark", "FDA 510(k)"]
    }
  }'

Option B: Via Web Dashboard (Coming Soon)

Visit https://app.howbetech.com/vertical-models/register

Step 3: Await Admin Approval

After registration:

1. Status: Your provider status will be pending
2. Review Time: 1-3 business days
3. Notification: You'll receive an email notification with approval or rejection details

Step 4: Monitor Your Performance

Once approved (status: active), you can:

• View your usage statistics
• Monitor success rate and response time
• Get real-time analytics on your model's performance

Key Metrics Tracked:

• usage_count - Total API calls
• success_count - Successful completions
• failure_count - Failed requests
• average_response_time_ms - Avg processing time
• success_rate - Overall success percentage

📡 API Endpoints

Base URL

https://api.howbetech.com/api/vertical-models

Authentication

Currently, no authentication required for provider registration (coming soon: API key authentication).

1. Register Provider

POST /providers

Register your AI model provider.

Request Body

{
  "user_id": 123,
  "provider_name": "YourAI Provider Name",
  "organization_name": "Your Organization",
  "website_url": "https://yourwebsite.com",
  "api_endpoint": "https://api.yourwebsite.com/v1/analyze",
  "api_key": "your_api_key",
  "contact_email": "contact@yourorg.com",
  "contact_phone": "+1234567890",
  "model_types": ["mri_analysis"],
  "description": "Description of your AI model",
  "capabilities": {
    "max_image_size_mb": 50,
    "supported_formats": ["DICOM", "PNG"]
  }
}

Response

{
  "success": true,
  "provider": {
    "id": 456,
    "provider_name": "YourAI Provider Name",
    "status": "pending",
    "created_at": "2026-01-07T10:00:00Z"
  },
  "message": "Provider registered successfully. Pending admin review."
}

2. Get Provider Details

GET /providers/{provider_id}

Retrieve your provider information.

Response

{
  "success": true,
  "provider": {
    "id": 456,
    "provider_name": "YourAI Provider Name",
    "status": "active",
    "usage_count": 1250,
    "success_rate": 0.97,
    "average_response_time_ms": 2800
  }
}

3. Get Providers by User

GET /providers/user/{user_id}

Get all providers registered by a user.

4. Update Provider

PUT /providers/{provider_id}

Update your provider information (e.g., new API endpoint, capabilities).

Request Body

{
  "api_endpoint": "https://api-v2.yourwebsite.com/analyze",
  "description": "Updated description"
}

5. Delete Provider

DELETE /providers/{provider_id}

Remove your provider from the platform.

6. Get Provider Statistics

GET /providers/{provider_id}/statistics

Get detailed performance metrics.

Response

{
  "success": true,
  "statistics": {
    "provider_id": 456,
    "provider_name": "YourAI Provider",
    "total_requests": 1250,
    "success_count": 1213,
    "failure_count": 37,
    "success_rate": 0.9704,
    "average_response_time_ms": 2800,
    "status_breakdown": {
      "completed": 1213,
      "failed": 37
    },
    "recent_activity": [
      {"date": "2026-01-07", "count": 45},
      {"date": "2026-01-06", "count": 38}
    ]
  }
}

7. Get Active Providers (SmartBe Platform Use)

GET /providers/active?model_type=mri_analysis

Get all active Vertical AI Model Providers for a specific model type. SmartBe uses this endpoint to select the best provider for each user request.

🔬 Request/Response Examples

Example 1: MRI Analysis

SmartBe Platform Request to Your API:

{
  "model_type": "mri_analysis",
  "input_data": {
    "scan_type": "brain",
    "sequence": "T1-weighted",
    "clinical_history": "45-year-old patient with chronic headaches",
    "slice_thickness": "1mm",
    "field_strength": "3T"
  },
  "image_url": "https://storage.howbetech.com/scans/brain-mri-789.dcm",
  "text_input": "Focus on detecting any mass lesions or abnormalities"
}

Your API Response:

{
  "success": true,
  "result": {
    "diagnosis": "Small meningioma detected in right frontal lobe",
    "findings": [
      "Well-circumscribed extra-axial mass measuring 1.2 cm",
      "Homogeneous enhancement post-contrast",
      "No significant mass effect",
      "No midline shift"
    ],
    "confidence_score": 0.92,
    "recommendations": [
      "Follow-up MRI in 6 months",
      "Neurosurgical consultation recommended"
    ],
    "coordinates": {
      "location": "Right frontal lobe",
      "size_cm": 1.2,
      "position": [45, 78, 120]
    },
    "severity": "low",
    "additional_data": {
      "contrast_enhanced": true,
      "analyzed_sequences": ["T1", "T2", "FLAIR"]
    }
  },
  "processing_time_ms": 3200
}

Example 2: ECG Analysis

SmartBe Platform Request:

{
  "model_type": "ecg_analysis",
  "input_data": {
    "patient_age": 65,
    "patient_sex": "male",
    "symptoms": ["chest pain", "shortness of breath"],
    "duration_seconds": 10,
    "sampling_rate_hz": 500
  },
  "image_url": "https://storage.howbetech.com/ecg/reading-321.pdf"
}

Your API Response:

{
  "success": true,
  "result": {
    "diagnosis": "Atrial fibrillation with rapid ventricular response",
    "findings": [
      "Irregularly irregular rhythm",
      "Absence of P waves",
      "Ventricular rate: 120-140 bpm",
      "No ST-segment changes"
    ],
    "confidence_score": 0.95,
    "arrhythmia_type": "atrial_fibrillation",
    "heart_rate_bpm": 132,
    "pr_interval_ms": null,
    "qrs_duration_ms": 88,
    "qt_interval_ms": 320,
    "recommendations": [
      "Rate control medication",
      "Anticoagulation assessment",
      "Cardiology referral"
    ],
    "urgency": "high"
  },
  "processing_time_ms": 1800
}

Example 3: Dermatology Analysis

SmartBe Platform Request:

{
  "model_type": "dermatology_analysis",
  "input_data": {
    "lesion_location": "upper back",
    "patient_age": 52,
    "skin_type": "Type II (fair)"
  },
  "image_url": "https://storage.howbetech.com/images/skin-lesion-456.jpg"
}

Your API Response:

{
  "success": true,
  "result": {
    "diagnosis": "Probable seborrheic keratosis",
    "findings": [
      "Well-demarcated lesion with stuck-on appearance",
      "Brown pigmentation",
      "Size: 8mm diameter",
      "Surface shows horn cysts"
    ],
    "confidence_score": 0.88,
    "differential_diagnosis": [
      {"condition": "Seborrheic keratosis", "probability": 0.88},
      {"condition": "Melanoma", "probability": 0.08},
      {"condition": "Pigmented basal cell carcinoma", "probability": 0.04}
    ],
    "recommendations": [
      "Benign appearance - reassurance",
      "Optional removal if symptomatic",
      "Routine skin checks annually"
    ],
    "urgency": "low",
    "biopsy_recommended": false
  },
  "processing_time_ms": 2100
}

🧪 Testing Your Integration

Step 1: Local Testing

Before registering, test your API endpoint:

# Test with curl
curl -X POST https://your-api-endpoint.com/v1/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_type": "mri_analysis",
    "input_data": {
      "scan_type": "brain"
    },
    "image_url": "https://example.com/test-image.dcm"
  }'

Step 2: Register in Staging

Use our staging environment for testing:

https://staging-api.howbetech.com/api/vertical-models

Step 3: Monitor Test Requests

After registration, you can submit test requests:

curl -X POST https://api.howbetech.com/api/vertical-models/requests \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "provider_id": 456,
    "model_type": "mri_analysis",
    "input_data": {"scan_type": "brain"},
    "image_url": "https://storage.howbetech.com/test/sample-mri.dcm"
  }'

Check request status:

curl https://api.howbetech.com/api/vertical-models/requests/{request_id}

⚡ Best Practices

1. API Response Time

• Target: < 5 seconds for real-time use cases
• Maximum: 30 seconds (requests may timeout after this)
• Optimization: Use model compression, caching, or GPU acceleration

2. Error Handling

Always return proper error responses:

{
  "success": false,
  "error": "Image format not supported. Expected DICOM, received JPEG",
  "error_code": "INVALID_FORMAT",
  "supported_formats": ["DICOM", "NIFTI"]
}

3. Confidence Scores

• Always include confidence scores (0-1 scale)
• Flag low-confidence results (< 0.7) for human review
• Provide alternative diagnoses with probabilities

4. HIPAA Compliance

• Use HTTPS only (no HTTP)
• Don't store patient data unless necessary
• Encrypt data in transit and at rest
• Log access for audit trails

5. API Availability

• Maintain 99.9% uptime
• Implement health check endpoints
• Use auto-scaling for high traffic
• Provide status page for downtime notifications

6. Versioning

• Version your API (e.g., /v1/analyze, /v2/analyze)
• Maintain backward compatibility
• Notify SmartBe before deprecating versions

📊 Performance Metrics

Your provider will be ranked based on:

1. Success Rate (weight: 50%)
   • Target: > 95%
   • Failures hurt your ranking
2. Response Time (weight: 30%)
   • Target: < 3 seconds
   • Faster = better ranking
3. Usage Count (weight: 20%)
   • More usage = established provider
   • Helps with cold start problem

SmartBe Selection Algorithm:

# Providers are ranked by:
1. Success rate (descending)
2. Average response time (ascending)
3. Total usage count (descending)

Top-ranked Vertical AI Model Providers get selected first by SmartBe's automated model selection system when users need specialized AI analysis.

🔄 Provider Lifecycle

┌─────────────┐
│  Register   │
└──────┬──────┘
       │
       v
┌─────────────┐     Approved      ┌────────────┐
│   Pending   ├─────────────────>│   Active   │
└──────┬──────┘                   └─────┬──────┘
       │                                │
       │ Rejected                       │ Suspended
       v                                v
┌─────────────┐                   ┌────────────┐
│  Rejected   │                   │ Suspended  │
└─────────────┘                   └─────┬──────┘
                                         │
                                         │ Reactivated
                                         v
                                   ┌────────────┐
                                   │   Active   │
                                   └────────────┘

Status Definitions

• Pending: Awaiting admin review
• Active: Live and available for SmartBe users
• Rejected: Registration denied (can reapply)
• Suspended: Temporarily disabled (due to quality issues)

📧 Email Notifications

You'll receive email notifications for:

1. Approval ✅
   • Congratulations message
   • Dashboard access
   • Getting started resources
2. Rejection ❌
   • Reason for rejection
   • Steps to reapply
   • Support contact
3. Suspension ⚠️
   • Reason for suspension
   • Impact explanation
   • Resolution steps
4. Reactivation ✅
   • Account restored message
   • Performance reminders

📝 Checklist Before Going Live

🎓 Example Integration Code

Python Client Example

import requests
from typing import Dict, Any

class SmartBeVerticalModel:
    def __init__(self, api_endpoint: str, api_key: str):
        self.api_endpoint = api_endpoint
        self.api_key = api_key

    def analyze(
        self,
        model_type: str,
        input_data: Dict[str, Any],
        image_url: str = None
    ) -> Dict[str, Any]:
        """
        Process medical data through your AI model
        """
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }

        payload = {
            "model_type": model_type,
            "input_data": input_data
        }

        if image_url:
            payload["image_url"] = image_url

        response = requests.post(
            self.api_endpoint,
            json=payload,
            headers=headers,
            timeout=30
        )

        return response.json()

# Usage
model = SmartBeVerticalModel(
    api_endpoint="https://api.yourservice.com/v1/analyze",
    api_key="your_api_key"
)

result = model.analyze(
    model_type="mri_analysis",
    input_data={"scan_type": "brain"},
    image_url="https://storage.howbetech.com/scans/mri-123.dcm"
)

print(result)

🚀 What's Next?

After successful integration:

1. Monitor Performance: Track your metrics daily
2. Optimize: Improve response time and accuracy
3. Scale: Handle increased traffic as usage grows
4. Feedback Loop: Use user feedback to improve your model
5. Updates: Keep your model up-to-date with latest research

📄 Legal & Compliance

• By integrating with SmartBe, you agree to our Terms of Service
• Ensure your AI model complies with FDA/CE regulations
• HIPAA compliance is mandatory
• Patient data must be handled securely

💰 Pricing & Business Model (Coming Soon)

We're currently in the beta phase and welcoming early partners. Revenue sharing and pricing models will be announced soon.

Early Partner Benefits:

• Free integration during beta
• Priority placement in SmartBe's automated provider selection
• Co-marketing opportunities
• Early access to new features

Contact partnerships@howbetech.com for partnership discussions.

🔒 Security & Privacy

Data Handling Requirements

1. Encryption
   • All API endpoints must use HTTPS/TLS 1.2+
   • Patient data must be encrypted at rest and in transit
2. Data Retention
   • Don't store patient images/data longer than necessary
   • Implement data deletion policies
   • Honor user data deletion requests
3. Access Control
   • Implement API key rotation
   • Use role-based access control
   • Log all access for audit trails
4. Compliance Certifications
   • HIPAA (required for US healthcare data)
   • GDPR (required for EU patients)
   • SOC 2 Type II (recommended)
   • ISO 27001 (recommended)

🛠️ Troubleshooting Common Issues

Issue 1: Registration Rejected

Possible Reasons:

• Incomplete contact information
• API endpoint not accessible
• Model type not properly specified
• Missing capability details

Solution: Review rejection email feedback and resubmit with corrections.

Issue 2: Low Success Rate

Symptoms: Your provider has < 90% success rate

Common Causes:

• API timeout (> 30 seconds)
• Invalid response format
• Image format not supported
• API endpoint downtime

Solutions:

1. Check your API logs for error patterns
2. Optimize processing time
3. Add better error handling
4. Implement health monitoring

Issue 3: Not Getting Selected by SmartBe Platform

Reasons:

• Low success rate compared to other Vertical AI Model Providers
• Slow response time
• Insufficient usage history (cold start)
• Model type not matching user needs

Solutions:

1. Improve success rate to > 95%
2. Reduce response time to < 3 seconds
3. Build reputation through consistent performance
4. Request featured placement (contact partnerships team)
5. Ensure your model type matches the categories users most frequently need

Issue 4: API Authentication Errors

Error: "Invalid API key" or "Unauthorized"

Solutions:

1. Verify your API key is correct in provider settings
2. Check if API key has expired
3. Ensure proper Authorization header format
4. Contact support if issue persists

📞 Getting Help

Self-Service Resources

1. Documentation: https://docs.howbetech.com/vertical-models
2. API Status: https://status.howbetech.com
3. FAQ: FAQ Page

Direct Support

Technical Issues:

• Email: support@howbetech.com
• Response time: < 24 hours (business days)

Partnership Inquiries:

• Email: partnerships@howbetech.com
• For commercial discussions, co-marketing, etc.

Emergency Support (Production issues):

• Email: urgent@howbetech.com
• Include "URGENT" in subject line
• Response time: < 2 hours

🎯 Quick Start Checklist

Ready to integrate? Follow this checklist:

🌟 Success Metrics

What Makes a Great Provider?

Top-performing Vertical AI Model Providers on SmartBe typically have:

Metric	Target	Top 10%
Success Rate	> 95%	> 99%
Response Time	< 5s	< 2s
Uptime	> 99.5%	> 99.9%
Confidence Score	> 0.85	> 0.92
User Satisfaction	> 4.0/5	> 4.7/5

📈 Roadmap

Coming Soon

• Provider Dashboard (Q1 2026)
  • Real-time analytics
  • Usage graphs
  • Performance trends
  • Revenue tracking
• Advanced Features (Q2 2026)
  • Batch processing support
  • Webhook notifications
  • Custom model training
  • A/B testing framework
• Enterprise Tier (Q3 2026)
  • Dedicated support
  • SLA guarantees
  • White-label options
  • Custom integrations

💡 Tips for Success

1. Start Small, Scale Fast

• Begin with one model type you're most confident in
• Perfect that before expanding to other types
• Build reputation through consistent quality

2. Optimize for Speed

• Use CDN for image loading
• Implement caching where possible
• Consider edge computing for faster response

3. Provide Clear Results

• Structure your responses consistently
• Include confidence scores
• Provide actionable recommendations
• Explain findings in plain language

4. Monitor & Iterate

• Check your metrics weekly
• Analyze failure patterns
• Continuously improve model accuracy
• Respond to user feedback

5. Stay Compliant

• Keep certifications up to date
• Regular security audits
• Follow data retention policies
• Update privacy policies as needed

---

Last Updated: January 7, 2026
Guide Version: 1.0.0
API Version: v1