Samsar is a generative video and media automation platform for turning prompts, product images, structured content, and creative ideas into finished videos and reusable studio assets.
It brings together one-shot text-to-video, image-list-to-video, image editing, audio generation, semantic search, recommendations, assistant workflows, multi-provider model routing, and detailed post-production controls across one integrated Studio and API surface.
Production app · Production API docs · Demo channel · Setup wizard
Features · Quick start · Workflows · Documentation · Adapters · API · Operations
- One-shot Studio text-to-video up to 3 minutes for documentary, infotainment, ed-tech, film summary, custom themes, and original ideas.
- One-shot image-list-to-video that turns product images into polished ad videos with optional narrator avatar, outro, and CTA.
- One-click scene re-rolls after render to fix small imperfections without rebuilding the full project.
- Full Studio workspace for detailed, granular post-processing.
- Sandboxed local logging, with logs and traces kept on your machine.
- Multi-provider model routing so each operation can use the best available provider and model.
- Built-in search and recommendations for creating a generative video library and Studio knowledge base.
Start with hosted Studio or the samsar-js client. One Samsar API key connects your application to managed video, image, audio and inference workflows. Move into the setup wizard below when you want your own deployment and supported provider adapters.
| I want to… | Start here | Then explore |
|---|---|---|
| Create in the browser | Hosted Studio | Visual workflows |
| Build with an API | Hosted Samsar.js | Video, images, chat, audio |
| Compare models and modalities | Full model matrix | Provider and adapter guide |
| Run my own deployment | Setup steps below | Native inference, Samsar.js and compatible provider adapters |
First API request with hosted Samsar.js
npm install samsar-jsimport SamsarClient from 'samsar-js';
const samsar = new SamsarClient({ apiKey: process.env.SAMSAR_API_KEY });
const available = await samsar.getSupportedTextToVideoModels();
console.log(available.data);
const job = await samsar.createVideoFromText({
prompt: 'A cinematic product launch in a sunlit gallery.',
image_model: 'GPTIMAGE2.5',
video_model: 'RUNWAYML',
duration: 30,
aspect_ratio: '16:9',
});
console.log(job.data.request_id); // Save this ID and poll for completion.Get a key from Samsar, keep it in your server environment, and follow the status and delivery contract. Hosted requests use Samsar credits; see pricing. No local Docker installation is needed for this path.
The following steps install a standalone deployment.
- Git.
Note
Node.js, npm, and Yarn are not host prerequisites for a standalone installation. The setup wizard and its JavaScript tooling run inside Docker.
If you cloned this repository directly, stay at the repository root and continue to step 2.
Using this repository as a deployable wrapper around sibling source projects?
This parent-workspace workflow additionally requires rsync, Node.js, and npm:
cd samsar
npm run syncThe sync script excludes common secret and generated paths when copying projects into this monorepo. Skip this workflow in a standalone clone.
After updating sibling source projects, sync all services, start the setup wizard, and rebuild the configured local stack with:
npm run sync:restartThis finishes the sync, starts the setup wizard on http://localhost:8089, and
waits for it before building application images. With an existing runtime config,
all image builds finish before application containers are replaced; data volumes
are preserved and the command waits for the configured services. A fresh install
opens the wizard for configuration and deployment. npm run docker:restart
performs the same wizard-first rebuild without another source sync.
It also packages the Vast.ai FLUX.2 standalone utility under
utils/vast-flux2. From a synchronized workspace or standalone clone:
cd utils/vast-flux2
./provision-vast-flux2.sh --check
./provision-vast-flux2.sh --configure-samsarFor an already provisioned endpoint, register the latest securely saved adapter with the running standalone Samsar processor:
cd utils/vast-flux2
./configure-samsar-custom-image-model.shThe provisioner stores credentials outside the repository under
~/.config/samsar/vast-flux2 with owner-only permissions. See
utils/vast-flux2/README.md for credential setup, URL output, instance
destruction, and advanced options.
How the launcher handles Docker on each platform
The direct setup launcher checks Docker before continuing:
| Platform | Bootstrap behavior |
|---|---|
| Linux | Requires Docker Engine 20.10.0+, Docker Compose 2.20.0+, and Buildx. Missing installations receive current packages; deficient existing installations are updated only through their existing installation channel without changing package families. |
| macOS | Requires Docker Desktop 4.84.0 or newer. Uses an existing compatible installation, or installs/updates it automatically when the Docker Desktop updater or Homebrew is available. |
| Windows | Requires Docker Desktop 4.84.0 or newer. setup.ps1 detects per-user and all-users installations, uses the Docker Desktop updater or winget to install/update it, and runs the launcher through WSL 2 integration. |
Set SAMSAR_SETUP_INSTALL_DOCKER=0 to disable automatic Docker installation and updates. An incompatible installation then produces a platform-specific manual update instruction instead of being changed.
On macOS without Homebrew, install Docker Desktop for Mac.
On Windows without winget, install Docker Desktop for Windows and enable WSL 2 integration.
On Linux, the launcher does not replace an existing distro, Snap, rootless, or Docker Desktop installation with a different package family. It updates through a recognized existing channel when that is safe and otherwise links the matching Docker Engine installation guide. Docker's convenience installer is used only as a fresh-install fallback, never to upgrade an existing Engine.
Arch requires a full system package upgrade, so the launcher asks for explicit confirmation (or requires --yes) before running pacman -Syu. Inside WSL, the launcher uses Docker Desktop's Windows integration and never installs or starts a competing in-distribution Engine.
The Linux version numbers are functional compatibility floors, not a recommendation to remain on an old patch; keep Docker on a current, vendor-supported release.
[!IMPORTANT] On macOS, use Docker Desktop 4.84.0 or newer. Earlier releases predate the 4.45.0 wake-from-sleep VM fix and the 4.79.0 VM-wake API 500 fix. The launcher verifies the installed app version before starting the setup wizard. When automatic Docker installation is enabled, it attempts an in-place update; otherwise it stops with an upgrade instruction.
Windows uses the same Docker Desktop minimum so launcher behavior stays consistent across Desktop platforms. Native Linux does not contain Docker Desktop's macOS VM/network path; its separate Engine and Compose floors are based on Samsar's runtime and compose-file features.
Linux, macOS, or WSL:
./setup.shWindows PowerShell:
.\setup.ps1Windows Command Prompt:
setup.cmdnpm run setup-wizard remains available as a developer convenience, but is not required for installation.
For a workspace with Node.js and npm, npm run deploy (also available as
npm run docker:up) starts the wizard first. With no saved runtime config, complete
configuration and deployment in that browser window. With a saved config, the
command continues into the application build after the wizard is ready. The
wizard stays available if an application build fails.
The launcher installs or starts Docker when supported, builds and starts the containerized setup wizard, waits for it to respond, and opens a one-time authenticated URL on http://localhost:8089. The wizard binds to loopback by default; use scripts/setup-wizard-remote.sh for remote hosts so access travels through an SSH tunnel. Set SAMSAR_SETUP_OPEN_BROWSER=0 to skip browser auto-open.
Complete the browser flow to write deployment config, render runtime env and model availability, build and start the selected Docker Compose profiles, publish the local media gateway when required, verify the processor API and Studio client, and prepare local login.
| Service | URL |
|---|---|
| Studio | http://localhost:3000 |
| Processor API | http://localhost:3002 |
| Local media through Processor API | http://localhost:3002/assets_v2/... |
| MinIO console (local storage mode) | http://localhost:9001 (loopback; generated credentials in runtime/secrets/minio.env) |
| Grafana logs | http://localhost:4000 (loopback; generated credentials in runtime/secrets/grafana.env) |
Stop the stack:
npm run docker:downWhat the five setup wizard steps configure
| Step | What it configures | Runtime effect |
|---|---|---|
| Providers | Inference routing, OpenAI, Google Cloud, Kimi K3, Alibaba Cloud, GMICloud through GenBlaze, OpenRouter, FAL, ElevenLabs, RunwayML, Samsar | Validates credentials and controls which models/actions appear in runtime/config/available-models.json. |
| Services | Processor, setup wizard, image generator, assistant query processor, audio generator, AI video layer generator, video renderer, frames processor, express video listener, and logger | Determines which Docker service families are enabled for the local runtime. |
| Mail and Data | Local or remote MongoDB, local MinIO, external S3/CloudFront, Backblaze B2, SMTP/SES/disabled mail | Writes database, storage, CDN, media, and mail settings. |
| Domain | Optional nginx reverse proxy for a public domain/subdomain, public IP, or private IP, with optional IP detection, port opening, and Let's Encrypt SSL for validated domains | Enables public or intranet access URLs for Studio and the processor API. |
| Admin | Organization and initial admin/login setup | Prepares Docker setup login and local access details. |
Use manual runtime config when you want direct control over credentials, provider selection, storage URLs, database settings, or mail settings.
Explore every setup step, validation, generated file, and lifecycle stage →
The diagrams below show the primary generation and discovery pipelines. Open any workflow to explore it, then select the diagram for its detailed documentation.
Text to Video
Image List to Video
Search Embeddings
Recommendations
Follow a workflow from the hosted Samsar.js API into its local deployment details. Each guide retains its endpoint, input, processing and verification sections.
| Workflow / guide | Hosted API reference | Repository guide |
|---|---|---|
| Model matrix | API overview · Models & pricing | Every modality, model key and compatible adapter |
| Providers and Models | Samsar managed provider API | Credentials, native options and routing |
| Text to Video | Video API | Models, pipeline and status |
| Image List to Video | Image-list API | Product videos, CTA and narrator settings |
| Image Edit | Image API · V2 edits | Generation, enhancement and edits |
| Speech, music, sound and lip sync | Audio · Video operations | Audio and performance guide |
| Inference and assistants | Chat · Assistant | Inference matrix · Billing and retries |
| Narrative and branching | Narrative API | Workflow allowlists |
| Search | Index and search | Templates, filters and indexing |
| Recommendations | Similarity API | Related content and product matching |
| Text Enhance | Enhance API | Inputs, billing and inference |
| Accounts and delivery | External users · Credits · Publications | Architecture |
| Setup and operations | V2 API | Setup wizard · Architecture |
| Area | Directory | Purpose |
|---|---|---|
| Studio app | apps/samsar-client |
Samsar Studio and VidGenie frontend. Runs on port 3000 in Docker. |
| Setup wizard | apps/setup-wizard |
Browser setup flow for providers, services, data, mail, and admin configuration. Starts on port 8089 before application builds through deploy, docker:up, and docker:restart. |
| Processor API | services/processor |
Public API, Studio API, auth, billing, session orchestration, search/recommendation APIs, and status endpoints. Runs on port 3002. |
| Generation workers | services/generator, services/ai-video-layer-generator, services/video-generator, services/audio-generator, services/frames-processor |
Image generation/editing, AI video layers, final rendering, speech/music/sound effects, frame processing, and media processing. |
| Workflow workers | services/express-video-listener, services/assistant-query-processor, services/task-processor |
Express video state machine, assistant queries, and scheduled/background tasks. |
| Provider gateway | services/genblaze-gateway |
Local GenBlaze gateway for credential-scoped GMICloud inference and media models. |
| Runtime config | runtime/config, runtime/secrets |
Generated deployment config, model availability, env files, and local secrets. Not committed. |
| Deployment | deploy/compose |
Docker Compose stack and local deployment configuration. |
| Docs | docs, pages |
Runtime notes, brand assets, and deeper Markdown documentation linked from this README. |
View the Docker deployment architecture
Start with the Samsar.js managed adapter for supported hosted workflows, then add compatible native or provider adapters to a standalone installation. Native inference and custom model endpoints can take precedence for their own models. Documentation order does not change the runtime’s configured routing.
Samsar.js is the common client and hosted service entry point. Supported deployment options include OpenAI, Anthropic, Google Cloud, Kimi, Alibaba Cloud, GMICloud through GenBlaze, fal, OpenRouter, ElevenLabs, and Runway.
The complete model matrix lists all 46 model keys in the standalone setup registry, plus the additional Studio catalog, custom endpoints and managed service models. Each row includes the request key, hosted path, supported adapters, workflow scope and usage notes.
| Modality | Models in the deployment registry | Explore and build |
|---|---|---|
| Inference & vision | GPT 6 Astra, Claude Opus 5.5, Gemini 4 Argon, Kimi K3, Qwen 3.8 Max | Matrix · Hosted chat |
| Image generation | GPTImage 2.5, Seedream 5 Pro, Nano Banana 2 / Pro, Qwen Image 3.0 Pro, Wan 2.7 Pro | Matrix · Image API |
| Image editing | GPTImage 2.5 Edit, Nano Banana 2 / Pro Edit, BRIA Eraser / GenFill | Matrix · Edit API |
| Video generation | Runway; Veo 3.1 text / fast / I2V / first-last-frame; Cosmos 3; Seedance 1.5 / 2.0 / 2.5; Kling 3 / 1.6 / 2.1 variants; Hailuo; Happy Horse 1.1 | Every video key · Video API |
| Speech | OpenAI TTS, Google TTS, ElevenLabs | Matrix and request values · Audio API |
| Music | Lyria 3, ElevenLabs Music | Matrix · Audio API |
| Lip sync | Sync, LatentSync, Kling, Hummingbird, Creatify | Matrix · Video operations |
| Sound effects | MMAudio V2, Mirelo AI; hosted audio also exposes SDAUDIO | Matrix · Audio and performance |
| Embeddings & search | Managed OpenAI embeddings (text-embedding-3-large) |
Matrix · Search |
| Transcript alignment | Managed Whisper (whisper-1) |
Matrix · Audio API |
Understand model keys, workflow support and native exceptions
- Model keys:
GPTIMAGE2.5identifies GPTImage 2.5; retiredGPTIMAGE2requests return an Invalid model validation error;SEEDREAMmaps to Seedream 5 Pro;HAPPYHORSEI2Vmaps to Happy Horse 1.1 I2V. Use Samsar keys rather than an upstream provider ID. - Inference aliases: current requests use
gpt-6-astra; older setup files can containgpt-5.6-sol, which the processor normalizes.KIMIK3is the setup key; usekimi-k3in inference requests. - Workflow scope: the complete Studio catalog is larger than the Express and branching allowlists. A model listed for image generation is not automatically selectable for an Express scene.
- Native-only model:
QWENIMAGE3PROneeds Alibaba Cloud standard pay-as-you-go credentials. It is not enabled by a Samsar key or Alibaba Token Plan. - Credential-scoped model routes: GenBlaze enables only exact validated GMICloud mappings. Legacy GPT Image 2 mappings do not satisfy the GPTImage 2.5 contract.
- Speech values: Express uses
tts_model: 'OPENAI','GOOGLE'or'ELEVENLABS', not the setup labelsOPENAI_TTSandGOOGLE_TTS.
For hosted use, create a Samsar API key and initialize samsar-js. For standalone use, open Providers in ./setup.sh, configure Samsar and any required native/provider keys, and validate them. The wizard writes secrets and computes deployment availability. Settings → Model Adapters controls supported per-model preference order.
| Path / adapter | What you supply | What to expect |
|---|---|---|
| Samsar.js | SAMSAR_API_KEY |
Managed routes for supported models using Samsar credits. API reference. |
| Native inference | OpenAI, Anthropic, Google, Kimi or Alibaba credentials for the selected model | Native-first paths where supported. Provider setup. |
| Media adapters | Supported Google, OpenAI, Runway, fal, Alibaba or ElevenLabs credentials | Only the models and operations mapped to that adapter. Per-model matrix. |
| GMICloud through GenBlaze | GMI_API_KEY and validated model mappings |
Credential-specific inference/media routes through the local gateway. Gateway details. |
| Custom model endpoint | Compatible endpoint and authorization | Your own registered adapter, including optional Vast.ai FLUX.2. |
npm run config:render writes backend environment files and runtime/config/available-models.json. Studio and the Express API filter models using the current deployment configuration. Keep credentials in server-side secrets.
See Providers and Models for routing and exceptions. Seedance 2.5 uses 5-, 10- or 15-second 720p scene renders; hosted production uses GMICloud internally, while standalone follows the selected supported adapter.
Choose one option under Mail & Data → Media storage in the setup wizard.
| Adapter | Wizard option | Configuration |
|---|---|---|
| MinIO | Local MinIO | No cloud credentials. Starts the bundled S3-compatible service with bucket samsar-resources; media remains local and is served through the Processor API. |
| S3-compatible / AWS S3 | External S3 / CloudFront | Enter bucket, region, access key, secret key, and an HTTPS public CDN base URL. Add an endpoint for non-AWS S3, enable path-style URLs when required, and optionally add CloudFront signing keys. |
| Backblaze B2 Cloud Storage | Backblaze B2 | Create a public bucket, then enter bucket name, Application Key ID, Application Key value, and its endpoint such as s3.us-east-005.backblazeb2.com. The wizard derives the public bucket URL and verifies region, bucket access, and writeFiles. Master keys upload through the native B2 API; standard application keys use the S3-compatible API. |
External S3 and B2 publish media for remote model providers. MinIO keeps media local and starts the local media tunnel automatically when a configured provider needs a public URL.
Use samsar-js against https://api.samsar.one/v1 for hosted workflows. The routes below are also served by the standalone processor at http://localhost:3002. To target it with the SDK, set baseUrl: 'http://localhost:3002/v1' and use credentials accepted by that processor. Auth accepts a Samsar API key, auth token, or app key where supported by the route. See the linked API reference for each contract.
The Studio one-shot flow exposes durations up to 3 minutes; the text-to-video API accepts requests from 10 to 240 seconds.
| Workflow | Main endpoints | Notes |
|---|---|---|
| Health | GET /v1/chat/health, GET /v1/image/health, GET /v1/video/health, GET /v2/health |
Per-route health checks for local verification. |
| Supported video models | GET /v1/video/supported_models |
Returns text-to-video and image-list-to-video model lists filtered by deployment availability. |
| Text enhance | POST /v1/chat/enhance |
Enhances copy from message, optional metadata, language, and maxwords. |
| Search indexing | POST /v1/chat/create_embedding, POST /v1/chat/create_embedding_from_url, POST /v1/chat/generate_embeddings_from_plain_text |
Creates reusable embedding templates from records, URLs, or plain text. |
| Search query | POST /v1/chat/search_against_embeddings |
Searches a template with search_term, filters, and optional reranking. |
| Recommendations | POST /v1/chat/similar_to_embeddings |
Returns similar records from a template using text or structured search JSON. |
| Assistant workflows | POST /v1/assistant/*, POST /v2/assistant/* aliases |
Runs assistant queries through the processor and configured inference provider. |
| Managed chat/assistant completions | POST /v2/external/chat/completions, POST /v2/external/assistant/completions |
OpenAI-compatible messages; synchronous or queued polling; published input, output, and cached-input token rates. |
| Image edit/generation | POST /v1/image/text_to_image, POST /v1/image/enhance, POST /v1/image/remove_branding, POST /v1/image/add_image_set |
Queues image sessions and returns request IDs for polling. |
| Image status | GET /v1/image/status?request_id=..., GET /v1/image/list |
Polls and lists image API sessions. |
| Text-to-video | POST /v1/video/text_to_video, POST /v2/text_to_video |
Requires prompt, image model, video model, and duration from 10 to 240 seconds. |
| Image-list-to-video | POST /v1/video/image_list_to_video, POST /v2/image_list_to_video |
Uses image URLs, prompt/metadata, selected models, aspect ratio, and optional CTA/outro/footer/narrator settings. |
| Video status | GET /v2/status, GET /v2/status_detailed, GET /v1/external_users/status |
Status endpoints support request IDs/session IDs; terminal provider/model failures include the exact stored error, with failed layer details in status_detailed. |
Studio image calls, edits, external image endpoints, and rerolls are charged on completion using the final image token and output prices. Production agent pipelines retain their flat stage pricing. Standalone Docker waives local image debits; calls through Samsar.js are charged by the hosted image endpoint. See Image billing and retries for status receipts, request keys, and regression checks.
Credits per one million tokens on the named native adapter. Generation and the listed edit keys share these rates. A dash means that token category is not offered on that route.
| Model | Adapter | Token category | Input | Cached input | Output |
|---|---|---|---|---|---|
GPTIMAGE2.5 / GPTIMAGE2.5EDIT |
OpenAI | Text tokens | 600 | — | — |
GPTIMAGE2.5 / GPTIMAGE2.5EDIT |
OpenAI | Image tokens | 960 | — | 3,600 |
NANOBANANA2 / NANOBANANA2EDIT |
Google global | Text tokens | 60 | 6 | 360 |
NANOBANANA2 / NANOBANANA2EDIT |
Google global | Image tokens | 60 | 6 | 7,200 |
NANOBANANA2 / NANOBANANA2EDIT |
Google regional | Text tokens | 66 | 6.6 | 396 |
NANOBANANA2 / NANOBANANA2EDIT |
Google regional | Image tokens | 66 | 6.6 | 7,920 |
NANOBANANAPRO / NANOBANANAPROEDIT |
Google global | Text tokens | 240 | 24 | 1,440 |
NANOBANANAPRO / NANOBANANAPROEDIT |
Google global | Image tokens | 240 | 24 | 14,400 |
NANOBANANAPRO / NANOBANANAPROEDIT |
Google regional | Text tokens | 264 | 26.4 | 1,584 |
NANOBANANAPRO / NANOBANANAPROEDIT |
Google regional | Image tokens | 264 | 26.4 | 15,840 |
Text output includes reasoning tokens when reported. The direct OpenAI Images API has no cached-input price.
Credits per generated image on the listed native adapter and configuration.
| Model | Adapter | Configuration | Credits / output image |
|---|---|---|---|
DALLE3 |
OpenAI | Standard · 1024×1024 | 4.8 |
DALLE3 |
OpenAI | Standard · 1792×1024 or 1024×1792 | 9.6 |
IMAGEN3 |
Standard generation | 4.8 | |
IMAGEN3FLASH |
Fast generation | 2.4 | |
WAN2.7PRO |
Alibaba international | 1K | 9 |
QWENIMAGE3PRO |
Alibaba international | 1K | 4.8 |
QWENIMAGE3PRO |
Alibaba international | 2K | 9 |
WAN2.7PRO |
Alibaba China / global | 1K | 8.25132 |
QWENIMAGE3PRO |
Alibaba China / global | 1K | 4.1256 |
QWENIMAGE3PRO |
Alibaba China / global | 2K | 8.25132 |
Supported Fal image routes have separate checked-in final model-call rates and do not require a runtime provider pricing lookup. Other adapter routes have configuration-specific final charges in their completion receipts; their prices should not be inferred from another adapter's table.
Studio AI-video calls, lip-sync and sound-effect layers, direct hosted video endpoints and scene rerolls are charged on completion at the final model-call output prices. Production agent pipelines keep their fixed stage prices. Standalone model adapters waive local debits and use the hosted direct endpoints through Samsar.js. See Video model billing and retries for endpoint scope, receipts, provider configuration and regression coverage.
These prices apply to individual model calls on the named native adapter. Per-second prices refer to generated output before scene trimming or padding. Multiple completed outputs are billable individually. Supported Fal routes have separate checked-in final model-call rates, including a 20% markup over the provider base price; the worker does not fetch a provider price while completing them.
| Model | Adapter | Configuration | Unit | Credits |
|---|---|---|---|---|
RUNWAYML |
Runway | Gen-4.5 | second | 14.4 |
VEO3.1 / VEO3.1I2V |
Google Cloud | 720p / 1080p, video | second | 24 |
VEO3.1 / VEO3.1I2V |
Google Cloud | 720p / 1080p, video + audio | second | 48 |
VEO3.1FAST / VEO3.1I2VFAST |
Google Cloud | 720p, video | second | 9.6 |
VEO3.1FAST / VEO3.1I2VFAST |
Google Cloud | 720p, video + audio | second | 12 |
VEO3.1FAST / VEO3.1I2VFAST |
Google Cloud | 1080p, video | second | 12 |
VEO3.1FAST / VEO3.1I2VFAST |
Google Cloud | 1080p, video + audio | second | 14.4 |
HAPPYHORSEI2V |
Alibaba international | Happy Horse 1.1, 720p | second | 16.8 |
HAPPYHORSEI2V |
Alibaba China / global | Happy Horse 1.1, 720p | second | 14.85228 |
HAILUOPRO |
MiniMax | Hailuo 02, 768p, 6 seconds | clip | 33.6 |
HAILUOPRO |
MiniMax | Hailuo 02, 768p, 10 seconds | clip | 67.2 |
Verified Fal rates have a 20% markup at 100 credits per USD. Final hosted rates are SYNCLIPSYNC 16 credits per measured output second, LATENTSYNC 24 credits per video through 40 output seconds or 0.6 credits per output second above 40 seconds, KLINGLIPSYNC 1.68 credits per input-video second rounded up to five-second blocks, and CREATIFYLIPSYNC 2 credits per measured output second. Fal publishes Creatify as $1 per video minute without naming the duration basis; output duration is Samsar's billing inference. Fal's Kling pricing callout and explanatory prose conflict; Samsar follows the callout's per-input-second unit. See the provider sources and billing details.
HUMMINGBIRDLIPSYNC uses a historical fallback of 15 credits per requested second because a current Fal price cannot be verified. This is not a verified Fal price plus markup. Hosted video sound effects use 0.12 credits per submitted audio second for MMAUDIOV2 and 1.2 credits per submitted second per sample for MIRELOAI, including the 20% adapter markup. Mirelo's sample multiplier is inferred from related Fal models; its SFX1.6 page does not state the multiplier explicitly. New calls request one sample; older calls used Fal's two-sample default. Other Fal or GMICloud AI-video calls have configuration-specific final charges in their completion receipts. Billing confirmation may remain pending after generation. Audio-only sound effects use their separate audio endpoint prices.
Assistant completions and public chat/assistant endpoints called through samsar-js use the final input, output, and cached-input token prices, listed in credits per one million tokens for each model and adapter route. Production agent pipeline inference retains its flat stage pricing.
For retries, pass { idempotencyKey: 'stable-request-id' } in SDK request options or reuse client_request_id. The same key and payload reuse the response and original charge; changed payloads return 409. Requests awaiting billing confirmation or completion after a timeout can remain pending; keep the same key while checking completion.
See Assistant billing and retries for endpoint scope, standalone behavior, tool limitations, and regression commands. Other media, narrative, and utility routes retain their route-specific pricing.
Manual Docker setup
Use this path only when you do not want the browser setup wizard to write runtime config for you.
Create a local runtime config:
mkdir -p runtime/config runtime/secrets
cp -n samsar.config.example.json runtime/config/samsar.config.jsonEdit runtime/config/samsar.config.json for provider enablement, non-secret provider settings, storage, database, and public URLs. Provider credentials can be kept in runtime/secrets/provider.credentials.json. The checked-in example is safe for local Docker defaults: local MongoDB, local MinIO-compatible storage, local media gateway, and no external provider enabled.
Render env files:
npm run config:renderInstall Docker-visible fonts and prepare the optional local logger stack:
npm run docker:setup-assetsStart the complete local Docker stack:
npm run docker:upDocker Compose profiles, volumes, and maintenance
Validate the rendered Compose configuration:
npm run docker:confignpm run docker:up first starts the setup wizard and waits for port 8089 to
respond. With runtime/config/samsar.config.json present, it renders
runtime/secrets/root.env, durable infrastructure credential env files, and
runtime/config/available-models.json, then initializes authenticated MongoDB and
starts the configured profiles. Without a saved config, it leaves configuration
and deployment to the wizard. The setup wizard adds the reverse-proxy profile only
when nginx access is enabled. A wizard startup failure stops deployment before
runtime configuration or application containers are changed.
| Profile | Services |
|---|---|
core |
client, processor |
workers |
generator, audio-generator, frames-processor, video-generator, ai-video-layer-generator, express-video-listener, assistant-query-processor, task-processor |
local-mongo |
mongo |
minio |
minio |
genblaze |
genblaze (enabled only with a validated GMICloud provider) |
local-media |
media-gateway, media-tunnel-controller |
logger |
loki, promtail, grafana |
reverse-proxy |
Optional reverse-proxy nginx service when enabled by the setup wizard. |
Run npm run docker:setup-assets whenever fonts or logger config need to be refreshed. It installs subtitle/render fonts into runtime/fonts, copies them into running Samsar service containers, and recreates Promtail/Grafana only when services.logger is enabled.
Persistent Docker state is stored in mongo-data, minio-data, media-assets, media-assets-v2, persistent-data, loki-data, promtail-data, and grafana-data.
Inspect logs:
docker compose -f deploy/compose/docker-compose.yml logs -f processor clientRebuild and replace only the frontend container:
docker compose -f deploy/compose/docker-compose.yml --profile core build client
docker compose -f deploy/compose/docker-compose.yml --profile core up -d --force-recreate --no-deps clientWhen making changes during an active generation session, prefer restarting only the affected client or API container.
Active jobs: Avoid restarting generation workers while a video, audio, or sound-effect job is active unless you have confirmed the worker is stuck or the job can safely resume.
Local media URLs and remote-provider access
In local Docker, completed render URLs are expected to look like:
http://localhost:3002/assets_v2/video/output/<session-id>/<file>.mp4
That browser URL is served by the configured processor API from the mounted media volume. It is not an S3 or CloudFront URL unless external media publishing is enabled in runtime config.
When a remote provider must fetch local-only media, the local-media profile starts a Compose-managed Cloudflared controller. It starts a quick tunnel when runtime config enables a remote media consumer, validates the exact media-gateway health marker, atomically publishes localMediaTunnel.publicUrl, and replaces the tunnel when health checks fail or a worker writes the shared refresh marker. It does not mount the Docker socket or depend on the setup-wizard process.
For a manual runtime, start or recreate only the local-media services:
docker compose --env-file runtime/secrets/root.env \
-f deploy/compose/docker-compose.yml \
--profile local-media up -d --build \
media-gateway media-tunnel-controllerInspect its lifecycle and current URL:
docker compose --env-file runtime/secrets/root.env \
-f deploy/compose/docker-compose.yml \
--profile local-media logs -f media-tunnel-controllerProvider workers reload and validate the published URL before each public adapter request. Browser previews continue to use the configured processor or reverse-proxy URL.
The legacy scripts/start-local-media-tunnel.sh command remains a compatibility wrapper that starts and waits for the same Compose services instead of creating a second tunnel container.
Runtime configuration and generated files
The main config file is runtime/config/samsar.config.json. Its local Docker defaults are:
database.provider:local-mongostorage.mode:local-miniostorage.provider:s3-compatiblestorage.backend:miniostorage.staticCdnUrl:http://localhost:3002/storage.externalMediaPublishEnabled:falsepublicUrls.clientApp:http://localhost:3000publicUrls.processorApi:http://localhost:3002publicUrls.media:http://localhost:3002reverseProxy.enabled:false
Enable only the providers you intend to use, then rerender:
npm run config:renderFor a manual Alibaba Cloud setup, enable the provider in runtime/config/samsar.config.json and save this as runtime/secrets/provider.credentials.json:
{
"version": 1,
"alibabaCloud": {
"apiKey": "<alibaba-model-studio-api-key>",
"apiHost": "https://workspace-id.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
}Protect it with chmod 600 runtime/secrets/provider.credentials.json before rendering. The setup wizard performs these steps automatically after validating the credentials.
Generated files:
runtime/secrets/root.env: env consumed by Docker services.runtime/secrets/application.env: generated application signing and custom-adapter encryption secrets.runtime/secrets/mongo.env: generated local MongoDB root and application credentials. Services use the application account through the authenticatedMONGO_URLinroot.env.runtime/secrets/minio.env: generated local MinIO administrator credentials.runtime/secrets/grafana.env: generated Grafana administrator credentials.runtime/secrets/provider.credentials.json: setup-wizard-managed provider keys and validated endpoints. Keep it private and mode0600.runtime/config/available-models.json: model/action availability derived from enabled providers.runtime/config/model-adapter-preferences.json: standalone-admin adapter order overrides saved from Settings → Model Adapters. Config rendering preserves this file.
See Architecture for storage and deployment defaults and Providers and Models for credential, availability, and fallback behavior.
Warning
Public reverse-proxy and domain access are disabled by default, but Docker publishes the Studio and processor ports on the host. Use host firewall rules or localhost-only Docker port bindings when the stack must not be reachable from other networks.
The setup wizard can optionally enable nginx for a public domain/subdomain, public IP, or private IP. For public domain access, add A records for the Studio and processor domains pointing to the machine IP in your DNS provider. For public/private IP access, the wizard can detect IP candidates and uses one machine IP: Studio at http://<ip> and the processor/media base at http://<ip>/api. For production deployment, non-SSL access needs port 80; Let's Encrypt SSL setup uses ports 80 and 443, then closes port 80 if Samsar opened it. The wizard can try to manage these host firewall rules automatically on supported Linux hosts.
Set a strong setup/admin password first and restrict access with HTTPS, firewall rules, and authentication.
For custom enterprise deployments behind a VPS, private network, or managed ingress, contact hello@samsar.one.
Run the fast, dependency-free test suite:
npm testValidate the generated runtime files and full Docker Compose deployment configuration:
npm run test:deploymentGitHub Actions runs both checks for pull requests into main and pushes to main.
Caution
Do not commit runtime credentials, generated assets, local uploads, dependency folders, or build output.
A local Docker page fails on first navigation
If a local Docker page fails only on first navigation with a dynamic import error, the browser is usually holding an old frontend build while the container serves a newer build. Refresh the tab. The Docker client server also returns a reload module for missing hashed JS chunks so stale tabs can recover automatically.
Local downloads open in a new tab
Confirm the processor API can serve the mounted asset:
curl -I http://localhost:3002/assets_v2/video/output/<session-id>/<file>.mp4Remote generation providers cannot fetch local media
Open Local media URLs and remote-provider access, then inspect the Compose-managed tunnel lifecycle and current URL. Provider workers validate the exact asset and wait for a refreshed tunnel before dispatching.
Grafana runs on a remote Docker host
Set GRAFANA_ROOT_URL and optionally GRAFANA_DOMAIN, GRAFANA_PORT, or LOKI_PORT before starting Compose.