0
# High-Level Utilities
1

2
Convenient high-level functions for common workflows like loading models from URLs and downloading datasets directly without explicit workspace/project navigation. These utilities simplify common operations and provide shortcuts for frequent tasks.
3

4
## Capabilities
5

6
### Model Loading
7

8
Load models directly from Roboflow URLs without manually navigating the workspace/project hierarchy.
9

10
```python { .api }
11
def load_model(model_url):
12
    """
13
    High-level function to load Roboflow models from URLs.
14
    
15
    Parameters:
16
    - model_url: str - Model URL from app.roboflow.com or universe.roboflow.com
17
                      Format: "https://app.roboflow.com/workspace/project/version"
18
                      or: "https://universe.roboflow.com/workspace/project/version"
19
    
20
    Returns:
21
    InferenceModel - Model object ready for inference
22
    
23
    Raises:
24
    ValueError - If URL is not from a supported domain
25
    """
26
```
27

28
### Dataset Download
29

30
Download datasets directly from URLs without workspace/project navigation.
31

32
```python { .api }
33
def download_dataset(dataset_url, model_format, location=None):
34
    """
35
    High-level function to download data from Roboflow URLs.
36
    
37
    Parameters:
38
    - dataset_url: str - Dataset URL from app.roboflow.com or universe.roboflow.com
39
                        Format: "https://app.roboflow.com/workspace/project/version"
40
                        or: "https://universe.roboflow.com/workspace/project/version"
41
    - model_format: str - Format to download dataset in ("yolov8", "yolov5", "pascal_voc", "coco", etc.)
42
    - location: str, optional - Directory to download to (default: current directory)
43
    
44
    Returns:
45
    Dataset - Dataset object with location information
46
    
47
    Raises:
48
    ValueError - If URL is not from a supported domain
49
    """
50
```
51

52
## Usage Examples
53

54
### Loading Models from URLs
55

56
```python
57
import roboflow
58

59
# Load model directly from app.roboflow.com URL
60
model = roboflow.load_model("https://app.roboflow.com/my-workspace/my-project/1")
61

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

66
# Load from Universe (public models)
67
public_model = roboflow.load_model("https://universe.roboflow.com/roboflow/microsoft-coco/1")
68
prediction = public_model.predict("test_image.jpg")
69
```
70

71
### Downloading Datasets from URLs
72

73
```python
74
import roboflow
75

76
# Download dataset in YOLO format
77
dataset = roboflow.download_dataset(
78
    dataset_url="https://app.roboflow.com/my-workspace/my-project/2",
79
    model_format="yolov8",
80
    location="./datasets"
81
)
82

83
print(f"Dataset downloaded to: {dataset.location}")
84

85
# Download public dataset from Universe
86
public_dataset = roboflow.download_dataset(
87
    dataset_url="https://universe.roboflow.com/roboflow/microsoft-coco/1", 
88
    model_format="coco",
89
    location="./public_datasets"
90
)
91

92
# Download in different formats
93
pascal_dataset = roboflow.download_dataset(
94
    dataset_url="https://app.roboflow.com/my-workspace/my-project/1",
95
    model_format="pascal_voc"
96
)
97
```
98

99
### Combining with Training Workflows
100

101
```python
102
import roboflow
103

104
# Download dataset and train model in one workflow
105
dataset = roboflow.download_dataset(
106
    dataset_url="https://app.roboflow.com/my-workspace/my-project/1",
107
    model_format="yolov8",
108
    location="./training_data"
109
)
110

111
# Use the dataset location for training
112
# (Note: This requires additional YOLOv8 training code)
113
print(f"Training data ready at: {dataset.location}")
114

115
# Or load pre-trained model for inference
116
model = roboflow.load_model("https://app.roboflow.com/my-workspace/my-project/1")
117
prediction = model.predict("new_image.jpg")
118
```
119

120
### URL Format Validation
121

122
```python
123
import roboflow
124

125
# Valid URLs - these will work
126
valid_urls = [
127
    "https://app.roboflow.com/workspace/project/1",
128
    "https://universe.roboflow.com/user/project/2",
129
    "https://app.roboflow.com/my-team/detection-project/3"
130
]
131

132
# Invalid URLs - these will raise ValueError
133
invalid_urls = [
134
    "https://example.com/project/1",           # Wrong domain
135
    "https://app.roboflow.com/project",        # Missing version
136
    "https://roboflow.com/workspace/project/1" # Wrong subdomain
137
]
138

139
try:
140
    model = roboflow.load_model("https://example.com/project/1")
141
except ValueError as e:
142
    print(f"Invalid URL: {e}")
143
```
144

