### Install OpenAI Node.js Client

Source: https://docs.regolo.ai/getting-started/choose-language

Install the official OpenAI library for Node.js.

```bash
npm install openai
```

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

### Install Regolo AI Client

Source: https://docs.regolo.ai/getting-started/quick-start

Install the necessary packages for Python or Node.js environments.

```bash
pip install regolo
```

```bash
npm install openai
```

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

### Install OpenAI Python Client

Source: https://docs.regolo.ai/getting-started/choose-language

Install the official OpenAI library to interact with the Regolo API.

```bash
pip install openai
```

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

### Install Regolo Python Client

Source: https://docs.regolo.ai/getting-started/choose-language

Install the official Regolo Python package via pip.

```bash
pip install regolo
```

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

### Configure Tool Choice Modes

Source: https://docs.regolo.ai/models/features/function-calling

Examples demonstrating various tool_choice configurations including auto, required, forced functions, allowed tool subsets, and disabling tools.

```python
payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"  # Default behavior
}
```

```python
payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "required"
}
```

```python
payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": {
        "type": "function",
        "function": {"name": "duckduckgo_search"}
    }
}
```

```python
payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,  # All available tools
    "tool_choice": {
        "type": "allowed_tools",
        "mode": "auto",
        "tools": [
            {"type": "function", "name": "duckduckgo_search"}
        ]
    }
}
```

```python
payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "none"
}
```

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

### Static Completions Request

Source: https://docs.regolo.ai/models/families/completions

Examples of how to perform a static completion request using the Python SDK, the requests library, and cURL.

```python
import regolo

regolo.default_key = "<YOUR_REGOLO_KEY>"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

print(regolo.static_completions(prompt="Tell me something about Rome."))
```

```python
import requests

api_url = "https://api.regolo.ai/v1/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}
data = {
    "model": "Llama-3.3-70B-Instruct",
    "prompt": "Tell me something about Rome.",
    "temperature": 0.7
}

response = requests.post(api_url, headers=headers, json=data)
print(response.json())
```

```bash
curl -X POST https://api.regolo.ai/v1/completions 
-H "Content-Type: application/json" 
-H "Authorization: Bearer YOUR_REGOLO_KEY" 
-d '{
    "model": "Llama-3.3-70B-Instruct",
    "prompt": "Tell me something about Rome.",
    "temperature": 0.7
}'
```

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

### Static Chat Completions Implementation

Source: https://docs.regolo.ai/models/families/completions

Examples for performing static chat completions using the Regolo Python client, the requests library, and cURL.

```python
import regolo

regolo.default_key = "<YOUR_REGOLO_KEY>"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

print(regolo.static_chat_completions(messages=[{"role": "user", "content": "Tell me something about rome"}]))
```

```python
import requests

api_url = "https://api.regolo.ai/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}
data = {
    "model": "Llama-3.3-70B-Instruct",
    "messages": [
        {"role": "user", "content": "Tell me something about Rome."}
    ]
}

response = requests.post(api_url, headers=headers, json=data)
print(response.json())
```

```bash
curl -X POST https://api.regolo.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_REGOLO_KEY" \
    -d '{
     "model": "Llama-3.3-70B-Instruct",
     "messages": [
        {
            "role": "user",
            "content": "Tell me something about Rome."
        }
    ]
}'
```

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

### GET /model_group/info

Source: https://docs.regolo.ai/models/catalog

Retrieves a list of all available models, including their descriptions, capabilities, and pricing information.

```APIDOC
## GET /model_group/info

### Description
Returns a list of all available models, with each entry describing the model's functionality, pricing, and supported parameters. Requires an API key for authentication.

### Method
GET

### Endpoint
https://api.regolo.ai/model_group/info

### Response
#### Success Response (200)
- **data** (array) - A list of model objects.

#### Response Example
{
  "data": [
    {
      "model_group": "gpt-oss-120b",
      "description": "Open-weight 117B Mixture-of-Experts model by OpenAI. Supports reasoning, tool use, and more.",
      "mode": "chat",
      "providers": ["hosted_vllm"],
      "quantization": "MXFP4",
      "max_input_tokens": 30000,
      "max_output_tokens": 90000,
      "supports_reasoning": true,
      "supports_function_calling": true,
      "supports_vision": false,
      "supports_web_search": true,
      "input_cost_per_token": 0.000001,
      "output_cost_per_token": 0.0000042,
      "supported_openai_params": ["temperature", "max_tokens", "tools", "reasoning_effort", "stream"]
    }
  ]
}
```

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

