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',
  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, add the credentials for your intended models, and let validation produce the available model list. Start with the Samsar adapter for its supported managed routes; add native inference or other provider adapters as needed.

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.
GPT Image 2.5	Keep stable keys GPTIMAGE2 and GPTIMAGE2EDIT. 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. Hosted routing and standalone adapter choices differ.
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.