Hosted Samsar.js & deployment adapters

Use Samsar.js with the hosted Samsar API as the starting point for media, workflows, search and delivery. When you operate a standalone installation, the same workflows can use supported local provider adapters. Native inference and custom model endpoints can take precedence where their model contract requires it.

Choose your path

Path	What you configure	Where work runs	Start here
Hosted Studio	Samsar account	Managed Samsar services	Open Studio
Hosted API with Samsar.js	Samsar API key in your server environment	Managed Samsar services and their upstream providers	SDK quick start
Standalone with Samsar.js adapter	Local Samsar installation + SAMSAR_API_KEY	Local orchestration; supported generation calls use hosted Samsar	External requests
Standalone with native/provider adapters	Local installation + the supported provider credentials	Local orchestration; model calls use configured providers	Model matrix
Custom model endpoint	Compatible endpoint, authorization and model configuration	Your model endpoint and local Samsar orchestration	Custom image utility

Calling the hosted API and selecting the Samsar adapter inside a standalone deployment are two different uses of Samsar.js. The SDK is a client; it does not deploy a model or turn provider credentials into a running service.

Start with hosted Samsar.js

npm install samsar-js

import SamsarClient from 'samsar-js';

const samsar = new SamsarClient({ apiKey: process.env.SAMSAR_API_KEY });
const job = await samsar.createVideoFromText({
  prompt: 'A calm travel film about a morning beside the sea.',
  image_model: 'GPTIMAGE2.5',
  video_model: 'RUNWAYML',
  duration: 30,
  aspect_ratio: '16:9',
  tts_model: 'OPENAI',
  backingtrack_model: 'LYRIA3',
});
// Save this ID. Generation continues asynchronously.
const requestId = job.data.request_id;
const status = await samsar.getStatus(requestId);
console.log(status.data);

The default base URL is https://api.samsar.one/v1. Keep the key on your server. Poll according to the Video API, or pass a webhook where supported. Hosted charges use Samsar credits; pricing and response credit headers describe billing.

Use the same SDK against a standalone processor

const local = new SamsarClient({
  apiKey: process.env.SAMSAR_LOCAL_API_KEY,
  baseUrl: 'http://localhost:3002/v1',
});
const available = await local.getSupportedTextToVideoModels();
console.log(available.data);

Use a key accepted by that local processor. Changing baseUrl changes the API host; it does not configure provider credentials. Add those in the setup wizard on the standalone installation.

Expand into supported adapters

Open Providers in the setup wizard. The Samsar API key appears first, followed by optional Inference, GMICloud, and Media provider groups. Each provider has a model tooltip and a link to obtain credentials. Continue is highlighted when the entered combination covers the required capabilities; credential validation then determines availability.

Hosted entry pointSamsar.jsCall the hosted Samsar service using Samsar credits. The samsar-js client is the common entry point.SAMSAR_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterOpenAINative GPT inference, image and speech adapters; also required for local embedding indexes.OPENAI_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterAnthropicNative Claude inference and assistant adapter.ANTHROPIC_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterGoogle CloudGemini, Nano Banana, Veo, Google speech and Lyria. Music credentials and model access are validated separately.Google service account / configured Google credentialsProvider documentation ↗Browse compatible models →

Deployment adapterKimiNative Kimi text, vision and structured output; Samsar is the supported alternative.KIMI_K3_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterAlibaba CloudNative Qwen inference in Docker, Qwen Image, Wan and Happy Horse. Qwen Image requires standard pay-as-you-go access.ALIBABA_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterGMICloud via GenBlazeOnly exact model and operation mappings validated for your credential are enabled by the local GenBlaze gateway.GMI_API_KEYProvider documentation ↗GenBlaze adapter source ↗Browse compatible models →

Deployment adapterfalSupported media, speech, music, lip-sync and sound-effect adapters.FAL_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterOpenRouterSupported inference and vision routes. This does not enable image, video or audio generation.OPENROUTER_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterElevenLabsDirect music adapter. Speech is enabled through fal in the setup registry; do not assume a direct key enables every speech route.ELEVENLABS_API_KEYProvider documentation ↗Browse compatible models →

Deployment adapterRunwayNative Runway video adapter.RUNWAY_API_KEYProvider documentation ↗Browse compatible models →

Your endpointCustom endpointRegister a compatible endpoint in your standalone deployment. Available only after configuration.Adapter URL and server-side authorizationProvider documentation ↗Browse compatible models →