145
### Batch Operations
146

147
```python
148
import roboflow
149

150
# Download multiple datasets
151
dataset_urls = [
152
    "https://app.roboflow.com/workspace/cars/1",
153
    "https://app.roboflow.com/workspace/people/2", 
154
    "https://app.roboflow.com/workspace/animals/1"
155
]
156

157
datasets = []
158
for url in dataset_urls:
159
    dataset = roboflow.download_dataset(
160
        dataset_url=url,
161
        model_format="yolov8",
162
        location=f"./datasets/{url.split('/')[-2]}"  # Use project name as folder
163
    )
164
    datasets.append(dataset)
165

166
print(f"Downloaded {len(datasets)} datasets")
167

168
# Load multiple models for ensemble inference
169
model_urls = [
170
    "https://app.roboflow.com/workspace/detector-v1/3",
171
    "https://app.roboflow.com/workspace/detector-v2/1"
172
]
173

174
models = []
175
for url in model_urls:
176
    model = roboflow.load_model(url)
177
    models.append(model)
178

179
# Run ensemble predictions
180
image_path = "test_image.jpg"
181
predictions = []
182
for model in models:
183
    prediction = model.predict(image_path)
184
    predictions.append(prediction)
185

186
print(f"Got {len(predictions)} predictions from ensemble")
187
```
188

189
## URL Parsing
190

191
The utilities automatically parse URLs to extract workspace, project, and version information:
192

193
- **URL Structure**: `https://{subdomain}.roboflow.com/{workspace}/{project}/{version}`
194
- **Supported Subdomains**: `app` (private projects), `universe` (public projects)
195
- **Workspace**: Team or individual workspace identifier
196
- **Project**: Project name within the workspace
197
- **Version**: Dataset/model version number
198

199
## Authentication
200

201
These utilities use the same authentication as the main SDK:
202

203
```python
204
import roboflow
205

206
# Set API key for private models/datasets
207
roboflow.Roboflow(api_key="your_api_key")
208

209
# Now utilities will use the authenticated session
210
model = roboflow.load_model("https://app.roboflow.com/private-workspace/project/1")
211

212
# Public Universe models don't require authentication
213
public_model = roboflow.load_model("https://universe.roboflow.com/roboflow/coco/1")
214
```
215

216
## Error Handling
217

218
The utilities provide clear error messages for common issues:
219

220
```python
221
import roboflow
222

223
try:
224
    # Invalid domain
225
    model = roboflow.load_model("https://example.com/workspace/project/1")
226
except ValueError as e:
227
    print(f"URL error: {e}")
228

229
try:
230
    # Invalid format
231
    dataset = roboflow.download_dataset(
232
        "https://app.roboflow.com/workspace/project/1",
233
        "invalid_format"
234
    )
235
except ValueError as e:
236
    print(f"Format error: {e}")
237

238
try:
239
    # Network/authentication error
240
    model = roboflow.load_model("https://app.roboflow.com/private/project/1")
241
except RuntimeError as e:
242
    print(f"Access error: {e}")
243
```
244

245
## Performance Tips
246

247
- **URL Validation**: URLs are validated before making API calls to catch errors early
248
- **Caching**: Consider caching downloaded models and datasets for repeated use
249
- **Authentication**: Set up authentication once to avoid repeated API key prompts
250
- **Location Management**: Use descriptive location paths to organize downloaded content
251

252
## Integration with Main SDK
253

254
These utilities work seamlessly with the main SDK:
255

256
```python
257
import roboflow
258

259
# Initialize SDK
260
rf = roboflow.Roboflow(api_key="your_api_key")
261

262
# Use utilities with authenticated session
263
model = roboflow.load_model("https://app.roboflow.com/workspace/project/1")
264

265
# Or access the same model through SDK
266
workspace = rf.workspace("workspace")
267
project = workspace.project("project")
268
version = project.version(1)
269
same_model = version.model
270

271
# Both models are equivalent
272
assert model.id == same_model.id
273
```