### Perform Video Completions with Remote URLs

Source: https://docs.regolo.ai/models/features/video-understanding

Examples of sending a video URL and text prompt to the Regolo API using the Python client, the requests library, and cURL.

```python
import regolo

regolo.default_key = "YOUR_REGOLO_KEY"
regolo.default_chat_model = "qwen3.5-122b"

print(regolo.static_chat_completions(messages=[{
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Please provide a detailed summary of this video."
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://your-public-video.url/video.mp4"
            }
        }
    ]
}]))
```

```python
import requests

url = "https://api.regolo.ai/v1/chat/completions"
payload = {
    "model": "qwen3.5-122b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Please provide a detailed summary of this video."
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://your-public-video.url/video.mp4"
                    }
                }
            ]
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

```bash
curl -X POST https://api.regolo.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_REGOLO_KEY" \
-d '{
    "model": "qwen3.5-122b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Provide a detailed summary of this video."
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://your-public-video.url/video.mp4"
                    }
                }
            ]
        }
    ]
}'
```

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

### GET /model_group/info

Source: https://docs.regolo.ai/models/catalog

Retrieves the full catalog including capabilities, pricing, token limits, descriptions, and accepted parameters for each model.

```APIDOC
## GET /model_group/info

### Description
Provides comprehensive details about models, including pricing, features, and constraints, suitable for model comparison or UI integration.

### Method
GET

### Endpoint
https://api.regolo.ai/model_group/info
```

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

### Stream Chat Completions via HTTP Requests

Source: https://docs.regolo.ai/models/families/completions

Examples for handling streamed chat completions using the requests library, demonstrating content extraction and raw response printing.

```python
import requests
import json

api_url = "https://api.regolo.ai/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}
data = {
    "model": "Llama-3.3-70B-Instruct",
    "messages": [
        {"role": "user", "content": "Tell me something about Rome."}
    ],
    "stream": True
}

response = requests.post(api_url, headers=headers, json=data, stream=True)

# Extract only content from streamed JSON
for line in response.iter_lines():
    if line:
        decoded_line = line.decode('utf-8')
        if decoded_line.startswith('data: '):
            json_str = decoded_line[6:]
            if json_str.strip() == '[DONE]':
                break
            try:
                json_data = json.loads(json_str)
                if 'choices' in json_data:
                    delta = json_data['choices'][0].get('delta', {})
                    content = delta.get('content', '')
                    if content:
                        print(content, end='', flush=True)
            except json.JSONDecodeError:
                pass
```

```python
import requests

api_url = "https://api.regolo.ai/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}
data = {
    "model": "Llama-3.3-70B-Instruct",
    "messages": [
        {"role": "user", "content": "Tell me something about Rome."}
    ],
    "stream": True
}

response = requests.post(api_url, headers=headers, json=data, stream=True)

# Show full JSON response
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))
```

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

### GET /models

Source: https://docs.regolo.ai/models/catalog

Retrieves a lightweight, OpenAI-compatible list of model IDs available for use in requests.

```APIDOC
## GET /models

### Description
Returns a list of model IDs that can be used as the 'model' parameter in API requests.

### Method
GET

### Endpoint
https://api.regolo.ai/models
```

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

### Model Response Structure

Source: https://docs.regolo.ai/models/catalog

Example of the JSON object returned for a single model entry in the data array.

```json
{
  "data": [
    {
      "model_group": "gpt-oss-120b",
      "description": "Open-weight 117B Mixture-of-Experts model by OpenAI. Supports reasoning, tool use, and more.",
      "mode": "chat",
      "providers": ["hosted_vllm"],
      "quantization": "MXFP4",
      "max_input_tokens": 30000,
      "max_output_tokens": 90000,
      "supports_reasoning": true,
      "supports_function_calling": true,
      "supports_vision": false,
      "supports_web_search": true,
      "input_cost_per_token": 0.000001,
      "output_cost_per_token": 0.0000042,
      "supported_openai_params": ["temperature", "max_tokens", "tools", "reasoning_effort", "stream"]
    }
  ]
}
```

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

### Chat Completions API Requests

Source: https://docs.regolo.ai/getting-started/first-api-call

Examples of how to send a chat completion request using the official Python SDK, the requests library, or cURL.

```python
import regolo

