Drop-In Migration from OpenAI SDK to Swarms

​

What This Covers

• The two-line migration: pointing your existing openai Python client at Swarms with no other code changes
• Why bearer-token auth works the same as x-api-key — your existing OpenAI auth pattern transfers
• The optional upgrade path: when to graduate from /v1/chat/completions (single model) to /v1/swarm/completions (multi-agent swarm)
• Realistic before/after architecture for an existing OpenAI-backed app
• What you don’t have to throw away — streaming, history, vision, retries

​

Why This Matters

​

The Two-Line Migration

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a senior financial analyst."},
        {"role": "user",   "content": "What are the top risks in EM bonds right now?"},
    ],
    max_tokens=512,
    temperature=0.3,
)

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

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ["SWARMS_API_KEY"],
    base_url="https://api.swarms.world/v1",   # <-- the only structural change
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a senior financial analyst."},
        {"role": "user",   "content": "What are the top risks in EM bonds right now?"},
    ],
    max_tokens=512,
    temperature=0.3,
)

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

​

Authentication: Bearer Token Works Too

• Your OpenAI SDK code keeps using Authorization: Bearer (transparently — you don’t see it)
• Your requests-style code can keep using x-api-key (matches every other guide)
• Mixed codebases work without translating between auth schemes

# Both of these authenticate the same request to Swarms.

# Style 1: OpenAI SDK (uses Authorization: Bearer under the hood)
client = OpenAI(api_key=os.environ["SWARMS_API_KEY"], base_url="https://api.swarms.world/v1")

# Style 2: raw requests with x-api-key
headers = {"x-api-key": os.environ["SWARMS_API_KEY"], "Content-Type": "application/json"}

# Style 3: raw requests with bearer — also accepted
headers_bearer = {"Authorization": f"Bearer {os.environ['SWARMS_API_KEY']}", "Content-Type": "application/json"}

​

What You Keep For Free

• Streaming (stream=True — token-by-token deltas)
• System / user / assistant messages, including full multi-turn history
• Vision / image input via the multimodal content array
• Standard error classes from the SDK (openai.RateLimitError, openai.APIStatusError, etc.)
• usage accounting in the response — prompt/completion/total token counts
• max_tokens, temperature, top_p, presence_penalty, frequency_penalty all forwarded

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ["SWARMS_API_KEY"],
    base_url="https://api.swarms.world/v1",
)

# Streaming, multi-turn, vision, error-handling — all unchanged from OpenAI.
stream = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a meticulous code reviewer."},
        {"role": "user", "content": "Review this function for edge cases: def divide(a, b): return a / b"},
    ],
    stream=True,
    max_tokens=1024,
)

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

​

The First Free Upgrade: max_loops

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "Write a solution, then critique it, then output the corrected version."},
        {"role": "user",   "content": "Implement longest_palindromic_substring(s: str) -> str."},
    ],
    max_tokens=2048,
    extra_body={"max_loops": 3},   # <-- self-iterate three times before returning
)

​

The Strategic Upgrade: /v1/swarm/completions

​

When to upgrade an endpoint

• The prompt has more than one role baked into it (e.g. “first research X, then critique it, then summarise”)
• You’re already doing your own agent orchestration in application code (function-calling loops, sub-agent dispatch)
• The output quality is bottlenecked on a single model trying to do too much in one pass
• You need parallel work — concurrent research across multiple angles — combined into one answer

​

Side-by-side: the same job, two endpoints

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ["SWARMS_API_KEY"],
    base_url="https://api.swarms.world/v1",
)

# One model, one pass. Cheap, fast, fine for simple analysis.
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a strategy analyst. Research, analyse, and recommend."},
        {"role": "user",   "content": "Should a Series-B SaaS company enter the German market?"},
    ],
    max_tokens=2048,
    extra_body={"max_loops": 2},  # self-iterate once for quality
)

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

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY  = os.environ["SWARMS_API_KEY"]
BASE_URL = "https://api.swarms.world"

# x-api-key OR Authorization: Bearer — pick whichever matches your stack
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# Four specialist agents, one synthesizer, run as a sequential workflow.
# Each agent is cheaper and tighter than the single generalist above —
# the synthesizer is where you spend the token budget.
payload = {
    "name": "German Market Entry Analysis",
    "swarm_type": "SequentialWorkflow",
    "task": "Should a Series-B SaaS company enter the German market?",
    "agents": [
        {
            "agent_name": "Market Researcher",
            "system_prompt": "Surface 3 key facts about the German SaaS market.",
            "model_name": "gpt-4.1-mini",
            "max_tokens": 768,
        },
        {
            "agent_name": "Competitive Analyst",
            "system_prompt": "Identify the top 3 incumbents and their moats.",
            "model_name": "gpt-4.1-mini",
            "max_tokens": 768,
        },
        {
            "agent_name": "Risk Analyst",
            "system_prompt": "List the top 3 entry risks and mitigations.",
            "model_name": "gpt-4.1-mini",
            "max_tokens": 768,
        },
        {
            "agent_name": "Director (Synthesizer)",
            "system_prompt": "Read the three briefings. Produce a go/no-go memo.",
            "model_name": "gpt-4.1",
            "max_tokens": 3072,
        },
    ],
}

resp = requests.post(f"{BASE_URL}/v1/swarm/completions", headers=headers, json=payload)
print(resp.json()["output"])

​

A Migration Plan You Can Actually Run

1. Day 1. Add a SWARMS_API_KEY to your secrets. Duplicate your OpenAI client construction into a swarms_client that differs only in api_key and base_url. Ship to staging behind a feature flag.
2. Day 2. Move your least-critical chat.completions endpoint to swarms_client. Confirm logs, retries, token counting, and streaming all behave. Diff the response on a few hundred prompts against the OpenAI baseline.
3. Day 3. Identify the one endpoint in your product that does the most prompt engineering — the long, multi-section system prompt with “first do X, then Y, then Z”. This is the one that wants to be a swarm. Cut it over to /v1/swarm/completions with 3–5 agents.
4. Day 4. Add the Cost Optimization Playbook patterns to that swarm — tier the workers, compress the handoffs.
5. Day 5. Schedule the batch / overnight pieces of your pipeline against the Night-Mode discount. Audit discount_active to confirm.

​

What You Don’t Have To Throw Away

• Your OpenAI SDK and any wrappers around it
• Your retry / circuit-breaker middleware
• Your token-counting and cost-tracking telemetry
• Your prompt-versioning system
• Your evaluation harness (the response shape is identical)
• Your streaming UI code
• Your Authorization: Bearer auth flow

​

Next Steps

• OpenAI-Compatible Chat Completions — full feature reference for the drop-in endpoint (streaming, vision, multi-turn, multi-loop) with TypeScript, Go, and Rust examples
• Cost Optimization Playbook — once you’re on /v1/swarm/completions, this is the architecture that gets your bill down
• Night-Mode Pricing Strategy — 50% off tokens 8 PM – 6 AM Pacific, schedule your batches accordingly