Skip to content

Commit 5e0f6b7

Browse files
zekeerbridge
zeke
and
erbridge
authored
revamp README (#70)
* revamp README Signed-off-by: Zeke Sikelianos <[email protected]> * Update README.md Co-authored-by: F <[email protected]> * Update README.md Co-authored-by: F <[email protected]> --------- Signed-off-by: Zeke Sikelianos <[email protected]> Co-authored-by: F <[email protected]>
1 parent ba9a4eb commit 5e0f6b7

File tree

1 file changed

+89
-77
lines changed

1 file changed

+89
-77
lines changed

Diff for: ‎README.md

+89-77
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,66 @@
11
# Replicate Python client
22

3-
This is a Python client for Replicate. It lets you run models from your Python code or Jupyter notebook, and do various other things on Replicate.
3+
This is a Python client for [Replicate](https://replicate.com). It lets you run models from your Python code or Jupyter notebook, and do various other things on Replicate.
44

5-
Grab your token from [replicate.com/account](https://replicate.com/account) and authenticate by setting it as an environment variable:
5+
## Install
6+
7+
```sh
8+
pip install replicate
9+
```
10+
11+
## Authenticate
12+
13+
Before running any Python scripts that use the API, you need to set your Replicate API token in your environment.
14+
15+
Grab your token from [replicate.com/account](https://replicate.com/account) and set it as an environment variable:
616

717
```
8-
export REPLICATE_API_TOKEN=[token]
18+
export REPLICATE_API_TOKEN=<your token>
919
```
1020

11-
You can run a model and get its output:
21+
We recommend not adding the token directly to your source code, because you don't want to put your credentials in source control. If anyone used your API key, their usage would be charged to your account.
22+
23+
## Run a model
24+
25+
Create a new Python file and add the following code:
1226

1327
```python
14-
$ python
15-
>>> import replicate
16-
>>> model = replicate.models.get("stability-ai/stable-diffusion")
17-
>>> version = model.versions.get("27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478")
18-
>>> version.predict(prompt="a 19th century portrait of a wombat gentleman")
19-
['https://replicate.com/api/models/stability-ai/stable-diffusion/files/50fcac81-865d-499e-81ac-49de0cb79264/out-0.png']
28+
import replicate
29+
model = replicate.models.get("stability-ai/stable-diffusion")
30+
version = model.versions.get("27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478")
31+
version.predict(prompt="a 19th century portrait of a wombat gentleman")
32+
33+
# ['https://replicate.com/api/models/stability-ai/stable-diffusion/files/50fcac81-865d-499e-81ac-49de0cb79264/out-0.png']
2034
```
2135

22-
Some models, like [replicate/resnet](/replicate/resnet), receive images as inputs. To pass a file as an input, use a file handle or URL
36+
Some models, like [methexis-inc/img2prompt](https://replicate.com/methexis-inc/img2prompt), receive images as inputs. To pass a file as an input, use a file handle or URL:
2337

2438
```python
25-
>>> model = replicate.models.get("replicate/resnet")
26-
>>> version = model.versions.get("dd782a3d531b61af491d1026434392e8afb40bfb53b8af35f727e80661489767")
27-
>>> version.predict(image=open("mystery.jpg", "rb"))
28-
[['n02123597', 'Siamese_cat', 0.8829364776611328],
29-
['n02123394', 'Persian_cat', 0.09810526669025421],
30-
['n02123045', 'tabby', 0.005758069921284914]]
39+
model = replicate.models.get("methexis-inc/img2prompt")
40+
version = model.versions.get("50adaf2d3ad20a6f911a8a9e3ccf777b263b8596fbd2c8fc26e8888f8a0edbb5")
41+
inputs = {
42+
"image": open("path/to/mystery.jpg", "rb"),
43+
}
44+
output = version.predict(**inputs)
45+
46+
# [['n02123597', 'Siamese_cat', 0.8829364776611328],
47+
# ['n02123394', 'Persian_cat', 0.09810526669025421],
48+
# ['n02123045', 'tabby', 0.005758069921284914]]
3149
```
3250

51+
## Compose models into a pipeline
52+
3353
You can run a model and feed the output into another model:
3454

3555
```python
36-
>>> laionide = replicate.models.get("afiaka87/laionide-v4").versions.get("b21cbe271e65c1718f2999b038c18b45e21e4fba961181fbfae9342fc53b9e05")
37-
>>> swinir = replicate.models.get("jingyunliang/swinir").versions.get("660d922d33153019e8c263a3bba265de882e7f4f70396546b6c9c8f9d47a021a")
38-
>>> image = laionide.predict(prompt="avocado armchair")
39-
>>> upscaled_image = swinir.predict(image=image)
56+
laionide = replicate.models.get("afiaka87/laionide-v4").versions.get("b21cbe271e65c1718f2999b038c18b45e21e4fba961181fbfae9342fc53b9e05")
57+
swinir = replicate.models.get("jingyunliang/swinir").versions.get("660d922d33153019e8c263a3bba265de882e7f4f70396546b6c9c8f9d47a021a")
58+
image = laionide.predict(prompt="avocado armchair")
59+
upscaled_image = swinir.predict(image=image)
4060
```
4161

62+
## Get output from a running model
63+
4264
Run a model and get its output while it's running:
4365

4466
```python
@@ -48,69 +70,77 @@ for image in version.predict(prompts="san francisco sunset"):
4870
display(image)
4971
```
5072

73+
## Run a model in the background
74+
5175
You can start a model and run it in the background:
5276

5377
```python
54-
>>> model = replicate.models.get("kvfrans/clipdraw")
55-
>>> version = model.versions.get("5797a99edc939ea0e9242d5e8c9cb3bc7d125b1eac21bda852e5cb79ede2cd9b")
56-
>>> prediction = replicate.predictions.create(
57-
... version=version,
58-
... input={"prompt":"Watercolor painting of an underwater submarine"})
78+
model = replicate.models.get("kvfrans/clipdraw")
79+
version = model.versions.get("5797a99edc939ea0e9242d5e8c9cb3bc7d125b1eac21bda852e5cb79ede2cd9b")
80+
prediction = replicate.predictions.create(
81+
version=version,
82+
input={"prompt":"Watercolor painting of an underwater submarine"})
5983

60-
>>> prediction
61-
Prediction(...)
84+
# >>> prediction
85+
# Prediction(...)
6286

63-
>>> prediction.status
64-
'starting'
87+
# >>> prediction.status
88+
# 'starting'
6589

66-
>>> dict(prediction)
67-
{"id": "...", "status": "starting", ...}
90+
# >>> dict(prediction)
91+
# {"id": "...", "status": "starting", ...}
6892

69-
>>> prediction.reload()
70-
>>> prediction.status
71-
'processing'
93+
# >>> prediction.reload()
94+
# >>> prediction.status
95+
# 'processing'
7296

73-
>>> print(prediction.logs)
74-
iteration: 0, render:loss: -0.6171875
75-
iteration: 10, render:loss: -0.92236328125
76-
iteration: 20, render:loss: -1.197265625
77-
iteration: 30, render:loss: -1.3994140625
97+
# >>> print(prediction.logs)
98+
# iteration: 0, render:loss: -0.6171875
99+
# iteration: 10, render:loss: -0.92236328125
100+
# iteration: 20, render:loss: -1.197265625
101+
# iteration: 30, render:loss: -1.3994140625
78102

79-
>>> prediction.wait()
103+
# >>> prediction.wait()
80104

81-
>>> prediction.status
82-
'succeeded'
105+
# >>> prediction.status
106+
# 'succeeded'
83107

84-
>>> prediction.output
85-
'https://.../output.png'
108+
# >>> prediction.output
109+
# 'https://.../output.png'
86110
```
87111

112+
## Cancel a prediction
113+
88114
You can cancel a running prediction:
89115

90116
```python
91-
>>> model = replicate.models.get("kvfrans/clipdraw")
92-
>>> version = model.versions.get("5797a99edc939ea0e9242d5e8c9cb3bc7d125b1eac21bda852e5cb79ede2cd9b")
93-
>>> prediction = replicate.predictions.create(
94-
... version=version,
95-
... input={"prompt":"Watercolor painting of an underwater submarine"})
117+
model = replicate.models.get("kvfrans/clipdraw")
118+
version = model.versions.get("5797a99edc939ea0e9242d5e8c9cb3bc7d125b1eac21bda852e5cb79ede2cd9b")
119+
prediction = replicate.predictions.create(
120+
version=version,
121+
input={"prompt":"Watercolor painting of an underwater submarine"})
96122

97-
>>> prediction.status
98-
'starting'
123+
# >>> prediction.status
124+
# 'starting'
99125

100-
>>> prediction.cancel()
126+
# >>> prediction.cancel()
101127

102-
>>> prediction.reload()
103-
>>> prediction.status
104-
'canceled'
128+
# >>> prediction.reload()
129+
# >>> prediction.status
130+
# 'canceled'
105131
```
106132

133+
## List predictions
134+
107135
You can list all the predictions you've run:
108136

109-
```
110-
>>> replicate.predictions.list()
111-
[<Prediction: 8b0ba5ab4d85>, <Prediction: 494900564e8c>]
137+
```python
138+
replicate.predictions.list()
139+
# [<Prediction: 8b0ba5ab4d85>, <Prediction: 494900564e8c>]
112140
```
113141

142+
## Load output files
143+
114144
Output files are returned as HTTPS URLs. You can load an output file as a buffer:
115145

116146
```python
@@ -124,24 +154,6 @@ urlretrieve(out[0], "/tmp/out.png")
124154
background = Image.open("/tmp/out.png")
125155
```
126156

127-
## Install
128-
129-
```sh
130-
pip install replicate
131-
```
132-
133-
## Authentication
134-
135-
Set the `REPLICATE_API_TOKEN` environment variable to your API token. For example, run this before running any Python scripts that use the API:
136-
137-
```
138-
export REPLICATE_API_TOKEN=<your token>
139-
```
140-
141-
We recommend not adding it directly to your source code, because you don't want to put your API in source control. If anyone uses your API key, their usage would be charged to your account.
142-
143-
If you have access to the API, [you can find your API key on your dashboard when signed in](https://replicate.com).
144-
145157
## Development
146158

147159
See [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)