Quickstart

Get your first Sansa API response in under 2 minutes.

Create an API key

Create an API key in your dashboard. Store it somewhere safe, then export it as an environment variable:

export SANSA_API_KEY="sk-sansa-..."

Install the OpenAI SDK

Sansa is compatible with the standard OpenAI SDKs.

npm install openai

pip install openai

Make your first request

Create a file and copy in the example from the code panel. The only difference from OpenAI is baseURL and your Sansa API key.

Run it. You should see a response in a few seconds.

Migrating an existing app? Use "sansa-auto" to let Sansa pick the best model for each request, or keep a specific model ID (e.g. "openai/gpt-5.4") to call it directly. See Models for the full list and behavior of each mode.

Stream a response

Set stream: true to get tokens as they're generated. See the code panel for a full example.

Streaming uses Server-Sent Events (SSE) and works with the OpenAI SDK. See the Streaming docs for chunk format and error handling.

Call a function

Define tools and the model will call them when relevant. Your code executes the function and sends the result back. See the code panel for the flow.

Full details in the Tools docs.

Next steps

Completions Reference — Full parameter reference, including image and audio inputs
Models — Auto-routing, calling specific models, and provider failover
Transcriptions — Transcribe audio files to text
Streaming — SSE format, chunk shape, error handling
Tools — Function calling and agentic loops
Reasoning — Extended thinking tokens

Make your first request

curl -X POST https://api.sansaml.com/v1/chat/completions \
  -H "Authorization: Bearer $SANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sansa-auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1708300000,
  "model": "openai/gpt-5.4-mini",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  },
  "sansa": {
    "routed": true,
    "routed_model": "openai/gpt-5.4-mini",
    "routing_latency_ms": 214
  }
}

Stream a response

const stream = await client.chat.completions.create({
  model: 'sansa-auto',
  messages: [{ role: 'user', content: 'Write a haiku about code.' }],
  stream: true,
});

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

Stream Response Chunk

{
  "id": "chatcmpl-xyz",
  "object": "chat.completion.chunk",
  "created": 1708300000,
  "model": "anthropic/claude-sonnet-4.6",
  "choices": [{
    "index": 0,
    "delta": { "content": "Code is " },
    "finish_reason": null
  }]
}

Call a function

const response = await client.chat.completions.create({
  model: 'sansa-auto',
  messages: [{ role: 'user', content: "What's the weather in Tokyo?" }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string' },
        },
        required: ['location'],
      },
    },
  }],
});

// Model responds with tool_calls — execute the
// function, then send the result back. See the
// Tools docs for the full loop.

Send an image

const response = await client.chat.completions.create({
  model: 'sansa-auto',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this image?' },
      { type: 'image_url', image_url: { url: 'https://example.com/photo.jpg' } },
    ],
  }],
});

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

Transcribe audio

import fs from 'fs';

const transcription = await client.audio.transcriptions.create({
  model: 'sansa-auto',
  file: fs.createReadStream('audio.mp3'),
});

console.log(transcription.text);

Tool Call Response

{
  "id": "chatcmpl-def456",
  "object": "chat.completion",
  "created": 1708300000,
  "model": "anthropic/claude-sonnet-4.6",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call12345",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\": \"Tokyo\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 68,
    "completion_tokens": 18,
    "total_tokens": 86
  }
}