docs/API_KEYS.md

🔑 VisionQ - API Keys & Authentication

🎯 Quick Answer

Do you need API keys for VisionQ?

NO! ❌

VisionQ works 100% offline without any API keys.

---

✅ What Works Without API Keys

All core features work without any authentication:

Feature	Model	API Key Needed?
Object Detection	YOLO/SSD	❌ No
Image Captioning	BLIP	❌ No
Visual Embeddings	CLIP	❌ No
OCR (90+ languages)	EasyOCR	❌ No
Text Embeddings	sentence-transformers	❌ No
Vector Search	FAISS	❌ No
Intent Classification	DistilBERT	❌ No
Speech Recognition	Vosk	❌ No
Text-to-Speech	pyttsx3	❌ No

Everything runs locally on your machine!

---

🔓 Optional: Hugging Face Token

When You Might Need It

A Hugging Face token is optional and only needed for:

1. Private Models - Models you've created and marked private
2. Gated Models - Some models require accepting terms
3. Higher Rate Limits - Faster model downloads
4. Enterprise Features - Advanced Hugging Face features

VisionQ Default Models

All default models in VisionQ are public and free:

• ✅ Salesforce/blip-image-captioning-base - Public
• ✅ openai/clip-vit-base-patch32 - Public
• ✅ typeform/distilbert-base-uncased-mnli - Public
• ✅ all-MiniLM-L6-v2 - Public

No token needed!

---

🔧 How to Add Hugging Face Token (Optional)

Step 1: Get Token

1. Go to https://huggingface.co/
2. Create free account (if you don't have one)
3. Go to Settings → Access Tokens
4. Click "New token"
5. Select "Read" access
6. Copy token

Step 2: Add to VisionQ

Method 1: Environment Variable (Recommended)

Create .env file in project root:

HUGGINGFACE_TOKEN=hf_your_token_here

Method 2: Direct Configuration

Edit config/settings.py:

HUGGINGFACE_TOKEN = "hf_your_token_here"

Method 3: System Environment

Windows:

setx HUGGINGFACE_TOKEN "hf_your_token_here"

Linux/Mac:

export HUGGINGFACE_TOKEN="hf_your_token_here"

Step 3: Restart VisionQ

Token will be automatically used for model downloads.

---

🌐 Internet Connection

First Run

Internet required to download models (~2GB):

• YOLO weights (~50MB)
• BLIP model (~1GB)
• CLIP model (~500MB)
• DistilBERT (~250MB)
• EasyOCR languages (~50MB each)

Download happens once - models are cached locally.

Subsequent Runs

No internet required! All models run offline.

---

🔒 Privacy & Security

Data Privacy

• ✅ No data sent to cloud
• ✅ All processing local
• ✅ No telemetry
• ✅ No tracking
• ✅ Memories stored locally

Model Security

• ✅ Models from trusted sources (Hugging Face, Ultralytics)
• ✅ Open-source and auditable
• ✅ No backdoors or malware
• ✅ Community-verified

Token Security

If you use a Hugging Face token:

• ✅ Store in .env file (not in code)
• ✅ Add .env to .gitignore
• ✅ Use "Read" access only
• ✅ Revoke if compromised

---

🚫 What VisionQ Does NOT Need

Service	Needed?	Why Not?
OpenAI API	❌ No	Using open-source models
Google Cloud Vision	❌ No	Using local YOLO/BLIP
AWS Rekognition	❌ No	Using local models
Azure Computer Vision	❌ No	Using local models
Anthropic API	❌ No	Using local models
Cohere API	❌ No	Using local models

VisionQ is 100% self-contained!

---

📊 Comparison: Cloud vs Local

Cloud-Based (Other Solutions)

❌ Requires API keys
❌ Costs money per request
❌ Needs internet connection
❌ Data sent to cloud
❌ Privacy concerns
❌ Rate limits
❌ Vendor lock-in

VisionQ (Local)

✅ No API keys needed
✅ Completely free
✅ Works offline
✅ Data stays local
✅ Full privacy
✅ No rate limits
✅ Open source

---

🎓 Model Sources

All models are from trusted open-source repositories:

Hugging Face Models

• BLIP: https://huggingface.co/Salesforce/blip-image-captioning-base
• CLIP: https://huggingface.co/openai/clip-vit-base-patch32
• DistilBERT: https://huggingface.co/typeform/distilbert-base-uncased-mnli
• MiniLM: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2

Other Sources

• YOLO: https://github.com/ultralytics/ultralytics
• EasyOCR: https://github.com/JaidedAI/EasyOCR
• FAISS: https://github.com/facebookresearch/faiss
• Vosk: https://alphacephei.com/vosk/

All are free, open-source, and require no API keys!

---

🔧 Troubleshooting

"Model download failed"

1. Check internet connection
2. Try again (downloads can be interrupted)
3. Clear cache: rm -rf ~/.cache/huggingface/
4. Use VPN if blocked in your region

"Authentication required"

This should never happen with default VisionQ models.

If it does:

1. Check you're using default models
2. Verify model names in config/settings.py
3. Try adding Hugging Face token (optional)

"Rate limit exceeded"

This only happens during model downloads if you download too many models quickly.

Solutions:

1. Wait a few minutes
2. Add Hugging Face token (increases limits)
3. Download models one at a time

---

📚 FAQ

Q: Do I need to pay for anything?

A: No! VisionQ is completely free. All models are open-source and free to use.

Q: Can I use VisionQ commercially?

A: Yes! All models have permissive licenses (MIT, Apache 2.0, etc.). Check individual model licenses for details.

Q: Will VisionQ always be free?

A: Yes! It's open-source and runs locally. No cloud costs, no subscriptions.

Q: What about GPU usage?

A: VisionQ works on CPU (free). GPU is optional for faster processing.

Q: Do I need a Hugging Face account?

A: No! Only needed if you want to use private/gated models.

Q: Can I use my own models?

A: Yes! Edit config/settings.py to point to your models.

---

✅ Summary

VisionQ requires:

• ✅ Python 3.8+
• ✅ ~2GB disk space (for models)
• ✅ Internet (first run only)
• ✅ Webcam (for vision features)

VisionQ does NOT require:

• ❌ API keys
• ❌ Cloud accounts
• ❌ Subscriptions
• ❌ Payment
• ❌ Internet (after first run)

100% free, 100% local, 100% private! 🔒

---

📞 Support

Questions about API keys?

Check:

1. This document
2. README.md
3. .env.example file
4. config/settings.py

Still have questions?

Open an issue on GitHub or check the documentation.

---

VisionQ - Powerful AI without the API hassle! 🚀