0
# Client & Authentication
1

2
Client configuration, authentication management, and HTTP transport customization for the Replicate API.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Create and configure Replicate API clients with custom authentication, base URLs, timeouts, and HTTP settings.
9

10
```python { .api }
11
class Client:
12
    def __init__(
13
        self,
14
        api_token: Optional[str] = None,
15
        *,
16
        base_url: Optional[str] = None,
17
        timeout: Optional[httpx.Timeout] = None,
18
        **kwargs
19
    ) -> None:
20
        """
21
        Initialize a Replicate API client.
22

23
        Parameters:
24
        - api_token: API token for authentication (defaults to REPLICATE_API_TOKEN env var)
25
        - base_url: Base URL for API requests (defaults to https://api.replicate.com)
26
        - timeout: HTTP timeout configuration
27
        - **kwargs: Additional HTTP client arguments
28
        """
29
```
30

31
### Default Client
32

33
The package provides a default client instance used by top-level functions.
34

35
```python { .api }
36
default_client: Client
37
```
38

39
Usage examples:
40

41
```python
42
import replicate
43

44
# Using default client (uses REPLICATE_API_TOKEN env var)
45
output = replicate.run("model-name", input={"prompt": "hello"})
46

47
# Using custom client
48
client = replicate.Client(api_token="your-token-here")
49
output = client.run("model-name", input={"prompt": "hello"})
50

51
# Custom base URL and timeout
52
import httpx
53
client = replicate.Client(
54
    api_token="your-token",
55
    base_url="https://custom-api.example.com",
56
    timeout=httpx.Timeout(30.0)
57
)
58
```
59

60
### Authentication Methods
61

62
Multiple authentication approaches depending on your use case.
63

64
#### Environment Variable (Recommended)
65

66
```python
67
import os
68
os.environ['REPLICATE_API_TOKEN'] = 'your-token-here'
69

70
import replicate
71
output = replicate.run("model-name", input={})
72
```
73

74
#### Client Constructor
75

76
```python
77
from replicate import Client
78

79
client = Client(api_token="your-token-here")
80
output = client.run("model-name", input={})
81
```
82

83
#### Cog Context Integration
84

85
For models running within Cog, the client automatically detects context-provided tokens:
86

87
```python
88
# In a Cog prediction, token is automatically available
89
import replicate
90
output = replicate.run("model-name", input={})
91
```
92

93
### Client Methods
94

95
All core functionality available on Client instances.
96

97
```python { .api }
98
class Client:
99
    def run(
100
        self,
101
        ref: str,
102
        input: Optional[Dict[str, Any]] = None,
103
        *,
104
        use_file_output: Optional[bool] = True,
105
        **params
106
    ) -> Union[Any, Iterator[Any]]:
107
        """Run a model and wait for its output."""
108

109
    async def async_run(
110
        self,
111
        ref: str,
112
        input: Optional[Dict[str, Any]] = None,
113
        *,
114
        use_file_output: Optional[bool] = True,
115
        **params
116
    ) -> Union[Any, AsyncIterator[Any]]:
117
        """Run a model and wait for its output asynchronously."""
118

119
    def stream(
120
        self,
121
        ref: str,
122
        *,
123
        input: Optional[Dict[str, Any]] = None,
124
        use_file_output: Optional[bool] = True,
125
        **params
126
    ) -> Iterator[ServerSentEvent]:
127
        """Stream a model's output."""
128

129
    async def async_stream(
130
        self,
131
        ref: str,
132
        input: Optional[Dict[str, Any]] = None,
133
        *,
134
        use_file_output: Optional[bool] = True,
135
        **params
136
    ) -> AsyncIterator[ServerSentEvent]:
137
        """Stream a model's output asynchronously."""
138
```
139

140
### Client Properties (Namespaces)
141

142
Access to all API functionality through organized namespaces.
143

