# 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