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? You don't need to change your model field. Any model value is accepted — Sansa ignores it and auto-routes regardless. Just swap baseURL and API key.

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
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": "sansa-auto",
  "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
  }
}

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": "sansa-auto",
  "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": "sansa-auto",
  "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
  }
}