regolo.default_key = "YOUR_API_KEY"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

response = regolo.static_chat_completions(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of Italy?"}
    ]
)
print(response)
```

```python
import requests

api_url = "https://api.regolo.ai/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "Llama-3.3-70B-Instruct",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of Italy?"}
    ]
}

response = requests.post(api_url, headers=headers, json=data)
print(response.json())
```

```bash
curl -X POST https://api.regolo.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
        "model": "Llama-3.3-70B-Instruct",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the capital of Italy?"}
        ]
    }'
```

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

### Perform Vision Completions with Remote Image URL

Source: https://docs.regolo.ai/models/features/vision

Examples of sending a remote image URL to the vision model using the Regolo Python client, the requests library, and cURL.

```python
import regolo

regolo.default_key = "YOUR_REGOLO_KEY"
regolo.default_chat_model = "deepseek-ocr-2"

print(regolo.static_chat_completions(messages=[{
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Extract all text from this image exactly as written. Preserve line breaks and punctuation."
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://cdn.britannica.com/16/234216-050-C66F8665/beagle-hound-dog.jpg",
                "format": "image/jpeg"
            }
        }
    ]
}]))
```

```python
import requests

url = "https://api.regolo.ai/v1/chat/completions"
payload = {
    "model": "deepseek-ocr-2",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extract all text from this image exactly as written. Preserve line breaks and punctuation."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/16/234216-050-C66F8665/beagle-hound-dog.jpg",
                        "format": "image/jpeg"
                    }
                }
            ]
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

```bash
curl -X POST https://api.regolo.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_REGOLO_KEY" \
-d '{
    "model": "deepseek-ocr-2",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extract all text from this image exactly as written. Preserve line breaks and punctuation."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/16/234216-050-C66F8665/beagle-hound-dog.jpg",
                        "format": "image/jpeg"
                    }
                }
            ]
        }
    ]
}'
```

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

### Stream Chat Completions with Regolo Client

Source: https://docs.regolo.ai/models/families/completions

Examples for processing streamed chat responses using the Regolo Python client, either by extracting content or viewing the full response structure.

```python
import regolo

regolo.default_key = "<YOUR_REGOLO_KEY>"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

client = regolo.RegoloClient()
response = client.run_chat(
    user_prompt="Tell me something about Rome.",
    full_output=True,
    stream=True
)

# Process streamed responses - extract only content (words)
while True:
    try:
        chunk = next(response)
        # Extract content from delta if it's a dict
        if isinstance(chunk, dict):
            content = chunk.get('choices', [{}])[0].get('delta', {}).get('content', '')
            if content:
                print(content, end="", flush=True)
        else:
            # If it's already a string, print it directly
            print(chunk, end="", flush=True)
    except StopIteration:
        break
```

```python
import regolo

regolo.default_key = "<YOUR_REGOLO_KEY>"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

client = regolo.RegoloClient()
response = client.run_chat(
    user_prompt="Tell me something about Rome.",
    full_output=True,
    stream=True
)

# Process streamed responses - show full JSON structure
while True:
    try:
        chunk = next(response)
        print(chunk)
    except StopIteration:
        break
```

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

### Send Base64 Image to Vision Model

Source: https://docs.regolo.ai/models/features/vision

Examples for encoding a local image file to Base64 and sending it to the vision model via the Regolo client, requests library, or cURL.

