Skip to content

Commit 51d6fad

Browse files
zekezeke
authored
docs: Spruce up README (#85)
* manual readme sprucing * Revise and expand documentation for `replicate.use()` Replaces the experimental section on `replicate.use()` with a more detailed and updated guide, including usage examples for image and language models, streaming, chaining, async support, accessing URLs, and prediction creation. Removes references to the API being experimental and updates model examples to use Anthropic Claude instead of Meta Llama.
1 parent c7424c5 commit 51d6fad

File tree

1 file changed

+164
-149
lines changed

1 file changed

+164
-149
lines changed

‎README.md‎

Lines changed: 164 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,193 @@
1-
# Replicate Python API library
1+
# Replicate Python API SDK
22

33
<!-- prettier-ignore -->
44
[![PyPI version](https://img.shields.io/pypi/v/replicate.svg?label=pypi%20(stable))](https://pypi.org/project/replicate/)
55

6-
The Replicate Python library provides convenient access to the Replicate REST API from any Python 3.8+
7-
application. The library includes type definitions for all request params and response fields,
8-
and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
6+
This is the repo for Replicate's official v2 Python SDK, which provides access to Replicate's HTTP API from any Python 3.8+
7+
application.
98

10-
It is generated with [Stainless](https://www.stainless.com/).
9+
## Docs
1110

12-
## Documentation
11+
- https://sdks.replicate.com/python
12+
- https://replicate.com/docs/reference/http
1313

14-
The REST API documentation can be found on [replicate.com](https://replicate.com/docs/reference/http). The full API of this library can be found in [api.md](api.md).
1514

1615
## Installation
1716

17+
The [`replicate`](https://pypi.org/project/replicate/) package is available on PyPI. Install it with [pip](https://pip.pypa.io/en/stable/):
18+
1819
```sh
19-
# install from PyPI
2020
pip install --pre replicate
2121
```
2222

2323
## Usage
2424

25-
The full API of this library can be found in [api.md](api.md).
25+
Start by getting a [Replicate API token](https://replicate.com/account/api-tokens), then set it as `REPLICATE_API_TOKEN` in your environment:
26+
27+
```sh
28+
export REPLICATE_API_TOKEN="r8_..."
29+
```
30+
31+
Then in your Python code, import the library and use it:
32+
33+
```python
34+
import replicate
35+
36+
claude = replicate.use("anthropic/claude-4.5-sonnet")
37+
seedream = replicate.use("bytedance/seedream-4")
38+
veo = replicate.use("google/veo-3-fast")
39+
40+
# Enhance a simple prompt
41+
image_prompt = claude(prompt="bananas wearing cowboy hats", system_prompt="turn prompts into image prompts")
42+
43+
# Generate an image from the enhanced prompt
44+
images = seedream(prompt=image_prompt)
45+
46+
# Generate a video from the image
47+
video = veo(prompt="dancing bananas", image_input=images[0])
48+
49+
open(video)
50+
```
51+
52+
### Initialization and authentication
53+
54+
The library uses the `REPLICATE_API_TOKEN` environment variable by default to implicitly initialize a client, but you can also initialize a client explicitly and set the `bearer_token` parameter:
2655

2756
```python
2857
import os
2958
from replicate import Replicate
3059

31-
replicate = Replicate(
32-
bearer_token=os.environ.get("REPLICATE_API_TOKEN"), # This is the default and can be omitted
60+
client = Replicate(
61+
bearer_token=os.environ.get("REPLICATE_API_TOKEN")
3362
)
63+
```
64+
65+
## Using `replicate.use()`
66+
67+
The `use()` method provides a more concise way to call Replicate models as functions, offering a more pythonic approach to running models:
68+
69+
```python
70+
import replicate
3471

35-
prediction = replicate.predictions.get(
36-
prediction_id="gm3qorzdhgbfurvjtvhg6dckhu",
72+
# Create a model function
73+
flux_dev = replicate.use("black-forest-labs/flux-dev")
74+
75+
# Call it like a regular Python function
76+
outputs = flux_dev(
77+
prompt="a cat wearing a wizard hat, digital art",
78+
num_outputs=1,
79+
aspect_ratio="1:1",
80+
output_format="webp",
3781
)
38-
print(prediction.id)
82+
83+
# outputs is a list of URLPath objects that auto-download when accessed
84+
for output in outputs:
85+
print(output) # e.g., Path(/tmp/a1b2c3/output.webp)
86+
```
87+
88+
### Language models with streaming
89+
90+
Many models, particularly language models, support streaming output. Use the `streaming=True` parameter to get results as they're generated:
91+
92+
```python
93+
import replicate
94+
95+
# Create a streaming language model function
96+
claude = replicate.use("anthropic/claude-4.5-sonnet", streaming=True)
97+
98+
# Stream the output
99+
output = claude(prompt="Write a haiku about Python programming", max_tokens=50)
100+
101+
for chunk in output:
102+
print(chunk, end="", flush=True)
39103
```
40104

41-
While you can provide a `bearer_token` keyword argument,
42-
we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
43-
to add `REPLICATE_API_TOKEN="My Bearer Token"` to your `.env` file
44-
so that your Bearer Token is not stored in source control.
105+
### Chaining models
106+
107+
You can easily chain models together by passing the output of one model as input to another:
108+
109+
```python
110+
import replicate
111+
112+
# Create two model functions
113+
flux_dev = replicate.use("black-forest-labs/flux-dev")
114+
claude = replicate.use("anthropic/claude-4.5-sonnet")
115+
116+
# Generate an image
117+
images = flux_dev(prompt="a mysterious ancient artifact")
118+
119+
# Describe the image
120+
description = claude(
121+
prompt="Describe this image in detail",
122+
image=images[0], # Pass the first image directly
123+
)
124+
125+
print(description)
126+
```
127+
128+
### Async support
129+
130+
For async/await patterns, use the `use_async=True` parameter:
131+
132+
```python
133+
import asyncio
134+
import replicate
135+
136+
137+
async def main():
138+
# Create an async model function
139+
flux_dev = replicate.use("black-forest-labs/flux-dev", use_async=True)
140+
141+
# Await the result
142+
outputs = await flux_dev(prompt="futuristic city at sunset")
143+
144+
for output in outputs:
145+
print(output)
146+
147+
148+
asyncio.run(main())
149+
```
150+
151+
### Accessing URLs without downloading
152+
153+
If you need the URL without downloading the file, use the `get_path_url()` helper:
154+
155+
```python
156+
import replicate
157+
from replicate.lib._predictions_use import get_path_url
158+
159+
flux_dev = replicate.use("black-forest-labs/flux-dev")
160+
outputs = flux_dev(prompt="a serene landscape")
161+
162+
for output in outputs:
163+
url = get_path_url(output)
164+
print(f"URL: {url}") # https://replicate.delivery/...
165+
```
166+
167+
### Creating predictions without waiting
168+
169+
To create a prediction without waiting for it to complete, use the `create()` method:
170+
171+
```python
172+
import replicate
173+
174+
claude = replicate.use("anthropic/claude-4.5-sonnet")
175+
176+
# Start the prediction
177+
run = claude.create(prompt="Explain quantum computing")
178+
179+
# Check logs while it's running
180+
print(run.logs())
181+
182+
# Get the output when ready
183+
result = run.output()
184+
print(result)
185+
```
186+
187+
### Current limitations
188+
189+
- The `use()` method must be called at the module level (not inside functions or classes)
190+
- Type hints are limited compared to the standard client interface
45191

46192
## Run a model
47193

@@ -516,137 +662,6 @@ with Replicate() as replicate:
516662
# HTTP client is now closed
517663
```
518664

519-
## Experimental: Using `replicate.use()`
520-
521-
> [!WARNING]
522-
> The `replicate.use()` interface is experimental and subject to change. We welcome your feedback on this new API design.
523-
524-
The `use()` method provides a more concise way to call Replicate models as functions. This experimental interface offers a more pythonic approach to running models:
525-
526-
```python
527-
import replicate
528-
529-
# Create a model function
530-
flux_dev = replicate.use("black-forest-labs/flux-dev")
531-
532-
# Call it like a regular Python function
533-
outputs = flux_dev(
534-
prompt="a cat wearing a wizard hat, digital art",
535-
num_outputs=1,
536-
aspect_ratio="1:1",
537-
output_format="webp",
538-
)
539-
540-
# outputs is a list of URLPath objects that auto-download when accessed
541-
for output in outputs:
542-
print(output) # e.g., Path(/tmp/a1b2c3/output.webp)
543-
```
544-
545-
### Language models with streaming
546-
547-
Many models, particularly language models, support streaming output. Use the `streaming=True` parameter to get results as they're generated:
548-
549-
```python
550-
import replicate
551-
552-
# Create a streaming language model function
553-
llama = replicate.use("meta/meta-llama-3-8b-instruct", streaming=True)
554-
555-
# Stream the output
556-
output = llama(prompt="Write a haiku about Python programming", max_tokens=50)
557-
558-
for chunk in output:
559-
print(chunk, end="", flush=True)
560-
```
561-
562-
### Chaining models
563-
564-
You can easily chain models together by passing the output of one model as input to another:
565-
566-
```python
567-
import replicate
568-
569-
# Create two model functions
570-
flux_dev = replicate.use("black-forest-labs/flux-dev")
571-
llama = replicate.use("meta/meta-llama-3-8b-instruct")
572-
573-
# Generate an image
574-
images = flux_dev(prompt="a mysterious ancient artifact")
575-
576-
# Describe the image
577-
description = llama(
578-
prompt="Describe this image in detail",
579-
image=images[0], # Pass the first image directly
580-
)
581-
582-
print(description)
583-
```
584-
585-
### Async support
586-
587-
For async/await patterns, use the `use_async=True` parameter:
588-
589-
```python
590-
import asyncio
591-
import replicate
592-
593-
594-
async def main():
595-
# Create an async model function
596-
flux_dev = replicate.use("black-forest-labs/flux-dev", use_async=True)
597-
598-
# Await the result
599-
outputs = await flux_dev(prompt="futuristic city at sunset")
600-
601-
for output in outputs:
602-
print(output)
603-
604-
605-
asyncio.run(main())
606-
```
607-
608-
### Accessing URLs without downloading
609-
610-
If you need the URL without downloading the file, use the `get_path_url()` helper:
611-
612-
```python
613-
import replicate
614-
from replicate.lib._predictions_use import get_path_url
615-
616-
flux_dev = replicate.use("black-forest-labs/flux-dev")
617-
outputs = flux_dev(prompt="a serene landscape")
618-
619-
for output in outputs:
620-
url = get_path_url(output)
621-
print(f"URL: {url}") # https://replicate.delivery/...
622-
```
623-
624-
### Creating predictions without waiting
625-
626-
To create a prediction without waiting for it to complete, use the `create()` method:
627-
628-
```python
629-
import replicate
630-
631-
llama = replicate.use("meta/meta-llama-3-8b-instruct")
632-
633-
# Start the prediction
634-
run = llama.create(prompt="Explain quantum computing")
635-
636-
# Check logs while it's running
637-
print(run.logs())
638-
639-
# Get the output when ready
640-
result = run.output()
641-
print(result)
642-
```
643-
644-
### Current limitations
645-
646-
- The `use()` method must be called at the module level (not inside functions or classes)
647-
- Type hints are limited compared to the standard client interface
648-
- This is an experimental API and may change in future releases
649-
650665
## Versioning
651666

652667
This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:

0 commit comments

Comments
 (0)