fal-js/apps/demo-nextjs-app-router/api_scripts/tuzi_api_queue.md

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:

{
  "token": "550e8400-e29b-41d4-a716-446655440000"
}

Example:

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:

{
  "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:

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:

{
  "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:

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:

{
  "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