OpenAI-Compatible API

# Bearer token (OpenAI SDK default)
Authorization: Bearer sk_your_api_key

# Or X-API-Key header
X-API-Key: sk_your_api_key

{
  "id": "chatcmpl-20250120100000a1b2c3d4",
  "object": "chat.completion",
  "created": 1737367200,
  "model": "shannon-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The response text from Shannon..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{"role":"assistant","content":"The"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{"content":" response text"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":25,"completion_tokens":150,"total_tokens":175}}

data: [DONE]

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1737367200,
  "model": "shannon-deep-research",
  "choices": [
    {
      "index": 0,
      "delta": {}
    }
  ],
  "shannon_events": [
    {
      "type": "AGENT_STARTED",
      "agent_id": "researcher_1",
      "message": "Starting research on query...",
      "timestamp": 1737367201,
      "payload": {}
    }
  ]
}

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Session-ID: my-conversation-1" \
  -H "Content-Type: application/json" \
  -d '{"model": "shannon-chat", "messages": [{"role": "user", "content": "Hello"}]}'

{
  "error": {
    "message": "Model 'invalid-model' not found. Use GET /v1/models to list available models.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer sk_your_key"

{
  "object": "list",
  "data": [
    {
      "id": "shannon-chat",
      "object": "model",
      "created": 1737367200,
      "owned_by": "shannon"
    },
    {
      "id": "shannon-deep-research",
      "object": "model",
      "created": 1737367200,
      "owned_by": "shannon"
    }
  ]
}

curl http://localhost:8080/v1/models/shannon-deep-research \
  -H "Authorization: Bearer sk_your_key"

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk_your_api_key",  # or "not-needed" if auth is disabled
)

# Non-streaming
response = client.chat.completions.create(
    model="shannon-chat",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Shannon?"}
    ],
)
print(response.choices[0].message.content)

# Ads Research (Shannon Cloud Only)
response = client.chat.completions.create(
    model="shannon-ads-research",
    messages=[
        {"role": "user", "content": "Analyze competitor ads for organic skincare products"}
    ],
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="shannon-deep-research",
    messages=[
        {"role": "user", "content": "Analyze the impact of AI on healthcare"}
    ],
    stream=True,
    stream_options={"include_usage": True},
)

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

    # Access Shannon-specific events (if available)
    if hasattr(chunk, "shannon_events") and chunk.shannon_events:
        for event in chunk.shannon_events:
            print(f"\n[{event['type']}] {event.get('message', '')}")

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk_your_api_key",
});

// Non-streaming
const response = await client.chat.completions.create({
  model: "shannon-chat",
  messages: [
    { role: "user", content: "What is Shannon?" }
  ],
});
console.log(response.choices[0].message.content);

// Streaming
const stream = await client.chat.completions.create({
  model: "shannon-deep-research",
  messages: [
    { role: "user", content: "Analyze the impact of AI on healthcare" }
  ],
  stream: true,
});

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

# Non-streaming
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "model": "shannon-chat",
    "messages": [
      {"role": "user", "content": "What is Shannon?"}
    ]
  }'

# Streaming
curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "model": "shannon-deep-research",
    "messages": [
      {"role": "user", "content": "Analyze the impact of AI on healthcare"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

# With session ID for multi-turn
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "X-Session-ID: my-session-1" \
  -d '{
    "model": "shannon-chat",
    "messages": [
      {"role": "system", "content": "You are a data analyst."},
      {"role": "user", "content": "Summarize Q4 revenue trends"}
    ]
  }'

import json
import httpx

def stream_with_events(query: str, model: str = "shannon-deep-research"):
    response = httpx.post(
        "http://localhost:8080/v1/chat/completions",
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer sk_your_api_key",
        },
        json={
            "model": model,
            "messages": [{"role": "user", "content": query}],
            "stream": True,
        },
        timeout=None,
    )

    for line in response.iter_lines():
        if not line.startswith("data: "):
            continue
        data = line[6:]
        if data == "[DONE]":
            break

        chunk = json.loads(data)

        # Print content deltas
        delta = chunk["choices"][0].get("delta", {})
        if delta.get("content"):
            print(delta["content"], end="", flush=True)

        # Print Shannon agent events
        for event in chunk.get("shannon_events", []):
            print(f"\n  [{event['type']}] {event.get('message', '')}")

stream_with_events("Research the latest developments in quantum computing")