### Full Tool Calling Example in Python

Source: https://docs.shuttleai.com/guides/tool-calling

This script demonstrates the complete flow of using tool calling with the ShuttleAI API. It includes defining tools, making an initial request, processing tool calls, and getting a final response. Ensure you have the OpenAI Python library installed.

```python
import json
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

# Define tools
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    }
]

# Simulated function
def get_weather(location, unit="celsius"):
    return {"location": location, "temperature": 22, "unit": unit, "condition": "sunny"}

# Start conversation
messages = [{"role": "user", "content": "What's the weather like in Tokyo?"}]

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message

# Process tool calls
if message.tool_calls:
    messages.append(message)
    
    for tool_call in message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = get_weather(**args)
        
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })

    # Get final answer
    response = client.chat.completions.create(
        model="shuttleai/auto",
        messages=messages,
        tools=tools
    )

print(response.choices[0].message.content)
```

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

### Full Tool Calling Example in Node.js

Source: https://docs.shuttleai.com/guides/tool-calling

This script demonstrates the complete flow of using tool calling with the ShuttleAI API in Node.js. It includes defining tools, making an initial request, processing tool calls, and getting a final response. Ensure you have the OpenAI Node.js library installed.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shuttle-xxx",
  baseURL: "https://api.shuttleai.com/v1",
});

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a location.",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "City name" },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
    },
  },
];

function getWeather(location, unit = "celsius") {
  return { location, temperature: 22, unit, condition: "sunny" };
}

const messages = [{ role: "user", content: "What's the weather like in Tokyo?" }];

let response = await client.chat.completions.create({
  model: "shuttleai/auto",
  messages,
  tools,
  tool_choice: "auto",
});

const message = response.choices[0].message;

if (message.tool_calls) {
  messages.push(message);

  for (const toolCall of message.tool_calls) {
    const args = JSON.parse(toolCall.function.arguments);
    const result = getWeather(args.location, args.unit);

    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify(result),
    });
  }

  response = await client.chat.completions.create({
    model: "shuttleai/auto",
    messages,
    tools,
  });
}

console.log(response.choices[0].message.content);
```

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

### Install OpenAI SDK

Source: https://docs.shuttleai.com/getting-started/quickstart

Install the necessary dependency to interact with the ShuttleAI API.

```bash
pip install openai
```

```bash
npm install openai
```

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

### Install OpenAI SDK for Python

Source: https://docs.shuttleai.com/api-reference/introduction

Install the OpenAI SDK to interact with the ShuttleAI API. Ensure you have Python and pip installed.

```bash
pip install openai
```

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

### GET /v1/models

Source: https://docs.shuttleai.com/api-reference/authentication

Example request demonstrating the use of the Authorization header.

```APIDOC
## GET /v1/models

### Description
Fetches the list of available models using the required authentication header.

### Method
GET

### Endpoint
https://api.shuttleai.com/v1/models

### Request Example
curl https://api.shuttleai.com/v1/models \
  -H "Authorization: Bearer shuttle-xxx"
```

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

### Install OpenAI SDK for Node.js

Source: https://docs.shuttleai.com/api-reference/introduction

Install the OpenAI SDK for Node.js to interact with the ShuttleAI API. Ensure you have Node.js and npm installed.

```bash
npm install openai
```

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

### Model metadata structure

Source: https://docs.shuttleai.com/models/model-tiers

Example JSON response showing the plan tier and capabilities for a specific model.

```json
{
  "id": "claude-opus-4.6",
  "plan": "premium",
  "request_multiplier": 2.0,
  "permission": {
    "context_length": 200000,
    "max_output": 32000,
    "tool_calling": true
  }
}
```

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

### Basic ShuttleAI Auto Usage

Source: https://docs.shuttleai.com/models/shuttleai-auto

Use 'shuttleai/auto' as the model to let ShuttleAI Auto select the best model for your request. This is the simplest way to get started.

```python
response = client.chat.completions.create(
    model="shuttleai/auto",  # Let Auto handle it
    messages=[{"role": "user", "content": "Write a Python function to merge two sorted lists."}]
)
```

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

### API Key Format Example

Source: https://docs.shuttleai.com/dashboard/api-keys

All ShuttleAI API keys begin with the 'shuttle-' prefix. This is a general representation of the key format.

```text
shuttle-xxxxxxxxxxxxxxxxxxxxx
```

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

### Enable Basic Streaming in Python

Source: https://docs.shuttleai.com/getting-started/streaming

Set `stream: true` in your request to enable streaming. This example shows how to iterate through the streamed chunks and print the content.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

stream = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "Write a short poem about AI." }],
    stream=True
)

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

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

### GET /v1/models

Source: https://docs.shuttleai.com/api-reference/introduction

Retrieves a list of all available models.

```APIDOC
## GET /v1/models

