0
# Gradio Client
1

2
A lightweight Python client library for interacting with Gradio applications as APIs. The client enables developers to programmatically connect to and make predictions on any Gradio app, whether hosted on Hugging Face Spaces or running elsewhere, providing a seamless bridge between interactive Gradio interfaces and programmatic access for batch processing, automation, and integration into larger ML pipelines.
3

4
## Package Information
5

6
- **Package Name**: gradio_client
7
- **Language**: Python
8
- **Installation**: `pip install gradio_client`
9
- **Python Version**: >=3.10
10

11
## Core Imports
12

13
```python
14
from gradio_client import Client
15
```
16

17
Common imports for file handling:
18

19
```python
20
from gradio_client import Client, file, handle_file, FileData
21
```
22

23
All public imports:
24

25
```python
26
from gradio_client import Client, file, handle_file, FileData, __version__
27
```
28

29
## Basic Usage
30

31
```python
32
from gradio_client import Client
33

34
# Connect to a Hugging Face Space
35
client = Client("abidlabs/whisper-large-v2")
36

37
# Make a synchronous prediction
38
result = client.predict("test.mp4", api_name="/predict")
39
print(result)  # >> "What a nice recording!"
40

41
# Submit an asynchronous job
42
job = client.submit("hello", api_name="/predict")
43
result = job.result()  # Wait for completion
44
print(result)  # >> 49
45

46
# Connect to a private Space with token
47
client = Client("username/private-space", hf_token="hf_...")
48

49
# Connect to any Gradio URL
50
client = Client("https://bec81a83-5b5c-471e.gradio.live")
51

52
# View available API endpoints
53
client.view_api()
54
```
55

56
## Architecture
57

58
The gradio_client architecture is built around several key components:
59

60
- **Client**: The main interface for connecting to and interacting with Gradio apps
61
- **Job**: Manages asynchronous predictions with status tracking and result retrieval
62
- **FileData**: Handles file upload/download with automatic encoding/decoding
63
- **Endpoints**: Internal representation of available API endpoints with parameter information
64
- **Communication protocols**: Supports WebSocket, Server-Sent Events (SSE) for real-time interaction
65

66
The client automatically handles authentication, file transfers, session management, and protocol negotiation, providing a simple interface while supporting advanced features like Space duplication, Discord bot deployment, and streaming responses.
67

68
## Capabilities
69

70
### Client Management
71

72
Core client functionality for connecting to Gradio applications, managing connections, and configuring client behavior including authentication, SSL verification, and custom headers.
73

74
```python { .api }
75
class Client:
76
    def __init__(
77
        self,
78
        src: str,
79
        hf_token: str | None = None,
80
        max_workers: int = 40,
81
        verbose: bool = True,
82
        auth: tuple[str, str] | None = None,
83
        httpx_kwargs: dict[str, Any] | None = None,
84
        *,
85
        headers: dict[str, str] | None = None,
86
        download_files: str | Path | Literal[False] = DEFAULT_TEMP_DIR,
87
        ssl_verify: bool = True,
88
        analytics_enabled: bool = True,
89
    ): ...
90

91
    def close(self) -> None: ...
92
    def reset_session(self) -> None: ...
93
    def view_api(self, all_endpoints: bool | None = None, print_info: bool = True, return_format: Literal["dict", "str"] | None = None) -> dict | str | None: ...
94
    def add_zero_gpu_headers(self, headers: dict[str, str]) -> dict[str, str]: ...
95
```
96

97
[Client Management](./client-management.md)
98

99
### Prediction and Jobs
100

101
Synchronous and asynchronous prediction capabilities with comprehensive job management, including status tracking, result retrieval, and cancellation support.
102

103
```python { .api }
104
def predict(self, *data, api_name: str | None = None, fn_index: int | None = None) -> Any: ...
105
def submit(self, *data, api_name: str | None = None, fn_index: int | None = None, result_callbacks: list[Callable] | None = None) -> Job: ...
106

107
class Job:
108
    def result(self, timeout: float | None = None) -> Any: ...
109
    def status(self) -> StatusUpdate: ...
110
    def cancel(self) -> bool: ...
111
    def outputs(self) -> list[tuple | Any]: ...
112
```
113

114
[Predictions and Jobs](./predictions-jobs.md)
115

116
### Space Management
117

118
Hugging Face Space operations including duplication for private use, hardware configuration, and deployment as Discord bots.
119

120
```python { .api }
121
@classmethod
122
def duplicate(
123
    cls,
124
    from_id: str,
125
    to_id: str | None = None,
126
    hf_token: str | None = None,
127
    duplicate_from: str = "spaces",
128
    **kwargs
129
) -> Client: ...
130

131
def deploy_discord(
132
    self,
133
    discord_bot_token: str,
134
    api_names: list[str] | str | None = None,
135
    to_id: str | None = None,
136
    hf_token: str | None = None,
137
    **kwargs
138
) -> None: ...
139
```
140

141
[Space Management](./space-management.md)
142

143
### File Handling
144

145
File upload, download, and processing utilities with automatic encoding/decoding, MIME type detection, and support for various file formats and sources.
146

147
```python { .api }
148
def file(filepath_or_url: str | Path) -> Any: ...
149
def handle_file(filepath_or_url: str | Path) -> Any: ...
150

151
class FileData(TypedDict):
152
    name: str | None  # filename
153
    data: str | None  # base64 encoded data
154
    size: NotRequired[int | None]  # size in bytes
155
    is_file: NotRequired[bool]  # whether the data corresponds to a file or base64 encoded data
156
    orig_name: NotRequired[str]  # original filename
157
    mime_type: NotRequired[str]
158
    is_stream: NotRequired[bool]
159
```
160

161
[File Handling](./file-handling.md)
162

163
### Streaming and Communication
164

165
Real-time message streaming and bidirectional communication with Gradio applications using WebSocket and Server-Sent Events protocols.
166

167
```python { .api }
168
def stream_messages(
169
    self,
170
    *data,
171
    api_name: str | None = None,
172
    fn_index: int | None = None
173
) -> Iterator[Any]: ...
174

175
def send_data(self, data: dict, hash_data: dict, protocol: str, request_headers: dict) -> Any: ...
176
```
177

178
[Streaming](./streaming.md)
179

180
### Error Handling
181

182
Comprehensive exception system for handling authentication errors, application errors, and communication failures with detailed error information.
183

184
```python { .api }
185
class AuthenticationError(ValueError):
186
    """Raised when authentication fails"""
187
    pass
188

189
class AppError(ValueError):
190
    """Raised when the upstream Gradio app throws an error"""
191
    def __init__(
192
        self,
193
        message: str = "Error raised.",
194
        duration: float | None = 10,
195
        visible: bool = True,
196
        title: str = "Error",
197
        print_exception: bool = True,
198
    ): ...
199
```
200

201
[Error Handling](./error-handling.md)
202

203
## Types
204

205
```python { .api }
206
from typing_extensions import NotRequired
207

208
StatusUpdate = dict[str, Any]
209

210
class ParameterInfo(TypedDict):
211
    label: str
212
    parameter_name: str
213
    parameter_has_default: NotRequired[bool]
214
    parameter_default: NotRequired[Any]
215
    type: dict
216
    python_type: dict
217
    component: str
218
    example_input: Any
219
```