DEPLOY_API_SERVER.md

Deploy API Server to Hugging Face Space

Problem

The current Hugging Face Space deployment is running in --hfdemo mode, which provides a Gradio UI but does NOT expose the API endpoints like /api/ping, /api/health, etc.

Solution

The Dockerfile has been updated to:

1. Run in --api mode instead of --hfdemo mode
2. Use port 7860 (required by Hugging Face Spaces) instead of the default port 8000

Deployment Steps

1. Commit and Push Changes

cd sci-image
git add Dockerfile
git commit -m "Switch to API server mode for Hugging Face Space"
git push

2. Push to Hugging Face Space

If you have the Hugging Face Space connected as a remote:

git push hf main

Or manually upload the updated Dockerfile to your Hugging Face Space at: https://huggingface.co/spaces/gsstec/sci-image/tree/main

3. Wait for Rebuild

The Hugging Face Space will automatically rebuild with the new Dockerfile. This may take 5-10 minutes.

4. Verify API Endpoints

Once deployed, test the endpoints:

Ping Endpoint:

curl https://gsstec-sci-image.hf.space/api/ping

Expected response:

{
  "status": "ok",
  "service": "AEGIS Bio-Digital Lab 10 - Visual System",
  "version": "1.0.0",
  "device": "cpu"
}

Health Endpoint:

curl https://gsstec-sci-image.hf.space/api/health

System Info:

curl https://gsstec-sci-image.hf.space/api/info

Available API Endpoints After Deployment

Health & Monitoring

• GET /api/ - Welcome message
• GET /api/ping - Health check for UptimeRobot
• GET /api/health - Detailed health status
• GET /api/info - System information
• GET /api/config - Current configuration
• GET /api/models - Available models

Image Generation

• POST /api/generate - General image generation
• POST /api/window7/generate-pathogen - Pathogen visualization
• POST /api/window7/generate-disease-visualization - Disease visualization
• POST /api/window9/generate-molecule - Molecular structure
• POST /api/window9/generate-drug-visualization - Drug visualization
• POST /api/aegis/generate-scientific - Scientific visualization

API Documentation

• /api/docs - Swagger UI documentation
• /api/redoc - ReDoc documentation
• /api/openapi.json - OpenAPI specification

UptimeRobot Configuration

After deployment, configure UptimeRobot:

• Monitor Type: HTTP(s)
• URL: https://gsstec-sci-image.hf.space/api/ping
• Interval: 5 minutes
• Expected Response: 200 OK with "status": "ok"

Testing Locally

To test the API server locally before deploying:

cd sci-image
python src/app.py --api

Then test:

curl http://localhost:8000/api/ping

Reverting to UI Mode

If you need to revert to the Gradio UI:

CMD ["python", "src/app.py","--hfdemo"]

Notes

• The API server runs on port 7860 (as configured in Dockerfile EXPOSE)
• CORS is enabled for all origins
• The server uses FastAPI with automatic OpenAPI documentation
• All endpoints are prefixed with /api/