### Description
List all available models accessible via the API.

### Method
GET

### Endpoint
/v1/models
```

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

### Enable Basic Streaming in Node.js

Source: https://docs.shuttleai.com/getting-started/streaming

Set `stream: true` in your request to enable streaming. This example demonstrates iterating over the stream and writing content to standard output.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shuttle-xxx",
  baseURL: "https://api.shuttleai.com/v1",
});

const stream = await client.chat.completions.create({
  model: "shuttleai/auto",
  messages: [{ role: "user", content: "Write a short poem about AI." }],
  stream: true,
});

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

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

### GET /v1/models

Source: https://docs.shuttleai.com/api-reference/endpoint/models

Retrieves a list of all available models supported by the ShuttleAI API.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of all available models supported by the ShuttleAI API.

### Method
GET

### Endpoint
https://api.shuttleai.com/v1/models

### Request Example
```bash
curl https://api.shuttleai.com/v1/models \
  -H "Authorization: Bearer shuttle-xxx"
```
```

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

### Async Streaming in Python

Source: https://docs.shuttleai.com/getting-started/streaming

For asynchronous applications, utilize the `AsyncOpenAI` client. This example shows how to use `async for` to process streamed chunks.

```python
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

async def main():
    stream = await client.chat.completions.create(
        model="shuttleai/auto",
        messages=[{"role": "user", "content": "Explain quantum computing." }],
        stream=True
    )

    async for chunk in stream:
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)

asyncio.run(main())
```

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

### Get Model

Source: https://docs.shuttleai.com/api-reference/endpoint/model

Fetches details for a specific model. Replace 'shuttleai' with the desired model identifier.

```APIDOC
## GET /v1/models/{model}

### Description
Fetches details for a specific model.

### Method
GET

### Endpoint
/v1/models/{model}

### Parameters
#### Path Parameters
- **model** (string) - Required - The identifier of the model to retrieve.

### Request Example
```bash cURL
curl https://api.shuttleai.com/v1/models/shuttleai \
  -H "Authorization: Bearer shuttle-xxx"
```
```

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

### SSE Format Example

Source: https://docs.shuttleai.com/getting-started/streaming

Each streamed chunk is a JSON object formatted as a Server-Sent Event (SSE). The stream concludes with a `data: [DONE]` message.

```text
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" world"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

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

### ShuttleAI Auto with System Message and Code Review (Node.js)

Source: https://docs.shuttleai.com/models/shuttleai-auto

Node.js example for using ShuttleAI Auto with a system message and a user prompt for code review. Ensure your API key and base URL are correctly configured.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shuttle-xxx",
  baseURL: "https://api.shuttleai.com/v1",
});

const response = await client.chat.completions.create({
  model: "shuttleai/auto",
  messages: [
    { role: "system", content: "You are a senior software engineer." },
    { role: "user", content: "Review this code and suggest improvements:\n\ndef fib(n):\n  if n <= 1: return n\n  return fib(n-1) + fib(n-2)" },
  ],
});

console.log(response.choices[0].message.content);
```

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

### Set API Key Environment Variable

Source: https://docs.shuttleai.com/dashboard/api-keys

Store your API key in environment variables for security. This example shows how to export the key as a bash variable.

```bash
export SHUTTLEAI_API_KEY="shuttle-xxx"
```

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

### Make a Chat Completion Request with cURL

Source: https://docs.shuttleai.com/getting-started/authentication

Example of how to make a chat completion request to the ShuttleAI API using cURL, including authentication and content type headers.

```bash
curl https://api.shuttleai.com/v1/chat/completions \
  -H "Authorization: Bearer shuttle-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "shuttleai/auto", "messages": [{"role": "user", "content": "Hi"}]}'
```

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

### GET /v1/models/{id}

Source: https://docs.shuttleai.com/api-reference/introduction

Retrieves details for a specific model by its ID.

```APIDOC
## GET /v1/models/{id}

### Description
Get detailed information for a specific model.

### Method
GET

### Endpoint
/v1/models/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the model.
```

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

