Narrative API

View llms.txt

The Narrative API creates reusable narrative structures without starting Samsar's image, audio, or video-generation stages. Generate a singular narrative from a prompt, then optionally expand that completed narrative into a binary tree of alternate paths.

• Base URL: https://api.samsar.one
• Canonical route prefix: /v2/external/narrative
• Auth: Authorization: Bearer <SAMSAR_API_KEY>
• Content-Type: application/json
• Execution: asynchronous; creation returns HTTP 202 and a request_id
• Concurrency: one narrative request is processed at a time per user
• Billing: actual underlying inference usage multiplied by 1.5x

Use this API when you need the same validated narrative structure that a text-to-video request would build during prompt generation, but want to decide separately how or whether to render it.

Workflow

1. Submit a narrative request and store the returned request_id.
2. Poll the request until its status is COMPLETED or FAILED.
3. On success, read themeJson, narrativeJson, and movieResourceList from the status response.
4. Optionally submit the completed singular request ID to create_branching and poll the new request ID for a branched resource tree.
5. When ready to render, submit either completed request ID to POST /v2/external/video/narrative_to_video.

Status reads are scoped to the authenticated user. Keep the same credentials for submission and polling. If the user submits another narrative while one is active, the additional accepted request remains PENDING until the active request reaches a terminal state.

Routes

Method	Route	Purpose
POST	/v2/external/narrative/create_single	Generate one validated narrative resource list from a prompt.
POST	/v2/external/narrative/create_branching	Expand a completed singular request into a validated binary narrative tree.
GET	/v2/external/narrative/status?request_id=...	Poll a narrative request.
POST	/v2/external/video/narrative_to_video	Render a completed singular or branched narrative without rerunning prompt generation.

See create_single to generate a singular resource list, create_branching to generate alternate paths, and Render a narrative as video to start the media pipeline from either result.

Returned artifacts

Field	Description
themeJson	The generated theme data used to guide the narrative.
narrativeJson	The validated narrative before final movie-resource enrichment.
movieResourceList	A linear stage-one structure for a singular request, or a complete node-based tree for a branched request.
branchingMeta	Branched requests only: compact branch-point, leaf, and node metadata for the generated tree.

These artifacts are stored on a standalone narrative request. Narrative creation does not create or modify a VideoSession, and it does not generate images, speech or audio files, music, or video. Both singular and branched results can later be rendered explicitly through POST /v2/external/video/narrative_to_video.

Authentication

A Samsar API key is recommended:

-H "Authorization: Bearer $SAMSAR_API_KEY"

The API also accepts a signed Samsar user auth token. Deployments using app credentials may authenticate with Authorization: AppKey <APP_KEY> and x-app-secret: <APP_SECRET>. Missing, expired, or invalid credentials are rejected before a request is created.

Metering

Narrative requests are usage-based. Samsar prices every inference response used to produce the terminal result at its underlying provider and model rate, sums those costs, and applies the 1.5x narrative multiplier once to the total.

For create_single, metered work includes theme generation, narrative generation, semantic validation or repair, retries, moderation inference when billable usage is returned, and any other inference call needed to produce the final linear movieResourceList. For create_branching, it includes every divergence-planning call, child-branch generation call, and validation retry across the entire tree. Calls completed before a failed request can still be charged because that provider usage was incurred.

A positive credit balance is required before new narrative inference begins. Once a request is accepted and inference has started, its exact incurred usage is settled in full. If the final charge is greater than the balance available at submission time, remaining_credits can be negative; add credits before submitting more narrative work.

Terminal status responses include a billing object. They also include x-credits-charged and x-credits-remaining response headers when those values are available.