# Authentication
Source: https://docs.shuttleai.com/api-reference/authentication
How to authenticate with the ShuttleAI API.
## API Key
All requests to the ShuttleAI API must include a valid API key in the `Authorization` header.
### Header format
```
Authorization: Bearer shuttle-xxx
```
### Getting a key
1. Sign up at [shuttleai.com](https://shuttleai.com/auth/register)
2. Go to [API Keys](https://shuttleai.com/keys)
3. Copy your master key or create a sub-key
### Example request
```bash theme={null}
curl https://api.shuttleai.com/v1/models \
-H "Authorization: Bearer shuttle-xxx"
```
## Key format
ShuttleAI API keys always start with the `shuttle-` prefix. If your key doesn't start with `shuttle-`, it's not a valid ShuttleAI key.
## Error responses
| Status | Description |
| ------- | ---------------------------------------- |
| **401** | Missing or invalid API key |
| **402** | No active plan on the account |
| **403** | Plan doesn't include the requested model |
| **423** | Account suspended |
For full error details, see [Error Codes](/guides/error-codes).
# Create Chat Completion
Source: https://docs.shuttleai.com/api-reference/endpoint/chat-completion
POST /v1/chat/completions
```bash cURL theme={null}
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!"}
]
}'
```
# Get Model
Source: https://docs.shuttleai.com/api-reference/endpoint/model
GET /v1/models/{id}
```bash cURL theme={null}
curl https://api.shuttleai.com/v1/models/shuttleai \
-H "Authorization: Bearer shuttle-xxx"
```
# List Models
Source: https://docs.shuttleai.com/api-reference/endpoint/models
GET /v1/models
```bash cURL theme={null}
curl https://api.shuttleai.com/v1/models \
-H "Authorization: Bearer shuttle-xxx"
```
# API Reference
Source: https://docs.shuttleai.com/api-reference/introduction
Complete reference for the ShuttleAI REST API.
The ShuttleAI API is fully **OpenAI-compatible**. If your code works with OpenAI, it works with ShuttleAI — just change the base URL and API key.
## Base URL
```
https://api.shuttleai.com/v1
```
## Authentication
All requests require a Bearer token in the `Authorization` header:
```
Authorization: Bearer shuttle-xxx
```
Get your API key from the [Dashboard](https://shuttleai.com/keys).
## SDKs
ShuttleAI works with any OpenAI-compatible SDK:
```python Python (OpenAI SDK) theme={null}
pip install openai
```
```bash Node.js (OpenAI SDK) theme={null}
npm install openai
```
### Python
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="shuttle-xxx",
base_url="https://api.shuttleai.com/v1"
)
```
### Node.js
```javascript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "shuttle-xxx",
baseURL: "https://api.shuttleai.com/v1",
});
```
## Available endpoints
| Endpoint | Method | Description |
| ---------------------- | ------ | -------------------------------- |
| `/v1/chat/completions` | POST | Generate text completions |
| `/v1/models` | GET | List all available models |
| `/v1/models/{id}` | GET | Get details for a specific model |
## Response format
All endpoints return JSON. Successful responses use standard HTTP 200. Errors return the appropriate HTTP status code with an error object:
```json theme={null}
{
"error": {
"message": "Error description",
"type": "error_type",
"code": 400
}
}
```
See [Error Codes](/guides/error-codes) for a complete reference.
## Rate limits
Rate limits depend on your [plan](/pricing/plans):
| Plan | Requests/minute |
| ------- | --------------- |
| Free | 2 |
| Basic | 10 |
| Premium | 30 |
| Scale | 80 |
Some models have [multipliers](/pricing/multipliers) that consume more than 1 request per call.
# API Keys
Source: https://docs.shuttleai.com/dashboard/api-keys
Create, manage, and secure your ShuttleAI API keys.
API keys authenticate your requests to the ShuttleAI API. You can manage your keys at [shuttleai.com/keys](https://shuttleai.com/keys).
## Master key
Every account has one **master key**. This is your primary API key with full access to all endpoints and models available on your plan.
Your master key is displayed as dots with only the last 4 characters visible for security. Use the **copy** button to copy it to your clipboard.
### Regenerating your master key
If your master key is compromised:
1. Go to [API Keys](https://shuttleai.com/keys)
2. Click the **Regenerate** button next to your master key
3. Confirm the action in the dialog
4. Update your key in all applications
Regenerating your master key **immediately invalidates** the old key. Any application using the old key will stop working.
## Sub-keys
Sub-keys let you create separate API keys for different applications, environments, or team members. Each sub-key has the same access level as your master key.
### Creating a sub-key
1. Go to [API Keys](https://shuttleai.com/keys)
2. Click **Create Sub-Key**
3. Give it a descriptive name (e.g., "Production Server", "Dev Environment")
4. Copy the new key
You can create up to **10 sub-keys** per account.
### Managing sub-keys
For each sub-key, you can:
* **Copy** — Copy the key to your clipboard
* **Rename** — Change the display name
* **Delete** — Permanently revoke the key
### Why use sub-keys?
Use different keys for development, staging, and production. If a dev key leaks, revoke just that one without affecting production.
Create a key for each app or service to track which application is making which requests.
If a key is compromised, delete just that sub-key. Your master key and other sub-keys remain unaffected.
## Key format
All ShuttleAI API keys start with the `shuttle-` prefix:
```
shuttle-xxxxxxxxxxxxxxxxxxxxx
```
## Best practices
Store your API key in environment variables, not in your source code.
```bash theme={null}
export SHUTTLEAI_API_KEY="shuttle-xxx"
```
Create a separate sub-key for each application instead of sharing your master key.
Periodically regenerate keys, especially if team members with access leave.
Add `.env` files to `.gitignore` to prevent accidentally committing keys.
```
# .gitignore
.env
.env.local
```
# Billing & Invoices
Source: https://docs.shuttleai.com/dashboard/billing
View invoices, manage payment methods, and understand your billing.
Manage your billing at [shuttleai.com/billing](https://shuttleai.com/billing).
## Billing overview
ShuttleAI uses **Stripe** for all payment processing. Your billing page shows:
* **Current plan** and subscription status
* **Invoice history** with amounts, dates, and payment status
* **Quick links** to view invoices and download PDFs
## Viewing invoices
The billing page displays a table of all your invoices:
| Column | Description |
| --------------- | ------------------------------------------- |
| **Date** | When the invoice was generated |
| **Description** | What the charge was for |
| **Amount** | Total charged |
| **Status** | `Paid`, `Open`, `Draft`, or `Void` |
| **Period** | The billing period this invoice covers |
| **Actions** | View the hosted invoice or download the PDF |
Click **View** to open the full invoice on Stripe, or **PDF** to download a copy for your records.
## Managing payment methods
To update your credit card or payment method:
1. Go to [shuttleai.com/billing](https://shuttleai.com/billing)
2. Click **Manage Billing** to open the Stripe billing portal
3. Update your payment method, view past invoices, or manage your subscription
The **Stripe billing portal** gives you full control over:
* Adding or removing payment methods
* Setting a default payment method
* Viewing detailed invoice breakdowns
* Downloading tax receipts
## Billing cycle
* Plans are billed **monthly**
* Your billing date is the day you first subscribed
* Upgrades are **prorated** — you pay the difference for the remaining period
* If payment fails, we'll retry a few times before your plan lapses
## Refunds
If you need a refund, contact us on [Discord](https://discord.com/invite/shuttleai) with your invoice details. Refunds are handled on a case-by-case basis.
## FAQ
You're charged immediately when you first subscribe, and then on the same day each month.
Yes — every invoice has a downloadable PDF and a hosted version on Stripe. Access them from the [Billing page](https://shuttleai.com/billing).
Stripe will retry the charge automatically. If it continues to fail, your plan will expire and you'll be prompted to update your payment method.
No. All payment information is handled securely by Stripe. ShuttleAI never sees or stores your card details.
# Dashboard Overview
Source: https://docs.shuttleai.com/dashboard/overview
Your command center for managing API usage, keys, plans, and more.
The ShuttleAI Dashboard at [shuttleai.com/dashboard](https://shuttleai.com/dashboard) is where you manage everything about your account.
## What you'll find
Real-time request charts, top models, and hourly activity breakdowns.
Generate, manage, and revoke your API keys and sub-keys.
Test models in a browser-based chat interface — no code required.
View and upgrade your subscription plan.
Invoices, payment history, and Stripe billing portal.
Browse all available models with details and capabilities.
## Analytics
The dashboard home page shows your usage at a glance:
* **Daily Requests** — Radial chart showing today's request count
* **Top Models** — Pie chart of your most-used models
* **Hourly Activity** — Area chart showing request distribution over time
* **Model Breakdown** — Stacked chart showing usage per model over time
Use the **date picker** to analyze usage for any period within the last 30 days.
## Navigation
The sidebar gives you quick access to all dashboard sections:
| Section | Description |
| -------------- | --------------------------------------------- |
| **Overview** | Usage analytics and request charts |
| **Playground** | Interactive chat interface for testing models |
| **API Keys** | Manage master key and sub-keys |
| **Plans** | View current plan and upgrade |
| **Billing** | Invoices and payment management |
| **Models** | Browse the full model catalog |
| **Settings** | Account settings, password, and 2FA |
## Quick links
External resources are also accessible from the sidebar:
* **[Status](https://status.shuttleai.com)** — Real-time API uptime and incident reports
* **[Docs](https://docs.shuttleai.com)** — You're here!
* **[Discord](https://discord.com/invite/shuttleai)** — Community support and announcements
* **[Telegram](https://t.me/shuttleai)** — Updates and discussion
# Choosing a Plan
Source: https://docs.shuttleai.com/dashboard/plans
How to subscribe to a plan and upgrade from the dashboard.
Manage your subscription at [shuttleai.com/plans](https://shuttleai.com/plans).
## Subscribing to a plan
Navigate to [shuttleai.com/plans](https://shuttleai.com/plans) or click **Plans** in the dashboard sidebar.
Review the available plans and pick the one that fits:
| Plan | Price | Best for |
| ----------- | ------- | --------------------------------------- |
| **Free** | \$0/mo | Testing and experimentation |
| **Basic** | \$10/mo | Personal projects and light usage |
| **Premium** | \$25/mo | Production apps needing frontier models |
| **Scale** | \$75/mo | High-volume applications |
Click the plan you want and complete payment through Stripe. Supports credit/debit cards.
Your plan activates **immediately**. You now have access to all models included in your tier.
## Upgrading your plan
You can upgrade at any time:
1. Go to [shuttleai.com/plans](https://shuttleai.com/plans)
2. Click the higher plan you want
3. Confirm the upgrade
Upgrades are **prorated** — you only pay the difference for the remaining days in your current billing period. Your new limits (RPM, context, models) take effect immediately.
### Upgrade path
```
Free → Basic → Premium → Scale
```
Each upgrade unlocks more models, higher rate limits, and larger context windows.
## What happens when your plan expires?
If your subscription ends or payment fails:
* Your plan reverts to **no plan** status
* You lose access to paid models
* The dashboard will prompt you to resubscribe
* Your API key, sub-keys, and usage history are preserved
## No-plan state
If you don't have an active plan:
* API calls to paid models return a **402** error
* Free models (GPT-OSS 20B, GPT-OSS 120B) remain accessible
* The dashboard shows a plan selection dialog prompting you to subscribe
## Downgrading
Self-service downgrades are not currently available. To downgrade:
1. Join our [Discord](https://discord.com/invite/shuttleai)
2. Open a support ticket
3. We'll process the change manually
## Enterprise
Need custom rate limits, SLAs, or team management? Enterprise plans are available with custom pricing.
Contact us on [Discord](https://discord.com/invite/shuttleai) to discuss your requirements.
# Playground
Source: https://docs.shuttleai.com/dashboard/playground
Test any model in a browser-based chat interface — no code required.
The ShuttleAI Playground at [shuttleai.com/playground](https://shuttleai.com/playground) is an interactive chat interface for testing models directly in your browser.
## Features
### Model selection
Use the **model selector** dropdown to choose any model available on your plan. The list shows all chat completion models with their provider and tier.
### System message
Set a **system message** to define the AI's behavior and personality. This is the same as the `system` role in the API:
```
You are a helpful coding assistant that writes clean, well-documented Python code.
```
### Parameter controls
Fine-tune model behavior with adjustable sliders:
| Parameter | Range | Description |
| --------------- | ----- | ----------------------------------------------------------------- |
| **Temperature** | 0 – 2 | Controls randomness. Lower = more focused, higher = more creative |
| **Top P** | 0 – 1 | Nucleus sampling. Controls diversity of token selection |
### Streaming
Responses stream in real-time, token by token — just like they would in your application. You can see the **tokens/second** rate displayed during generation.
### Stop generation
Click the **Stop** button to immediately halt a response mid-generation. Useful when you can see the model is going in the wrong direction.
## Using the Playground
Pick a model from the dropdown. Start with **ShuttleAI Auto** if you're not sure.
Define how the AI should behave. Leave blank for default behavior.
Enter your prompt in the input field at the bottom.
Press Enter or click Send. Continue the conversation, adjust parameters, or try a different model.
## Tips
Try the same prompt with different models to compare quality and speed. Open multiple browser tabs for side-by-side comparison.
Use the Playground to validate your prompts and system messages before integrating them into your application.
Click the **Clear** button to start a fresh conversation. This resets the message history but keeps your system message and parameters.
## Error handling
The Playground shows clear error messages for common issues:
| Error | Meaning |
| ------- | ---------------------------------------------------------- |
| **429** | Rate limit exceeded — wait and try again |
| **402** | No active plan — [subscribe to a plan](/dashboard/plans) |
| **403** | Model requires a higher plan — [upgrade](/dashboard/plans) |
# Authentication
Source: https://docs.shuttleai.com/getting-started/authentication
Authenticate your API requests with a ShuttleAI API key.
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.
## Getting your API key
1. Log in to the [ShuttleAI Dashboard](https://shuttleai.com/dashboard)
2. Navigate to [API Keys](https://shuttleai.com/keys)
3. Copy your master key, or create a sub-key for specific use cases
Never share your API key or commit it to version control. Treat it like a password.
## Using your key
Include your API key in the `Authorization` header of every request:
```bash theme={null}
Authorization: Bearer shuttle-xxxxxxxxxxxxx
```
### With the OpenAI SDK
```python Python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="shuttle-xxx",
base_url="https://api.shuttleai.com/v1"
)
```
```javascript Node.js theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "shuttle-xxx",
baseURL: "https://api.shuttleai.com/v1",
});
```
### With cURL
```bash theme={null}
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"}]}'
```
## Environment variables
Store your key in an environment variable to keep it out of your code:
```bash Linux / macOS theme={null}
export SHUTTLEAI_API_KEY="shuttle-xxx"
```
```powershell Windows (PowerShell) theme={null}
$env:SHUTTLEAI_API_KEY = "shuttle-xxx"
```
```cmd Windows (CMD) theme={null}
set SHUTTLEAI_API_KEY=shuttle-xxx
```
Then reference it in your code:
```python Python theme={null}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["SHUTTLEAI_API_KEY"],
base_url="https://api.shuttleai.com/v1"
)
```
```javascript Node.js theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.SHUTTLEAI_API_KEY,
baseURL: "https://api.shuttleai.com/v1",
});
```
## Sub-keys
Sub-keys let you create scoped API keys for different applications or team members. You can create up to **10 sub-keys** per account.
Manage sub-keys from the [API Keys page](https://shuttleai.com/keys) in the dashboard. Each sub-key can be individually renamed or revoked without affecting your master key.
See [API Keys](/dashboard/api-keys) for a full guide on managing your keys.
# Welcome to ShuttleAI
Source: https://docs.shuttleai.com/getting-started/introduction
Affordable, high-performance AI APIs — one key, every model.
## What is ShuttleAI?
ShuttleAI gives you access to the world's best AI models through a single, unified API. One API key — GPT-5.2, Claude Opus 4.6, Claude Sonnet 4.6, open-source models, and more — all at a fraction of the cost.
Make your first API call in under a minute.
Explore available models and capabilities.
Plans starting at \$0/month.
Manage keys, billing, and usage.
## Why ShuttleAI?
Access GPT-5.2, Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5, and more through a single OpenAI-compatible endpoint. No juggling multiple providers.
Our plans are designed to save you money. Use the **ShuttleAI Auto** model to let our smart router pick the best model for your task — automatically optimizing for cost and quality.
Drop-in replacement for OpenAI's API. Use any existing OpenAI SDK or library — just swap the base URL and API key.
Get started with GPT-OSS 20B and GPT-OSS 120B at no cost. Upgrade when you need more.
## Get started in 3 steps
Sign up at [shuttleai.com](https://shuttleai.com) and grab your API key from the [dashboard](https://shuttleai.com/keys).
Start free or pick a [plan](/pricing/plans) that fits your usage. Plans start at **\$10/month** for access to GPT-5.2 and Claude Haiku 4.5.
Point your OpenAI SDK at `https://api.shuttleai.com/v1` and start building.
```python theme={null}
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)
```
# Quickstart
Source: https://docs.shuttleai.com/getting-started/quickstart
Make your first ShuttleAI API call in under a minute.
ShuttleAI is fully compatible with the OpenAI SDK. Just change the base URL and API key — everything else works out of the box.
## Prerequisites
* A ShuttleAI account — [sign up here](https://shuttleai.com/auth/register)
* An API key — [generate one here](https://shuttleai.com/keys)
## Installation
```bash Python theme={null}
pip install openai
```
```bash Node.js theme={null}
npm install openai
```
## Your first request
```python Python theme={null}
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 Node.js theme={null}
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 theme={null}
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?"}
]
}'
```
## Response format
```json theme={null}
{
"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
}
}
```
## Using a specific model
Replace `"shuttleai/auto"` with any model ID to target a specific model:
```python theme={null}
# Use GPT-5.2 directly
response = client.chat.completions.create(
model="gpt-5.2",
messages=[{"role": "user", "content": "Hello!"}]
)
```
Use the `shuttleai/auto` model (ShuttleAI Auto) to let our smart router automatically pick the best model for your task. It's the most cost-efficient way to use the API. [Learn more →](/models/shuttleai-auto)
## Next steps
Set up your API key properly.
Get responses token by token.
See what models are available.
Give models access to functions.
# Streaming
Source: https://docs.shuttleai.com/getting-started/streaming
Receive AI responses token-by-token in real time using server-sent events.
Streaming lets you display AI responses as they're generated, instead of waiting for the full response. This creates a much better user experience for chat interfaces.
ShuttleAI uses **Server-Sent Events (SSE)** — the same streaming format as OpenAI.
## Basic streaming
Set `stream: true` in your request to enable streaming:
```python Python theme={null}
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)
```
```javascript Node.js theme={null}
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);
}
```
```bash cURL theme={null}
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
}'
```
## Async streaming (Python)
For async applications, use the async client:
```python theme={null}
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())
```
## Stream with usage stats
To receive token usage statistics with your stream, enable `stream_options`:
```python theme={null}
stream = client.chat.completions.create(
model="shuttleai/auto",
messages=[{"role": "user", "content": "Hello!"}],
stream=True,
stream_options={"include_usage": True}
)
```
The final chunk in the stream will include a `usage` object with `prompt_tokens`, `completion_tokens`, and `total_tokens`.
## SSE format
Each streamed chunk is a JSON object sent as an SSE event:
```
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]
```
The stream ends with `data: [DONE]`.
# The ShuttleAI API Abuse System
Source: https://docs.shuttleai.com/guides/abuse-system
How ShuttleAI detects and handles API abuse — dynamic thresholds, concurrency limits, reselling detection, and enforcement escalation.
ShuttleAI uses a multi-layered abuse detection system to keep the platform fair, fast, and affordable for everyone. This page explains what we consider abuse, how we detect it, and what happens when it's flagged.
Reselling API access, proxying requests for third parties, or operating ShuttleAI as a cheap upstream proxy is **strictly prohibited** and will result in account termination.
***
## What Counts as Abuse
For an AI API, abuse isn't just "high usage." It's **behavioral patterns** that indicate misuse:
* Mass reselling traffic through a single key
* Sudden massive spikes in token consumption
* High concurrency from a low-age account
* 24/7 maxed-out throughput usage
* Unusual token patterns (e.g., huge context windows on every request)
We detect **behavior**, not just raw volume.
***
## Dynamic Percentile Thresholds
Instead of hard-coding a flat token limit, ShuttleAI uses a **dynamic percentile system** that scales with real usage across each plan tier.
This means the threshold naturally adjusts as the platform grows — no manual tuning required.
Percentiles are computed **per tier**. Free users do not affect Premium thresholds, and Premium users do not affect Scale thresholds. Full tier isolation is enforced.
***
## Abuse Score
Every ShuttleAI account has an **abuse score** from 0 to 100, visible in your dashboard. It represents how much of your plan's monthly budget you've consumed.
* Score **resets on the 1st of each month**
* The score is calculated as a percentage of your plan's monthly unit budget
* You can check your current score anytime via the dashboard
It's not just how high your score gets — it's **how fast**. A score of 25 reached gradually over a month is normal. A score of 25 reached in a few hours raises flags.
The faster your abuse score climbs, the more likely it is to trigger review. Most users never exceed 50%.
**Upgrading your plan directly lowers your abuse score.** Your score is a percentage of your plan's monthly unit budget — a higher-tier plan means a larger budget, so the same amount of usage translates to a lower score. If your score is climbing high, upgrading to a higher plan is the fastest way to bring it back down and give yourself more headroom.
***
## Concurrency & Rate Limits
Tokens alone don't tell the full story. We also enforce **concurrency and rate limits** per tier:
| Plan | Concurrent Requests | RPM Cap | TPM Cap |
| ------- | ------------------- | -------- | -------- |
| Free | 2 | Low | Low |
| Basic | 5 | Moderate | Moderate |
| Premium | 15 | High | High |
| Scale | Custom | Custom | Custom |
We track:
* Requests per minute (RPM)
* Parallel / concurrent requests
* Burst usage patterns
* Model mix usage
***
## Reselling & Proxy Detection
Reselling ShuttleAI access is the single biggest abuse risk. Someone buying a Premium plan and reselling GPT-5.2 access at a markup undermines the entire platform.
***
## Enforcement Thresholds
ShuttleAI uses your abuse score and the **rate of increase** to determine enforcement actions.
* If reached in a short amount of time, you may receive an email asking about your use case
* No action taken — just a check-in
* Possible warning issued to your account
* You'll be asked to slow down usage
* Your API key is automatically deactivated
* Support may restore your key
Reaching 100% doesn't mean you're banned — it means your key is paused until a human can review your account. Most cases are resolved quickly.
Rarely does anyone exceed 50%. If you're hitting these thresholds, it's likely a misconfiguration or runaway process — reach out on [Discord](https://discord.com/invite/shuttleai) and we'll help.
***
## Transparency Policy
We believe in being transparent about **what** we protect against, without giving abusers a roadmap.
### Published (this page)
* Safe floor numbers per plan
* General abuse policy and enforcement steps
* Types of behavior we monitor
### Not Published
* Exact percentile formula
* Exact unit costs per model
If we exposed the exact math, people would game it.
***
## Summary
| Allowed | Not Allowed |
| --------------------------------------------- | ------------------------------------------- |
| Using the API in your own app | Reselling API access to others |
| Building tools for personal use | Offering a proxy / wrapper API |
| Moderate, direct application traffic | Excessive or redistributed traffic |
| Using a normal amount | 24/7 maxed-out bot-like usage |
| Upgrading your plan to lower your abuse score | Staying on a low tier and hammering the API |
Questions about a specific use case? Reach out on [Discord](https://discord.com/invite/shuttleai) and we'll help you figure out if it fits.
# Error Codes
Source: https://docs.shuttleai.com/guides/error-codes
Common API error codes, what they mean, and how to fix them.
When something goes wrong, the ShuttleAI API returns a JSON error response with an HTTP status code, error message, and error type.
## Error response format
```json theme={null}
{
"error": {
"message": "Detailed error description",
"type": "error_type",
"code": 400
}
}
```
## Error codes
### 400 — Bad Request
**Your request is malformed or missing required fields.**
Common causes:
* Missing or empty `messages` array
* Invalid `model` ID
* Malformed JSON body
* Invalid parameter values (e.g., `temperature: 5`)
**Fix:** Check your request body against the [API reference](/api-reference/introduction).
***
### 401 — Unauthorized
**Your API key is missing, invalid, or malformed.**
Common causes:
* No `Authorization` header
* API key doesn't start with `shuttle-`
* Typo in the API key
**Fix:** Double-check your API key. Make sure the header is `Authorization: Bearer shuttle-xxx`.
***
### 402 — Payment Required
**You don't have an active plan.**
Common causes:
* No subscription on your account
* Subscription has expired
* Payment failed
**Fix:** [Subscribe to a plan](https://shuttleai.com/plans) or check your [billing page](https://shuttleai.com/billing) for payment issues.
***
### 403 — Forbidden
**Your plan doesn't include access to the requested model.**
Common causes:
* Trying to use a Premium model on a Basic plan
* Trying to use a Basic model on a Free plan
**Fix:** [Upgrade your plan](https://shuttleai.com/plans) to access higher-tier models, or switch to a model available on your current tier.
***
### 423 — Locked
**Your account has been suspended.**
Common causes:
* Terms of service violation
* Abuse detected
**Fix:** Contact support on [Discord](https://discord.com/invite/shuttleai) for more information.
***
### 429 — Too Many Requests
**You've exceeded your rate limit.**
Common causes:
* Sending more requests per minute than your plan allows
* Not accounting for [request multipliers](/pricing/multipliers)
**Fix:** Wait until the next minute window and retry. Consider upgrading for higher rate limits.
Implement exponential backoff in your code to handle 429 errors gracefully:
```python theme={null}
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
```
***
### 500 — Internal Server Error
**Something went wrong on our end.**
**Fix:** Wait a moment and retry. If the error persists, check [status.shuttleai.com](https://status.shuttleai.com) or report it on [Discord](https://discord.com/invite/shuttleai).
***
### 503 — Service Unavailable
**The requested model or service is temporarily unavailable.**
Common causes:
* Model is undergoing maintenance
* Upstream provider is down
* High demand causing temporary capacity issues
**Fix:** Try a different model, or wait and retry. Check [status.shuttleai.com](https://status.shuttleai.com) for ongoing incidents.
## Best practices
Never assume API calls will succeed. Wrap calls in try/catch and handle each error code appropriately.
For 429 and 5xx errors, retry with exponential backoff instead of immediately re-sending.
Log the full error response (message + type + code) to make debugging easier.
Use the [Dashboard](/dashboard/overview) to understand your usage patterns and avoid hitting rate limits.
# MCP Servers
Source: https://docs.shuttleai.com/guides/mcp-servers
Connect AI models to external tools and services using the Model Context Protocol.
The **Model Context Protocol (MCP)** lets you connect AI models to external tool servers. Instead of defining tools inline, you point the model at an MCP server URL and it discovers and uses the available tools automatically.
## How MCP works
1. You provide an MCP server URL in the `tools` array
2. The model connects to the server and discovers available tools
3. The model calls tools as needed to fulfill the request
4. Results are incorporated into the final response
## Using an MCP server
Add an MCP tool type to your request:
```python theme={null}
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)
```
## MCP tool parameters
| Parameter | Type | Required | Description |
| ------------------ | --------- | -------- | ---------------------------------------- |
| `type` | string | Yes | Must be `"mcp"` |
| `server_url` | string | Yes | URL of the MCP server |
| `server_label` | string | No | Human-readable label for the server |
| `allowed_tools` | string\[] | No | Restrict which tools the model can use |
| `require_approval` | string | No | `"never"` to auto-approve tool calls |
| `headers` | object | No | Custom headers to send to the MCP server |
## ShuttleAI's official MCP server
We provide an official MCP server at:
```
https://mcp.shuttleai.com/mcp
```
Available tools on the official server:
| Tool | Description |
| ----------------- | ------------------------- |
| `chat_completion` | Generate text completions |
| `list_models` | List available models |
| `model_analytics` | Get model usage analytics |
### Authentication
Pass your API key to the MCP server via headers:
```python theme={null}
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"
}
}
]
)
```
## Filtering tools
Use `allowed_tools` to restrict which tools the model can access:
```python theme={null}
tools=[
{
"type": "mcp",
"server_url": "https://mcp.shuttleai.com/mcp",
"allowed_tools": ["list_models", "chat_completion"],
"require_approval": "never"
}
]
```
## Combining MCP with function tools
You can use MCP tools alongside regular function tools in the same request:
```python theme={null}
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"
}
]
```
## Building your own MCP server
Any server that implements the [Model Context Protocol](https://modelcontextprotocol.io/) specification can be used with ShuttleAI. This lets you give AI models access to your own internal tools, databases, and APIs.
# Run OpenClaw with ShuttleAI
Source: https://docs.shuttleai.com/guides/openclaw
Connect OpenClaw to ShuttleAI in minutes — one API for Claude, GPT, and more.
[OpenClaw](https://openclaw.com) is a powerful open-source AI agent. It can browse the web, manage files, run terminal commands, and connect to apps like Discord or WhatsApp.
ShuttleAI gives you **one API** for Claude, GPT, and other top models — so you don't have to juggle multiple providers. One subscription. One endpoint. Simple.
## Why use ShuttleAI with OpenClaw?
OpenClaw supports any LLM provider. ShuttleAI makes it easier by unifying everything under one API:
* **ShuttleAI Auto** — Smart router that picks the best model for each task
* **Claude Opus 4.6** — Deep reasoning and complex agent workflows
* **Claude Sonnet 4.6** — Fast, high-quality responses
* **GPT-5.2** — Latest GPT-5 series
* **GPT-OSS 120B** — Free, high-performance open-source model
* And more at [shuttleai.com/models](https://shuttleai.com/models)
No switching dashboards. No juggling API keys from different companies.
## Step 1 — Create a ShuttleAI account
Go to [shuttleai.com](https://shuttleai.com) and click **Get API Key** to create your account.
Pick a plan based on the models you need:
| Plan | Best for | Key models |
| ----------- | ----------------- | ----------------------------------------- |
| **Free** | Testing | GPT-OSS 20B, GPT-OSS 120B |
| **Basic** | Light usage | ShuttleAI Auto, GPT-5.2, Claude Haiku 4.5 |
| **Premium** | Agent workflows | Claude Opus 4.6, Claude Sonnet 4.6 |
| **Scale** | Production agents | All models + priority |
For serious agent workflows with Claude Opus or Sonnet, choose **Premium** or **Scale**.
Go to the [Dashboard](https://shuttleai.com/keys) and copy your API key.
## Step 2 — Locate your OpenClaw config
OpenClaw stores its configuration at:
```
~/.openclaw/openclaw.json
```
This file controls your providers and models.
You can override the default location using environment variables: `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, or `OPENCLAW_CONFIG_PATH`.
The workspace directory for agent memory is usually:
```
~/openclaw/workspace
```
## Step 3 — Edit openclaw\.json
Open the config file:
```bash theme={null}
nano ~/.openclaw/openclaw.json
```
Add ShuttleAI as a provider:
```json theme={null}
{
"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"
}
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual ShuttleAI API key. Save and exit.
## Step 4 — Restart OpenClaw
Restart the agent to apply the new config:
```bash theme={null}
openclaw restart
```
Verify the connection:
```bash theme={null}
openclaw gateway health
```
If it returns healthy, ShuttleAI is connected.
## Adding more models
You can add additional models under the ShuttleAI provider:
```json theme={null}
{
"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"
}
]
}
}
}
}
```
Now your agent can:
* Use **Opus** for deep reasoning
* Use **Sonnet** for fast tasks
* Use **Auto** for the most cost-efficient routing
* Use **GPT-OSS** for lightweight, free work
All from one API.
## Why teams choose ShuttleAI for OpenClaw
No token math. Predictable monthly plans instead of per-token billing.
One endpoint, one key — access Claude, GPT, and more without switching providers.
Upgrade your plan as your agent usage grows. No infrastructure changes needed.
Reliable infrastructure built for always-on agents and bots.
# Tool Calling
Source: https://docs.shuttleai.com/guides/tool-calling
Give AI models the ability to call functions and interact with external systems.
Tool calling (also known as function calling) lets models request to execute functions you define. The model decides when to call a tool and what arguments to pass — your application executes the function and returns the result.
Tool calling requires the **Basic** plan or higher. Check [shuttleai.com/models](https://shuttleai.com/models) to see which models support tool calling.
## How it works
Describe the functions the model can call, including their parameters.
Include the tool definitions in your API request alongside the conversation.
If the model determines it needs to use a tool, it responds with a `tool_calls` array instead of a regular message.
Your application runs the requested function with the provided arguments.
Send the function result back to the model as a `tool` message.
The model incorporates the function result and produces a final answer.
## Example: Weather lookup
### 1. Define the tool
```python theme={null}
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"]
}
}
}
]
```
### 2. Send the request
```python theme={null}
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"
)
```
### 3. Handle the tool call
```python theme={null}
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)
```
## Full example
Here's the complete flow in one script:
```python Python theme={null}
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)
```
```javascript Node.js theme={null}
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);
```
## Parallel tool calls
Models can request **multiple tool calls** in a single response. For example, if the user asks "What's the weather in Tokyo and New York?", the model may return two tool calls at once.
Always iterate over the full `tool_calls` array and return results for all of them before sending the next request.
## Tool choice
Control when the model uses tools with `tool_choice`:
| Value | Behavior |
| --------------------------------------------------- | ---------------------------------------------- |
| `"auto"` | Model decides whether to call a tool (default) |
| `"none"` | Model will never call tools |
| `"required"` | Model must call at least one tool |
| `{"type": "function", "function": {"name": "..."}}` | Force a specific tool |
## Streamed tool calls
Tool calls work with streaming too. When streaming, tool call arguments arrive incrementally across chunks. The OpenAI SDK handles this automatically.
## Supported models
Tool calling is supported on models that have the **Tools** badge at [shuttleai.com/models](https://shuttleai.com/models), including:
* ShuttleAI Auto
* GPT-5.2
* Claude Opus 4.6
* Claude Sonnet 4.6
* Claude Haiku 4.5
# Model Tiers
Source: https://docs.shuttleai.com/models/model-tiers
Understand the free, basic, and premium model tiers and what they include.
Every model on ShuttleAI is assigned a **tier** that determines the minimum plan required to use it. Higher-tier models generally offer better reasoning, larger context windows, or are from frontier providers.
## Tier breakdown
### Free tier
Available to everyone — no plan required.
| Model | Provider | Context | Notes |
| ------------ | -------- | ------- | ---------------------------------- |
| GPT-OSS 20B | OpenAI | 131K | Lightweight open-source model |
| GPT-OSS 120B | OpenAI | 131K | High-performance open-source model |
Free-tier models are ideal for experimentation, prototyping, and lightweight tasks.
### Basic tier
Requires the **Basic** plan (\$10/mo) or higher.
| Model | Provider | Context | Notes |
| ---------------- | --------- | ------- | ----------------------- |
| ShuttleAI Auto | ShuttleAI | 400K | Smart request router |
| GPT-5.2 | OpenAI | 400K | Latest GPT-5 series |
| Claude Haiku 4.5 | Anthropic | 200K | Fastest Anthropic model |
Basic-tier models offer strong performance for everyday use at an affordable price.
### Premium tier
Requires the **Premium** plan (\$25/mo) or higher.
| Model | Provider | Context | Notes |
| ----------------- | --------- | ------- | -------------------------------- |
| Claude Opus 4.6 | Anthropic | 200K | Most intelligent Anthropic model |
| Claude Sonnet 4.6 | Anthropic | 200K | Best speed/intelligence balance |
Premium-tier models are frontier-level — the most capable models available.
The **Scale** plan (\$75/mo) includes access to **all** models plus early access to beta models and higher rate limits. See [Plans](/pricing/plans) for details.
## How tiers affect your usage
* If your plan doesn't include a model's tier, the API returns a **403** error
* You can always use models from **lower** tiers (e.g., Premium plans can use Free and Basic models)
* Some models have a [request multiplier](/pricing/multipliers) that costs multiple requests per call
## Checking model requirements
Use the verbose models endpoint to see tier requirements for each model:
```bash theme={null}
curl https://api.shuttleai.com/v1/models/verbose \
-H "Authorization: Bearer shuttle-xxx"
```
Each model includes a `plan` field indicating the minimum tier:
```json theme={null}
{
"id": "claude-opus-4.6",
"plan": "premium",
"request_multiplier": 2.0,
"permission": {
"context_length": 200000,
"max_output": 32000,
"tool_calling": true
}
}
```
See the complete, up-to-date model list with tiers at shuttleai.com/models.
# Models
Source: https://docs.shuttleai.com/models/overview
ShuttleAI gives you access to the world's best AI models through a single API.
ShuttleAI provides access to models from **OpenAI**, **Anthropic**, **open-source communities**, and our own proprietary routing model — all through one unified, OpenAI-compatible API.
Our model list is updated frequently. For the most current list of available models, visit [shuttleai.com/models](https://shuttleai.com/models).
## Featured models
| Model | Provider | Context | Tier | Highlights |
| --------------------- | --------- | ------- | ------- | ------------------------------------------------- |
| **ShuttleAI Auto** | ShuttleAI | 400K | Basic | Smart router — picks the best model automatically |
| **GPT-5.2** | OpenAI | 400K | Basic | Latest GPT-5 series with improved reasoning |
| **GPT-OSS 120B** | OpenAI | 131K | Free | High-performance open-source model |
| **GPT-OSS 20B** | OpenAI | 131K | Free | Lightweight open-source model |
| **Claude Opus 4.6** | Anthropic | 200K | Premium | Anthropic's most intelligent model |
| **Claude Sonnet 4.6** | Anthropic | 200K | Premium | Best balance of speed and intelligence |
| **Claude Haiku 4.5** | Anthropic | 200K | Basic | Ultra-fast with near-frontier intelligence |
## Model tiers
Every model is assigned to a **tier** that determines which [plan](/pricing/plans) you need:
Open-source models like GPT-OSS 20B and GPT-OSS 120B. No plan required.
GPT-5.2, Claude Haiku 4.5, ShuttleAI Auto, and more. Requires the **Basic** plan (\$10/mo) or higher.
Frontier models like Claude Opus 4.6 and Claude Sonnet 4.6. Requires the **Premium** plan (\$25/mo) or higher.
## Listing models via API
Fetch all available models programmatically:
```bash theme={null}
curl https://api.shuttleai.com/v1/models \
-H "Authorization: Bearer shuttle-xxx"
```
For detailed model info including context limits, tool support, and plan requirements:
```bash theme={null}
curl https://api.shuttleai.com/v1/models/verbose \
-H "Authorization: Bearer shuttle-xxx"
```
### Verbose response fields
Each model in the verbose response includes:
| Field | Description |
| --------------------------- | -------------------------------------------------------------------------- |
| `id` | Model ID to use in API requests |
| `plan` | Minimum plan tier required (`free`, `basic`, `premium`) |
| `request_multiplier` | Cost multiplier applied to this model ([learn more](/pricing/multipliers)) |
| `permission.context_length` | Maximum input context window |
| `permission.max_output` | Maximum output tokens |
| `permission.tool_calling` | Whether the model supports tool/function calling |
## Using a model
Specify the model ID in the `model` field of your request:
```python theme={null}
response = client.chat.completions.create(
model="gpt-5.2", # or "shuttleai/auto", "claude-opus-4.6", etc.
messages=[{"role": "user", "content": "Hello!"}]
)
```
Not sure which model to use? Try [ShuttleAI Auto](/models/shuttleai-auto) — it intelligently routes your request to the best model for the job and is the most cost-efficient option.
See the full, always-up-to-date list of available models at shuttleai.com/models.
# ShuttleAI Auto
Source: https://docs.shuttleai.com/models/shuttleai-auto
Our intelligent request router that automatically picks the best model for every task.
## What is ShuttleAI Auto?
**ShuttleAI Auto** (`shuttleai`) is our proprietary smart routing model. Instead of you choosing which model to use for each request, ShuttleAI Auto analyzes your prompt and dynamically routes it to the best model for the task.
Whether it's a quick question, a complex coding task, or a long-form creative piece — ShuttleAI Auto picks the right model automatically.
```python theme={null}
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."}]
)
```
## Why use ShuttleAI Auto?
Auto optimizes for the best balance of quality and cost. You get great results without overpaying for a frontier model when a lighter one would do.
Stop wondering whether to use GPT-5.2 or Claude — Auto makes that decision for you based on the actual task.
As we add new models and improve routing logic, Auto gets better automatically. No code changes needed on your end.
Supports up to 400K tokens of context, so it can handle even the longest documents and conversations.
## How it works
ShuttleAI Auto analyzes the characteristics of your request — including complexity, length, domain, and required capabilities — then routes it to the most appropriate model available for your plan tier.
ShuttleAI Auto requires the **Basic** plan (\$10/mo) or higher.
## Capabilities
| Feature | Supported |
| ----------------------- | ----------- |
| Text generation | ✅ |
| Tool / function calling | ✅ |
| Streaming | ✅ |
| System messages | ✅ |
| Context window | 400K tokens |
## When to use Auto vs. a specific model
| Use case | Recommendation |
| ------------------------------------ | ------------------------------------------------- |
| General-purpose tasks | **ShuttleAI Auto** — best cost-efficiency |
| You need a specific model's behavior | Use that model directly (e.g., `claude-opus-4.6`) |
| Maximum quality, cost doesn't matter | Pick a frontier model like `claude-opus-4.6` |
| Free tier usage | Use `gpt-oss-20b` or `gpt-oss-120b` directly |
## Example
```python Python theme={null}
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)
```
```javascript Node.js theme={null}
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);
```
**Getting started?** Just use `"shuttleai/auto"` as your model everywhere. You'll get great results at the lowest cost, and you can always switch to a specific model later if needed.
# Multipliers
Source: https://docs.shuttleai.com/pricing/multipliers
How request and context multipliers work and what they mean for your usage.
ShuttleAI uses **multipliers** to fairly price access to different models and context sizes. There are two types: **request multipliers** and **context multipliers**.
***
## Request multipliers
Every model has a **request multiplier** — a number that determines how many of your per-minute requests each API call consumes.
Most models have a **1x multiplier** (one API call = one request). Larger or more expensive models have a higher multiplier to reflect their compute cost.
## How they work
Your plan gives you a set number of **requests per minute (RPM)**:
| Plan | RPM |
| ------- | --- |
| Free | 2 |
| Basic | 10 |
| Premium | 30 |
| Scale | 80 |
When you call a model, the multiplier is deducted from your available RPM:
You send a request to a model with a 2x multiplier.
The system deducts **2 requests** from your per-minute quota instead of 1.
If you're on the Premium plan (30 RPM), you now have 28 RPM remaining for that minute.
## Examples
### Basic plan (10 RPM)
| Model | Multiplier | Effective calls/min |
| ---------------- | ---------- | ------------------- |
| ShuttleAI Auto | 1x | 10 |
| GPT-5.2 | 1.5x | \~6 |
| Claude Haiku 4.5 | 1x | 10 |
### Premium plan (30 RPM)
| Model | Multiplier | Effective calls/min |
| ----------------- | ---------- | ------------------- |
| ShuttleAI Auto | 1x | 30 |
| GPT-5.2 | 1.5x | 20 |
| Claude Opus 4.6 | 2x | 15 |
| Claude Sonnet 4.6 | 2x | 15 |
| Claude Haiku 4.5 | 1x | 30 |
### Scale plan (80 RPM)
| Model | Multiplier | Effective calls/min |
| ----------------- | ---------- | ------------------- |
| ShuttleAI Auto | 1x | 80 |
| GPT-5.2 | 1.5x | \~53 |
| Claude Opus 4.6 | 2x | 40 |
| Claude Sonnet 4.6 | 2x | 40 |
| Claude Haiku 4.5 | 1x | 80 |
## Checking multipliers
You can check any model's multiplier using the verbose models endpoint:
```bash theme={null}
curl https://api.shuttleai.com/v1/models/verbose \
-H "Authorization: Bearer shuttle-xxx"
```
Each model includes a `request_multiplier` field:
```json theme={null}
{
"id": "claude-opus-4.6",
"plan": "premium",
"request_multiplier": 2.0
}
```
You can also see multipliers displayed on each model card at [shuttleai.com/models](https://shuttleai.com/models).
## Tips for managing multipliers
ShuttleAI Auto has a 1x multiplier and intelligently routes to the best model for each task. It's the most cost-efficient way to use the API.
Use lighter models (1x) for simple tasks and save your budget for frontier model calls (2x) when you need maximum quality.
The [Dashboard](/dashboard/overview) shows your request usage in real time, including breakdowns by model. Use this to understand how multipliers affect your usage patterns.
If you're consistently hitting rate limits, consider upgrading your plan. The jump from Basic (10 RPM) to Premium (30 RPM) gives you 3x the capacity.
## Rate limit errors
If you exceed your RPM (accounting for multipliers), the API returns a **429 Too Many Requests** error:
```json theme={null}
{
"error": {
"message": "Rate limit exceeded. Please try again later.",
"type": "rate_limit_error",
"code": 429
}
}
```
Wait until the next minute window to retry, or upgrade your plan for higher limits.
***
## Context window limits & scaling
Your plan determines the **maximum number of tokens** you can send in a single request. This is a hard limit — requests that exceed it are rejected.
| Plan | Max context |
| ------- | ----------- |
| Free | 8K tokens |
| Basic | 16K tokens |
| Premium | 36K tokens |
| Scale | 128K tokens |
If your request exceeds your plan's context limit, the API will return an error. You cannot go over your plan's max — upgrade your plan for a higher limit.
```
### Context scaling (paid plans only)
For paid plans (Basic, Premium, Scale), a **context scaling multiplier** is applied on top of the model's request multiplier. This scales smoothly based on prompt size using **0.1x per 1K tokens**:
```
scaleFactor = promptTokens / 10000
totalCost = model\_request\_multiplier × scaleFactor
```
This means larger prompts consume more of your per-minute quota gradually rather than in large blocks:
| Prompt size | Scale factor | With 1x model | With 2x model |
|-------------|-------------|----------------|----------------|
| 1K tokens | 0.1x | 0.1 request | 0.2 requests |
| 5K tokens | 0.5x | 0.5 request | 1 request |
| 10K tokens | 1x | 1 request | 2 requests |
| 20K tokens | 2x | 2 requests | 4 requests |
| 50K tokens | 5x | 5 requests | 10 requests |
The Free plan does **not** have context scaling — you pay only the model's base request multiplier, but you're limited to 8K tokens max.
```
### Examples
* A 10K prompt on the Basic plan with a 1x model = **1 request** (10K is within the first 16K block)
* A 20K prompt on the Premium plan with a 1x model = **2 requests** (ceil(20K / 16K) = 2)
* A 100K prompt on the Scale plan with a 2x model = **14 requests** (ceil(100K / 16K) = 7, × 2x model = 14)
### Why context scaling exists
Processing more tokens requires more compute. Context scaling ensures that heavy token usage is priced fairly while keeping costs low for everyday requests.
### Tips for managing context costs
Only include the context the model actually needs. Trim unnecessary history, instructions, or documents.
If you regularly need large context windows, upgrade to a plan with a higher limit. The Scale plan (128K) gives you the most room.
Instead of sending the full chat history every time, periodically summarize older messages to reduce token count.
The [Dashboard](/dashboard/overview) shows your request usage. Watch for requests that consume more than expected — it may be context scaling.
# Plans & Pricing
Source: https://docs.shuttleai.com/pricing/plans
Simple, affordable monthly plans that scale with your usage.
ShuttleAI offers monthly subscription plans designed to give you access to the best AI models at a fraction of the cost of going direct to each provider.
## Plans
### \$0/month
* **2 requests/minute**
* **8K** max context
* GPT-OSS 20B, GPT-OSS 120B
* Great for testing and experimentation
### \$10/month
* **10 requests/minute**
* **16K** max context
* Everything in Free, plus:
* **ShuttleAI Auto**, **GPT-5.2**, **Claude Haiku 4.5**
* Tool calling support
### \$25/month
* **30 requests/minute**
* **36K** max context
* Everything in Basic, plus:
* **Claude Opus 4.6**, **Claude Sonnet 4.6**
* Extended thinking / reasoning
### \$75/month
* **80 requests/minute**
* **128K** max context
* **All models** including beta/early access
* Priority support
Need more? **Enterprise** plans with custom rate limits, SLAs, and dedicated support are available. [Contact us on Discord](https://discord.com/invite/shuttleai) to discuss.
## Plan comparison
| Feature | Free | Basic | Premium | Scale |
| ------------------ | ------------ | ------------ | ------------ | ------------ |
| **Price** | \$0/mo | \$10/mo | \$25/mo | \$75/mo |
| **Requests/min** | 2 | 10 | 30 | 80 |
| **Max context** | 8K | 16K | 36K | 128K |
| **Free models** | ✅ | ✅ | ✅ | ✅ |
| **Basic models** | — | ✅ | ✅ | ✅ |
| **Premium models** | — | — | ✅ | ✅ |
| **Beta models** | — | — | — | ✅ |
| **Tool calling** | — | ✅ | ✅ | ✅ |
| **Sub-keys** | ✅ (up to 10) | ✅ (up to 10) | ✅ (up to 10) | ✅ (up to 10) |
## Request multipliers
Some models consume more than one request per API call. For example, a model with a **2x multiplier** uses 2 of your requests-per-minute quota for each call.
This means a Premium plan (30 RPM) calling a 2x model effectively gets 15 calls/minute for that model.
Understand how multipliers work and plan your usage accordingly.
## How to subscribe
1. Go to [shuttleai.com/plans](https://shuttleai.com/plans)
2. Click on the plan you want
3. Complete checkout via Stripe
4. Your plan activates immediately
You can also subscribe from the [Dashboard Plans page](/dashboard/plans).
## Free trial
New users can try the **Free** plan which includes access to GPT-OSS models at no cost. A valid payment method is required for verification to prevent abuse, but you will **not** be charged.
## Upgrading
You can upgrade your plan at any time from the [Plans page](https://shuttleai.com/plans). Upgrades take effect immediately — you'll be prorated for the remainder of your current billing period.
Downgrades are not currently available through self-service. Contact support on [Discord](https://discord.com/invite/shuttleai) if you need to downgrade.
## Billing
All plans are billed monthly through Stripe. You can view invoices, payment history, and manage your payment method from the [Billing page](https://shuttleai.com/billing).
View invoices, update payment methods, and manage your subscription.