### API Key Header Format

Source: https://docs.shuttleai.com/api-reference/authentication

Include your API key in the Authorization header as a Bearer token. Ensure the key starts with 'shuttle-'.

```text
Authorization: Bearer shuttle-xxx
```

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

### Add ShuttleAI Provider to OpenClaw Config

Source: https://docs.shuttleai.com/guides/openclaw

Configure OpenClaw to use ShuttleAI by adding its details to the `openclaw.json` file. Replace `YOUR_API_KEY_HERE` with your actual ShuttleAI API key. This setup enables the `shuttleai/auto` model for smart routing.

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "shuttleai": {
        "baseUrl": "https://api.shuttleai.com/v1",
        "apiKey": "YOUR_API_KEY_HERE",
        "api": "openai-completions",
        "models": [
          {
            "id": "shuttleai/auto",
            "name": "ShuttleAI API",
            "reasoning": false,
            "input": ["text"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "shuttleai/auto"
      }
    }
  }
}
```

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

### Model Multiplier Response Example

Source: https://docs.shuttleai.com/pricing/multipliers

The verbose models endpoint response includes a `request_multiplier` field for each model. This value indicates how many requests a single API call to that model consumes from your per-minute quota.

```json
{
  "id": "claude-opus-4.6",
  "plan": "premium",
  "request_multiplier": 2.0
}
```

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

### Initialize OpenAI Client using Environment Variable (Python)

Source: https://docs.shuttleai.com/getting-started/authentication

Initialize the OpenAI Python SDK by referencing the ShuttleAI API key stored in an environment variable.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SHUTTLEAI_API_KEY"],
    base_url="https://api.shuttleai.com/v1"
)
```

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

### Initialize OpenAI Client using Environment Variable (Node.js)

Source: https://docs.shuttleai.com/getting-started/authentication

Initialize the OpenAI Node.js SDK by referencing the ShuttleAI API key stored in an environment variable.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SHUTTLEAI_API_KEY,
  baseURL: "https://api.shuttleai.com/v1",
});
```

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

### Open OpenClaw Config File

Source: https://docs.shuttleai.com/guides/openclaw

Use the `nano` editor to open the `openclaw.json` configuration file located in the user's home directory. This is where you will add the ShuttleAI provider details.

```bash
nano ~/.openclaw/openclaw.json
```

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

### Initialize OpenAI Client in Python

Source: https://docs.shuttleai.com/api-reference/introduction

Initialize the OpenAI client with your ShuttleAI API key and the ShuttleAI base URL. This client can then be used for all API requests.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)
```

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

### Make your first API call with ShuttleAI

Source: https://docs.shuttleai.com/

Use this Python code with the OpenAI SDK to make a request to ShuttleAI. Ensure you have your API key and the correct base URL.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

```

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

### Make First API Call with OpenAI SDK

Source: https://docs.shuttleai.com/getting-started/introduction

Use this Python snippet to make your first API call using the OpenAI SDK. Ensure you have your API key and the correct base URL for ShuttleAI.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

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

### Send a tool-enabled request in Python

Source: https://docs.shuttleai.com/guides/tool-calling

Initialize the OpenAI client with ShuttleAI base URL and include tools in the chat completion request.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)
```

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

### Initialize OpenAI Client in Node.js

Source: https://docs.shuttleai.com/api-reference/introduction

Initialize the OpenAI client with your ShuttleAI API key and the ShuttleAI base URL. This client can then be used for all API requests.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shuttle-xxx",
  baseURL: "https://api.shuttleai.com/v1",
});
```

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

### Use an MCP Server with ShuttleAI

Source: https://docs.shuttleai.com/guides/mcp-servers

Add an MCP tool type to your request to connect to an external tool server. The model discovers and uses available tools automatically.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "List all available models"}],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://mcp.shuttleai.com/mcp",
            "server_label": "ShuttleAI MCP",
            "require_approval": "never"
        }
    ]
)

print(response.choices[0].message.content)
```

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

### List Models with cURL

Source: https://docs.shuttleai.com/api-reference/endpoint/models

Use this cURL command to list all available models from the ShuttleAI API. Ensure you replace 'shuttle-xxx' with your actual API key.

```bash
curl https://api.shuttleai.com/v1/models \
  -H "Authorization: Bearer shuttle-xxx"
```

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

### Fetch verbose model information