Understand ordering and fallback

The documentation begins with hosted Samsar.js. A standalone runtime still uses its validated provider configuration and saved preferences. Native inference may lead a model’s chain; optional media adapters can be reordered where the settings expose that model.

1. Setup writes runtime/config/available-models.json from validated providers.
2. Settings → Model Adapters lets a standalone administrator reorder available inference, text-to-image and image-to-video adapters.
3. Overrides live in runtime/config/model-adapter-preferences.json; rendering config preserves them.
4. A definitive failure can advance a supported fallback chain. An asynchronous job already accepted by a provider stays pinned to that provider while polling.

These controls are specific to standalone installations. Hosted routing is managed by Samsar. Adding a provider to the table does not mean it is compatible with every model from that provider.

Model-specific exceptions

Model or operation	What to know
Kimi K3	Native Kimi first, Samsar alternative; OpenRouter is not in the Kimi chain. Use kimi-k3 in inference requests; KIMIK3 is the setup key.
Qwen inference	Hosted QWEN3.8 uses OpenRouter internally. Native Alibaba Qwen is a Docker option.
Qwen Image 3.0 Pro	QWENIMAGE3PRO requires the native Alibaba adapter with standard pay-as-you-go credentials. A Token Plan key does not enable this model.
GPTImage 2.6	Use stable keys GPTIMAGE2.5 and GPTIMAGE2.5EDIT, now targeting 2.6 Sunburst at High quality. Retired GPTIMAGE2 and GPTIMAGE2EDIT keys are rejected for new requests. Older GenBlaze GPT Image 2 mappings are excluded from these contracts.
Seedance 2.0	Provider-billed standalone I2V via fal or the exact validated GenBlaze route; no Samsar adapter in the setup registry.
Seedance 2.5	Uses 5, 10 or 15 second 720p scene buckets. Agent/Vidgenie is 60 credits/sec; standard Express is 50. Direct clips use separate model-call pricing.
Kling 4	KLINGIMGTOVID4 / KLINGTXTTOVID4: 720p, no native audio, 5–30-second clips in five-second steps. Old 3 Pro/Turbo keys are compatibility aliases for new requests.
GMICloud via GenBlaze	Only exact, credential-validated model/operation mappings are exposed. Approximate model matches do not enable a route.
ElevenLabs speech	The hosted speech contract accepts ELEVENLABS; standalone setup advertises speech through fal. Direct ElevenLabs music has its own adapter.
Local search and recommendations	Local embedding indexes require OPENAI_API_KEY; URL crawling also requires FIRECRAWL_API_KEY. A Samsar key alone does not satisfy that local implementation. Hosted clients use Samsar.js.

Verify before generating

Use Express model discovery for video workflow allowlists and the provider capability API for onboarding capabilities. Neither is a live guarantee of every upstream model. Local generated configuration and validated GenBlaze mappings determine what your own deployment can offer.

See the repository provider guide for runtime details and the model matrix to compare compatible choices.

GPT and Claude model choices

Text inference, vision, and assistant requests support these models at high or xhigh effort:

Samsar model	Native provider model	OpenRouter model
gpt-6-astra	gpt-6-astra	openai/gpt-6-astra
gpt-6.1-sol	gpt-6.1-sol	openai/gpt-6.1-sol
claude-opus-5.5	claude-opus-5-5	anthropic/claude-opus-5.5
claude-fable-5.1	claude-fable-5-1	anthropic/claude-fable-5.1

Use OPENAI_API_KEY for native GPT, ANTHROPIC_API_KEY for native Claude, or OPENROUTER_API_KEY for OpenRouter. Samsar-hosted requests use SAMSAR_API_KEY. Existing defaults remain GPT 6 Astra and high; selecting Sol no longer redirects to Astra. Saved -xhigh model aliases remain accepted.

Production and standalone deployments prefer native Anthropic for Claude text and vision requests when ANTHROPIC_API_KEY is configured. OpenRouter remains the next configured provider when that key is absent; explicit provider selection is preserved. This applies to both Claude models at High and XHigh effort.

For pipeline and narrative calls, set inference_model and effort. For chat calls, set model and reasoning: { effort: "xhigh" } (or "high"). Account, Vidgenie, and Assistant selectors expose both model families and effort levels; standalone installations show only configured models.

Assistant token rates are listed on the pricing page. High and XHigh use the same per-token rates; total charges depend on actual input, cached input, and output usage. Thinking tokens count as output tokens.