```python
import regolo
import base64
from pathlib import Path

regolo.default_key = "YOUR_REGOLO_KEY"
regolo.default_chat_model = "deepseek-ocr-2"

IMAGE_PATH = Path("beagle-hound-dog.jpg")

if not IMAGE_PATH.exists():
    raise FileNotFoundError(f"Image not found: {IMAGE_PATH.resolve()}")

with open(IMAGE_PATH, "rb") as f:
    image_bytes = f.read()

image_b64 = base64.b64encode(image_bytes).decode("utf-8")

result = regolo.static_chat_completions(
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Extract all text from this image exactly as written. Preserve line breaks and punctuation."
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:image/jpeg;base64,{image_b64}",
                    "format": "image/jpeg"
                }
            }
        ]
    }],
    max_tokens=4096,  # Important: maintain a wide output token window to avoid issues
    full_output=True
)

print("Model response:")
print(result["choices"][0]["message"]["content"])
```

```python
import base64
import json
import requests
from pathlib import Path

API_URL = "https://api.regolo.ai/v1/chat/completions"
API_KEY = "YOUR-API-KEY"
MODEL = "deepseek-ocr-2"

IMAGE_PATH = Path("beagle-hound-dog.jpg")

if not IMAGE_PATH.exists():
    raise FileNotFoundError(f"Image not found: {IMAGE_PATH.resolve()}")

with open(IMAGE_PATH, "rb") as f:
    image_bytes = f.read()

image_b64 = base64.b64encode(image_bytes).decode("utf-8")

payload = {
    "model": MODEL,
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract all text from this image exactly as written. Preserve line breaks and punctuation."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_b64}",
                        "format": "image/jpeg"
                    }
                }
            ]
        }
    ],
    "max_tokens": 4096  # Important: maintain a wide output token window to avoid issues
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

print("Sending request to Regolo AI API...")
response = requests.post(API_URL, headers=headers, data=json.dumps(payload))

if response.status_code != 200:
    print(f"Error {response.status_code}:")
    print(response.text)
else:
    result = response.json()
    try:
        content = result["choices"][0]["message"]["content"]
        print("Model response:")
        print(content)
    except Exception:
        print("Unexpected response format:")
        print(response.text)
```

```bash
# Encode local image to base64
IMAGE_B64=$(base64 -w 0 beagle-hound-dog.jpg)

curl -X POST https://api.regolo.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-API-KEY" \
-d "{
    \"model\": \"deepseek-ocr-2\",
    \"messages\": [
        {
            \"role\": \"user\",
            \"content\": [
                {
                    \"type\": \"text\",
                    \"text\": \"Extract all text from this image exactly as written. Preserve line breaks and punctuation.\"
                },
                {
                    \"type\": \"image_url\",
                    \"image_url\": {
                        \"url\": \"data:image/jpeg;base64,$IMAGE_B64\",
                        \"format\": \"image/jpeg\"
                    }
                }
            ]
        }
    ],
    \"max_tokens\": 4096  # Important: maintain a wide output token window to avoid issues
}"
```

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

### Use OpenAI Python Client

Source: https://docs.regolo.ai/getting-started/choose-language

Initialize the OpenAI client with the Regolo base URL to perform chat completions.

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.regolo.ai/v1"
)