Source: https://docs.shuttleai.com/models/model-tiers

Retrieve a list of all models with their associated tier requirements and metadata.

```bash
curl https://api.shuttleai.com/v1/models/verbose \
  -H "Authorization: Bearer shuttle-xxx"
```

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

### View Upgrade Path

Source: https://docs.shuttleai.com/dashboard/plans

Displays the progression sequence for available subscription tiers.

```text
Free → Basic → Premium → Scale
```

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

### List available models via API

Source: https://docs.shuttleai.com/models/overview

Retrieve a list of all accessible models using the ShuttleAI API. Requires a valid API key in the Authorization header.

```bash
curl https://api.shuttleai.com/v1/models \
  -H "Authorization: Bearer shuttle-xxx"
```

```bash
curl https://api.shuttleai.com/v1/models/verbose \
  -H "Authorization: Bearer shuttle-xxx"
```

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

### ShuttleAI Auto with System Message and Code Review

Source: https://docs.shuttleai.com/models/shuttleai-auto

Demonstrates using ShuttleAI Auto with a system message to define the AI's role and a user prompt for code review. Requires setting the API key and base URL.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

# ShuttleAI Auto handles model selection
response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[
        {"role": "system", "content": "You are a senior software engineer."},
        {"role": "user", "content": "Review this code and suggest improvements:\n\ndef fib(n):\n  if n <= 1: return n\n  return fib(n-1) + fib(n-2)"}
    ]
)

print(response.choices[0].message.content)
```

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

### Authentication Overview

Source: https://docs.shuttleai.com/api-reference/authentication

Details on how to authenticate requests using the Bearer token scheme.

```APIDOC
## Authentication

### Description
All requests to the ShuttleAI API must include a valid API key in the Authorization header to authenticate the user.

### Header Format
Authorization: Bearer shuttle-xxx

### Key Requirements
- API keys must start with the `shuttle-` prefix.

### Error Responses
- **401**: Missing or invalid API key
- **402**: No active plan on the account
- **403**: Plan doesn't include the requested model
- **423**: Account suspended
```

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

### Documentation Index

Source: https://docs.shuttleai.com/api-reference/endpoint/model

Fetches the complete documentation index to discover all available API pages.

```APIDOC
## Documentation Index

### Description
Fetch the complete documentation index at: https://docs.shuttleai.com/llms.txt
Use this file to discover all available pages before exploring further.

### Method
GET

### Endpoint
https://docs.shuttleai.com/llms.txt
```

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

### Stream with Usage Statistics in Python

Source: https://docs.shuttleai.com/getting-started/streaming

Enable token usage statistics in your stream by setting `stream_options` with `include_usage: True`. The final chunk will contain a `usage` object.

```python
stream = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
    stream_options={"include_usage": True}
)
```

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

### Add More Models to ShuttleAI Provider in OpenClaw

Source: https://docs.shuttleai.com/guides/openclaw

Extend the ShuttleAI provider configuration in `openclaw.json` to include additional models like GPT-5.2, Claude Opus, and Claude Sonnet. This allows the agent to utilize specific models for different tasks, such as deep reasoning or fast responses.

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "shuttleai": {
        "baseUrl": "https://api.shuttleai.com/v1",
        "apiKey": "YOUR_API_KEY_HERE",
        "api": "openai-completions",
        "models": [
          {
            "id": "shuttleai/auto",
            "name": "ShuttleAI Auto",
            "reasoning": false,
            "input": ["text"]
          },
          {
            "id": "openai/gpt-5.2",
            "name": "GPT-5.2"
          },
          {
            "id": "anthropic/claude-opus-4.6",
            "name": "Claude Opus 4.6"
          },
          {
            "id": "anthropic/claude-sonnet-4.6",
            "name": "Claude Sonnet 4.6"
          }
        ]
      }
    }
  }
}
```

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

### Set ShuttleAI API Key Environment Variable (Windows CMD)

Source: https://docs.shuttleai.com/getting-started/authentication

Store your ShuttleAI API key in an environment variable for secure access on Windows using the Command Prompt.

```cmd
set SHUTTLEAI_API_KEY=shuttle-xxx
```

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

### Create Chat Completion with cURL

Source: https://docs.shuttleai.com/api-reference/endpoint/chat-completion

Use this request to send a chat prompt to the ShuttleAI API. Ensure the Authorization header includes your valid API key.

