返回提交历史
Modified
README.md
+2
-0
Added
docs/requests.md
+391
-0
XFEstudio/gpt4free
Create requests.md (#2429)
* Create requests.md * Update requests.md * Update README.md
e7e9d7df
代码差异
2 个文件
+393
-0
@@ -63,6 +63,7 @@ Is your site on this repository and you want to take it down? Send an email to t
63
63
- [Local Inference](docs/local.md)
64
64
- [Configuration](#configuration)
65
65
- [Full Documentation for Python API](#full-documentation-for-python-api)
66
- [Requests API from G4F](docs/requests.md)
66
67
- [Client API from G4F](docs/client.md)
67
68
- [AsyncClient API from G4F](docs/async_client.md)
68
69
- [🚀 Providers and Models](docs/providers-and-models.md)
@@ -206,6 +207,7 @@ print(f"Generated image URL: {image_url}")
206
207
207
208
#### **Full Documentation for Python API**
208
209
- **New:**
210
- **Requests API from G4F:** [/docs/requests](docs/requests.md)
209
211
- **Client API from G4F:** [/docs/client](docs/client.md)
210
212
- **AsyncClient API from G4F:** [/docs/async_client](docs/async_client.md)
211
213
@@ -0,0 +1,391 @@
1
# G4F Requests API Guide
2
3
## Table of Contents
4
- [Introduction](#introduction)
5
- [Getting Started](#getting-started)
6
- [Installing Dependencies](#installing-dependencies)
7
- [Making API Requests](#making-api-requests)
8
- [Text Generation](#text-generation)
9
- [Using the Chat Completions Endpoint](#using-the-chat-completions-endpoint)
10
- [Streaming Text Generation](#streaming-text-generation)
11
- [Model Retrieval](#model-retrieval)
12
- [Fetching Available Models](#fetching-available-models)
13
- [Image Generation](#image-generation)
14
- [Creating Images with AI](#creating-images-with-ai)
15
- [Advanced Usage](#advanced-usage)
16
17
## Introduction
18
19
Welcome to the G4F Requests API Guide, a powerful tool for leveraging AI capabilities directly from your Python applications using HTTP requests. This guide will take you through the steps of setting up requests to interact with AI models for a variety of tasks, from text generation to image creation.
20
21
## Getting Started
22
23
### Installing Dependencies
24
25
Ensure you have the `requests` library installed in your environment. You can install it via `pip` if needed:
26
27
```bash
28
pip install requests
29
```
30
31
This guide provides examples on how to make API requests using Python's `requests` library, focusing on tasks such as text and image generation, as well as retrieving available models.
32
33
## Making API Requests
34
35
Before diving into specific functionalities, it's essential to understand how to structure your API requests. All endpoints assume that your server is running locally at `http://localhost`. If your server is running on a different port, adjust the URLs accordingly (e.g., `http://localhost:8000`).
36
37
## Text Generation
38
39
### Using the Chat Completions Endpoint
40
41
To generate text responses using the chat completions endpoint, follow this example:
42
43
```python
44
import requests
45
46
# Define the payload
47
payload = {
48
"model": "gpt-4o",
49
"temperature": 0.9,
50
"messages": [{"role": "system", "content": "Hello, how are you?"}]
51
}
52
53
# Send the POST request to the chat completions endpoint
54
response = requests.post("http://localhost/v1/chat/completions", json=payload)
55
56
# Check if the request was successful
57
if response.status_code == 200:
58
# Print the response text
59
print(response.text)
60
else:
61
print(f"Request failed with status code {response.status_code}")
62
print("Response:", response.text)
63
```
64
65
**Explanation:**
66
- This request sends a conversation context to the model, which in turn generates and returns a response.
67
- The `temperature` parameter controls the randomness of the output.
68
69
### Streaming Text Generation
70
71
For scenarios where you want to receive partial responses or stream data as it's generated, you can utilize the streaming capabilities of the API. Here's how you can implement streaming text generation using Python's `requests` library:
72
73
```python
74
import requests
75
import json
76
from queue import Queue
77
78
def fetch_response(url, model, messages):
79
"""
80
Sends a POST request to the streaming chat completions endpoint.
81
82
Args:
83
url (str): The API endpoint URL.
84
model (str): The model to use for text generation.
85
messages (list): A list of message dictionaries.
86
87
Returns:
88
requests.Response: The streamed response object.
89
"""
90
payload = {"model": model, "messages": messages}
91
headers = {
92
"Content-Type": "application/json",
93
"Accept": "text/event-stream",
94
}
95
response = requests.post(url, headers=headers, json=payload, stream=True)
96
if response.status_code != 200:
97
raise Exception(
98
f"Failed to send message: {response.status_code} {response.text}"
99
)
100
return response
101
102
def process_stream(response, output_queue):
103
"""
104
Processes the streamed response and extracts messages.
105
106
Args:
107
response (requests.Response): The streamed response object.
108
output_queue (Queue): A queue to store the extracted messages.
109
"""
110
for line in response.iter_lines():
111
if line:
112
line = line.decode("utf-8")
113
if line == "data: [DONE]":
114
break
115
if line.startswith("data: "):
116
try:
117
data = json.loads(line[6:])
118
message = data.get("message", "")
119
if message:
120
output_queue.put(message)
121
except json.JSONDecodeError:
122
continue
123
124
# Define the API endpoint
125
chat_url = "http://localhost/v1/chat/completions"
126
127
# Define the payload
128
model = "gpt-4o"
129
messages = [{"role": "system", "content": "Hello, how are you?"}]
130
131
# Initialize the queue to store output messages
132
output_queue = Queue()
133
134
try:
135
# Fetch the streamed response
136
response = fetch_response(chat_url, model, messages)
137
138
# Process the streamed response
139
process_stream(response, output_queue)
140
141
# Retrieve messages from the queue
142
while not output_queue.empty():
143
msg = output_queue.get()
144
print(msg)
145
146
except Exception as e:
147
print(f"An error occurred: {e}")
148
```
149
150
**Explanation:**
151
- **`fetch_response` Function:**
152
- Sends a POST request to the streaming chat completions endpoint with the specified model and messages.
153
- Sets the `Accept` header to `text/event-stream` to enable streaming.
154
- Raises an exception if the request fails.
155
156
- **`process_stream` Function:**
157
- Iterates over each line in the streamed response.
158
- Decodes the line and checks for the termination signal `"data: [DONE]"`.
159
- Parses lines that start with `"data: "` to extract the message content.
160
- Enqueues the extracted messages into `output_queue` for further processing.
161
162
- **Main Execution:**
163
- Defines the API endpoint, model, and messages.
164
- Initializes a `Queue` to store incoming messages.
165
- Fetches and processes the streamed response.
166
- Retrieves and prints messages from the queue.
167
168
**Usage Tips:**
169
- Ensure your local server supports streaming and the `Accept` header appropriately.
170
- Adjust the `chat_url` if your local server runs on a different port or path.
171
- Use threading or asynchronous programming for handling streams in real-time applications.
172
173
## Model Retrieval
174
175
### Fetching Available Models
176
177
To retrieve a list of available models, you can use the following function:
178
179
```python
180
import requests
181
182
def fetch_models():
183
"""
184
Retrieves the list of available models from the API.
185
186
Returns:
187
dict: A dictionary containing available models or an error message.
188
"""
189
url = "http://localhost/v1/models/"
190
try:
191
response = requests.get(url)
192
response.raise_for_status() # Raise an error for HTTP issues
193
return response.json() # Parse and return the JSON response
194
except Exception as e:
195
return {"error": str(e)} # Return an error message if something goes wrong
196
197
models = fetch_models()
198
199
print(models)
200
```
201
202
**Explanation:**
203
- The `fetch_models` function makes a GET request to the models endpoint.
204
- It handles HTTP errors and returns a parsed JSON response containing available models or an error message.
205
206
## Image Generation
207
208
### Creating Images with AI
209
210
The following function demonstrates how to generate images using a specified model:
211
212
```python
213
import requests
214
215
def generate_image(prompt: str, model: str = "flux-4o"):
216
"""
217
Generates an image based on the provided text prompt.
218
219
Args:
220
prompt (str): The text prompt for image generation.
221
model (str, optional): The model to use for image generation. Defaults to "flux-4o".
222
223
Returns:
224
tuple: A tuple containing the image URL, caption, and the full response.
225
"""
226
payload = {
227
"model": model,
228
"temperature": 0.9,
229
"prompt": prompt.replace(" ", "+"),
230
}
231
232
try:
233
response = requests.post("http://localhost/v1/images/generate", json=payload)
234
response.raise_for_status()
235
res = response.json()
236
237
data = res.get("data")
238
if not data or not isinstance(data, list):
239
raise ValueError("Invalid 'data' in response")
240
241
image_url = data[0].get("url")
242
if not image_url:
243
raise ValueError("No 'url' found in response data")
244
245
timestamp = res.get("created")
246
caption = f"Prompt: {prompt}\nCreated: {timestamp}\nModel: {model}"
247
return image_url, caption, res
248
249
except Exception as e:
250
return None, f"Error: {e}", None
251
252
prompt = "A tiger in a forest"
253
254
image_url, caption, res = generate_image(prompt)
255
256
print("API Response:", res)
257
print("Image URL:", image_url)
258
print("Caption:", caption)
259
```
260
261
**Explanation:**
262
- The `generate_image` function constructs a request to create an image based on a text prompt.
263
- It handles responses and possible errors, ensuring a URL and caption are returned if successful.
264
265
## Advanced Usage
266
267
This guide has demonstrated basic usage scenarios for the G4F Requests API. The API provides robust capabilities for integrating advanced AI into your applications. You can expand upon these examples to fit more complex workflows and tasks, ensuring your applications are built with cutting-edge AI features.
268
269
### Handling Concurrency and Asynchronous Requests
270
271
For applications requiring high performance and non-blocking operations, consider using asynchronous programming libraries such as `aiohttp` or `httpx`. Here's an example using `aiohttp`:
272
273
```python
274
import aiohttp
275
import asyncio
276
import json
277
from queue import Queue
278
279
async def fetch_response_async(url, model, messages, output_queue):
280
"""
281
Asynchronously sends a POST request to the streaming chat completions endpoint and processes the stream.
282
283
Args:
284
url (str): The API endpoint URL.
285
model (str): The model to use for text generation.
286
messages (list): A list of message dictionaries.
287
output_queue (Queue): A queue to store the extracted messages.
288
"""
289
payload = {"model": model, "messages": messages}
290
headers = {
291
"Content-Type": "application/json",
292
"Accept": "text/event-stream",
293
}
294
295
async with aiohttp.ClientSession() as session:
296
async with session.post(url, headers=headers, json=payload) as resp:
297
if resp.status != 200:
298
text = await resp.text()
299
raise Exception(f"Failed to send message: {resp.status} {text}")
300
301
async for line in resp.content:
302
decoded_line = line.decode('utf-8').strip()
303
if decoded_line == "data: [DONE]":
304
break
305
if decoded_line.startswith("data: "):
306
try:
307
data = json.loads(decoded_line[6:])
308
message = data.get("message", "")
309
if message:
310
output_queue.put(message)
311
except json.JSONDecodeError:
312
continue
313
314
async def main():
315
chat_url = "http://localhost/v1/chat/completions"
316
model = "gpt-4o"
317
messages = [{"role": "system", "content": "Hello, how are you?"}]
318
output_queue = Queue()
319
320
try:
321
await fetch_response_async(chat_url, model, messages, output_queue)
322
323
while not output_queue.empty():
324
msg = output_queue.get()
325
print(msg)
326
327
except Exception as e:
328
print(f"An error occurred: {e}")
329
330
# Run the asynchronous main function
331
asyncio.run(main())
332
```
333
334
**Explanation:**
335
- **`aiohttp` Library:** Facilitates asynchronous HTTP requests, allowing your application to handle multiple requests concurrently without blocking.
336
- **`fetch_response_async` Function:**
337
- Sends an asynchronous POST request to the streaming chat completions endpoint.
338
- Processes the streamed response line by line.
339
- Extracts messages and enqueues them into `output_queue`.
340
- **`main` Function:**
341
- Defines the API endpoint, model, and messages.
342
- Initializes a `Queue` to store incoming messages.
343
- Invokes the asynchronous fetch function and processes the messages.
344
345
**Benefits:**
346
- **Performance:** Handles multiple requests efficiently, reducing latency in high-throughput applications.
347
- **Scalability:** Easily scales with increasing demand, making it suitable for production environments.
348
349
**Note:** Ensure you have `aiohttp` installed:
350
351
```bash
352
pip install aiohttp
353
```
354
355
## Conclusion
356
357
By following this guide, you can effectively integrate the G4F Requests API into your Python applications, enabling powerful AI-driven functionalities such as text and image generation, model retrieval, and handling streaming data. Whether you're building simple scripts or complex, high-performance applications, the examples provided offer a solid foundation to harness the full potential of AI in your projects.
358
359
Feel free to customize and expand upon these examples to suit your specific needs. If you encounter any issues or have further questions, don't hesitate to seek assistance or refer to additional resources.
360
361
---
362
363
# Additional Notes
364
365
1. **Adjusting the Base URL:**
366
- The guide assumes your API server is accessible at `http://localhost`. If your server runs on a different port (e.g., `8000`), update the URLs accordingly:
367
```python
368
# Example for port 8000
369
chat_url = "http://localhost:8000/v1/chat/completions"
370
```
371
372
2. **Environment Variables (Optional):**
373
- For better flexibility and security, consider using environment variables to store your base URL and other sensitive information.
374
```python
375
import os
376
377
BASE_URL = os.getenv("API_BASE_URL", "http://localhost")
378
chat_url = f"{BASE_URL}/v1/chat/completions"
379
```
380
381
3. **Error Handling:**
382
- Always implement robust error handling to gracefully manage unexpected scenarios, such as network failures or invalid responses.
383
384
4. **Security Considerations:**
385
- Ensure that your local API server is secured, especially if accessible over a network. Implement authentication mechanisms if necessary.
386
387
5. **Testing:**
388
- Utilize tools like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) for testing your API endpoints before integrating them into your code.
389
390
6. **Logging:**
391
- Implement logging to monitor the behavior of your applications, which is crucial for debugging and maintaining your systems.