response = client.chat.completions.create(
    model="Llama-3.3-70B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

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

### Perform Web Search with Function Calling

Source: https://docs.regolo.ai/models/features/function-calling

Demonstrates the standard workflow for initiating a tool call, executing the function, and providing the result back to the model for a final response.

```python
# Create messages list
messages = [
    {"role": "user", "content": "Find me some news about AI"}
]

# Initial request with tools
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"
}

response = requests.post(
    f"{REGOLO_BASE_URL}/chat/completions",
    headers=headers,
    json=payload
)

message = response.json()["choices"][0]["message"]

# Handle function call
if message.get("tool_calls"):
    for tool_call in message["tool_calls"]:
        if tool_call["function"]["name"] == "duckduckgo_search":
            args = json.loads(tool_call["function"]["arguments"])
            search_results = duckduckgo_search(
                query=args.get("query"),
                max_results=args.get("max_results", 10),
                region=args.get("region", "wt-wt")
            )

            # Add assistant message with tool_calls and tool response
            messages.append(message)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "name": tool_call["function"]["name"],
                "content": search_results
            })

            # Make follow-up call with updated messages
            followup_payload = {
                "model": "gpt-oss-120b",
                "messages": messages
            }

            followup_response = requests.post(
                f"{REGOLO_BASE_URL}/chat/completions",
                headers=headers,
                json=followup_payload
            )

            followup_response.raise_for_status()
            final_answer = followup_response.json()["choices"][0]["message"]["content"]
            print(final_answer)
else:
    print(message.get("content", ""))
```

```python
# Create messages list
messages = [
    {"role": "user", "content": "Find me some news about AI"}
]

# Initial request with tools
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"
}

response = requests.post(
    f"{REGOLO_BASE_URL}/chat/completions",
    headers=headers,
    json=payload
)

# Show full JSON response
print(response.json())

message = response.json()["choices"][0]["message"]

# Handle function call
if message.get("tool_calls"):
    for tool_call in message["tool_calls"]:
        if tool_call["function"]["name"] == "duckduckgo_search":
            args = json.loads(tool_call["function"]["arguments"])
            search_results = duckduckgo_search(
                query=args.get("query"),
                max_results=args.get("max_results", 10),
                region=args.get("region", "wt-wt")
            )

            # Add assistant message with tool_calls and tool response
            messages.append(message)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "name": tool_call["function"]["name"],
                "content": search_results
            })

            # Make follow-up call with updated messages
            followup_payload = {
                "model": "gpt-oss-120b",
                "messages": messages
            }

            followup_response = requests.post(
                f"{REGOLO_BASE_URL}/chat/completions",
                headers=headers,
                json=followup_payload
            )

            followup_response.raise_for_status()
            # Show full JSON response
            print(followup_response.json())
else:
    print(message.get("content", ""))
```

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

### Use OpenAI Node.js Client

Source: https://docs.regolo.ai/getting-started/choose-language

Initialize the client with the Regolo base URL and perform a standard chat completion.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'YOUR_API_KEY',
    baseURL: 'https://api.regolo.ai/v1'
});

async function main() {
    const response = await client.chat.completions.create({
        model: 'Llama-3.3-70B-Instruct',
        messages: [{ role: 'user', content: 'Hello!' }]
    });
    console.log(response.choices[0].message.content);
}

main();
```

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

### Configure top_p parameter

Source: https://docs.regolo.ai/models/features/response-parameters

Controls token diversity via nucleus sampling.

```python
data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Write a creative poem"}
    ],
    "top_p": 0.9  # Allow more diverse word choices
}
```

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

### Execute full API request

Source: https://docs.regolo.ai/models/features/response-parameters

Demonstrates a complete request using the requests library with multiple parameters.

```python
import requests

api_url = "https://api.regolo.ai/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_REGOLO_KEY"
}
data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Write a creative story"}
    ],
    "temperature": 0.8,
    "max_tokens": 500,
    "top_p": 0.9,
    "frequency_penalty": 0.3,
    "presence_penalty": 0.4
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])
```

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

### Perform Rerank API Request

Source: https://docs.regolo.ai/models/families/rerank

Examples of how to call the Rerank endpoint using cURL and Python. Ensure the documents are tagged correctly as per the model's requirements.

```bash
  curl --request POST \
    --url https://api.regolo.ai/rerank \
    --header 'Authorization: Bearer REGOLO_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "Qwen3-Reranker-4B",
      "query": "<Instruct>: Given a web search query, retrieve relevant passages that answer the query\n<Query>: What is the capital of China?",
      "documents": [
        "<Document>: The capital of China is Beijing.",
        "<Document>: Gravity is a force that attracts two bodies towards each other..."
      ],
      "top_n": 5
    }'
```

```python
import requests

api_key = "REGOLO_API_KEY"
url = "https://api.regolo.ai/rerank"

task = "Given a web search query, retrieve relevant passages that answer the query"
query_text = "What is the capital of China?"

documents = [
    "The capital of China is Beijing.",
    "Gravity is a force that attracts two bodies towards each other..."
]

payload = {
    "model": "Qwen3-Reranker-4B",
    "query": f"<Instruct>: {task}\n<Query>: {query_text}",
    "documents": [f"<Document>: {doc}" for doc in documents],
    "top_n": 5
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": f"Bearer {api_key}"}
)

results = response.json().get('results', [])
for res in results:
    score = res['relevance_score']
    clean_text = res['document']['text'].replace("<Document>: ", "")
    print(f"Score: {score:.4f} | Text: {clean_text}")