```bash
curl https://api.shuttleai.com/v1/chat/completions \
  -H "Authorization: Bearer shuttle-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shuttleai/auto",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

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

### Define a weather lookup tool in Python

Source: https://docs.shuttleai.com/guides/tool-calling

Define the structure of a function for the model to call, including parameters and descriptions.

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g. 'San Francisco'"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location"]
            }
        }
    }
]
```

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

### Enable Basic Streaming with cURL

Source: https://docs.shuttleai.com/getting-started/streaming

Use `stream: true` in your JSON payload to enable streaming when making requests via cURL. Ensure the `Authorization` and `Content-Type` headers are correctly set.

```bash
curl https://api.shuttleai.com/v1/chat/completions \
  -H "Authorization: Bearer shuttle-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shuttleai/auto",
    "messages": [{"role": "user", "content": "Write a short poem about AI." }],
    "stream": true
    }'
```

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

### Combine MCP Tools with Function Tools

Source: https://docs.shuttleai.com/guides/mcp-servers

You can use MCP tools alongside regular function tools in the same request. This allows for a flexible combination of internal and external tool access.

```python
tools = [
    # Regular function tool
    {
        "type": "function",
        "function": {
            "name": "get_user_data",
            "description": "Get data for the current user",
            "parameters": {"type": "object", "properties": {}}
        }
    },
    # MCP tool
    {
        "type": "mcp",
        "server_url": "https://mcp.shuttleai.com/mcp",
        "require_approval": "never"
    }
]
```

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

### Add .env to .gitignore

Source: https://docs.shuttleai.com/dashboard/api-keys

Prevent accidental commitment of environment files containing API keys by adding them to your .gitignore file.

```gitignore
# .gitignore
.env
.env.local
```

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

### Handle tool calls and return results in Python

Source: https://docs.shuttleai.com/guides/tool-calling

Process the model's tool call request, execute the local function, and append the result back to the message history for a final response.

```python
message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "get_weather":
            import json
            args = json.loads(tool_call.function.arguments)
            
            # Your function — call a real weather API here
            weather_result = get_weather(args["location"], args.get("unit", "celsius"))
            
            # Add the assistant's tool call message
            messages.append(message)
            
            # Add the tool result
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(weather_result)
            })

    # Get the final response
    final_response = client.chat.completions.create(
        model="shuttleai/auto",
        messages=messages,
        tools=tools
    )
    
    print(final_response.choices[0].message.content)
```

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

### Make a Chat Completion Request

Source: https://docs.shuttleai.com/getting-started/quickstart

Perform a chat completion request using the OpenAI SDK or cURL.

```python
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is ShuttleAI?"}
    ]
)

print(response.choices[0].message.content)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shuttle-xxx",
  baseURL: "https://api.shuttleai.com/v1",
});

const response = await client.chat.completions.create({
  model: "shuttleai/auto",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is ShuttleAI?" },
  ],
});

console.log(response.choices[0].message.content);
```

```bash
curl https://api.shuttleai.com/v1/chat/completions \
  -H "Authorization: Bearer shuttle-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shuttleai/auto",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is ShuttleAI?"}
    ]
  }'
```

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

### Calculate Context Scaling Cost

Source: https://docs.shuttleai.com/pricing/multipliers

Formula to determine the total request cost based on prompt tokens and the model's base request multiplier.

```text
scaleFactor = promptTokens / 10000
totalCost = model\_request\_multiplier × scaleFactor
```

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

### POST /v1/chat/completions

Source: https://docs.shuttleai.com/api-reference/introduction

Generates text completions using the specified model.

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

### Description
Generate text completions based on the provided input.

### Method
POST

### Endpoint
/v1/chat/completions
```

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

### Implement Exponential Backoff in Python

Source: https://docs.shuttleai.com/guides/error-codes

A helper function to handle 429 rate limit errors by retrying requests with increasing wait times.

```python
import time

def make_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 1s, 2s, 4s
            else:
                raise
