0
# Models & Predictions
1

2
Comprehensive management of AI models, versions, and prediction lifecycle including creation, monitoring, cancellation, and output retrieval.
3

4
## Capabilities
5

6
### Model Management
7

8
Discover, retrieve, and manage AI models hosted on Replicate.
9

10
```python { .api }
11
class Models:
12
    def get(self, name: str) -> Model:
13
        """
14
        Get a model by name.
15

16
        Parameters:
17
        - name: Model name in format "owner/name"
18

19
        Returns:
20
        Model object with metadata and version access
21
        """
22

23
    def list(self, **params) -> Page[Model]:
24
        """
25
        List models.
26

27
        Returns:
28
        Paginated list of Model objects
29
        """
30

31
    def search(self, query: str, **params) -> Page[Model]:
32
        """
33
        Search for models.
34

35
        Parameters:
36
        - query: Search query string
37

38
        Returns:
39
        Paginated list of matching Model objects
40
        """
41

42
    def create(
43
        self,
44
        owner: str,
45
        name: str,
46
        *,
47
        hardware: str,
48
        visibility: Literal["public", "private"],
49
        description: Optional[str] = None,
50
        github_url: Optional[str] = None,
51
        paper_url: Optional[str] = None,
52
        license_url: Optional[str] = None,
53
        cover_image_url: Optional[str] = None
54
    ) -> Model:
55
        """
56
        Create a new model.
57

58
        Parameters:
59
        - owner: Model owner username or organization
60
        - name: Model name
61
        - hardware: Hardware SKU for running the model
62
        - visibility: Model visibility (public or private)
63
        - description: Model description (optional)
64
        - github_url: GitHub source code URL (optional)
65
        - paper_url: Research paper URL (optional)
66
        - license_url: License URL (optional)
67
        - cover_image_url: Cover image URL (optional)
68

69
        Returns:
70
        Created Model object
71
        """
72

73
    async def async_create(
74
        self,
75
        owner: str,
76
        name: str,
77
        **params
78
    ) -> Model:
79
        """
80
        Create a new model asynchronously.
81

82
        Parameters same as create method.
83

84
        Returns:
85
        Created Model object
86
        """
87
```
88

89
### Model Objects
90

91
Models represent AI models with metadata, versions, and capabilities.
92

93
```python { .api }
94
class Model:
95
    url: str
96
    """The URL of the model."""
97

98
    owner: str
99
    """The owner of the model."""
100

101
    name: str
102
    """The name of the model."""
103

104
    description: Optional[str]
105
    """The description of the model."""
106

107
    visibility: Literal["public", "private"]
108
    """The visibility of the model."""
109

110
    github_url: Optional[str]
111
    """The GitHub URL of the model."""
112

113
    paper_url: Optional[str]
114
    """The URL of the paper related to the model."""
115

116
    license_url: Optional[str]
117
    """The URL of the license for the model."""
118

119
    run_count: int
120
    """The number of runs of the model."""
121

122
    cover_image_url: Optional[str]
123
    """The URL of the cover image for the model."""
124

125
    default_example: Optional[Prediction]
126
    """The default example of the model."""
127

128
    latest_version: Optional[Version]
129
    """The latest version of the model."""
130

131
    @property
132
    def id(self) -> str:
133
        """Return the qualified model name, in the format `owner/name`."""
134

135
    @property
136
    def versions(self) -> Versions:
137
        """Access to model versions."""
138
```
139

140
### Model Versions
141

142
Specific versions of models with schemas and prediction capabilities.
143

144
```python { .api }
145
class Version:
146
    id: str
147
    """The unique ID of the version."""
148

149
    created_at: str
150
    """When the version was created."""
151

152
    cog_version: Optional[str]
153
    """The version of Cog used to create this version."""
154

155
    openapi_schema: Optional[Dict[str, Any]]
156
    """The OpenAPI schema for the version."""
157

158
class Versions:
159
    def get(self, id: str) -> Version:
160
        """Get a specific version by ID."""
161

162
    def list(self, **params) -> Page[Version]:
163
        """List all versions for the model."""
164
```
165

166
### Prediction Management
167

168
Create, monitor, and manage prediction requests for model execution.
169

170
```python { .api }
171
class Predictions:
172
    def create(
173
        self,
174
        model: Optional[str] = None,
175
        version: Optional[str] = None,
176
        input: Optional[Dict[str, Any]] = None,
177
        *,
178
        stream: Optional[bool] = None,
179
        webhook: Optional[str] = None,
180
        webhook_events_filter: Optional[List[str]] = None,
181
        **params
182
    ) -> Prediction:
183
        """
184
        Create a new prediction.
185

186
        Parameters:
187
        - model: Model name in format "owner/name"
188
        - version: Specific version ID (optional if using latest)
189
        - input: Input parameters for the model
190
        - stream: Enable streaming output
191
        - webhook: Webhook URL for completion notification
192
        - webhook_events_filter: Events to trigger webhook
193

194
        Returns:
195
        Prediction object to monitor progress and retrieve output
196
        """
197

198
    def get(self, id: str) -> Prediction:
199
        """
200
        Get a prediction by ID.
201

202
        Parameters:
203
        - id: Prediction ID
204

205
        Returns:
206
        Prediction object with current status and output
207
        """
208

209
    def list(self, **params) -> Page[Prediction]:
210
        """
211
        List predictions.
212

213
        Returns:
214
        Paginated list of Prediction objects
215
        """
216

217
    def cancel(self, id: str) -> Prediction:
218
        """
219
        Cancel a running prediction.
220

221
        Parameters:
222
        - id: Prediction ID
223

224
        Returns:
225
        Updated Prediction object with canceled status
226
        """
227
```
228