```

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

### Web Search Function Calling with Streaming

Source: https://docs.regolo.ai/models/features/function-calling

Demonstrates the full flow of sending a request with tools, processing a function call, and streaming the final response.

```python
# Create messages list
messages = [
    {"role": "user", "content": "Find me some news about AI"}
]

# Initial request with tools
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"
}

response = requests.post(
    f"{REGOLO_BASE_URL}/chat/completions",
    headers=headers,
    json=payload
)

message = response.json()["choices"][0]["message"]

# Handle function call
if message.get("tool_calls"):
    for tool_call in message["tool_calls"]:
        if tool_call["function"]["name"] == "duckduckgo_search":
            args = json.loads(tool_call["function"]["arguments"])
            search_results = duckduckgo_search(
                query=args.get("query"),
                max_results=args.get("max_results", 10),
                region=args.get("region", "wt-wt")
            )

            # Add assistant message with tool_calls and tool response
            messages.append(message)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "name": tool_call["function"]["name"],
                "content": search_results
            })

            # Make follow-up call with streaming enabled
            followup_payload = {
                "model": "gpt-oss-120b",
                "messages": messages,
                "stream": True
            }

            followup_response = requests.post(
                f"{REGOLO_BASE_URL}/chat/completions",
                headers=headers,
                json=followup_payload,
                stream=True
            )

            # Extract only content from streamed JSON
            for line in followup_response.iter_lines():
                if line:
                    decoded_line = line.decode('utf-8')
                    if decoded_line.startswith('data: '):
                        json_str = decoded_line[6:]
                        if json_str.strip() == '[DONE]':
                            break
                        try:
                            json_data = json.loads(json_str)
                            if 'choices' in json_data:
                                delta = json_data['choices'][0].get('delta', {})
                                content = delta.get('content', '')
                                if content:
                                    print(content, end='', flush=True)
                        except json.JSONDecodeError:
                            pass
else:
    print(message.get("content", ""))
```

```python
# Create messages list
messages = [
    {"role": "user", "content": "Find me some news about AI"}
]

# Initial request with tools
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "model": "gpt-oss-120b",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"
}

response = requests.post(
    f"{REGOLO_BASE_URL}/chat/completions",
    headers=headers,
    json=payload
)

# Show full JSON response
print(response.json())

message = response.json()["choices"][0]["message"]

# Handle function call
if message.get("tool_calls"):
    for tool_call in message["tool_calls"]:
        if tool_call["function"]["name"] == "duckduckgo_search":
            args = json.loads(tool_call["function"]["arguments"])
            search_results = duckduckgo_search(
                query=args.get("query"),
                max_results=args.get("max_results", 10),
                region=args.get("region", "wt-wt")
            )

            # Add assistant message with tool_calls and tool response
            messages.append(message)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "name": tool_call["function"]["name"],
                "content": search_results
            })

            # Make follow-up call with streaming enabled
            followup_payload = {
                "model": "gpt-oss-120b",
                "messages": messages,
                "stream": True
            }

            followup_response = requests.post(
                f"{REGOLO_BASE_URL}/chat/completions",
                headers=headers,
                json=followup_payload,
                stream=True
            )

            # Show full JSON response
            for line in followup_response.iter_lines():
                if line:
                    print(line.decode('utf-8'))
else:
    print(message.get("content", ""))
```

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

### Set Environment Variables

Source: https://docs.regolo.ai/getting-started/choose-language

Set the API key in the environment for Linux/macOS or Windows.

```bash
export REGOLO_API_KEY="your-api-key"
```

```powershell
$env:REGOLO_API_KEY = "your-api-key"
```

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

### Use Regolo Python Client

Source: https://docs.regolo.ai/getting-started/choose-language

Configure the client with an API key and perform chat completions or session-based chat.

```python
import regolo

regolo.default_key = "YOUR_API_KEY"
regolo.default_chat_model = "Llama-3.3-70B-Instruct"

# Simple completion
response = regolo.static_chat_completions(
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response)

