Run a model from Python

Learn how to run a model on Replicate from within your Python code. It could be an app, a notebook, an evaluation script, or anywhere else you want to use machine learning.

Install the Python library

We maintain an open-source Python client for the API. Install it with pip:

pip install replicate


Authenticate by setting your token in an environment variable:

export REPLICATE_API_TOKEN=<token>

Find your API token on the account page.

Run predictions

You can run any public model on Replicate from your Python code. The following example runs stability-ai/stable-diffusion:

$ python
>>> import replicate
>>> model = replicate.models.get("stability-ai/stable-diffusion")
>>> model.predict(prompt="a 19th century portrait of a wombat gentleman")

Some models, like replicate/resnet in the following example, receive images as inputs. To pass a file as an input, use a file handle or URL:

>>> model = replicate.models.get("replicate/resnet")
>>> model.predict(image=open("mystery.jpg", "rb"))
# or...
>>> model.predict(image="")

URLs are more efficient if your file is already in the cloud somewhere, or it is a large file. Files are output as URLs.

Some models output progressively, as the model is running. They will return an iterator, and you can iterate over that output:

>>> model = replicate.models.get("pixray/text2image")
>>> for image in model.predict(prompts="robots talking to robots"):
...    print(image)

By default, model.predict() uses the latest version. If you're running a model in production, you should pin to a particular version to ensure its API or behavior doesn't change.

If you want to pin to a particular version, you can get a version with its ID, then call the predict() method on that version:

>>> model = replicate.models.get("replicate/hello-world")
>>> version = model.versions.get("5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa")
>>> version.predict(text="python")
"hello python"

Next steps

Read the full Python client documentation on GitHub.

You can also run models with the raw HTTP API. Refer to the HTTP API reference for more details.