229
### Prediction Objects
230

231
Predictions represent model execution requests with status, input, output, and metadata.
232

233
```python { .api }
234
class Prediction:
235
    id: str
236
    """The unique ID of the prediction."""
237

238
    model: str
239
    """Model identifier in format `owner/name`."""
240

241
    version: str
242
    """Version identifier used for prediction."""
243

244
    status: Literal["starting", "processing", "succeeded", "failed", "canceled"]
245
    """The status of the prediction."""
246

247
    input: Optional[Dict[str, Any]]
248
    """The input to the prediction."""
249

250
    output: Optional[Any]
251
    """The output of the prediction."""
252

253
    logs: Optional[str]
254
    """The logs of the prediction."""
255

256
    error: Optional[str]
257
    """The error encountered during the prediction, if any."""
258

259
    metrics: Optional[Dict[str, Any]]
260
    """Metrics for the prediction."""
261

262
    created_at: Optional[str]
263
    """When the prediction was created."""
264

265
    started_at: Optional[str]
266
    """When the prediction was started."""
267

268
    completed_at: Optional[str]
269
    """When the prediction was completed, if finished."""
270

271
    urls: Optional[Dict[str, str]]
272
    """URLs associated with the prediction (get, cancel)."""
273

274
    def wait(self, **params) -> "Prediction":
275
        """Wait for the prediction to complete."""
276

277
    def cancel(self) -> "Prediction":
278
        """Cancel the prediction."""
279

280
    def reload(self) -> "Prediction":
281
        """Reload the prediction from the API."""
282

283
    def stream(self) -> Iterator[ServerSentEvent]:
284
        """Stream the prediction output (if streaming enabled)."""
285

286
    @dataclass
287
    class Progress:
288
        """The progress of a prediction."""
289
        percentage: float
290
```
291

292
### Usage Examples
293

294
#### Basic Model Execution
295

296
```python
297
import replicate
298

299
# Simple model run
300
output = replicate.run(
301
    "stability-ai/stable-diffusion-3",
302
    input={"prompt": "An astronaut riding a rainbow unicorn"}
303
)
304

305
# Handle file output
306
if hasattr(output, 'read'):
307
    with open("output.png", "wb") as f:
308
        f.write(output.read())
309
```
310

311
#### Background Predictions
312

313
```python
314
import replicate
315

316
# Create background prediction
317
model = replicate.models.get("kvfrans/clipdraw")
318
version = model.versions.get("5797a99edc939ea0e9242d5e8c9cb3bc7d125b1eac21bda852e5cb79ede2cd9b")
319

320
prediction = replicate.predictions.create(
321
    version=version,
322
    input={"prompt": "Watercolor painting of an underwater submarine"}
323
)
324

325
# Monitor progress
326
print(f"Status: {prediction.status}")
327
print(f"Logs: {prediction.logs}")
328

329
# Wait for completion
330
prediction.wait()
331
print(f"Final status: {prediction.status}")
332

333
# Access output
334
if prediction.output:
335
    with open("output.png", "wb") as f:
336
        f.write(prediction.output.read())
337
```
338

339
#### Webhooks
340

341
```python
342
import replicate
343

344
# Create prediction with webhook
345
prediction = replicate.predictions.create(
346
    model="ai-forever/kandinsky-2.2",
347
    input={"prompt": "Watercolor painting of an underwater submarine"},
348
    webhook="https://example.com/your-webhook",
349
    webhook_events_filter=["completed"]
350
)
351
```
352

353
#### Model Pipelines
354

355
```python
356
import replicate
357

358
# Chain models together
359
laionide = replicate.models.get("afiaka87/laionide-v4")
360
swinir = replicate.models.get("jingyunliang/swinir")
361

362
# Generate image
363
image = laionide.latest_version.predict(prompt="avocado armchair")
364

365
# Upscale image
366
upscaled_image = swinir.latest_version.predict(image=image)
367
```
368

369
#### Listing and Searching
370

371
```python
372
import replicate
373

374
# List your predictions
375
predictions = replicate.predictions.list()
376
for prediction in predictions.results:
377
    print(f"ID: {prediction.id}, Status: {prediction.status}")
378

379
# Paginate through results
380
if predictions.next:
381
    next_page = replicate.predictions.list(predictions.next)
382

383
# Search for models
384
results = replicate.models.search("text-to-image")
385
for model in results.results:
386
    print(f"{model.owner}/{model.name}: {model.description}")
387
```
388

389
#### Cancellation
390

391
```python
392
import replicate
393

394
# Create and cancel prediction
395
prediction = replicate.predictions.create(
396
    model="kvfrans/clipdraw",
397
    input={"prompt": "Complex artwork"}
398
)
399

400
# Cancel if needed
401
if prediction.status in ["starting", "processing"]:
402
    prediction.cancel()
403
    print("Prediction canceled")
404
```