Skip to main content

​
Overview

switchAILocal is fully compatible with the OpenAI Python SDK. Simply point the SDK to your local switchAILocal instance and you can access all configured providers through a single, unified API.

​
Installation

Install the official OpenAI Python SDK: 
pip install openai

​
Quick Start

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",  # Must match a key in config.yaml
)

# Auto-routing: switchAILocal picks the best available provider
completion = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[
        {"role": "user", "content": "What is the meaning of life?"}
    ]
)

print(completion.choices[0].message.content)

​
Advanced Features

​
Multi-turn Conversations

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",
)

messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Write a Python function to calculate factorial"}
]

response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=messages
)

# Add assistant response to conversation
messages.append({
    "role": "assistant",
    "content": response.choices[0].message.content
})

# Continue conversation
messages.append({
    "role": "user",
    "content": "Now add error handling"
})

response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=messages
)

​
Temperature and Parameters

completion = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "Write a creative story"}],
    temperature=0.9,      # Higher = more creative
    max_tokens=1000,      # Limit response length
    top_p=0.95,           # Nucleus sampling
)

​
CLI Attachments (Files & Folders)

Pass local files and folders to CLI providers like Gemini or Vibe: 
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",
)

completion = client.chat.completions.create(
    model="geminicli:gemini-2.5-pro",
    messages=[{"role": "user", "content": "Explain the logic in this file"}],
    extra_body={
        "cli": {
            "attachments": [
                {"type": "file", "path": "/path/to/script.py"},
                {"type": "folder", "path": "./src/internal"}
            ]
        }
    }
)

​
CLI Flags (Auto-approve, Sandbox)

Control CLI behavior with standardized flags: 
completion = client.chat.completions.create(
    model="vibe:mistral-large",
    messages=[{"role": "user", "content": "Update the version in package.json"}],
    extra_body={
        "cli": {
            "flags": {
                "auto_approve": True,  # Auto-approve actions
                "sandbox": True        # Run in sandbox mode
            }
        }
    }
)

​
Session Management

Resume or name specific CLI sessions: 
completion = client.chat.completions.create(
    model="geminicli:gemini-2.5-pro",
    messages=[{"role": "user", "content": "Continue our previous discussion"}],
    extra_body={
        "cli": {
            "session_id": "latest"  # Or use a custom session name
        }
    }
)

​
List Available Models

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",
)

models = client.models.list()
for model in models.data:
    print(f"{model.id} ({model.owned_by})")

​
Error Handling

from openai import OpenAI, APIError, APIConnectionError

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",
)

try:
    completion = client.chat.completions.create(
        model="gemini-2.5-pro",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(completion.choices[0].message.content)
except APIConnectionError as e:
    print(f"Connection error: {e}")
except APIError as e:
    print(f"API error: {e.status_code} - {e.message}")

​
Provider Prefixes

Use these prefixes to route to specific providers:
PrefixProviderExample
geminicli:Google Gemini CLIgeminicli:gemini-2.5-pro
claudecli:Anthropic Claude CLIclaudecli:claude-sonnet-4
ollama:Ollama (local)ollama:llama3.2
lmstudio:LM Studio (local)lmstudio:mistral-7b
switchai:Traylinx switchAIswitchai:switchai-fast
gemini:Google AI Studiogemini:gemini-2.5-pro
claude:Anthropic APIclaude:claude-3-5-sonnet
openai:OpenAI APIopenai:gpt-4
Omit the prefix to let switchAILocal automatically route to the best available provider for that model.

​
Environment Variables

You can configure the client using environment variables: 
import os
from openai import OpenAI

# Set environment variables
os.environ["OPENAI_BASE_URL"] = "http://localhost:18080/v1"
os.environ["OPENAI_API_KEY"] = "sk-test-123"

# Client automatically uses environment variables
client = OpenAI()

completion = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "Hello!"}]
)

​
Next Steps

Node.js SDK

Use switchAILocal with Node.js

Go SDK

Embed switchAILocal in Go applications

Examples

See more usage examples

API Reference

Complete API documentation