### Install Freebuff CLI

Source: https://github.com/quorinex/freebuff2api/blob/main/README.md

Use npm to install the Freebuff CLI tool globally.

```bash
npm i -g freebuff
```

--------------------------------

### Configure Freebuff2API

Source: https://github.com/quorinex/freebuff2api/blob/main/README.md

Example configuration file for the proxy server, defining listen address, upstream URL, and auth tokens.

```json
{
  "LISTEN_ADDR": ":8080",
  "UPSTREAM_BASE_URL": "https://codebuff.com",
  "AUTH_TOKENS": ["eyJhb..."],
  "ROTATION_INTERVAL": "6h",
  "REQUEST_TIMEOUT": "15m",
  "API_KEYS": [],
  "HTTP_PROXY": ""
}
```

--------------------------------

### GET /v1/models

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Lists all available models that can be used with the chat completions endpoint. The model list is dynamically fetched from Freebuff's free-agents configuration and refreshed every 6 hours. Returns models in OpenAI's list format.

```APIDOC
## GET /v1/models

### Description
Lists all available AI models supported by the proxy, formatted according to OpenAI's API standards.

### Method
GET

### Endpoint
/v1/models

### Parameters
No parameters are required for this endpoint.

### Request Example
```bash
curl -X GET http://localhost:8080/v1/models \
  -H "Authorization: Bearer your-proxy-api-key"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object returned, always `list`.
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of object, always `model`.
  - **created** (integer) - Unix timestamp of when the model was created or last updated.
  - **owned_by** (string) - The entity that owns the model (e.g., `Freebuff2API`).
  - **root** (string) - The root model ID if this is a fine-tuned model.
  - **permission** (array) - Permissions associated with the model.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "minimax/minimax-m2.7",
      "object": "model",
      "created": 1234567890,
      "owned_by": "Freebuff2API",
      "root": "minimax/minimax-m2.7",
      "permission": []
    },
    {
      "id": "google/gemini-2.5-flash-lite",
      "object": "model",
      "created": 1234567890,
      "owned_by": "Freebuff2API",
      "root": "google/gemini-2.5-flash-lite",
      "permission": []
    }
  ]
}
```
```

--------------------------------

### GET /healthz

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Health check endpoint that returns server status, uptime, and detailed information about token pools, active runs, and session states. Useful for monitoring and debugging token rotation issues.

```APIDOC
## GET /healthz

### Description
Provides a health check for the Freebuff2API server, indicating its operational status and potentially offering insights into internal states like token pool health.

### Method
GET

### Endpoint
/healthz

### Parameters
No parameters are required for this endpoint.

### Request Example
```bash
curl -X GET http://localhost:8080/healthz
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the server is healthy (`true`) or not (`false`).

#### Response Example
```json
{
  "ok": true
}
```
```

--------------------------------

### Build Freebuff2API from Source

Source: https://github.com/quorinex/freebuff2api/blob/main/README.md

Steps to clone the repository and compile the Go binary.

```bash
git clone https://github.com/Quorinex/Freebuff2API.git
cd Freebuff2API
go build -o Freebuff2API .
./Freebuff2API -config config.json
```

--------------------------------

### Deploy Freebuff2API with Docker

Source: https://github.com/quorinex/freebuff2api/blob/main/README.md

Commands to run the pre-built Docker image or build the service from source.

```bash
docker run -d --name Freebuff2API \
  -p 8080:8080 \
  -e AUTH_TOKENS="token1,token2" \
  ghcr.io/quorinex/freebuff2api:latest
```

```bash
docker build -t Freebuff2API .
docker run -d -p 8080:8080 -e AUTH_TOKENS="token1,token2" Freebuff2API
```

--------------------------------

### List Available Models

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Retrieve a list of available models in OpenAI format.

```bash
curl -X GET http://localhost:8080/v1/models \
  -H "Authorization: Bearer your-proxy-api-key"
```

--------------------------------

### Run Freebuff2API with Docker using a Config File

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Deploy the proxy server using Docker, mounting a configuration file to \/app\/config.json within the container. This method allows for more complex configurations.

```bash
docker run -d --name freebuff2api \
  -p 8080:8080 \
  -v /path/to/config.json:/app/config.json \
  ghcr.io/quorinex/freebuff2api:latest \
  -config /app/config.json
```

--------------------------------

### Run Freebuff2API with Docker using Environment Variables

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Deploy the proxy server using Docker, configuring authentication tokens and other settings via environment variables. Ensure the port 8080 is exposed.

```bash
docker run -d --name freebuff2api \
  -p 8080:8080 \
  -e AUTH_TOKENS="token1,token2,token3" \
  -e API_KEYS="my-secret-api-key" \
  -e ROTATION_INTERVAL="4h" \
  ghcr.io/quorinex/freebuff2api:latest
