Developer ReferenceOfficial SDK v1.0

Tanvelo Gateway & SDK Documentation

Tanvelo provides a unified, production-grade LLM API Gateway and dedicated SDKs. Call OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Groq, Mistral, and local Ollama models with a single script and built-in rate-limiting, deterministic fallbacks, budgets, and token metering.

Connect Providers

Add your OpenAI, Anthropic, Gemini, or custom endpoints under Providers. Keys are AES-256 encrypted.

Generate Gateway Key

Create an authenticated gateway key under API Keys. Only SHA-256 hashes are persisted.

Call Any Model via SDK

Use @tanvelo/sdk in TypeScript or tanvelo in Python to route calls instantly.

Official Tanvelo SDK (TypeScript & Python)

One unified SDK to call OpenAI, Anthropic, Gemini, DeepSeek, or Ollama with automatic model fallback.

Recommended

TypeScript / Node.js SDK (@tanvelo/sdk)

Install with npm install @tanvelo/sdk

import { Tanvelo } from '@tanvelo/sdk';

// Initialize the Tanvelo Client
const tanvelo = new Tanvelo({
  apiKey: process.env.TANVELO_API_KEY, // or 'tanvelo_live_...'
  baseUrl: 'http://localhost:4000/v1',
});

async function run() {
  // Call any provider: OpenAI, Anthropic, Gemini, DeepSeek, Groq, Ollama
  const response = await tanvelo.chat.completions.create({
    model: 'gpt-4o',
    fallbacks: ['claude-3-5-sonnet', 'gemini-1.5-pro'],
    messages: [
      { role: 'system', content: 'You are an intelligent code assistant.' },
      { role: 'user', content: 'Explain Tanvelo gateway architecture.' }
    ],
    temperature: 0.7,
  });

  console.log(response.choices[0].message.content);
  console.log('Provider used:', response._tanvelo?.provider);
  console.log('Latency:', response._tanvelo?.latencyMs, 'ms');
}

run();

Python SDK (tanvelo.py)

Native zero-dependency Python client with streaming & fallback support

from tanvelo import Tanvelo

# Initialize Tanvelo Client
client = Tanvelo(
    api_key="YOUR_TANVELO_API_KEY",
    base_url="http://localhost:4000/v1"
)

# 1. Standard Completion across any provider
response = client.chat.completions.create(
    model="claude-3-5-sonnet", # or gpt-4o, gemini-1.5-pro, deepseek-chat
    fallbacks=["gpt-4o-mini", "gemini-1.5-flash"],
    messages=[
        {"role": "user", "content": "Generate a clean TypeScript interface."}
    ]
)
print(response.content)

# 2. Real-Time Streaming
for chunk in client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Stream a short explanation."}],
    stream=True
):
    print(chunk.delta, end="", flush=True)

POST

/v1/chat/completions

OpenAI-compatible chat completion endpoint supporting standard JSON and Server-Sent Events (SSE) streaming.

Headers:

Content-Type: application/json

Authorization: Bearer YOUR_TANVELO_API_KEY

X-Tanvelo-Fallbacks: claude-3-5-sonnet,gemini-1.5-pro (optional)

Response Headers:

X-Tanvelo-Request-Id: req_c82fa0...

X-Tanvelo-Provider: openai (or anthropic / gemini / deepseek)

X-Tanvelo-Model: gpt-4o

X-Tanvelo-Latency-Ms: 142

X-Tanvelo-Cost-Usd: 0.000350 (non-streaming with pricing)

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 59

X-RateLimit-Reset: 45 (seconds remaining)

Retry-After: 45 (emitted on HTTP 429)

cURL & Drop-in OpenAI SDK Compatibility

cURL Direct Call

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TANVELO_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain Tanvelo federation gateway."}
    ],
    "temperature": 0.7
  }'

OpenAI SDK (Zero Code Change Drop-in)

import OpenAI from "openai";

// Tanvelo is 100% drop-in compatible with the OpenAI SDK
const openai = new OpenAI({
  baseURL: "http://localhost:4000/v1",
  apiKey: "YOUR_TANVELO_API_KEY",
});

const response = await openai.chat.completions.create({
  model: "claude-3-5-sonnet", // Tanvelo transparently translates to Anthropic
  messages: [{ role: "user", content: "Hello from OpenAI SDK via Tanvelo!" }],
});

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

Webhook Signature Verification (HMAC-SHA256)

import crypto from 'crypto';

// Verify Tanvelo webhook signatures
function verifyTanveloWebhook(payloadRaw, signatureHeader, secret) {
  // Signature header format: "t=TIMESTAMP,v1=SIGNATURE"
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );

  const timestamp = parts.t;
  const signature = parts.v1;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payloadRaw}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}