0
# Client Management
1

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

4
## Capabilities
5

6
### Client Initialization
7

8
Initialize a client connection to a Gradio application with comprehensive configuration options.
9

10
```python { .api }
11
class Client:
12
    def __init__(
13
        self,
14
        src: str,
15
        hf_token: str | None = None,
16
        max_workers: int = 40,
17
        verbose: bool = True,
18
        auth: tuple[str, str] | None = None,
19
        httpx_kwargs: dict[str, Any] | None = None,
20
        *,
21
        headers: dict[str, str] | None = None,
22
        download_files: str | Path | Literal[False] = DEFAULT_TEMP_DIR,
23
        ssl_verify: bool = True,
24
        analytics_enabled: bool = True,
25
    ):
26
    """
27
    Initialize a Gradio client.
28

29
    Parameters:
30
    - src: Hugging Face Space name (e.g. "abidlabs/whisper") or full URL
31
    - hf_token: Optional Hugging Face token for private Spaces
32
    - max_workers: Maximum thread workers for concurrent requests
33
    - verbose: Whether to print status messages
34
    - auth: Basic authentication credentials as (username, password) tuple
35
    - httpx_kwargs: Additional arguments for HTTP client (timeouts, proxies, etc.)
36
    - headers: Additional headers to send with requests
37
    - download_files: Directory for downloaded files or False to disable downloading
38
    - ssl_verify: Whether to verify SSL certificates
39
    - analytics_enabled: Whether to enable telemetry
40
    """
41
```
42

43
### Connection Management
44

45
Manage client connections and sessions with proper cleanup and reset capabilities.
46

47
```python { .api }
48
def close(self) -> None:
49
    """
50
    Close the client connection and cleanup resources.
51
    
52
    Properly terminates all active connections and cleans up temporary files.
53
    Should be called when the client is no longer needed.
54
    """
55

56
def reset_session(self) -> None:
57
    """
58
    Reset the current session.
59
    
60
    Clears the current session state and generates a new session hash.
61
    Useful for starting fresh without creating a new client instance.
62
    """
63
```
64

65
### API Inspection
66

67
Inspect and view available API endpoints with detailed parameter information.
68

69
```python { .api }
70
def view_api(
71
    self,
72
    all_endpoints: bool | None = None,
73
    print_info: bool = True,
74
    return_format: Literal["dict", "str"] | None = None,
75
) -> dict | str | None:
76
    """
77
    Display information about available API endpoints.
78

79
    Parameters:
80
    - all_endpoints: If True, shows all endpoints. If False, only named endpoints. 
81
                    If None, shows named endpoints or unnamed if no named exist.
82
    - print_info: Whether to print the API information to console
83
    - return_format: Format for returned information ("dict", "str", or None)
84

85
    Returns:
86
    API information as dict/string based on return_format, or None if no format specified
87
    """
88

89
def add_zero_gpu_headers(self, headers: dict[str, str]) -> dict[str, str]:
90
    """
91
    Add Zero-GPU specific headers for quota tracking.
92
    
93
    Adds x-ip-token header for Zero-GPU Spaces when called from within
94
    a Gradio app's LocalContext. Must be called from inside a prediction
95
    function, not during client instantiation.
96

97
    Parameters:
98
    - headers: Existing headers dictionary to modify
99

100
    Returns:
101
    Updated headers dictionary with Zero-GPU headers if available
102
    """
103
```
104

105
## Usage Examples
106

107
### Basic Connection
108

109
```python
110
from gradio_client import Client
111

112
# Connect to a public Space
113
client = Client("abidlabs/whisper-large-v2")
114

115
# Connect to a private Space
116
client = Client("username/private-space", hf_token="hf_...")
117

118
# Connect to any Gradio URL
119
client = Client("https://example.com/gradio-app")
120
```
121

122
### Advanced Configuration
123

124
```python
125
from gradio_client import Client
126

127
# Client with custom configuration
128
client = Client(
129
    "abidlabs/whisper",
130
    max_workers=10,
131
    verbose=False,
132
    headers={"Custom-Header": "value"},
133
    download_files="/custom/download/path",
134
    ssl_verify=False,
135
    httpx_kwargs={
136
        "timeout": 30.0,
137
        "proxies": {"http://": "http://proxy:8080"}
138
    }
139
)
140

141
# View available APIs
142
client.view_api()
143

144
# Clean up when done
145
client.close()
146
```
147

148
### Authentication
149

150
```python
151
from gradio_client import Client
152

153
# Basic authentication
154
client = Client(
155
    "https://protected-app.com",
156
    auth=("username", "password")
157
)
158

159
# Hugging Face token authentication
160
client = Client(
161
    "username/private-space",
162
    hf_token="hf_your_token_here"
163
)
164
```