```

--------------------------------

### Configure Freebuff2API Server

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Use a JSON file to define server settings like listen address, upstream URL, and authentication tokens.

```json
{
  "LISTEN_ADDR": ":8080",
  "UPSTREAM_BASE_URL": "https://codebuff.com",
  "AUTH_TOKENS": ["your-freebuff-auth-token-1", "your-freebuff-auth-token-2"],
  "ROTATION_INTERVAL": "6h",
  "REQUEST_TIMEOUT": "15m",
  "API_KEYS": ["optional-proxy-api-key"],
  "HTTP_PROXY": "http://proxy.example.com:8080"
}
```

--------------------------------

### Build Freebuff2API from Source using Docker

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Build a Docker image for Freebuff2API from its source code. This is useful for development or when using a custom build.

```bash
docker build -t freebuff2api .
docker run -d -p 8080:8080 -e AUTH_TOKENS="token1,token2" freebuff2api
```

--------------------------------

### Execute Chat Completion Requests

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Perform chat completions using standard OpenAI-compatible POST requests. Supports both streaming and function calling.

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-api-key" \
  -d '{
    "model": "minimax/minimax-m2.7",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "stream": true
  }'
```

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-api-key" \
  -d '{
    "model": "google/gemini-2.5-flash-lite",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "stream": false
  }'
```

--------------------------------

### Python OpenAI SDK Integration with Freebuff2API

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Integrate Freebuff2API with the Python openai library. Set the base_url to your Freebuff2API instance and use any available model. The api_key is only needed if API_KEYS is configured in the proxy.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="your-proxy-api-key"  # Only needed if API_KEYS is configured
)

# List available models
models = client.models.list()
for model in models.data:
    print(model.id)

# Chat completion
response = client.chat.completions.create(
    model="minimax/minimax-m2.7",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

--------------------------------

### POST /v1/chat/completions

Source: https://context7.com/quorinex/freebuff2api/llms.txt

The main chat completions endpoint that accepts OpenAI-format requests and proxies them to Freebuff's backend. Supports streaming responses, function calling with tool definitions, and automatic model-to-agent routing. The endpoint handles session management, run rotation, and retries transparently.

```APIDOC
## POST /v1/chat/completions

### Description
Proxies OpenAI-format chat completion requests to Freebuff's backend, supporting streaming, function calling, and automatic model routing.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Query Parameters
- **stream** (boolean) - Optional - Whether to stream the response.

#### Request Body
- **model** (string) - Required - The model to use for chat completions.
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author of the message (e.g., `system`, `user`, `assistant`).
  - **content** (string) - Required - The content of the message.
- **tools** (array) - Optional - A list of tools the model may call.
  - **type** (string) - Required - The type of tool. Currently, only `function` is supported.
  - **function** (object) - Required - The definition of the function that the model may generate JSON inputs for.
    - **name** (string) - Required - The name of the function to be called.
    - **description** (string) - Optional - Description of the function the model may use to determine how to call the function.
    - **parameters** (object) - Optional - The parameters the function expects.
      - **type** (string) - Required - The type of the parameter. Currently, only `object` is supported.
      - **properties** (object) - Required - A map of parameter names to their properties.
      - **required** (array) - Optional - An array of parameter names that are required.

### Request Example
```json
{
  "model": "minimax/minimax-m2.7",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "stream": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the chat completion.
- **object** (string) - The type of object returned, usually `chat.completion` or `chat.completion.chunk` for streaming.
- **created** (integer) - Unix timestamp of when the completion was created.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - The index of the choice.
  - **delta** (object) - The delta content for streaming responses.
    - **role** (string) - The role of the author of the message.
    - **content** (string) - The content of the message.
  - **message** (object) - The message content for non-streaming responses.
    - **role** (string) - The role of the author of the message.
    - **content** (string) - The content of the message.
    - **tool_calls** (array) - A list of tool calls if the model decided to call a tool.
      - **id** (string) - The ID of the tool call.
      - **type** (string) - The type of the tool call (`function`).
      - **function** (object) - The function definition.
        - **name** (string) - The name of the function to call.
        - **arguments** (string) - The arguments to pass to the function, as a JSON string.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., `stop`, `length`, `tool_calls`).

#### Response Example (Streaming)
```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"minimax/minimax-m2.7","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"minimax/minimax-m2.7","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
data: [DONE]
```

#### Response Example (Function Calling)
```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "google/gemini-2.5-flash-lite",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_xxx",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\":\"San Francisco\"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```
```

--------------------------------

### Freebuff Credentials Format

Source: https://github.com/quorinex/freebuff2api/blob/main/README.md

The structure of the local credentials file generated by the Freebuff CLI.

```json
{
  "default": {
    "id": "user_10293847",
    "name": "Zhang San",
    "email": "zhangsan@example.com",
    "authToken": "fa82b5c1-e39d-4c7a-961f-d2b3c4e5f6a7",
    ...
  }
}
```

--------------------------------

### Node.js OpenAI SDK Integration with Freebuff2API

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Integrate Freebuff2API with the Node.js openai library. Set the baseURL to your Freebuff2API instance and use any available model. The apiKey is required if API_KEYS is configured in the proxy.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'your-proxy-api-key'
});

async function main() {
  const stream = await client.chat.completions.create({
    model: 'google/gemini-2.5-flash-lite',
    messages: [{ role: 'user', content: 'Write a haiku about programming' }],
    stream: true
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
}

main();
```

--------------------------------

### Check Server Health

Source: https://context7.com/quorinex/freebuff2api/llms.txt

Query the health check endpoint to monitor server status and token pool information.

```bash
curl -X GET http://localhost:8080/healthz
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.