```

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

### Include API Key in Authorization Header

Source: https://docs.shuttleai.com/getting-started/authentication

Every request to the ShuttleAI API requires a valid API key. Keys are prefixed with `shuttle-` and sent as a Bearer token in the `Authorization` header.

```bash
Authorization: Bearer shuttle-xxxxxxxxxxxxx
```

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

### Create Chat Completion

Source: https://docs.shuttleai.com/api-reference/endpoint/chat-completion

This endpoint allows you to create chat completions by sending a model and a list of messages.

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

### Description
Creates a chat completion request.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for completion.
- **messages** (array) - Required - A list of messages comprising the conversation so far.
  - **role** (string) - Required - The role of the author of a message (e.g., system, user, assistant).
  - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model": "shuttleai/auto",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the completion.
- **object** (string) - The type of object returned, usually 'chat.completion'.
- **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.
  - **message** (object) - The message content.
    - **role** (string) - The role of the author of the message.
    - **content** (string) - The content of the message.
  - **finish_reason** (string) - The reason the model stopped generating tokens.
- **usage** (object) - Usage statistics for the request.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the completion.
  - **total_tokens** (integer) - Total number of tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "shuttleai/auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```
```

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

### Filter Available Tools on an MCP Server

Source: https://docs.shuttleai.com/guides/mcp-servers

Use the `allowed_tools` parameter to restrict which tools the model can access on an MCP server. This enhances security and control.

```python
tools=[
    {
        "type": "mcp",
        "server_url": "https://mcp.shuttleai.com/mcp",
        "allowed_tools": ["list_models", "chat_completion"],
        "require_approval": "never"
    }
]
```

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

### Authenticate MCP Server Calls

Source: https://docs.shuttleai.com/guides/mcp-servers

Pass your API key to the MCP server via headers for authentication. This ensures secure access to the external tools.

```python
response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "List all available models"}],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://mcp.shuttleai.com/mcp",
            "server_label": "ShuttleAI",
            "require_approval": "never",
            "headers": {
                "Authorization": "Bearer shuttle-xxx"
            }
        }
    ]
)
```

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

### Retrieve model information via cURL

Source: https://docs.shuttleai.com/api-reference/endpoint/model

Use this request to fetch details for a specific model. Requires a valid Bearer token in the Authorization header.

```bash
curl https://api.shuttleai.com/v1/models/shuttleai \
  -H "Authorization: Bearer shuttle-xxx"
```

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

### Set ShuttleAI API Key Environment Variable (Windows PowerShell)

Source: https://docs.shuttleai.com/getting-started/authentication

Store your ShuttleAI API key in an environment variable for secure access on Windows using PowerShell.

```powershell
$env:SHUTTLEAI_API_KEY = "shuttle-xxx"
```

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

### Verify OpenClaw Gateway Health

Source: https://docs.shuttleai.com/guides/openclaw

Check the health of the OpenClaw gateway to confirm that the ShuttleAI connection has been successfully established and is functioning correctly.

```bash
openclaw gateway health
```

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

### Restart OpenClaw Agent

Source: https://docs.shuttleai.com/guides/openclaw

After modifying the `openclaw.json` configuration file, restart the OpenClaw agent to apply the changes.

```bash
openclaw restart
```

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

### Execute chat completion with a specific model

Source: https://docs.shuttleai.com/models/overview

Use the model ID in the chat completions endpoint to route requests to a specific model.

```python
response = client.chat.completions.create(
    model="gpt-5.2",  # or "shuttleai/auto", "claude-opus-4.6", etc.
    messages=[{"role": "user", "content": "Hello!"}]
)
```

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

### Rate Limit Exceeded Error Response

Source: https://docs.shuttleai.com/pricing/multipliers

When your API usage exceeds your plan's RPM limit (factoring in multipliers), the API will return a 429 Too Many Requests error. This response indicates that you need to wait for the next minute window or consider upgrading your plan.

```json
{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "type": "rate_limit_error",
    "code": 429
  }
}
```

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

### API Response Format

Source: https://docs.shuttleai.com/getting-started/quickstart

The structure of the JSON response returned by the chat completions endpoint.

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "shuttleai/auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "ShuttleAI is a unified AI API platform..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 45,
    "total_tokens": 69
  }
}
```

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

### Target a Specific Model

Source: https://docs.shuttleai.com/getting-started/quickstart

Override the default model by specifying a different model ID in the request.

```python
# Use GPT-5.2 directly
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

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

### API Error Response Format

Source: https://docs.shuttleai.com/guides/error-codes

The standard JSON structure returned by the API when a request fails.

```json
{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": 400
  }
}
```

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

### Error Response Format

Source: https://docs.shuttleai.com/api-reference/introduction

This is the JSON structure for error responses from the ShuttleAI API. It includes a message, type, and HTTP status code.

```json
{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "code": 400
  }
}
```

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