Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(providers): add Sail Research adapter (#1125)

Tashfeen36de660fab25
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsx
index 9ef39594..0be6b2d1 100644
--- a/client/src/components/keys/shared.tsx
+++ b/client/src/components/keys/shared.tsx
@@ -29,6 +29,7 @@ export const PLATFORMS: { value: Platform; label: string; url: string; keyless?:
{ value: 'google', label: 'Google AI Studio', url: 'https://aistudio.google.com/apikey' },
{ value: 'groq', label: 'Groq', url: 'https://console.groq.com/keys' },
{ value: 'cerebras', label: 'Cerebras', url: 'https://cloud.cerebras.ai' },
+ { value: 'sail', label: 'Sail Research ($5 monthly with payment method)', url: 'https://app.sailresearch.com' },
{ value: 'bai', label: 'B.AI (promotional free model)', url: 'https://b.ai' },
{ value: 'nvidia', label: 'NVIDIA NIM', url: 'https://build.nvidia.com/settings/api-keys' },
{ value: 'mistral', label: 'Mistral', url: 'https://console.mistral.ai/api-keys/' },
diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.ts
index 10931343..68be2db9 100644
--- a/client/src/lib/routing.ts
+++ b/client/src/lib/routing.ts
@@ -376,6 +376,7 @@ export const platformColors: Record<string, string> = {
google: '#4285f4',
groq: '#f55036',
cerebras: '#8b5cf6',
+ sail: '#0ea5e9',
bai: '#111827',
nvidia: '#76b900',
mistral: '#f59e0b',
diff --git a/docs/providers/01-supported-platforms.md b/docs/providers/01-supported-platforms.md
index 2c31d133..7809d08f 100644
--- a/docs/providers/01-supported-platforms.md
+++ b/docs/providers/01-supported-platforms.md
@@ -1,12 +1,12 @@
# Supported platforms
-The `Platform` union in [`shared/types.ts` (line 59)](../../shared/types.ts) is the single source of truth for platform identity; the runtime registry in [`server/src/providers/index.ts`](../../server/src/providers/index.ts) must match it. The union currently declares **41 members**:
+The `Platform` union in [`shared/types.ts` (line 59)](../../shared/types.ts) is the single source of truth for platform identity; the runtime registry in [`server/src/providers/index.ts`](../../server/src/providers/index.ts) must match it. The union currently declares **42 members**:
-- **39 built-in platforms** registered as adapters at startup,
-- plus the **`custom`** placeholder (a real OpenAI-compatible adapter built per API key, since its base URL is user-supplied), giving **40 entries** in the registry map,
+- **40 built-in platforms** registered as adapters at startup,
+- plus the **`custom`** placeholder (a real OpenAI-compatible adapter built per API key, since its base URL is user-supplied), giving **41 entries** in the registry map,
- plus **`sambanova`**, retained in the type union but no longer registered — it was dropped in V23 (June 2026) when its free tier was permanently retired (every chat call returns 402 "payment method required" once the one-time $5 trial credit lapses).
-Of the 39 built-in platforms, **7 use dedicated native adapters** and **32 ride `OpenAICompatProvider`** against a provider-specific base URL. Three platforms are registered keyless (`kilo`, `ovh`, and `aihorde`, which auto-configures with its documented anonymous sentinel key). The public catalog headline in the README counts ~34 free providers / 474 model families / 635 free endpoints (~7.4 billion tokens/month of listed capacity) — fewer than the union because several registered gateways keep their free rosters in the hosted catalog rather than shipping them to every binary.
+Of the 40 built-in platforms, **8 use dedicated native adapters** and **32 ride `OpenAICompatProvider`** against a provider-specific base URL. Three platforms are registered keyless (`kilo`, `ovh`, and `aihorde`, which auto-configures with its documented anonymous sentinel key). The public catalog headline in the README counts ~34 free providers / 474 model families / 635 free endpoints (~7.4 billion tokens/month of listed capacity) — fewer than the union because several registered gateways keep their free rosters in the hosted catalog rather than shipping them to every binary.
## Catalog
@@ -15,6 +15,7 @@ Of the 39 built-in platforms, **7 use dedicated native adapters** and **32 ride
| `google` | Google Gemini | Keyed | Native (`GoogleProvider`) | Gemini wire format; 60s default timeout because Gemma reasoning variants take 20–60s on cold start. |
| `groq` | Groq | Keyed | OpenAI-compat | Standard compatible endpoint at `api.groq.com/openai/v1`. |
| `cerebras` | Cerebras | Keyed | OpenAI-compat | `api.cerebras.ai/v1`. |
+| `sail` | Sail Research | Keyed (payment method required for recurring credit) | Native (`SailProvider`) | Stable `/v1/responses` integration submits background jobs and polls them to completion; flex-only models use the `flex` completion window. Sail grants $5 in monthly credits while a payment method is attached, then charges usage beyond that credit. |
| `bai` | B.AI | Keyed | OpenAI-compat | Gateway added in #918; only catalog row is a limited-time 0-credit promo, kept in the hosted catalog. |
| `anyapi` | AnyAPI | Keyed | OpenAI-compat | Free tier $0/no card/recurring, capped at 100K tokens/day over "free and basic" models; no RPM/RPD published (#772). Model ids arrive via catalog-sync, never seeded blind. |
| `nvidia` | NVIDIA NIM | Keyed | OpenAI-compat | `parallel_tool_calls` pinned false (#255); 180s timeout doubles as streaming first-byte grace (#584). |
diff --git a/docs/providers/03-adding-a-new-provider.md b/docs/providers/03-adding-a-new-provider.md
index c8c42b26..f189d16b 100644
--- a/docs/providers/03-adding-a-new-provider.md
+++ b/docs/providers/03-adding-a-new-provider.md
@@ -1,6 +1,6 @@
# Adding a new provider
-A contributor walkthrough that mirrors how the existing 37 built-in platforms are wired. Read [`server/src/providers/index.ts`](../../server/src/providers/index.ts) alongside this guide — it is both the registry and the best documentation of per-platform judgment calls.
+A contributor walkthrough that mirrors how the existing 40 built-in platforms are wired. Read [`server/src/providers/index.ts`](../../server/src/providers/index.ts) alongside this guide — it is both the registry and the best documentation of per-platform judgment calls.
## 1. Declare the platform
diff --git a/docs/providers/CHANGELOG.md b/docs/providers/CHANGELOG.md
index 870f74ec..3a45e4ab 100644
--- a/docs/providers/CHANGELOG.md
+++ b/docs/providers/CHANGELOG.md
@@ -4,6 +4,7 @@ Revision history for `docs/providers/`, listing the upstream commits that shaped
| Commit | Date | Summary |
| --- | --- | --- |
+| Unreleased | 2026-09-01 | Add the native Sail Research background Responses adapter and catalog-ready platform wiring. |
| `ef4519a` | 2026-08-23 | feat(providers): add xkiro.com as OpenAI-compatible provider (#967) |
| `68ddca4` | 2026-08-23 | feat(providers): add UnoRouter (unorouter.com) as OpenAI-compatible provider (#875) |
| `df1000a` | 2026-08-20 | Qianfan/Volcengine Ark/LongCat/iFlytek Spark (#936) — four Chinese domestic OpenAI-compat platforms. |
diff --git a/server/src/__tests__/lib/key-parser.test.ts b/server/src/__tests__/lib/key-parser.test.ts
index db0f0a57..1744bb68 100644
--- a/server/src/__tests__/lib/key-parser.test.ts
+++ b/server/src/__tests__/lib/key-parser.test.ts
@@ -65,6 +65,8 @@ describe('key parser', () => {
expect(detectPlatform('ANY_API_')).toBe('anyapi');
expect(detectPlatform('BAI_')).toBe('bai');
expect(detectPlatform('B_AI_')).toBe('bai');
+ expect(detectPlatform('SAIL_')).toBe('sail');
+ expect(detectPlatform('SAIL_RESEARCH_')).toBe('sail');
expect(detectPlatform('SAMBANOVA_')).toBeNull();
});
@@ -80,6 +82,7 @@ describe('key parser', () => {
expect(AUTH_JSON_PROVIDER_MAP['model-scope']).toBe('modelscope');
expect(AUTH_JSON_PROVIDER_MAP['any-api']).toBe('anyapi');
expect(AUTH_JSON_PROVIDER_MAP['b-ai']).toBe('bai');
+ expect(AUTH_JSON_PROVIDER_MAP['sail-research']).toBe('sail');
const result = parseAuthJson(JSON.stringify({
credential_pool: {
gemini: [{ id: '1', label: 'Gemini', auth_type: 'api_key', access_token: 'AIza-test' }],
diff --git a/server/src/__tests__/providers/sail.test.ts b/server/src/__tests__/providers/sail.test.ts
new file mode 100644
index 00000000..c5ab14d9
--- /dev/null
+++ b/server/src/__tests__/providers/sail.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { SailProvider } from '../../providers/sail.js';
+
+function jsonResponse(body: unknown, status = 200): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ });
+}
+
+function completed(id = 'resp_done', model = 'zai-org/GLM-5.2-FP8') {
+ return {
+ id,
+ model,
+ created_at: 1_700_000_000,
+ status: 'completed',
+ output: [{
+ type: 'message',
+ role: 'assistant',
+ content: [{ type: 'output_text', text: 'OK' }],
+ }],
+ usage: {
+ input_tokens: 12,
+ output_tokens: 3,
+ total_tokens: 15,
+ input_tokens_details: { cached_tokens: 2 },
+ output_tokens_details: { reasoning_tokens: 1 },
+ },
+ };
+}
+
+describe('SailProvider', () => {
+ afterEach(() => vi.restoreAllMocks());
+
+ it('submits a background Responses job, polls it, and normalizes the result', async () => {
+ const calls: Array<{ url: string; init?: RequestInit; body?: any }> = [];
+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+ calls.push({
+ url: String(url),
+ init,
+ body: init?.body ? JSON.parse(String(init.body)) : undefined,
+ });
+ if (calls.length === 1) {
+ return jsonResponse({ id: 'resp_1', status: 'queued' }, 202);
+ }
+ return jsonResponse(completed('resp_1'));
+ });
+
+ const provider = new SailProvider({ pollIntervalMs: 0, timeoutMs: 1_000 });
+ const result = await provider.chatCompletion(
+ 'sail-key',
+ [{ role: 'user', content: 'Reply OK' }],
+ 'zai-org/GLM-5.2-FP8',
+ { max_tokens: 64, reasoning_effort: 'none', temperature: 0 },
+ );
+
+ expect(calls.map(call => call.url)).toEqual([
+ 'https://api.sailresearch.com/v1/responses',
+ 'https://api.sailresearch.com/v1/responses/resp_1',
+ ]);
+ expect((calls[0].init?.headers as Record<string, string>).Authorization).toBe('Bearer sail-key');
+ expect(calls[0].body).toMatchObject({
+ model: 'zai-org/GLM-5.2-FP8',
+ input: [{ role: 'user', content: 'Reply OK' }],
+ background: true,
+ max_output_tokens: 64,
+ metadata: { completion_window: 'asap' },
+ reasoning: { effort: 'none' },
+ temperature: 0,
+ });
+ expect(result.choices[0].message.content).toBe('OK');
+ expect(result.choices[0].finish_reason).toBe('stop');
+ expect(result.usage).toEqual({
+ prompt_tokens: 12,
+ completion_tokens: 3,
+ total_tokens: 15,
+ prompt_tokens_details: { cached_tokens: 2 },
+ completion_tokens_details: { reasoning_tokens: 1 },
+ });
+ expect(result._routed_via).toEqual({ platform: 'sail', model: 'zai-org/GLM-5.2-FP8' });
+ });
+
+ it('maps Chat Completions tools and tool history onto Responses items', async () => {
+ let body: any;
+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {
+ body = JSON.parse(String(init?.body));
+ return jsonResponse({
+ id: 'resp_tools',
+ model: 'moonshotai/Kimi-K2.6',
+ status: 'completed',
+ output: [{ type: 'function_call', call_id: 'call_new', name: 'weather', arguments: '{"city":"Dublin"}' }],
+ usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
+ });
+ });
+
+ const provider = new SailProvider({ pollIntervalMs: 0 });
+ const result = await provider.chatCompletion('k', [
+ { role: 'assistant', content: '', tool_calls: [{ id: 'call_old', type: 'function', function: { name: 'weather', arguments: '{"city":"Cork"}' } }] },
+ { role: 'tool', content: 'rain', tool_call_id: 'call_old' },
+ { role: 'user', content: 'How about Dublin?' },
+ ], 'moonshotai/Kimi-K2.6', {
+ tools: [{ type: 'function', function: { name: 'weather', description: 'Get weather', parameters: { type: 'object' }, strict: true } }],
+ tool_choice: { type: 'function', function: { name: 'weather' } },
+ });
+
+ expect(body.input).toEqual([
+ { type: 'function_call', call_id: 'call_old', name: 'weather', arguments: '{"city":"Cork"}' },
+ { type: 'function_call_output', call_id: 'call_old', output: 'rain' },
+ { role: 'user', content: 'How about Dublin?' },
+ ]);
+ expect(body.tools[0]).toMatchObject({ type: 'function', name: 'weather', strict: true });
+ expect(body.tool_choice).toEqual({ type: 'function', name: 'weather' });
+ expect(result.choices[0].finish_reason).toBe('tool_calls');
+ expect(result.choices[0].message.tool_calls?.[0]).toMatchObject({
+ id: 'call_new',
+ function: { name: 'weather', arguments: '{"city":"Dublin"}' },
+ });
+ });
+
+ it('uses flex background mode and clamps gpt-oss none reasoning to low', async () => {
+ const bodies: any[] = [];
+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {
+ const body = JSON.parse(String(init?.body));
+ bodies.push(body);
+ return jsonResponse(completed(`resp_${bodies.length}`, body.model));
+ });
+ const provider = new SailProvider({ pollIntervalMs: 0 });
+
+ await provider.chatCompletion('k', [{ role: 'user', content: 'hi' }],
+ 'nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16');
+ await provider.chatCompletion('k', [{ role: 'user', content: 'hi' }],
+ 'openai/gpt-oss-120b', { reasoning_effort: 'none' });
+
+ expect(bodies[0].metadata).toEqual({ completion_window: 'flex' });
+ expect(bodies[0].background).toBe(true);
+ expect(bodies[1].metadata).toEqual({ completion_window: 'asap' });
+ expect(bodies[1].reasoning).toEqual({ effort: 'low' });
+ });
+
+ it('synthesizes streaming chunks from the completed background response', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(jsonResponse(completed()));
+ const provider = new SailProvider({ pollIntervalMs: 0 });
+ const chunks = [];
+ for await (const chunk of provider.streamChatCompletion(
+ 'k', [{ role: 'user', content: 'hi' }], 'zai-org/GLM-5.2-FP8',
+ )) chunks.push(chunk);
+
+ expect(chunks.map(chunk => chunk.choices[0].delta)).toEqual([
+ { role: 'assistant' },
+ { content: 'OK' },
+ {},
+ ]);
+ expect(chunks.at(-1)?.choices[0].finish_reason).toBe('stop');
+ });
+
+ it('validates keys against the authenticated model roster and preserves errors', async () => {
+ vi.spyOn(global, 'fetch')
+ .mockResolvedValueOnce(jsonResponse({ object: 'list', data: [] }))
+ .mockResolvedValueOnce(jsonResponse({ error: { message: 'Invalid API key' } }, 401));
+ const provider = new SailProvider();
+
+ await expect(provider.validateKey('good')).resolves.toBe(true);
+ await expect(provider.validateKey('bad')).resolves.toEqual({
+ valid: false,
+ error: 'Sail Research key validation failed (HTTP 401): Invalid API key',
+ });
+ });
+});
diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.ts
index 44a73243..95158d85 100644
--- a/server/src/lib/key-parser.ts
+++ b/server/src/lib/key-parser.ts
@@ -42,6 +42,9 @@ export const PREFIX_MAP: Record<string, string> = {
GEMINI_: 'google',
GROQ_: 'groq',
CEREBRAS_: 'cerebras',
+ SAIL_: 'sail',
+ SAILRESEARCH_: 'sail',
+ SAIL_RESEARCH_: 'sail',
BAI_: 'bai',
B_AI_: 'bai',
NVIDIA_: 'nvidia',
@@ -102,6 +105,9 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {
gemini: 'google',
google: 'google',
groq: 'groq',
+ sail: 'sail',
+ 'sail-research': 'sail',
+ sailresearch: 'sail',
bai: 'bai',
'b-ai': 'bai',
openrouter: 'openrouter',
diff --git a/server/src/lib/sampling-params.ts b/server/src/lib/sampling-params.ts
index 1e1ca80b..1ba4ac8b 100644
--- a/server/src/lib/sampling-params.ts
+++ b/server/src/lib/sampling-params.ts
@@ -238,6 +238,13 @@ export const GITHUB_MAX_OUTPUT_TOKENS = 400;
// silently no-op'ing the policy; the string-typed accessors below cast at the
// boundary since routes carry platform ids as plain strings.
export const PLATFORM_PARAM_POLICIES: Partial<Record<Platform, PlatformParamPolicy>> = {
+ // Sail's stable Responses API accepts temperature/top_p, JSON Schema output,
+ // tools and reasoning effort. The remaining Chat Completions knobs are not
+ // supported and are intentionally omitted by the dedicated adapter.
+ sail: {
+ drop: ['top_k', 'min_p', 'seed', 'presence_penalty', 'frequency_penalty', 'repetition_penalty', 'logit_bias', 'logprobs', 'top_logprobs'],
+ jsonObjectToSchema: true,
+ },
// Mistral's API is strict (422 on unknown body keys) and names its seed
// `random_seed`. It has no top_k/min_p/logit_bias/logprobs equivalents, and
// no reasoning_effort (Magistral's reasoning has no request-side knob).
diff --git a/server/src/providers/index.ts b/server/src/providers/index.ts
index 6a6e4fbf..5b55fc03 100644
--- a/server/src/providers/index.ts
+++ b/server/src/providers/index.ts
@@ -8,6 +8,7 @@ import { AIHordeProvider } from './aihorde.js';
import { ModelScopeProvider } from './modelscope.js';
import { PollinationsProvider } from './pollinations.js';
import { ZhipuProvider } from './zhipu.js';
+import { SailProvider } from './sail.js';
const providers = new Map<Platform, BaseProvider>();
@@ -34,6 +35,14 @@ register(new OpenAICompatProvider({
baseUrl: 'https://api.cerebras.ai/v1',
}));
+// Sail Research — its stable API is /v1/responses and all calls are submitted
+// as background jobs, then polled. The dedicated adapter translates terminal
+// Responses objects back to Chat Completions and handles flex-only models.
+// Sail grants $5 in free credits every month when a payment method is attached;
+// usage beyond that grant is pay-as-you-go. Live-tested 2026-09-01. Model rows
+// stay in Oracle so the existing Premium-now / Free-after-30-days gate applies.
+register(new SailProvider());
+
// B.AI — OpenAI-compatible gateway. Provider support is first-class, but the
// only free catalog row currently published is a limited-time 0-credit promo;
// keep commercial eligibility in the hosted catalog rather than seeding it.
diff --git a/server/src/providers/sail.ts b/server/src/providers/sail.ts
new file mode 100644
index 00000000..fe0b7aff
--- /dev/null
+++ b/server/src/providers/sail.ts
@@ -0,0 +1,404 @@
+import type {
+ ChatCompletionChunk,
+ ChatCompletionResponse,
+ ChatMessage,
+ ChatToolCall,
+ ChatToolChoice,
+ Platform,
+ TokenUsage,
+} from '@freellmapi/shared/types.js';
+import {
+ BaseProvider,
+ providerHttpError,
+ type CompletionOptions,
+ type KeyValidationResult,
+} from './base.js';
+import { contentToString } from '../lib/content.js';
+import { resolveMaxTokens } from '../lib/sampling-params.js';
+import {
+ recordQuotaObservationsFromResponse,
+ type QuotaObservationContext,
+} from '../services/provider-quota.js';
+import { providerTimeoutMs } from '../lib/provider-timeout.js';
+
+const BASE_URL = 'https://api.sailresearch.com/v1';
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const POLL_REQUEST_TIMEOUT_MS = 30_000;
+
+// Sail serves these models only through its best-effort flex completion window.
+// Flex requests must use the Responses API in background mode and be polled.
+const FLEX_ONLY_MODELS = new Set([
+ 'Qwen/Qwen3.6-35B-A3B',
+ 'nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16',
+]);
+
+type SailStatus = 'queued' | 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'cancelled';
+
+interface SailUsage {
+ input_tokens?: number;
+ output_tokens?: number;
+ total_tokens?: number;
+ input_tokens_details?: { cached_tokens?: number };
+ output_tokens_details?: { reasoning_tokens?: number };
+}
+
+interface SailOutputContent {
+ type?: string;
+ text?: string;
+}
+
+interface SailOutputItem {
+ id?: string;
+ type?: string;
+ role?: string;
+ content?: SailOutputContent[];
+ call_id?: string;
+ name?: string;
+ arguments?: string;
+}
+
+interface SailResponse {
+ id?: string;
+ model?: string;
+ created_at?: number;
+ status?: SailStatus;
+ output?: SailOutputItem[];
+ usage?: SailUsage;
+ error?: { message?: string } | null;
+ incomplete_details?: { reason?: string } | null;
+}
+
+interface SailProviderOptions {
+ timeoutMs?: number;
+ pollIntervalMs?: number;
+}
+
+/**
+ * Sail Research adapter.
+ *
+ * Sail's stable surface is the OpenAI Responses API, not streaming Chat
+ * Completions. Every request is submitted with `background: true`, then polled
+ * until terminal. That is required for its flex-only models and avoids proxy
+ * timeouts for core models that spend several minutes queued. The completed
+ * Responses object is normalized back into FreeLLMAPI's Chat Completions shape;
+ * streaming callers receive a small synthesized role/content/finish sequence.
+ */
+export class SailProvider extends BaseProvider {
+ readonly platform: Platform = 'sail';
+ readonly name = 'Sail Research';
+ private readonly timeoutMs: number;
+ private readonly pollIntervalMs: number;
+
+ constructor(options: SailProviderOptions = {}) {
+ super();
+ this.timeoutMs = providerTimeoutMs('sail', options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+ this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+ }
+
+ private authHeaders(apiKey: string): Record<string, string> {
+ return {
+ 'Authorization': `Bearer ${apiKey}`,
+ 'Content-Type': 'application/json',
+ };
+ }
+
+ private completionWindow(modelId: string): 'asap' | 'flex' {
+ return FLEX_ONLY_MODELS.has(modelId) ? 'flex' : 'asap';
+ }
+
+ private reasoningEffort(modelId: string, options?: CompletionOptions): string | undefined {
+ const requested = options?.reasoning_effort;
+ if (!requested) return undefined;
+ // Live API validation: gpt-oss rejects none/minimal and accepts
+ // low/medium/high/xhigh/max. Clamp the two weaker OpenAI spellings to low.
+ if (modelId === 'openai/gpt-oss-120b' && (requested === 'none' || requested === 'minimal')) {
+ return 'low';
+ }
+ return requested;
+ }
+
+ /** Translate Chat Completions history into Responses input items. */
+ private inputItems(messages: ChatMessage[]): Array<Record<string, unknown>> {
+ const input: Array<Record<string, unknown>> = [];
+ for (const message of messages) {
+ const text = contentToString(message.content);
+ if (message.role === 'tool') {
+ input.push({
+ type: 'function_call_output',
+ call_id: message.tool_call_id ?? message.name ?? 'unknown_call',
+ output: text,
+ });
+ continue;
+ }
+
+ if (text || !message.tool_calls?.length) {
+ input.push({ role: message.role, content: text });
+ }
+ for (const call of message.tool_calls ?? []) {
+ input.push({
+ type: 'function_call',
+ call_id: call.id,
+ name: call.function.name,
+ arguments: call.function.arguments,
+ });
+ }
+ }
+ return input;
+ }
+
+ private toolChoice(choice: ChatToolChoice | undefined): unknown {
+ if (!choice || typeof choice === 'string') return choice;
+ return { type: 'function', name: choice.function.name };
+ }
+
+ private textFormat(options?: CompletionOptions): Record<string, unknown> | undefined {
+ const format = options?.response_format;
+ if (!format) return undefined;
+ if (format.type === 'json_schema') {
+ return {
+ type: 'json_schema',
+ name: format.json_schema?.name ?? 'response',
+ schema: format.json_schema?.schema ?? { type: 'object' },
+ strict: format.json_schema?.strict ?? false,
+ };
+ }
+ // Sail rejects Responses `json_object`; preserve the caller's intent with
+ // a permissive JSON schema, the supported equivalent.
+ return {
+ type: 'json_schema',
+ name: 'response',
+ schema: { type: 'object', additionalProperties: true },
+ strict: false,
+ };
+ }
+
+ private buildBody(messages: ChatMessage[], modelId: string, options?: CompletionOptions): Record<string, unknown> {
+ const maxOutputTokens = resolveMaxTokens(this.platform, options?.max_tokens);
+ const reasoningEffort = this.reasoningEffort(modelId, options);
+ const textFormat = this.textFormat(options);
+ const tools = options?.tools?.map(tool => ({
+ type: 'function',
+ name: tool.function.name,
+ description: tool.function.description,
+ parameters: tool.function.parameters,
+ strict: tool.function.strict,
+ }));
+
+ return {
+ model: modelId,
+ input: this.inputItems(messages),
+ background: true,
+ metadata: { completion_window: this.completionWindow(modelId) },
+ ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),
+ ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+ ...(options?.top_p !== undefined ? { top_p: options.top_p } : {}),
+ ...(reasoningEffort ? { reasoning: { effort: reasoningEffort } } : {}),
+ ...(tools?.length ? { tools } : {}),
+ ...(options?.tool_choice !== undefined ? { tool_choice: this.toolChoice(options.tool_choice) } : {}),
+ ...(textFormat ? { text: { format: textFormat } } : {}),
+ // `stop`, `parallel_tool_calls`, seed/penalties/logprobs and multimodal
+ // input are not supported on Sail's stable Responses API.
+ };
+ }
+
+ private errorText(body: unknown, status: number, statusText: string): string {
+ const parsed = body as { error?: { message?: unknown }; detail?: unknown; message?: unknown };
+ if (typeof parsed?.error?.message === 'string' && parsed.error.message) return parsed.error.message;
+ if (typeof parsed?.detail === 'string' && parsed.detail) return parsed.detail;
+ if (typeof parsed?.message === 'string' && parsed.message) return parsed.message;
+ return statusText || `HTTP ${status}`;
+ }
+
+ private recordQuota(res: Response, modelId: string | undefined, quotaContext?: QuotaObservationContext): void {
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'responses',
+ });
+ }
+
+ private async parseResponse(res: Response): Promise<SailResponse> {
+ const body = await res.json().catch(() => ({})) as SailResponse;
+ if (!res.ok) {
+ throw providerHttpError(
+ res,
+ `${this.name} API error ${res.status}: ${this.errorText(body, res.status, res.statusText)}`,
+ body,
+ );
+ }
+ return body;
+ }
+
+ private async wait(ms: number, signal?: AbortSignal): Promise<void> {
+ if (ms <= 0) return;
+ if (signal?.aborted) throw signal.reason ?? new Error('Sail request aborted');
+ await new Promise<void>((resolve, reject) => {
+ let timer: ReturnType<typeof setTimeout>;
+ let onAbort: () => void;
+ const finish = (error?: unknown) => {
+ clearTimeout(timer);
+ signal?.removeEventListener('abort', onAbort);
+ if (error !== undefined) reject(error);
+ else resolve();
+ };
+ onAbort = () => {
+ finish(signal?.reason ?? new Error('Sail request aborted'));
+ };
+ timer = setTimeout(() => finish(), ms);
+ signal?.addEventListener('abort', onAbort, { once: true });
+ });
+ }
+
+ private async runResponse(
+ apiKey: string,
+ messages: ChatMessage[],
+ modelId: string,
+ options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
+ ): Promise<SailResponse> {
+ const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
+ const startedAt = Date.now();
+ const remaining = () => timeoutMs <= 0 ? POLL_REQUEST_TIMEOUT_MS : Math.max(1, timeoutMs - (Date.now() - startedAt));
+ const requestTimeout = () => Math.min(POLL_REQUEST_TIMEOUT_MS, remaining());
+
+ const submit = await this.fetchWithTimeout(`${BASE_URL}/responses`, {
+ method: 'POST',
+ headers: this.authHeaders(apiKey),
+ body: JSON.stringify(this.buildBody(messages, modelId, options)),
+ }, requestTimeout(), { signal: options?.signal, timeoutBounds: 'request' });
+ this.recordQuota(submit, modelId, quotaContext);
+ let response = await this.parseResponse(submit);
+
+ if (!response.id) throw new Error(`${this.name} returned no response id`);
+ const responseId = response.id;
+ while (response.status === 'queued' || response.status === 'in_progress') {
+ if (timeoutMs > 0 && Date.now() - startedAt >= timeoutMs) {
+ throw new Error(`${this.name} response ${responseId} did not complete within ${timeoutMs}ms`);
+ }
+ await this.wait(Math.min(this.pollIntervalMs, remaining()), options?.signal);
+ const poll = await this.fetchWithTimeout(`${BASE_URL}/responses/${encodeURIComponent(responseId)}`, {
+ method: 'GET',
+ headers: this.authHeaders(apiKey),
+ }, requestTimeout(), { signal: options?.signal, timeoutBounds: 'request' });
+ this.recordQuota(poll, modelId, quotaContext);
+ response = await this.parseResponse(poll);
+ }
+
+ if (response.status === 'failed' || response.status === 'cancelled') {
+ const reason = response.error?.message ?? response.status;
+ throw new Error(`${this.name} response ${response.id} ${reason}`);
+ }
+ if (response.status !== 'completed' && response.status !== 'incomplete') {
+ throw new Error(`${this.name} returned unexpected response status: ${response.status ?? 'missing'}`);
+ }
+ return response;
+ }
+
+ private usageOf(usage?: SailUsage): TokenUsage {
+ return {
+ prompt_tokens: usage?.input_tokens ?? 0,
+ completion_tokens: usage?.output_tokens ?? 0,
+ total_tokens: usage?.total_tokens ?? (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0),
+ prompt_tokens_details: { cached_tokens: usage?.input_tokens_details?.cached_tokens ?? 0 },
+ completion_tokens_details: { reasoning_tokens: usage?.output_tokens_details?.reasoning_tokens ?? 0 },
+ };
+ }
+
+ private normalize(response: SailResponse, modelId: string): ChatCompletionResponse {
+ const text = (response.output ?? [])
+ .filter(item => item.type === 'message')
+ .flatMap(item => item.content ?? [])
+ .filter(content => content.type === 'output_text' && typeof content.text === 'string')
+ .map(content => content.text as string)
+ .join('');
+ const toolCalls: ChatToolCall[] = (response.output ?? [])
+ .filter(item => item.type === 'function_call' && typeof item.name === 'string')
+ .map((item, index) => ({
+ id: item.call_id ?? item.id ?? `call_sail_${index + 1}`,
+ type: 'function',
+ function: {
+ name: item.name as string,
+ arguments: item.arguments ?? '{}',
+ },
+ }));
+ const incomplete = response.status === 'incomplete';
+ const finishReason = toolCalls.length > 0
+ ? 'tool_calls'
+ : incomplete && response.incomplete_details?.reason === 'max_output_tokens' ? 'length' : 'stop';
+ const out: ChatCompletionResponse = {
+ id: response.id ?? this.makeId(),
+ object: 'chat.completion',
+ created: response.created_at ?? Math.floor(Date.now() / 1000),
+ model: response.model ?? modelId,
+ choices: [{
+ index: 0,
+ message: {
+ role: 'assistant',
+ content: text,
+ ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+ },
+ finish_reason: finishReason,
+ }],
+ usage: this.usageOf(response.usage),
+ };
+ out._routed_via = { platform: this.platform, model: modelId };
+ return out;
+ }
+
+ async chatCompletion(
+ apiKey: string,
+ messages: ChatMessage[],
+ modelId: string,
+ options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ return this.normalize(
+ await this.runResponse(apiKey, messages, modelId, options, quotaContext),
+ modelId,
+ );
+ }
+
+ async *streamChatCompletion(
+ apiKey: string,
+ messages: ChatMessage[],
+ modelId: string,
+ options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ const data = await this.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ const choice = data.choices[0];
+ const content = contentToString(choice.message.content);
+ const toolCalls = choice.message.tool_calls ?? [];
+ const base = {
+ id: data.id,
+ object: 'chat.completion.chunk' as const,
+ created: data.created,
+ model: data.model,
+ };
+ yield { ...base, choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] };
+ if (content) yield { ...base, choices: [{ index: 0, delta: { content }, finish_reason: null }] };
+ if (toolCalls.length > 0) {
+ yield { ...base, choices: [{ index: 0, delta: { tool_calls: toolCalls }, finish_reason: null }] };
+ }
+ yield { ...base, choices: [{ index: 0, delta: {}, finish_reason: choice.finish_reason }] };
+ }
+
+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult> {
+ const res = await this.fetchWithTimeout(`${BASE_URL}/models`, {
+ method: 'GET',
+ headers: this.authHeaders(apiKey),
+ }, POLL_REQUEST_TIMEOUT_MS, { timeoutBounds: 'request' });
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'models',
+ });
+ return this.validationResult(res);
+ }
+}
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index b104ca1c..00c003a7 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -30,7 +30,7 @@ export const keysRouter = Router();
// was dropped in V4 and re-added in V13 via the router.huggingface.co route.
// SambaNova was dropped in V23 (free tier permanently retired).
const PLATFORMS = [
- 'google', 'groq', 'cerebras', 'bai', 'nvidia', 'mistral',
+ 'google', 'groq', 'cerebras', 'sail', 'bai', 'nvidia', 'mistral',
'openrouter', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama',
'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'ovh', 'agnes', 'reka', 'siliconflow',
'routeway', 'bazaarlink', 'ainative', 'aion', 'anyapi', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'modelscope',
diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.ts
index 5835e48a..bf4b1a41 100644
--- a/server/src/services/provider-quota.ts
+++ b/server/src/services/provider-quota.ts
@@ -115,6 +115,7 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): stri
if (platform === 'google') return 'google::project';
if (platform === 'groq') return 'groq::account';
if (platform === 'cerebras') return 'cerebras::shared';
+ if (platform === 'sail') return 'sail::monthly-credit';
if (platform === 'bai') return 'bai::promo';
if (platform === 'sambanova') return 'sambanova::shared';
if (platform === 'nvidia') return 'nvidia::credit-pool';
@@ -162,7 +163,7 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): stri
}
function isSharedPool(platform: Platform): boolean {
- return ['openrouter', 'google', 'groq', 'cerebras', 'bai', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aion', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'anyapi', 'modelscope', 'aihorde'].includes(platform);
+ return ['openrouter', 'google', 'groq', 'cerebras', 'sail', 'bai', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aion', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'anyapi', 'modelscope', 'aihorde'].includes(platform);
}
type HeaderSpec = { metric: QuotaMetric; limit: string; remaining?: string; reset?: string; strategy?: QuotaResetStrategy };
diff --git a/shared/types.ts b/shared/types.ts
index ea3ab5e4..06dfacc3 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -64,6 +64,10 @@ export type Platform =
| 'google'
| 'groq'
| 'cerebras'
+ // Sail Research — native Responses API provider. $5 in free credits refreshes
+ // monthly when a payment method is attached; usage beyond the grant is
+ // pay-as-you-go. Background polling is required for its flex-only models.
+ | 'sail'
// B.AI — OpenAI-compatible gateway. Its catalog row is a live-tested,
// limited-time 0-credit promotion, not a recurring free allowance.
| 'bai'