156 lines
3.5 KiB
Markdown
156 lines
3.5 KiB
Markdown
# Tu-Zi API Proxy Service Documentation
|
|
|
|
## Overview
|
|
|
|
This API provides a queueing proxy service for requests to Tu-Zi services. It allows asynchronous processing of requests with authentication management, concurrency control, and status tracking.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
/api/tu_zi
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Submit API Request
|
|
|
|
Submits a request to a Tu-Zi API endpoint and returns a token for tracking.
|
|
|
|
**Endpoint:** `POST /api/tu_zi`
|
|
|
|
**Headers:**
|
|
|
|
- `X-Api-Target` (required): The full URL of the Tu-Zi API endpoint to call
|
|
|
|
**Request Body:**
|
|
|
|
- The raw body content to be forwarded to the target API
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"token": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
curl -X POST "https://animator-gg-api.ca2324.servep2p.com:8443/api/tu_zi" \
|
|
-H "X-Api-Target: https://api.tu-zi.com/v1/chat/completions" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"model": "gpt-4-gizmo-g-2fkFE8rbu",
|
|
"messages": [
|
|
{
|
|
"role": "user",
|
|
"content": "Who are you? What can you do?"
|
|
}
|
|
],
|
|
"stream": false
|
|
}'
|
|
```
|
|
|
|
### Get Request Status
|
|
|
|
Retrieves the status and result of an API request by token.
|
|
|
|
**Endpoint:** `GET /api/tu_zi?token={token}`
|
|
|
|
**Query Parameters:**
|
|
|
|
- `token` (required): The execution token returned by the POST request
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"status": "completed",
|
|
"result": {
|
|
"taskId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"success": true,
|
|
"response": "{ ... response from Tu-Zi API ... }"
|
|
},
|
|
"timestamp": 1743991194237
|
|
}
|
|
```
|
|
|
|
**Status Values:**
|
|
|
|
- `pending`: Request is waiting in the queue
|
|
- `running`: Request is currently being processed
|
|
- `completed`: Request has completed successfully
|
|
- `failed`: Request failed to complete
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
curl -X GET "https://animator-gg-api.ca2324.servep2p.com:8443/api/tu_zi?token=550e8400-e29b-41d4-a716-446655440000"
|
|
```
|
|
|
|
### Get Queue Statistics
|
|
|
|
Retrieves information about the current request queue.
|
|
|
|
**Endpoint:** `GET /api/tu_zi/queue`
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"size": 3,
|
|
"pending": 2,
|
|
"isPaused": false,
|
|
"activeExecutions": 5
|
|
}
|
|
```
|
|
|
|
**Response Fields:**
|
|
|
|
- `size`: Number of requests in the queue
|
|
- `pending`: Number of pending requests
|
|
- `isPaused`: Whether the queue is paused
|
|
- `activeExecutions`: Total number of active executions (including completed but not yet expired)
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
curl -X GET "https://animator-gg-api.ca2324.servep2p.com:8443/api/tu_zi/queue"
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The API returns appropriate HTTP status codes:
|
|
|
|
- `200 OK`: Request processed successfully
|
|
- `400 Bad Request`: Missing required parameters
|
|
- `500 Internal Server Error`: Server-side error during request execution
|
|
|
|
Error responses include a JSON body with an error message:
|
|
|
|
```json
|
|
{
|
|
"error": "Error message description"
|
|
}
|
|
```
|
|
|
|
## Authentication
|
|
|
|
The service automatically adds appropriate authentication headers to requests based on the target hostname. Currently, the service supports:
|
|
|
|
- Tu-Zi domains (`*.tu-zi.com`)
|
|
|
|
## Request Lifecycle
|
|
|
|
- The service uses a queue to manage concurrent requests (default: 2)
|
|
- Each request result is stored for 3 hours after completion
|
|
- After this time, the result will be purged, and querying the token will return an "Invalid execution token or result expired" error
|
|
|
|
## Client Usage Pattern
|
|
|
|
1. Submit a request to the Tu-Zi API through the proxy
|
|
2. Receive a token immediately
|
|
3. Poll the status endpoint with the token until the status is "completed" or "failed"
|
|
4. Process the response or handle the error
|