0
# Roboflow
1

2
The official Python SDK for working with the Roboflow computer vision platform. This package enables developers to create and manage machine learning projects, upload images and annotations, train vision models, and run inference on hosted or self-hosted models. It provides a comprehensive API for workspace, project, and version management following Roboflow's hierarchical structure.
3

4
## Package Information
5

6
- **Package Name**: roboflow
7
- **Language**: Python
8
- **Installation**: `pip install roboflow`
9

10
## Core Imports
11

12
```python
13
import roboflow
14
```
15

16
Primary entry point:
17

18
```python
19
from roboflow import Roboflow
20
```
21

22
High-level utility functions:
23

24
```python
25
from roboflow import (
26
    login,
27
    initialize_roboflow, 
28
    load_model,
29
    download_dataset
30
)
31
```
32

33
Specialized model imports:
34

35
```python
36
from roboflow import CLIPModel, GazeModel
37
```
38

39
## Basic Usage
40

41
```python
42
import roboflow
43

44
# Authenticate and create client
45
rf = roboflow.Roboflow(api_key="your_api_key")
46

47
# Access your workspace
48
workspace = rf.workspace()
49

50
# Get a project
51
project = workspace.project("your-project-name")
52

53
# Get a specific version
54
version = project.version(1)
55

56
# Download dataset
57
dataset = version.download("yolov8")
58

59
# Train a model
60
model = version.train()
61

62
# Run inference
63
prediction = model.predict("path/to/image.jpg")
64
```
65

66
## Architecture
67

68
The Roboflow SDK follows a hierarchical structure that mirrors the Roboflow platform organization:
69

70
- **Roboflow**: Main client providing authentication and workspace access
71
- **Workspace**: Container for projects and team management
72
- **Project**: Individual computer vision project with multiple versions
73
- **Version**: Specific dataset version with training capability
74
- **Model**: Trained model for running inference
75

76
The SDK supports various computer vision tasks including object detection, classification, instance segmentation, semantic segmentation, and keypoint detection, with specialized model classes for each task type.
77

78
## Capabilities
79

80
### Authentication and Initialization
81

82
Core authentication functionality for accessing the Roboflow platform, including API key validation, workspace configuration, and CLI-based login flows.
83

84
```python { .api }
85
class Roboflow:
86
    def __init__(self, api_key=None, model_format="undefined", notebook="undefined"): ...
87
    def workspace(self, the_workspace=None): ...
88
    def project(self, project_name, the_workspace=None): ...
89

90
def login(workspace=None, force=False): ...
91
def initialize_roboflow(the_workspace=None): ...
92
def check_key(api_key, model, notebook, num_retries=0): ...
93
```
94

95
[Authentication](./authentication.md)
96

97
### Workspace Management
98

99
Comprehensive workspace operations including project listing, creation, dataset uploads, and advanced workflows like active learning and CLIP-based image comparison.
100

101
```python { .api }
102
class Workspace:
103
    def __init__(self, info, api_key, default_workspace, model_format): ...
104
    def list_projects(self): ...
105
    def project(self, project_id): ...
106
    def create_project(self, project_name, project_type, project_license, annotation): ...
107
    def upload_dataset(self, dataset_path, project_name, num_workers=10, dataset_format="NOT_USED", project_license="MIT", project_type="object-detection", batch_name=None, num_retries=0): ...
108
```
109

110
[Workspace Management](./workspace-management.md)
111

112
### Project Operations
113

114
Project-level operations including version management, training, image uploads, annotation handling, and search functionality.
115

116
```python { .api }
117
class Project:
118
    def __init__(self, api_key: str, a_project: dict, model_format: Optional[str] = None): ...
119
    def version(self, version_number: int, local: Optional[str] = None): ...
120
    def versions(self): ...
121
    def generate_version(self, settings): ...
122
    def train(self, new_version_settings=None, speed=None, checkpoint=None, plot_in_notebook=False): ...
123
    def upload_image(self, image_path, hosted_image=False, image_id=None, split="train", batch_name=None, tag_names=[], inference=None, overwrite=False): ...
124
    def image(self, image_id: str): ...
125
    def get_batches(self): ...
126
    def get_batch(self, batch_id: str): ...
127
    def create_annotation_job(self, batch_id: str, annotator_email: str): ...
128
```
129

130
[Project Operations](./project-operations.md)
131

132
### Dataset Versions
133

134
Dataset version management including downloads, exports, training, and deployment of specific dataset versions.
135

136
```python { .api }
137
class Version:
138
    def __init__(self, version_data, project_info, model_format, api_key, name, local=None): ...
139
    def download(self, model_format=None, location=None, overwrite: bool = False): ...
140
    def export(self, model_format=None): ...
141
    def train(self, speed=None, model_type=None, checkpoint=None, plot_in_notebook=False): ...
142
    def deploy(self, model_type: str, model_path: str, filename: str = "weights/best.pt"): ...
143
```
144

145
[Dataset Versions](./dataset-versions.md)
146

147
### Model Inference
148

149
Comprehensive inference capabilities across different computer vision tasks, supporting both image and video inputs with various specialized model types.
150

151
```python { .api }
152
class InferenceModel:
153
    def __init__(self, api_key, version_id, colors=None, *args, **kwargs): ...
154
    def predict(self, image_path, prediction_type=None, **kwargs): ...
155
    def predict_video(self, video_path, fps=1, prediction_type=None, **kwargs): ...
156
    def download(self, format="pt", location="."): ...
157

158
# Specialized model classes
159
class ObjectDetectionModel(InferenceModel): ...
160
class ClassificationModel(InferenceModel): ...
161
class InstanceSegmentationModel(InferenceModel): ...
162
class SemanticSegmentationModel(InferenceModel): ...
163
class KeypointDetectionModel(InferenceModel): ...
164
class CLIPModel(InferenceModel): ...
165
class GazeModel(InferenceModel): ...
166
```
167

168
[Model Inference](./model-inference.md)
169

170
### High-Level Utilities
171

172
Convenient high-level functions for common workflows like loading models from URLs and downloading datasets directly without explicit workspace/project navigation.
173

174
```python { .api }
175
def load_model(model_url): ...
176
def download_dataset(dataset_url, model_format, location=None): ...
177
```
178

179
[High-Level Utilities](./high-level-utilities.md)
180

181
## Exception Handling
182

183
The SDK defines several exception classes for error handling:
184

185
```python { .api }
186
class RoboflowError(Exception): ...
187
class ImageUploadError(RoboflowError): ...
188
class AnnotationSaveError(RoboflowError): ...
189
class DeploymentApiError(Exception): ...
190
```
191

192
Most methods can raise `RoboflowError` or its subclasses on API failures, authentication issues, or invalid parameters. Always wrap API calls in try-catch blocks for production usage.