144
```python { .api }
145
class Client:
146
    @property
147
    def accounts(self) -> Accounts:
148
        """Namespace for operations related to accounts."""
149

150
    @property  
151
    def collections(self) -> Collections:
152
        """Namespace for operations related to collections of models."""
153

154
    @property
155
    def deployments(self) -> Deployments:
156
        """Namespace for operations related to deployments."""
157

158
    @property
159
    def files(self) -> Files:
160
        """Namespace for operations related to files."""
161

162
    @property
163
    def hardware(self) -> Hardware:
164
        """Namespace for operations related to hardware."""
165

166
    @property
167
    def models(self) -> Models:
168
        """Namespace for operations related to models."""
169

170
    @property
171
    def predictions(self) -> Predictions:
172
        """Namespace for operations related to predictions."""
173

174
    @property
175
    def trainings(self) -> Trainings:
176
        """Namespace for operations related to trainings."""
177

178
    @property
179
    def webhooks(self) -> Webhooks:
180
        """Namespace for operations related to webhooks."""
181
```
182

183
### HTTP Transport Customization
184

185
Advanced HTTP configuration with automatic retry logic and custom transport options.
186

187
```python { .api }
188
class RetryTransport:
189
    def __init__(
190
        self,
191
        wrapped_transport: Union[httpx.BaseTransport, httpx.AsyncBaseTransport],
192
        *,
193
        max_attempts: int = 10,
194
        max_backoff_wait: float = 60,
195
        backoff_factor: float = 0.1,
196
        jitter_ratio: float = 0.1,
197
        retryable_methods: Optional[Iterable[str]] = None,
198
        retry_status_codes: Optional[Iterable[int]] = None
199
    ) -> None:
200
        """
201
        Custom HTTP transport with automatic retry using exponential backoff.
202

203
        Parameters:
204
        - wrapped_transport: Underlying HTTP transport
205
        - max_attempts: Maximum retry attempts
206
        - max_backoff_wait: Maximum wait time between retries
207
        - backoff_factor: Exponential backoff factor
208
        - jitter_ratio: Jitter ratio for randomization (0-0.5)
209
        - retryable_methods: HTTP methods to retry (defaults to GET, PUT, DELETE, etc.)
210
        - retry_status_codes: Status codes to retry (defaults to 429, 503, 504)
211
        """
212
```
213

214
### Account Management
215

216
Access account information and settings.
217

218
```python { .api }
219
class Accounts:
220
    def current(self) -> Account:
221
        """
222
        Get the current account information.
223

224
        Returns:
225
        Account object with username, name, and type information
226
        """
227

228
    async def async_current(self) -> Account:
229
        """
230
        Get the current account information asynchronously.
231

232
        Returns:
233
        Account object with username, name, and type information
234
        """
235

236
class Account:
237
    type: Literal["user", "organization"]
238
    """The type of account."""
239

240
    username: str
241
    """The username of the account."""
242

243
    name: str
244
    """The name of the account."""
245

246
    github_url: Optional[str]
247
    """The GitHub URL of the account."""
248
```
249

250
Usage examples:
251

252
```python
253
import replicate
254

255
# Get current account info
256
account = replicate.accounts.current()
257
print(f"Account: {account.username} ({account.type})")
258
print(f"Name: {account.name}")
259

260
# Using custom client
261
client = replicate.Client(api_token="your-token")
262
account = client.accounts.current()
263
```
264

265
### Configuration Options
266

267
Environment variables for default configuration:
268

269
- **`REPLICATE_API_TOKEN`**: API authentication token
270
- **`REPLICATE_BASE_URL`**: Custom API base URL (defaults to https://api.replicate.com)
271
- **`REPLICATE_POLL_INTERVAL`**: Polling interval for prediction status (defaults to 0.5 seconds)
272

273
Usage examples:
274

275
```python
276
import os
277
import httpx
278
from replicate import Client
279

280
# Basic configuration
281
os.environ['REPLICATE_API_TOKEN'] = 'your-token'
282
os.environ['REPLICATE_POLL_INTERVAL'] = '1.0'
283

284
# Advanced client configuration
285
client = Client(
286
    api_token="your-token",
287
    base_url="https://api.replicate.com",
288
    timeout=httpx.Timeout(connect=5.0, read=30.0),
289
    headers={"User-Agent": "MyApp/1.0"},
290
    transport=custom_transport
291
)
292
```