# Using RegoloClient for chat sessions
client = regolo.RegoloClient()
client.add_prompt_to_chat(role="user", prompt="Tell me a joke")
role, content = client.run_chat()
print(content)
```

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

### Create a Chat Application with Regolo

Source: https://docs.regolo.ai/getting-started/welcome

A Streamlit-based chat interface using the Regolo client to manage prompts and display responses.

```python
    import streamlit as st
    import regolo

    regolo.default_key = "YOUR-API-KEY-HERE"
    regolo.default_chat_model = "Llama-3.3-70B-Instruct"

    client = regolo.RegoloClient()

    st.title("Regolo.ai Chat")

    if "messages" not in st.session_state:
        st.session_state.messages = []

    for msg in st.session_state.messages:
        with st.chat_message(msg["role"]):
            st.markdown(msg["content"])

    user_input = st.chat_input("Write a message...")
    if user_input:
        st.session_state.messages.append({"role": "user", "content": user_input})

        with st.chat_message("user"):
            st.markdown(user_input)

        client.add_prompt_to_chat(role="user", prompt=user_input)
        for msg in st.session_state.messages:
            client.add_prompt_to_chat(role=msg["role"], prompt=msg["content"])

        response = client.run_chat()

        role, content = response

        st.session_state.messages.append({"role": role, "content": content})

        with st.chat_message(role):
            st.markdown(content)
```

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

### Define a System Prompt

Source: https://docs.regolo.ai/getting-started/playground

Set a custom system prompt to define the assistant's persona and response style.

```text
You are a helpful coding assistant specialized in Python.
Provide concise answers with code examples when relevant.
```

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

### Configure temperature parameter

Source: https://docs.regolo.ai/models/features/response-parameters

Adjusts output randomness; lower values increase focus, while higher values increase creativity.

```python
data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Tell me a story"}
    ],
    "temperature": 0.7  # Balanced creativity
}
```

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

### Configure temperature for factual responses

Source: https://docs.regolo.ai/models/features/faq

Set a low temperature value to prioritize factual accuracy in model outputs.

```bash
# For factual answers
curl -L -X POST 'https://api.regolo.ai/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What year did WW2 end?"
      }
    ],
    "model": "qwen3.5-122b",
    "temperature": 0.2
  }'
```

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

### Generate images using the Regolo Python client

Source: https://docs.regolo.ai/models/families/images

Uses the regolo library to generate and save an image from a text prompt.

```python
import regolo
from io import BytesIO
from PIL import Image

# pip install regolo Pillow

regolo.default_image_generation_model = "Qwen-Image"
regolo.default_key = "YOUR_REGOLO_KEY"

img_bytes = regolo.static_image_create(prompt="A Boat in the sea")[0]

image = Image.open(BytesIO(img_bytes))

# Save the Image
output_path = "generated_image.png"
image.save(output_path)
print(f"Image saved to: {output_path}")
```

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

### POST /v1/chat/completions

Source: https://docs.regolo.ai/models/features/video-understanding

Sends a request to the chat completions endpoint with a video URL and a text prompt to receive an analysis or summary.

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

### Description
Processes a video file provided via a public URL alongside a text prompt to generate insights, summaries, or analysis.

### Method
POST

### Endpoint
https://api.regolo.ai/v1/chat/completions

### Request Body
- **model** (string) - Required - The model identifier (e.g., "qwen3.5-122b").
- **messages** (array) - Required - A list of message objects containing the user prompt and video content.

### Request Example
{
  "model": "qwen3.5-122b",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Provide a detailed summary of this video."
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://your-public-video.url/video.mp4"
          }
        }
      ]
    }
  ]
}
```

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

### Configure seed parameter

Source: https://docs.regolo.ai/models/features/response-parameters

Enables reproducible outputs by setting a deterministic seed.

```python
data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Generate a random number"}
    ],
    "seed": 42  # Reproducible output
}
```

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

### Transcribe audio using OpenAI Client

Source: https://docs.regolo.ai/models/families/stt

Configures the OpenAI Python client to point to the Regolo API base URL for transcription tasks.

