SamsarOne developer platform

Build generative media workflows with one API

Create videos, transform images, generate speech and music, run inference, and publish results through hosted Samsar.js. Start with one Samsar API key, then explore supported deployment adapters when you need your own runtime.

Explore the model matrixStart with videoOpen Playground ↗

Base URLhttps://api.samsar.one/v1Bearer authentication

Choose a workflow

Each workflow starts with the hosted API. The interactive model matrix connects model keys to API contracts and compatible adapters; deployment adapters explains native and standalone options.

GenerateVideo APICreate, translate, join, reroll, and customize videos.TransformImage APIEnhance, edit, validate, and organize image assets.InferChat APIRun managed chat, moderation, and embedding workflows.AssistAssistant APIBuild session-aware, multimodal assistant experiences.StructureNarrative APICreate reusable singular or branching story structures.PlatformExternal usersGive your customers isolated credits, history, and access.SoundSpeech, music & transcriptsGenerate narration, backing tracks and effects; align transcripts.PerformLip sync & video soundCompare models for matching speech and adding sound to video.

Make your first request

Install the client in your server application:

npm install samsar-js

Hosted Samsar.js: discover models, then create a video

import SamsarClient from 'samsar-js';

const samsar = new SamsarClient({ apiKey: process.env.SAMSAR_API_KEY });
const models = await samsar.getSupportedTextToVideoModels();
console.log(models.data); // Check the available image and video selections.

const job = await samsar.createVideoFromText({
  prompt: 'A cinematic product reveal in a quiet gallery.',
  duration: 10,
  aspect_ratio: '16:9',
  image_model: 'GPTIMAGE2',
  video_model: 'RUNWAYML',
});
// Persist the ID; generation continues asynchronously.
console.log(job.data.request_id);

Follow the status contract to poll to completion or configure a webhook. To use a local deployment, see the adapter guide.

Prefer HTTP? Follow the equivalent request flow

1

Create an API key

Generate a key in Samsar Studio and keep it on your server. Never expose it in browser code.

2

Check express model availability

The video-generation allowlist can vary with the providers configured for a deployment.

List express models available to this deployment

curl "https://api.samsar.one/v1/video/supported_models"

3

Submit work and track usage

Send your key as a bearer token. Asynchronous generation routes return a request ID; poll the documented status route or provide a webhook.

Create a video

curl -X POST "https://api.samsar.one/v1/video/text_to_video" \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "A cinematic product reveal in a quiet gallery.",
      "duration": 10,
      "aspect_ratio": "16:9",
      "image_model": "GPTIMAGE2",
      "video_model": "RUNWAYML"
    }
  }'

Read credit headers

When an endpoint deducts credits, inspect x-credits-charged and x-credits-remaining. See Models & pricing for current rates and billing units.

Pick the right API surface

Surface	Use it when…	Base path
Core APIs	One Samsar account owns and submits the work.	/v1/video, /v1/image, /v1/chat, /v1/assistant
V2 API	One client needs a unified surface for internal and external-user actors.	/v2
External users	Your platform needs per-customer credits, history, and login state.	/v1/external_users
External requests	A deployment uses Samsar as a managed fallback provider.	/v2/external
Narrative API	You want story structure first and media rendering later.	/v2/external/narrative

Before you ship

• Keep API keys in server-side secrets.
• Store every asynchronous request_id before starting a polling loop.
• Reuse stable client request IDs where an endpoint supports idempotent retries.
• Query runtime model availability instead of hard-coding a deployment-wide assumption.
• Treat credit headers as the final billed amount; estimates can change with duration and optional stages.