Roboflow Inference

Common errors

• inference.core.exceptions.InferenceException: 401: Unauthorized

  cause The provided `ROBOFLOW_API_KEY` is either missing, incorrect, or expired.
  fix Set the `ROBOFLOW_API_KEY` environment variable with a valid key from your Roboflow dashboard, or pass it explicitly when initializing `InferenceHTTPClient`.

• No module named 'torch'

  cause You are attempting to use the `inference-gpu` package but PyTorch (torch) is not installed in your Python environment.
  fix First install PyTorch with CUDA support corresponding to your system (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`), then install `inference-gpu`.

• inference.core.exceptions.InferenceException: 404: Not Found (Model 'your_project/1' does not exist)

  cause The `model_id` provided to `client.infer()` is incorrect or refers to a project/version that does not exist or is not public/shared with your API key.
  fix Double-check the `model_id` format (e.g., `"my-project/1"`) and ensure the project and version are correct and accessible with your API key.

• Model loading failures due to environment constrains violated

  cause This error, often seen in local inference setups, indicates that the local environment (e.g., CPU, RAM, specific dependencies) does not meet the requirements for the model being loaded.
  fix Review your local environment's specifications against the model's requirements. For complex models, consider using cloud inference or ensuring all necessary local dependencies (like specific CUDA versions or libraries) are correctly installed.

• FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/local/image.jpg'

  cause The `image_path` provided to `client.infer()` is a local file path that does not exist or is inaccessible.
  fix Ensure the local file path is correct and the image file exists at that location. If using a URL, ensure it's a valid and accessible URL.

Warnings

• breaking Starting with v1.2.0, the `inference-models` engine became the default backend for running predictions. While the old inference backend is still available in opt-out mode, users might experience changes in behavior or performance if they relied on the previous default.
  Fix: Review the `inference-models` documentation for any required code adjustments or explicitly opt-out to use the old backend if necessary (refer to official documentation for opting out).
• deprecated Python 3.9 support was deprecated starting with the v1.1.0 release. Users on Python 3.9 might encounter issues or lack of future updates.
  Fix: Upgrade your Python environment to Python 3.10 or higher. The library officially supports Python >=3.10, <3.13.
• gotcha For GPU acceleration using `inference-gpu`, PyTorch and torchvision with CUDA support must be installed *prior* to installing `inference-gpu`. Simply `pip install inference-gpu` will not install PyTorch automatically for GPU.
  Fix: Install `torch`, `torchvision`, and `torchaudio` with the correct CUDA version first (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`), then install `inference-gpu` (`pip install inference-gpu`).
• gotcha Authentication requires `ROBOFLOW_API_KEY` to be set, typically as an environment variable or passed directly to the `InferenceHTTPClient`. Missing or incorrect keys will result in 'Unauthorized' errors.
  Fix: Ensure `ROBOFLOW_API_KEY` is correctly set in your environment or passed as an argument to `InferenceHTTPClient`. You can obtain your API key from your Roboflow dashboard settings.
• gotcha When using `InferenceHTTPClient.infer()`, the `model_id` parameter expects a string in the format `project_id/version_number` (e.g., 'my-project/1'). Incorrect formatting or non-existent project/version will lead to 'Not Found' errors.
  Fix: Verify the `model_id` string matches your Roboflow project ID and model version exactly. You can find this information on your Roboflow project page.

Install

• pip install inference For CPU inference (default)
• pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 && pip install inference-gpu For GPU inference (e.g., CUDA 11.8)

Imports

• InferenceHTTPClient

  from inference import InferenceHTTPClient

• Camera

  from inference.core.interfaces.camera import Camera

  Used for processing live camera streams.
• Roboflow

  from inference.core.models.roboflow import Roboflow

  Used for loading models directly from Roboflow for local inference, alternative to InferenceHTTPClient.

Quickstart

This quickstart demonstrates how to perform object detection using Roboflow's cloud inference service. It initializes `InferenceHTTPClient` with an API key and then sends an image URL for inference. Ensure your `ROBOFLOW_API_KEY` and `ROBOFLOW_PROJECT_VERSION` environment variables are set.

import os
from inference import InferenceHTTPClient

# IMPORTANT: Set ROBOFLOW_API_KEY, ROBOFLOW_WORKSPACE, and ROBOFLOW_PROJECT_VERSION
# as environment variables for actual use. Get them from your Roboflow dashboard.
# For local testing, you may uncomment and set these directly:
# os.environ["ROBOFLOW_API_KEY"] = "YOUR_API_KEY" 
# os.environ["ROBOFLOW_WORKSPACE"] = "YOUR_WORKSPACE_ID"
# os.environ["ROBOFLOW_PROJECT_VERSION"] = "YOUR_PROJECT_ID/YOUR_VERSION" # e.g., "my-project/1"

api_key = os.environ.get("ROBOFLOW_API_KEY", "")
workspace = os.environ.get("ROBOFLOW_WORKSPACE", "")
project_version = os.environ.get("ROBOFLOW_PROJECT_VERSION", "your_project/1") # Replace with your actual project/version

if not api_key:
    print("WARNING: ROBOFLOW_API_KEY environment variable not set. Inference may fail.")
if not workspace:
    print("WARNING: ROBOFLOW_WORKSPACE environment variable not set. This may not be critical for HTTPClient but is for other features.")
if project_version == "your_project/1":
    print("WARNING: ROBOFLOW_PROJECT_VERSION environment variable not set. Using placeholder.")


try:
    # Initialize the client for cloud inference
    client = InferenceHTTPClient(
        api_url="https://detect.roboflow.com", # Or https://infer.roboflow.com for multi-model workflows
        api_key=api_key
    )

    # Example image (replace with a real image path or URL)
    image_url = "https://i.ibb.co/L5hY63C/roboflow-example.jpg"

    # Perform inference
    print(f"Performing inference on {image_url} using model {project_version}...")
    result = client.infer(
        image_path=image_url,
        model_id=project_version,
        # confidence=0.5, # Optional: set confidence threshold
        # overlap=0.3,    # Optional: set NMS overlap threshold
    )

    print("\nInference successful:")
    # The result object has a .json() method for the raw API response
    # print(result.json(indent=2))

    # Accessing structured predictions
    if result and result.predictions:
        print(f"Found {len(result.predictions)} predictions.")
        for i, pred in enumerate(result.predictions[:3]): # Print details for first 3 predictions
            print(f"  Prediction {i+1}: Class='{pred.class_name}', Confidence={pred.confidence:.2f}, Box=({pred.x},{pred.y},{pred.width},{pred.height})")
    else:
        print("No predictions found or unexpected result structure.")

except Exception as e:
    print(f"\nAn error occurred during inference: {e}")
    if "401: Unauthorized" in str(e) or "authentication" in str(e):
        print("HINT: Check your ROBOFLOW_API_KEY. It might be missing or invalid.")
    elif "404: Not Found" in str(e) and ("Model" in str(e) or "project" in str(e)):
        print("HINT: Check your ROBOFLOW_PROJECT_VERSION. The model might not exist or the version is wrong.")
    else:
        print("HINT: Refer to the Roboflow Inference documentation for troubleshooting.")