```python
import openai
from pathlib import Path

# OpenAI client configuration
openai.api_key = "YOUR_REGOLO_KEY"
openai.base_url = "https://api.regolo.ai/v1/"

# Audio file to transcribe
AUDIO_FILE = "/path/to/your/audio"
OUTPUT_FILE = "/path/to/output/transcription.txt"

# Transcribe the file
with open(AUDIO_FILE, "rb") as audio_file:
    transcript = openai.audio.transcriptions.create(
        model="faster-whisper-large-v3",
        file=audio_file,
        language="en",
        response_format="text"
    )

# Save the transcription
output_path = Path(OUTPUT_FILE)
output_path.parent.mkdir(parents=True, exist_ok=True)

with open(output_path, "w", encoding="utf-8") as f:
    f.write(transcript)

print(f"Transcription saved to: {OUTPUT_FILE}")
```

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

### Configure n parameter

Source: https://docs.regolo.ai/models/features/response-parameters

Specifies the number of completion variations to generate.

```python
data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Suggest a name"}
    ],
    "n": 3  # Generate 3 different suggestions
}
```

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

### POST /v1/chat/completions

Source: https://docs.regolo.ai/models/features/vision

Sends a text prompt and an image URL to the vision model for processing.

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

### Description
Processes an image provided via a remote URL alongside a text prompt.

### Method
POST

### Endpoint
https://api.regolo.ai/v1/chat/completions

### Request Body
- **model** (string) - Required - The model identifier (e.g., "deepseek-ocr-2").
- **messages** (array) - Required - A list of message objects containing the role and content (text and image_url).

### Request Example
{
    "model": "deepseek-ocr-2",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extract all text from this image."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/16/234216-050-C66F8665/beagle-hound-dog.jpg",
                        "format": "image/jpeg"
                    }
                }
            ]
        }
    ]
}
```

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

### Transcribe audio using Regolo Client

Source: https://docs.regolo.ai/models/families/stt

Uses the official regolo Python library to perform static audio transcription.

```python
import regolo
from pathlib import Path

# Regolo configuration
regolo.default_key = "YOUR_REGOLO_KEY"
regolo.default_audio_transcription_model = "faster-whisper-large-v3"

# Audio file to transcribe
AUDIO_FILE = "/path/to/your/audio"
OUTPUT_FILE = "/path/to/output/transcription.txt"

# Transcribe the file
transcript = regolo.static_audio_transcription(file=AUDIO_FILE)

# Save the transcription
output_path = Path(OUTPUT_FILE)
output_path.parent.mkdir(parents=True, exist_ok=True)

with open(output_path, "w", encoding="utf-8") as f:
    f.write(transcript)

print(f"Transcription saved to: {OUTPUT_FILE}")
```

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

### Tool Choice Configuration

Source: https://docs.regolo.ai/models/features/function-calling

The tool_choice parameter allows users to define how the model interacts with provided tools. Options include auto, required, specific function forcing, allowed tool subsets, and disabling tools.

```APIDOC
## Tool Choice Configuration

### Description
The `tool_choice` parameter controls whether the model calls tools and which tools it is permitted to use.

### Parameters
- **tool_choice** (string|object) - Optional - Defines the tool selection strategy. Can be "auto", "required", "none", or an object specifying a forced function or allowed tools.
```

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

### Retrieve Model Information

Source: https://docs.regolo.ai/models/catalog

Fetch the list of available models and their metadata using Python or cURL. Ensure the Authorization header includes a valid API key.

```python
import requests

url = "https://api.regolo.ai/model_group/info"
headers = {"Authorization": "Bearer YOUR_REGOLO_KEY"}

response = requests.get(url, headers=headers)
models = response.json()["data"]
print(f"{len(models)} models available")
```

```bash
curl -X GET https://api.regolo.ai/model_group/info \
  -H "Authorization: Bearer YOUR_REGOLO_KEY"
```

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

### Execute cURL Request

Source: https://docs.regolo.ai/getting-started/choose-language

Perform a direct POST request to the Regolo API using cURL.

```bash
curl -X POST https://api.regolo.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
        "model": "Llama-3.3-70B-Instruct",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

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

### Reduce repetition with penalties

Source: https://docs.regolo.ai/models/features/faq

Apply frequency and presence penalties to discourage token repetition and encourage the introduction of new topics.

```bash
# Reduce repetition
curl -L -X POST 'https://api.regolo.ai/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 10 different programming languages"
      }
    ],
    "model": "qwen3.5-122b",
    "frequency_penalty": 0.5,
    "presence_penalty": 0.4
  }'
```