### Start Powershell Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Initiate a Powershell session to run the setup scripts. ```powershell pwsh ``` -------------------------------- ### Install Project Requirements Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Install all Python dependencies listed in the requirements.txt file. ```pip pip3 install -r requirements.txt ``` -------------------------------- ### API Key and Admin Key Authentication Examples - Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Demonstrates making authenticated requests using both api_key for inference and admin_key for administrative tasks. Includes an example of an incorrect key response. ```python import requests # Inference request with api_key response = requests.post( "http://localhost:80/v1/vision/detection", files={"image": open("photo.jpg", "rb").read()}, data={"api_key": "inference_key"}, ).json() # Admin request with admin_key admin_response = requests.post( "http://localhost:80/v1/vision/listmodels", data={"admin_key": "admin_key"}, ).json() # Wrong key — returns 401 bad_response = requests.post( "http://localhost:80/v1/vision/detection", files={"image": open("photo.jpg", "rb").read()}, data={"api_key": "wrong_key"}, ).json() # {"success": false, "error": "Incorrect api key"} ``` -------------------------------- ### Run GPU Setup Script Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Execute the Powershell script to set up the environment for the GPU version of DeepStack. ```powershell .\setup_docker_gpu.ps1 ``` -------------------------------- ### Install Font Awesome 5 with npm Source: https://github.com/johnolafenwa/deepstack/blob/dev/server/assets/vendor/fontawesome-free/README.md Use this command to install the Font Awesome 5 Free package as a dependency in your project using npm. ```bash $ npm i --save @fortawesome/fontawesome-free ``` -------------------------------- ### Run CPU Setup Script Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Execute the Powershell script to set up the environment for the CPU version of DeepStack. ```powershell .\setup_docker_cpu.ps1 ``` -------------------------------- ### Start DeepStack Docker Container with API and Admin Keys Source: https://context7.com/johnolafenwa/deepstack/llms.txt Launches a DeepStack Docker container with specified vision modules enabled and custom API and admin keys set via environment variables. A local volume is mounted for data persistence. ```bash # Start with both keys docker run -e VISION-DETECTION=True \ -e VISION-FACE=True \ -e API-KEY=inference_key \ -e ADMIN-KEY=admin_key \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:cpu ``` -------------------------------- ### Install Font Awesome 5 with Yarn Source: https://github.com/johnolafenwa/deepstack/blob/dev/server/assets/vendor/fontawesome-free/README.md Use this command to install the Font Awesome 5 Free package as a dependency in your project using yarn. ```bash $ yarn add @fortawesome/fontawesome-free ``` -------------------------------- ### Install PyTorch for CPU Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Install the CPU-specific version of PyTorch and Torchvision. This is required for the CPU version of DeepStack. ```pip pip3 install torch==1.6.0+cpu torchvision==0.7.0+cpu -f https://download.pytorch.org/whl/torch_stable.html ``` -------------------------------- ### Install PyTorch for GPU Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Install the GPU-specific version of PyTorch and Torchvision. This is required for the GPU version of DeepStack. ```pip pip3 install torch==1.6.0+cu101 torchvision==0.7.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html ``` -------------------------------- ### Object Detection API Request (curl) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Sends an image to the DeepStack object detection API using curl. This command-line example demonstrates how to send the image file and specify parameters like 'min_confidence' and 'api_key'. ```bash curl -X POST http://localhost:80/v1/vision/detection \ -F "image=@street.jpg" \ -F "min_confidence=0.5" \ -F "api_key=mysecretkey" ``` -------------------------------- ### Download Binary Dependencies Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Execute the Powershell script to download necessary binary dependencies. ```powershell .\download_dependencies.ps1 ``` -------------------------------- ### Create and Activate Virtual Environment Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Create a Python virtual environment and activate it to manage project dependencies. ```python python3.7 -m venv venv ``` ```bash source venv/bin/activate ``` -------------------------------- ### Backup Custom Models and Face Embeddings - Bash Source: https://context7.com/johnolafenwa/deepstack/llms.txt Creates a .zip archive of all custom models and the face embeddings database. The archive is returned as a binary file download. Requires the admin key. ```bash curl -X POST http://localhost:80/v1/backup \ -F "admin_key=adminpass" \ --output deepstack_backup.zip ``` -------------------------------- ### Run Benchmark Script - Bash Source: https://context7.com/johnolafenwa/deepstack/llms.txt Executes the benchmark script to measure end-to-end throughput against the object detection endpoint. Requires specifying IP, port, API key, and the folder containing test images. ```bash # Run benchmark against a folder of images python3 demo/benchmark.py \ --ip localhost \ --port 5000 \ --api_key mysecretkey \ --images_folder /path/to/test/images # Sample output: # Processing 50 images in folder /path/to/test/images # Processed image number 0 : /path/to/test/images/img001.jpg, 3 predictions # ... # Processing completes in 12.34567 seconds, total of 147 predictions ``` -------------------------------- ### Navigate to Server Directory Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Change directory to the server component of DeepStack. ```bash cd server ``` -------------------------------- ### Run DeepStack Docker Image (Jetson) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Pulls and runs the DeepStack Docker image optimized for NVIDIA Jetson devices. Enables object detection API. Uses the NVIDIA container runtime, maps a local volume for data storage, and exposes port 80. ```bash docker run --runtime nvidia \ -e VISION-DETECTION=True \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:jetpack ``` -------------------------------- ### Run DeepStack Docker Image (GPU) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Pulls and runs the GPU-enabled DeepStack Docker image. Requires NVIDIA drivers and Docker runtime. Enables object detection and face detection APIs, and sets CUDA mode. Maps a local volume for data storage and exposes port 80. ```bash docker run --gpus all \ -e VISION-DETECTION=True \ -e VISION-FACE=True \ -e CUDA_MODE=True \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:gpu ``` -------------------------------- ### Run DeepStack Docker Image (ARM64) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Pulls and runs the DeepStack Docker image for Raspberry Pi and other ARM64 devices. Enables object detection API. Maps a local volume for data storage and exposes port 80. ```bash docker run -e VISION-DETECTION=True \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:arm64-cpu ``` -------------------------------- ### Run DeepStack Docker Image (CPU) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Pulls and runs the CPU version of the DeepStack Docker image. Enables object detection, face detection, scene classification, and image enhancement APIs. Sets an API key and maps a local volume for data storage. Port 80 is exposed, mapping to the container's port 5000. ```bash docker run -e VISION-DETECTION=True \ -e VISION-FACE=True \ -e VISION-SCENE=True \ -e VISION-ENHANCE=True \ -e API-KEY=mysecretkey \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:cpu ``` -------------------------------- ### Navigate to DeepStack Directory Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Change the current directory to the cloned DeepStack repository. ```bash cd DeepStack ``` -------------------------------- ### Run DeepStack Server Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Execute the compiled DeepStack server. Ensure all necessary environment variables are set. ```powershell .\server ``` -------------------------------- ### Restore Custom Models and Face Embeddings - Bash Source: https://context7.com/johnolafenwa/deepstack/llms.txt Restores custom models and face embeddings from a backup .zip file. Requires the backup file and admin key. ```bash curl -X POST http://localhost:80/v1/restore \ -F "file=@deepstack_backup.zip" \ -F "admin_key=adminpass" # {"success":true} ``` -------------------------------- ### Build DeepStack Server Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Compile the DeepStack server application using the Go compiler. ```go go build ``` -------------------------------- ### Register Face with cURL Source: https://context7.com/johnolafenwa/deepstack/llms.txt This cURL command demonstrates how to register a face image for a named user. Ensure the image file is accessible and the API key is correctly provided. ```bash curl -X POST http://localhost:80/v1/vision/face/register \ -F "image=@alice1.jpg" \ -F "userid=Alice" \ -F "api_key=mysecretkey" ``` -------------------------------- ### Configure DeepStack Performance Mode and Threads Source: https://context7.com/johnolafenwa/deepstack/llms.txt Runs the DeepStack Docker image with custom performance settings. Allows setting the 'MODE' to 'Low', 'Medium', or 'High', and 'THREADCOUNT' to control the number of parallel AI inference workers. Defaults are Medium mode and 5 threads. ```bash # MODE options: Low | Medium (default) | High # THREADCOUNT controls parallel AI inference workers (default: 5) docker run -e VISION-DETECTION=True \ -e MODE=High \ -e THREADCOUNT=10 \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:cpu ``` -------------------------------- ### Restore Custom Models and Face Embeddings - Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Sends the backup file content for restoration. The file is opened in binary read mode and passed as multipart/form-data. ```python import requests backup_file = open("deepstack_backup.zip", "rb").read() response = requests.post( "http://localhost:80/v1/restore", files={"file": backup_file}, data={"admin_key": "admin_key"}, ).json() # Expected: {"success": true} print("Restore status:", response["success"]) ``` -------------------------------- ### Enable DeepStack APIs Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Set environment variables to enable specific DeepStack APIs. Multiple APIs can be enabled simultaneously. ```powershell $env:VISION_DETECTION = "True" ``` ```powershell $env:VISION_FACE = "True" ``` ```powershell $env:VISION_SCENE = "True" ``` -------------------------------- ### Classify Image Scene with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Use this snippet to classify the overall scene in an image. Ensure VISION-SCENE is enabled and the image file exists. ```python import requests image_data = open("indoor_photo.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/scene", files={"image": image_data}, data={"api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "label": "conference_room", # "confidence": 0.87, # "duration": 0.065 # } if response["success"]: print(f"Scene: {response['label']} ({response['confidence']:.1%} confidence)") ``` -------------------------------- ### Build DeepStack CPU Docker Image Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Build the Docker image for the CPU version of DeepStack. Ensure you are in the DeepStack directory or adjust the path accordingly. ```docker cd .. && sudo docker build -t deepquestai/deepstack:cpu . -f Dockerfile.cpu ``` -------------------------------- ### Docker Run Command for Custom Detection Source: https://context7.com/johnolafenwa/deepstack/llms.txt This command launches a DeepStack container with custom detection enabled. It mounts the model store and exposes the API port. ```bash # Mount the model store and enable custom detection docker run -e VISION-DETECTION=True \ -v /path/to/models:/modelstore/detection \ -v localstorage:/datastore \ -p 80:5000 \ deepquestai/deepstack:cpu ``` -------------------------------- ### Register Custom Model at Runtime with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Uploads a TensorFlow model and its configuration file to DeepStack without restarting the server. Requires the admin key. ```python import requests model_file = open("custom_model.pb", "rb").read() config_file = open("config.json", "rb").read() response = requests.post( "http://localhost:80/v1/vision/addmodel", files={"model": model_file, "config": config_file}, data={"name": "vehicle_classifier", "admin_key": "adminpass"}, ).json() # Expected: {"success": true, "message": "model registered", "duration": 0.01} print(response["message"]) ``` -------------------------------- ### Restore Source: https://context7.com/johnolafenwa/deepstack/llms.txt Restores custom models and face embeddings from a previously created backup .zip file. Requires the backup file and an admin key. ```APIDOC ## POST /v1/restore ### Description Restores custom models and face embeddings from a previously created backup .zip file. ### Method POST ### Endpoint /v1/restore ### Parameters #### Request Body - **file** (file) - Required - The backup .zip file. - **admin_key** (string) - Required - The administrator key for authentication. ### Response #### Success Response (200) - **success** (boolean) - Indicates if the restore operation was successful. ### Request Example ```bash curl -X POST http://localhost:80/v1/restore \ -F "file=@deepstack_backup.zip" \ -F "admin_key=adminpass" ``` ``` -------------------------------- ### Build DeepStack GPU Docker Image Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Build the Docker image for the GPU version of DeepStack. Ensure you are in the DeepStack directory or adjust the path accordingly. ```docker sudo docker build -t deepquestai/deepstack:gpu . -f Dockerfile.gpu ``` -------------------------------- ### Backup Source: https://context7.com/johnolafenwa/deepstack/llms.txt Creates a .zip archive containing all custom models and the face embeddings database. This archive is returned as a binary file download, useful for persisting state or migrating. ```APIDOC ## POST /v1/backup ### Description Creates a .zip archive containing all custom models and the face embeddings database, returned as a binary file download. Useful for persisting state across container restarts or migrating to a new host. ### Method POST ### Endpoint /v1/backup ### Parameters #### Request Body - **admin_key** (string) - Required - The administrator key for authentication. ### Response #### Success Response (200) - **binary file** - The backup archive (.zip). ### Request Example ```bash curl -X POST http://localhost:80/v1/backup \ -F "admin_key=adminpass" \ --output deepstack_backup.zip ``` ``` -------------------------------- ### Build DeepStack Jetson Docker Image Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Build the Docker image for the Jetson version of DeepStack. Ensure you are in the DeepStack directory or adjust the path accordingly. ```docker sudo docker build -t deepquestai/deepstack:jetpack . -f Dockerfile.gpu-jetpack ``` -------------------------------- ### Backup Custom Models and Face Embeddings - Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Saves the backup archive to a local file. The response content is written in binary mode. ```python import requests response = requests.post( "http://localhost:80/v1/backup", data={"admin_key": "adminpass"}, ) with open("deepstack_backup.zip", "wb") as f: f.write(response.content) print("Backup saved:", len(response.content), "bytes") ``` -------------------------------- ### Register Custom Model at Runtime Source: https://context7.com/johnolafenwa/deepstack/llms.txt Uploads a TensorFlow .pb model file and its config.json to the DeepStack datastore at runtime. ```APIDOC ## POST /v1/vision/addmodel ### Description Uploads a TensorFlow `.pb` model file and its `config.json` to the DeepStack datastore at runtime without restarting the server. Requires the `admin_key`. ### Method POST ### Endpoint /v1/vision/addmodel ### Parameters #### Form Data - **model** (file) - Required - The TensorFlow model file (`.pb`). - **config** (file) - Required - The model configuration file (`config.json`). - **name** (string) - Required - The name to register the model under. - **admin_key** (string) - Required - The DeepStack admin key. ### Request Example ```python import requests model_file = open("custom_model.pb", "rb").read() config_file = open("config.json", "rb").read() response = requests.post( "http://localhost:80/v1/vision/addmodel", files={"model": ("custom_model.pb", model_file), "config": ("config.json", config_file)}, data={"name": "vehicle_classifier", "admin_key": "adminpass"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **message** (string) - A message confirming the model registration. - **duration** (float) - The time taken for the operation in seconds. #### Response Example ```json {"success": true, "message": "model registered", "duration": 0.01} ``` ``` -------------------------------- ### List Registered Models with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Retrieves a list of all models currently stored in the DeepStack datastore. Requires the admin key. ```python import requests response = requests.post( "http://localhost:80/v1/vision/listmodels", data={"admin_key": "adminpass"}, ).json() # Expected response: # { # "success": true, # "models": [ # {"name": "vehicle_classifier", "modelsize": 14.3, "dateupdated": "2024-03-01T10:00:00Z"} # ] # } for model in response.get("models", []): print(f"{model['name']} — {model['modelsize']:.1f} MB, updated {model['dateupdated']}") ``` -------------------------------- ### Custom Model Inference with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Performs inference using a custom YOLOv5 model deployed in the model store. Specify the model name and optionally set a minimum confidence threshold. ```python import requests # Assumes a model file "mask_detector.pt" is in the modelstore directory image_data = open("person_wearing_mask.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/custom/mask_detector", files={"image": image_data}, data={"min_confidence": 0.5, "api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "predictions": [ # {"label": "mask", "confidence": 0.97, "x_min": 80, "y_min": 20, "x_max": 160, "y_max": 130}, # {"label": "no_mask", "confidence": 0.89, "x_min": 250, "y_min": 15, "x_max": 340, "y_max": 125} # ], # "duration": 0.098 # } for pred in response.get("predictions", []): print(f"{pred['label']}: {pred['confidence']:.2f}") ``` -------------------------------- ### Clone DeepStack Repository Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Use this command to clone the DeepStack repository from GitHub. ```git git clone https://github.com/johnolafenwa/DeepStack.git ``` -------------------------------- ### List Registered Models Source: https://context7.com/johnolafenwa/deepstack/llms.txt Returns all models currently stored in the DeepStack datastore. ```APIDOC ## POST /v1/vision/listmodels ### Description Returns all models currently stored in the DeepStack datastore, with their name, file size (MB), and last-updated timestamp. ### Method POST ### Endpoint /v1/vision/listmodels ### Parameters #### Form Data - **admin_key** (string) - Required - The DeepStack admin key. ### Request Example ```python import requests response = requests.post( "http://localhost:80/v1/vision/listmodels", data={"admin_key": "adminpass"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **models** (array) - A list of registered models. - **name** (string) - The name of the model. - **modelsize** (float) - The size of the model in MB. - **dateupdated** (string) - The last updated timestamp of the model. #### Response Example ```json { "success": true, "models": [ {"name": "vehicle_classifier", "modelsize": 14.3, "dateupdated": "2024-03-01T10:00:00Z"} ] } ``` ``` -------------------------------- ### List Registered Faces with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt This script retrieves a list of all registered user IDs from the face embeddings database. It makes a POST request to the `/v1/vision/face/list` endpoint. ```python import requests response = requests.post( "http://localhost:80/v1/vision/face/list", data={"api_key": "mysecretkey"}, ).json() # Expected: {"success": true, "faces": ["Alice", "Bob", "Carol"], "duration": 0.002} if response["success"]: print("Registered faces:", response["faces"]) ``` -------------------------------- ### Enhance Image Resolution with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Upscales a low-resolution image by 4x using a deep learning model. Requires VISION-ENHANCE to be enabled. The enhanced image is returned as a base64-encoded string. ```python import requests import base64 from PIL import Image from io import BytesIO image_data = open("low_res.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/enhance", files={"image": image_data}, data={"api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "base64": "", # "width": 1200, # "height": 632, # "duration": 1.45 # } if response["success"]: print(f"Enhanced size: {response['width']}x{response['height']}") img_bytes = base64.b64decode(response["base64"]) enhanced_image = Image.open(BytesIO(img_bytes)) enhanced_image.save("enhanced_output.jpg") ``` -------------------------------- ### Register Face with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt Use this function to register one or more face images for a named user. Multiple images can be submitted in a single request for better recognition accuracy. Requires the face API to be enabled. ```python import requests def register_face(image_path: str, user_id: str, api_key: str = "") -> dict: image_data = open(image_path, "rb").read() response = requests.post( "http://localhost:80/v1/vision/face/register", files={"image": image_data}, data={"userid": user_id, "api_key": api_key}, ).json() return response # Register multiple people people = [ ("images/alice1.jpg", "Alice"), ("images/bob1.jpg", "Bob"), ("images/carol1.jpg", "Carol"), ] for img_path, name in people: result = register_face(img_path, name, api_key="mysecretkey") # Expected: {"success": true, "message": "face added", "duration": 0.04} print(f"Registered {name}: {result}") ``` -------------------------------- ### Fetch Large Files with Git LFS Source: https://github.com/johnolafenwa/deepstack/blob/dev/README.md Ensure all large files tracked by Git LFS are downloaded. ```git git lfs pull ``` -------------------------------- ### Image Enhancement (Super-Resolution) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Upscales a low-resolution image by 4× using a deep learning super-resolution model. ```APIDOC ## POST /v1/vision/enhance ### Description Upscales a low-resolution image by 4× using a deep learning super-resolution model (BEBYGan). Returns the enhanced image as a base64-encoded JPEG string along with the output dimensions. Requires `VISION-ENHANCE=True`. ### Method POST ### Endpoint /v1/vision/enhance ### Parameters #### Form Data - **image** (file) - Required - The low-resolution image file to enhance. - **api_key** (string) - Required - Your DeepStack API key. ### Request Example ```python import requests import base64 from PIL import Image from io import BytesIO image_data = open("low_res.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/enhance", files={"image": ("low_res.jpg", image_data)}, data={"api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **base64** (string) - The enhanced image as a base64-encoded JPEG string. - **width** (integer) - The width of the enhanced image. - **height** (integer) - The height of the enhanced image. - **duration** (float) - The time taken for the operation in seconds. #### Response Example ```json { "success": true, "base64": "", "width": 1200, "height": 632, "duration": 1.45 } ``` ``` -------------------------------- ### Custom Model Inference Source: https://context7.com/johnolafenwa/deepstack/llms.txt Runs inference against a user-deployed custom YOLOv5 model. ```APIDOC ## POST /v1/vision/custom/{model_name} ### Description Runs inference against a user-deployed custom YOLOv5 model (`.pt` file). Models are loaded from the `MODELSTORE-DETECTION` directory at startup; each `.pt` file registers a route at `/v1/vision/custom/`. Returns predictions in the same format as the built-in detection endpoint. ### Method POST ### Endpoint /v1/vision/custom/{model_name} ### Parameters #### Path Parameters - **model_name** (string) - Required - The name of the custom model (filename without extension). #### Form Data - **image** (file) - Required - The image file to analyze. - **min_confidence** (float) - Optional - The minimum confidence threshold for predictions. - **api_key** (string) - Required - Your DeepStack API key. ### Request Example ```python import requests # Assumes a model file "mask_detector.pt" is in the modelstore directory image_data = open("person_wearing_mask.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/custom/mask_detector", files={"image": ("person_wearing_mask.jpg", image_data)}, data={"min_confidence": 0.5, "api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **predictions** (array) - A list of prediction objects. - **label** (string) - The predicted object label. - **confidence** (float) - The confidence score for the prediction. - **x_min** (integer) - The minimum x-coordinate of the bounding box. - **y_min** (integer) - The minimum y-coordinate of the bounding box. - **x_max** (integer) - The maximum x-coordinate of the bounding box. - **y_max** (integer) - The maximum y-coordinate of the bounding box. - **duration** (float) - The time taken for the operation in seconds. #### Response Example ```json { "success": true, "predictions": [ {"label": "mask", "confidence": 0.97, "x_min": 80, "y_min": 20, "x_max": 160, "y_max": 130}, {"label": "no_mask", "confidence": 0.89, "x_min": 250, "y_min": 15, "x_max": 340, "y_max": 125} ], "duration": 0.098 } ``` ``` -------------------------------- ### Face Detection API Request (Python) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Sends an image to the DeepStack face detection API and retrieves face coordinates. The Python script uses the 'requests' library to post image data and an optional 'min_confidence' threshold. The response includes confidence scores and bounding box coordinates for detected faces. ```python import requests image_data = open("group_photo.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/face", files={"image": image_data}, data={"min_confidence": 0.6, "api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "predictions": [ # {"confidence": 0.98, "x_min": 45, "y_min": 30, "x_max": 120, "y_max": 140}, # {"confidence": 0.95, "x_min": 200, "y_min": 25, "x_max": 280, "y_max": 145} # ], # "duration": 0.085 ``` -------------------------------- ### Object Detection API Source: https://context7.com/johnolafenwa/deepstack/llms.txt Detects common objects in an image using a YOLOv5 model. Returns bounding boxes, class labels, and confidence scores. The default confidence threshold is 0.40. ```APIDOC ## POST /v1/vision/detection ### Description Detects up to 80 common objects (COCO classes) in an image using a YOLOv5 model. Returns bounding boxes, class labels, and confidence scores for each detected object. The default confidence threshold is `0.40`. ### Method POST ### Endpoint /v1/vision/detection ### Parameters #### Query Parameters - **min_confidence** (float) - Optional - Minimum confidence threshold for detected objects. - **api_key** (string) - Optional - API key for authentication. #### Request Body - **image** (file) - Required - The image file to process. ### Request Example ```bash curl -X POST http://localhost:80/v1/vision/detection \ -F "image=@street.jpg" \ -F "min_confidence=0.5" \ -F "api_key=mysecretkey" ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **predictions** (array) - An array of detected objects, each with: - **label** (string) - The class label of the detected object. - **confidence** (float) - The confidence score of the detection. - **x_min** (integer) - The minimum x-coordinate of the bounding box. - **y_min** (integer) - The minimum y-coordinate of the bounding box. - **x_max** (integer) - The maximum x-coordinate of the bounding box. - **y_max** (integer) - The maximum y-coordinate of the bounding box. - **duration** (float) - The time taken for the detection in seconds. #### Response Example ```json { "success": true, "predictions": [ {"label": "person", "confidence": 0.92, "x_min": 100, "y_min": 50, "x_max": 200, "y_max": 300}, {"label": "car", "confidence": 0.87, "x_min": 320, "y_min": 120, "x_max": 500, "y_max": 280} ], "duration": 0.123 } ``` ``` -------------------------------- ### Object Detection API Request (Python) Source: https://context7.com/johnolafenwa/deepstack/llms.txt Sends an image to the DeepStack object detection API and processes the results. The Python script uses the 'requests' library to send a POST request with image data and optional parameters like 'min_confidence' and 'api_key'. It then draws bounding boxes on the image based on the predictions. ```python import requests from PIL import Image, ImageDraw # Send image for object detection image_data = open("street.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/detection", files={"image": image_data}, data={"min_confidence": 0.5, "api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "predictions": [ # {"label": "person", "confidence": 0.92, "x_min": 100, "y_min": 50, "x_max": 200, "y_max": 300}, # {"label": "car", "confidence": 0.87, "x_min": 320, "y_min": 120, "x_max": 500, "y_max": 280} # ], # "duration": 0.123 # } if response["success"]: image = Image.open("street.jpg").convert("RGB") draw = ImageDraw.Draw(image) for obj in response["predictions"]: draw.rectangle( [(obj["x_min"], obj["y_min"]), (obj["x_max"], obj["y_max"])], outline="red", width=3 ) draw.text((obj["x_min"], obj["y_min"] - 12), f'{obj["label"]} {obj["confidence"]:.2f}') image.save("output.jpg") else: print("Error:", response.get("error")) ``` -------------------------------- ### Recognize Faces in an Image with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt This Python script sends an image to the face recognition API and processes the predictions. It identifies registered faces and flags unknown individuals. The `min_confidence` parameter can be adjusted to change the detection threshold. ```python import requests image_data = open("office_photo.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/face/recognize", files={"image": image_data}, data={"min_confidence": 0.6, "api_key": "mysecretkey"}, ).json() # Expected response: # { # "success": true, # "predictions": [ # {"userid": "Alice", "confidence": 0.91, "x_min": 45, "y_min": 30, "x_max": 120, "y_max": 140}, # {"userid": "unknown", "confidence": 0.00, "x_min": 200, "y_min": 25, "x_max": 280, "y_max": 145} # ], # "duration": 0.112 # } if response["success"]: for face in response["predictions"]: if face["userid"] != "unknown": print(f"Recognized: {face['userid']} (confidence: {face['confidence']:.2f})") else: print("Unknown person detected") ``` -------------------------------- ### API Security Source: https://context7.com/johnolafenwa/deepstack/llms.txt DeepStack supports API Key and Admin Key for authentication. The API Key protects inference endpoints, while the Admin Key protects model management and backup/restore endpoints. Both keys are passed as form fields. ```APIDOC ## API Security ### Description DeepStack supports two levels of key-based authentication: `api_key` for inference endpoints and `admin_key` for model management and backup/restore endpoints. Both keys are passed as form fields in every request. ### Authentication - **api_key** (string) - Used for vision inference endpoints. - **admin_key** (string) - Used for model management and backup/restore endpoints. ### Example Usage ```python import requests # Inference request with api_key response = requests.post( "http://localhost:80/v1/vision/detection", files={"image": open("photo.jpg", "rb").read()}, data={"api_key": "inference_key"}, ).json() # Admin request with admin_key admin_response = requests.post( "http://localhost:80/v1/vision/listmodels", data={"admin_key": "admin_key"}, ).json() ``` ``` -------------------------------- ### Face Detection API Source: https://context7.com/johnolafenwa/deepstack/llms.txt Detects faces in an image and returns bounding box coordinates for each face. Does not perform recognition. Default confidence threshold is 0.55. ```APIDOC ## POST /v1/vision/face ### Description Detects faces in an image and returns bounding box coordinates for each face. Does not perform recognition — use `/v1/vision/face/recognize` for identity matching. Default confidence threshold is `0.55`. ### Method POST ### Endpoint /v1/vision/face ### Parameters #### Query Parameters - **min_confidence** (float) - Optional - Minimum confidence threshold for detected faces. - **api_key** (string) - Optional - API key for authentication. #### Request Body - **image** (file) - Required - The image file to process. ### Request Example ```python import requests image_data = open("group_photo.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/face", files={"image": image_data}, data={"min_confidence": 0.6, "api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **predictions** (array) - An array of detected faces, each with: - **confidence** (float) - The confidence score of the detection. - **x_min** (integer) - The minimum x-coordinate of the bounding box. - **y_min** (integer) - The minimum y-coordinate of the bounding box. - **x_max** (integer) - The maximum x-coordinate of the bounding box. - **y_max** (integer) - The maximum y-coordinate of the bounding box. - **duration** (float) - The time taken for the detection in seconds. #### Response Example ```json { "success": true, "predictions": [ {"confidence": 0.98, "x_min": 45, "y_min": 30, "x_max": 120, "y_max": 140}, {"confidence": 0.95, "x_min": 200, "y_min": 25, "x_max": 280, "y_max": 145} ], "duration": 0.085 } ``` ``` -------------------------------- ### Classify Image Scene with cURL Source: https://context7.com/johnolafenwa/deepstack/llms.txt This cURL command sends an image to the DeepStack API for scene recognition. It requires the image file to be present. ```bash curl -X POST http://localhost:80/v1/vision/scene \ -F "image=@indoor_photo.jpg" \ -F "api_key=mysecretkey" # {"success":true,"label":"conference_room","confidence":0.87,"duration":0.065} ``` -------------------------------- ### Scene Recognition Source: https://context7.com/johnolafenwa/deepstack/llms.txt Classifies the overall scene depicted in an image, returning a single scene label and a confidence score. ```APIDOC ## POST /v1/vision/scene ### Description Classifies the overall scene depicted in an image, returning a single scene label (e.g., `"conference_room"`, `"beach"`, `"kitchen"`) and a confidence score. Requires `VISION-SCENE=True`. ### Method POST ### Endpoint /v1/vision/scene ### Parameters #### Form Data - **image** (file) - Required - The image file to analyze. - **api_key** (string) - Required - Your DeepStack API key. ### Request Example ```python import requests image_data = open("indoor_photo.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/scene", files={"image": ("indoor_photo.jpg", image_data)}, data={"api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **label** (string) - The classified scene label. - **confidence** (float) - The confidence score for the scene label. - **duration** (float) - The time taken for the operation in seconds. #### Response Example ```json { "success": true, "label": "conference_room", "confidence": 0.87, "duration": 0.065 } ``` ``` -------------------------------- ### Face Matching Source: https://context7.com/johnolafenwa/deepstack/llms.txt Compares exactly two face images and returns a similarity score between 0 and 1. A score above ~0.65 typically indicates the same person. No prior registration is required. ```APIDOC ## POST /v1/vision/face/match ### Description Compares exactly two face images and returns a similarity score between 0 and 1. A score above ~0.65 typically indicates the same person. No prior registration is required. ### Method POST ### Endpoint /v1/vision/face/match ### Parameters #### Form Data - **image1** (file) - Required - The first face image file. - **image2** (file) - Required - The second face image file. - **api_key** (string) - Optional - The API key for authentication. ### Request Example ```python import requests image1 = open("person_a_photo1.jpg", "rb").read() image2 = open("person_a_photo2.jpg", "rb").read() response = requests.post( "http://localhost:80/v1/vision/face/match", files={"image1": image1, "image2": image2}, data={"api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **similarity** (float) - The similarity score between the two faces (0 to 1). - **duration** (float) - The time taken to process the request in seconds. #### Response Example ```json { "success": true, "similarity": 0.82, "duration": 0.09 } ``` ``` -------------------------------- ### Match Two Faces with Python Source: https://context7.com/johnolafenwa/deepstack/llms.txt This code snippet compares two face images to determine similarity. It sends pairs of images to the face match API and prints the resulting similarity score. A score above approximately 0.65 typically indicates the same person. No prior registration is required. ```python import requests image1 = open("person_a_photo1.jpg", "rb").read() image2 = open("person_a_photo2.jpg", "rb").read() image3 = open("person_b_photo.jpg", "rb").read() # Same person — expect high similarity response = requests.post( "http://localhost:80/v1/vision/face/match", files={"image1": image1, "image2": image2}, data={"api_key": "mysecretkey"}, ).json() # Expected: {"success": true, "similarity": 0.82, "duration": 0.09} print("Same person similarity:", response["similarity"]) # e.g. 0.82 # Different people — expect low similarity response2 = requests.post( "http://localhost:80/v1/vision/face/match", files={"image1": image1, "image2": image3}, data={"api_key": "mysecretkey"}, ).json() print("Different person similarity:", response2["similarity"]) # e.g. 0.21 ``` -------------------------------- ### List Registered Faces Source: https://context7.com/johnolafenwa/deepstack/llms.txt Returns all `userid` values currently stored in the face embeddings database. ```APIDOC ## POST /v1/vision/face/list ### Description Returns all `userid` values currently stored in the face embeddings database. ### Method POST ### Endpoint /v1/vision/face/list ### Parameters #### Form Data - **api_key** (string) - Optional - The API key for authentication. ### Request Example ```python import requests response = requests.post( "http://localhost:80/v1/vision/face/list", data={"api_key": "mysecretkey"}, ).json() ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **faces** (array) - A list of registered user IDs. - **duration** (float) - The time taken to process the request in seconds. #### Response Example ```json { "success": true, "faces": ["Alice", "Bob", "Carol"], "duration": 0.002 } ``` ``` -------------------------------- ### Face Registration Source: https://context7.com/johnolafenwa/deepstack/llms.txt Registers one or more face images for a named user so they can later be recognized. The `userid` form field names the identity. Multiple images can be submitted in a single request for better recognition accuracy. Requires the face API to be enabled (`VISION-FACE=True`). ```APIDOC ## POST /v1/vision/face/register ### Description Registers one or more face images for a named user so they can later be recognized. The `userid` form field names the identity. Multiple images can be submitted in a single request for better recognition accuracy. Requires the face API to be enabled (`VISION-FACE=True`). ### Method POST ### Endpoint /v1/vision/face/register ### Parameters #### Form Data - **image** (file) - Required - The face image file. - **userid** (string) - Required - The name of the identity. - **api_key** (string) - Optional - The API key for authentication. ### Request Example ```bash curl -X POST http://localhost:80/v1/vision/face/register \ -F "image=@alice1.jpg" \ -F "userid=Alice" \ -F "api_key=mysecretkey" ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **message** (string) - A message confirming the action (e.g., "face added"). - **duration** (float) - The time taken to process the request in seconds. #### Response Example ```json { "success": true, "message": "face added", "duration": 0.04 } ``` ```