Video API

Base URL: https://api.samsar.one/v1
Auth: Authorization: Bearer <API_KEY>
Content-Type: application/json
Webhooks are optional; otherwise poll GET /status?request_id=....
Credits are charged when a request is accepted; where available, responses include x-credits-charged and x-credits-remaining.

Pricing

Credits are charged when a request is accepted. Standard /video/text_to_video and /video/image_list_to_video express models are billed per rendered second by model. Image-list add_narrator_avatar adds an optional 4 credits/sec avatar generation stage, and image-list express_cta_generation adds an optional 1 credit/sec CTA text-generation stage. Video model keys outside the documented supported values are not supported as default route model values. /video/translate_video and /video/join_videos are billed at a flat 3 credits/sec based on the source/joined video duration. /video/add_outro_image, /video/update_outro_image, /video/update_footer_image, /external_users/add_outro_image, /external_users/update_outro_image, and /external_users/update_footer_image are billed at a flat 75 credits/request. /video/clone and /v2/video/clone do not charge additional credits.

`video_model`	Text-to-video credits/sec	Unit options (seconds)
`VEO3.1I2V`	60	`6`, `8`
`VEO3.1I2VFAST`	36	`6`, `8`
`SEEDANCEI2V` (Seedance 1.5)	30	`5`, `10`
`KLINGIMGTOVID3PRO`	36	`5`, `10`
`HAPPYHORSEI2V`	36	`5`, `10`, `15`
`RUNWAYML`	30	`5`, `10`

For each listed standard model, the per-second price is split into these components:

Component	Credits/sec
Pipeline	4
Inference	4
Image Gen / Edit	2
Speech	2
Music	2
Effects and lipsync	2
Video	Remainder by model

That gives this per-model distribution:

`video_model`	Pipeline	Inference	Image Gen / Edit	Speech	Music	Effects and lipsync	Video	Total
`VEO3.1I2V`	4	4	2	2	2	2	44	60
`VEO3.1I2VFAST`	4	4	2	2	2	2	20	36
`SEEDANCEI2V`	4	4	2	2	2	2	14	30
`KLINGIMGTOVID3PRO`	4	4	2	2	2	2	20	36
`HAPPYHORSEI2V`	4	4	2	2	2	2	20	36
`RUNWAYML`	4	4	2	2	2	2	14	30

Text-to-video formula credits = duration_seconds × model_rate

Image list to video formula credits = duration_seconds × model_rate, using the same model rates as the text-to-video table above. Add duration_seconds × 4 when add_narrator_avatar is true and duration_seconds × 1 when express_cta_generation is true.

Translate video formula credits = duration_seconds × 3

Join videos formula credits = duration_seconds × 3

Clone video POST /video/clone and POST /v2/video/clone currently do not charge additional credits.

Add outro image formula credits = 75

Update outro image formula credits = 75

Update footer image formula credits = 75

Remove subtitles POST /video/remove_subtitles currently does not charge additional credits.

Add subtitles POST /video/add_subtitles currently does not charge additional credits.

Cancel render POST /video/cancel_render currently does not charge additional credits.

Example: a 10-second RUNWAYML text-to-video render costs 300 credits.

GET /video/supported_models

Fetch the currently supported image_model and video_model keys for POST /video/text_to_video.

Request

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

Success response (200)

{
  "IMAGE_MODELS": [
    { "label": "GPTIMAGE2", "value": "GPTIMAGE2", "basePrice": 46 },
    { "label": "NANOBANANA2", "value": "NANOBANANA2", "basePrice": 23 },
    { "label": "SEEDREAM", "value": "SEEDREAM", "basePrice": 15 },
    { "label": "CUSTOM_TEXT_TO_IMAGE", "value": "CUSTOM_TEXT_TO_IMAGE", "basePrice": 10 }
  ],
  "VIDEO_MODELS": [
    {
      "label": "VEO3.1I2V",
      "value": "VEO3.1I2V",
      "basePrice": 60,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 44,
        "total": 60,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    },
    {
      "label": "VEO3.1I2VFAST",
      "value": "VEO3.1I2VFAST",
      "basePrice": 36,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 20,
        "total": 36,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    },
    {
      "label": "Seedance 1.5",
      "value": "SEEDANCEI2V",
      "basePrice": 30,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 14,
        "total": 30,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    },
    {
      "label": "KLINGIMGTOVID3PRO",
      "value": "KLINGIMGTOVID3PRO",
      "basePrice": 36,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 20,
        "total": 36,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    },
    {
      "label": "Happy Horse 1.0 I2V",
      "value": "HAPPYHORSEI2V",
      "basePrice": 36,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 20,
        "total": 36,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    },
    {
      "label": "RunwayML Gen 4.5",
      "value": "RUNWAYML",
      "basePrice": 30,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 14,
        "total": 30,
        "optionalAddons": {
          "express_cta_generation": 1
        }
      }
    }
  ]
}

IMAGE_MODELS and VIDEO_MODELS are generated from the server-side text-to-video allowlist.
Each standard priced item includes label (display text), value (request key), basePrice (lowest configured per-unit price for that model), and pricingDistribution in credits/sec. pricingDistribution.optionalAddons.express_cta_generation is the image-list express CTA surcharge in credits/sec. Custom image-to-video adapters are configured through the top-level custom model configuration, not as a standard VIDEO_MODELS item.
Use each item’s value directly as image_model and video_model in POST /video/text_to_video.
This endpoint does not require authentication.

POST /video/text_to_video

Submit a prompt-only request to start video generation. Webhooks are optional.

Request body

{
  "input": {
    "prompt": "Required text, max 1000 chars",
    "image_model": "GPTIMAGE2 | NANOBANANA2 | SEEDREAM | CUSTOM_TEXT_TO_IMAGE",
    "video_model": "VEO3.1I2V | VEO3.1I2VFAST | SEEDANCEI2V | KLINGIMGTOVID3PRO | HAPPYHORSEI2V | RUNWAYML",
    "duration": 30,
    "tone": "grounded | cinematic",
    "aspect_ratio": "16:9 | 9:16",
    "language": "auto | en | es | fr | de | pt | it | nl | sv | hi | ar | ru | ja | ko | th | zh",
    "enable_subtitles": true,
    "font_key": "Poppins",
    "outro_image_url": "https://cdn.example.com/outro.png",
    "generate_outro_image": false,
    "cta_url": "https://example.com/book",
    "cta_text_top": "Scan to book",
    "cta_text_bottom": "Limited availability",
    "cta_logo": "https://cdn.example.com/logo-white.png",
    "add_footer_animation": true,
    "footer_metadata": [
      { "url": "https://example.com/book", "title": "Book now" }
    ]
  },
  "webhookUrl": "https://example.com/webhook"
}

prompt, image_model, video_model, duration are required; duration ≤ 240 seconds.
language is optional; pass auto (default) or one of the listed language codes.
enable_subtitles optional; defaults to true. Set to false to skip subtitle generation entirely.
font_key optional; must be supported for the chosen language. It sets both subtitle and speaker fonts. Use GET /supported_fonts or /fonts to preview choices.
Provided outro image mode: set outro_image_url to append a custom outro frame. add_outro_animation is optional; when true, it applies a fade overlay during the outro. add_outro_focus_area requires add_outro_animation: true and a valid outro_focust_area.
Generated outro image mode: set generate_outro_image: true and provide cta_url. Samsar creates a QR-code outro image server-side from cta_url, optional cta_text_top, optional cta_text_bottom, and optional cta_logo. This mode automatically enables add_outro_animation, add_outro_focus_area, and computes outro_focust_area.
Footer QR mode: set add_footer_animation: true and provide footer_metadata with { "url", "title" } items. A single item is applied to every generated scene; multiple items map by generated scene index. The frame processor renders the bottom CTA section only on layers where this option is enabled.
Use only one outro mode in a request. If generate_outro_image is true, omit outro_image_url, add_outro_animation, add_outro_focus_area, and outro_focust_area because Samsar derives those values.
outro_focust_area / outro_focus_area values are { x, y, width, height } within the output canvas (16:9 is 1792x1024, 9:16 is 1024x1792).
Request bodies can be nested under input (recommended) or sent as a flat JSON payload.

Sample request

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 timelapse of clouds over a futuristic city at sunrise",
      "duration": 30,
      "image_model": "GPTIMAGE2",
      "video_model": "RUNWAYML",
      "tone": "grounded",
      "aspect_ratio": "16:9",
      "language": "en",
      "enable_subtitles": true,
      "font_key": "Poppins",
      "generate_outro_image": true,
      "cta_url": "https://example.com/tour",
      "cta_text_top": "Scan for the tour",
      "cta_text_bottom": "Book a demo",
      "add_footer_animation": true,
      "footer_metadata": [
        { "url": "https://example.com/tour", "title": "Book a demo" }
      ]
    }
  }'

Success response (200)

{
  "request_id": "vid_a1b2c3d4",
  "session_id": "vid_a1b2c3d4"
}

Error responses

400 invalid or missing fields (empty prompt, unsupported models, duration > 240, etc.)
401 invalid API key

POST /video/image_list_to_video

Create a video from an ordered list of images. Samsar builds a narrative from the images and optional metadata, then renders the video using VEO3.1I2V, VEO3.1I2VFAST, SEEDANCEI2V, KLINGIMGTOVID3PRO, HAPPYHORSEI2V, or RUNWAYML. If video_model is omitted, it defaults to RUNWAYML.

Request body

{
  "input": {
    "image_urls": [
      "https://cdn.example.com/frame1.png",
      "https://cdn.example.com/frame2.png"
    ],
    "prompt": "Optional high-level direction",
    "metadata": { "project": "launch_trailer" },
    "video_model": "VEO3.1I2V | VEO3.1I2VFAST | SEEDANCEI2V | KLINGIMGTOVID3PRO | HAPPYHORSEI2V | RUNWAYML",
    "aspect_ratio": "16:9 | 9:16",
    "language": "auto | en | es | fr | de | pt | it | nl | sv | hi | ar | ru | ja | ko | th | zh",
    "enable_subtitles": true,
    "font_key": "Poppins",
    "limit_single_narrator": false,
    "add_narrator_avatar": false,
    "generate_outro_image": false,
    "express_cta_generation": false,
    "cta_url": "https://example.com/book",
    "cta_text_top": "Scan to book",
    "cta_text_bottom": "Limited availability",
    "cta_logo": "https://cdn.example.com/logo-white.png",
    "add_footer_animation": false,
    "footer_metadata": [
      { "url": "https://example.com/blue-lagoon", "title": "Blue Lagoon Tour" }
    ]
  },
  "webhookUrl": "https://example.com/webhook"
}

image_urls required; non-empty array of URL strings or objects containing image_url, imageUrl, url, src, enhanced_url, or enhancedUrl. Object entries may also include title, image_text, activity_title, name, or label for narration context.
metadata optional plain object forwarded into the narrative builder.
prompt optional text used to guide pacing/tone.
video_model optional; supported values are VEO3.1I2V, VEO3.1I2VFAST, SEEDANCEI2V, KLINGIMGTOVID3PRO, HAPPYHORSEI2V, and RUNWAYML. Defaults to RUNWAYML.
aspect_ratio optional; supports 16:9 and 9:16. Omitted or unsupported values fall back to 16:9.
language optional; defaults to auto for detection.
enable_subtitles optional; defaults to true. Set to false to skip subtitle generation entirely.
font_key optional; must be supported for the chosen language. It sets both subtitle and speaker fonts.
limit_single_narrator optional boolean; defaults to false. When true, Samsar keeps all narration under one narrator identity.
add_narrator_avatar optional boolean; defaults to false. When true, Samsar automatically enables limit_single_narrator, generates an influencer-style human narrator avatar suitable for the image-list narrative, and overlays the avatar video bottom-center or centered in the footer row when footer metadata is present.
Provided outro image mode: set outro_image_url to append a custom outro frame. add_outro_animation is optional; when true, it applies a fade-to-black overlay during the outro. add_outro_focus_area requires add_outro_animation: true and a valid outro_focust_area.
Generated outro image mode: set generate_outro_image: true and provide cta_url. Samsar creates a QR-code outro image server-side from the input images, cta_url, optional cta_text_top, optional cta_text_bottom, and optional cta_logo. This mode automatically enables add_outro_animation, add_outro_focus_area, and computes outro_focust_area.
Footer QR mode: set add_footer_animation: true and provide footer_metadata with one { "url", "title" } item per image scene. Samsar generates one QR image per scene in the frame processor and renders a footer section on every frame with the title on the left and QR code on the right.
Express CTA generation mode: set express_cta_generation: true with one cta_url and omit cta_text_top, cta_text_bottom, and footer_metadata. Samsar generates concise per-scene footer CTA titles from the image scene payload and clean outro CTA text from the session context, then normalizes the request into the same generated-outro and footer payload shape before rendering. Compatibility aliases include expressCtaGeneration, auto_generate_cta_text, autoGenerateCtaText, generate_cta_texts, and generateCtaTexts.
Use only one outro mode in a request. If generate_outro_image or express_cta_generation is true, omit outro_image_url, add_outro_animation, add_outro_focus_area, and outro_focust_area because Samsar derives those values.
outro_focust_area / outro_focus_area values are { x, y, width, height } within the output canvas (16:9 is 1792x1024, 9:16 is 1024x1792).
Credits for standard express models are billed using the render duration that results from the provided images/metadata: VEO3.1I2V is 60 credits/sec, VEO3.1I2VFAST is 36 credits/sec, SEEDANCEI2V is 30 credits/sec, KLINGIMGTOVID3PRO is 36 credits/sec, HAPPYHORSEI2V is 36 credits/sec, and RUNWAYML is 30 credits/sec. Narrator avatar generation adds 4 credits/sec when add_narrator_avatar is true. Express CTA generation adds 1 credit/sec when express_cta_generation is true.

Sample request: provided outro image

curl -X POST https://api.samsar.one/v1/video/image_list_to_video \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image_urls": [
        "https://cdn.example.com/frame1.png",
        "https://cdn.example.com/frame2.png"
      ],
      "prompt": "Make this feel like a fast-paced teaser",
      "metadata": { "project": "launch_trailer" },
      "video_model": "KLINGIMGTOVID3PRO",
      "aspect_ratio": "16:9",
      "language": "en",
      "enable_subtitles": true,
      "font_key": "Poppins",
      "limit_single_narrator": true,
      "outro_image_url": "https://cdn.example.com/outro.png",
      "add_outro_animation": true,
      "add_outro_focus_area": true,
      "outro_focust_area": { "x": 240, "y": 140, "width": 720, "height": 420 }
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Sample request: generate QR outro image server-side

curl -X POST https://api.samsar.one/v1/video/image_list_to_video \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image_urls": [
        { "image_url": "https://cdn.example.com/frame1.png", "title": "Blue Lagoon Tour" },
        { "image_url": "https://cdn.example.com/frame2.png", "title": "Sunset Dinner" }
      ],
      "prompt": "Travel offer reel with a scannable booking outro",
      "metadata": { "project": "destination_campaign" },
      "video_model": "RUNWAYML",
      "aspect_ratio": "9:16",
      "language": "en",
      "enable_subtitles": true,
      "font_key": "Poppins",
      "add_narrator_avatar": true,
      "generate_outro_image": true,
      "cta_url": "https://example.com/book",
      "cta_text_top": "Scan to book",
      "cta_text_bottom": "Limited availability",
      "cta_logo": "https://cdn.example.com/logo-white.png",
      "add_footer_animation": true,
      "footer_metadata": [
        { "url": "https://example.com/blue-lagoon", "title": "Blue Lagoon Tour" },
        { "url": "https://example.com/sunset-dinner", "title": "Sunset Dinner" }
      ]
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Sample request: express CTA generation from one link

curl -X POST https://api.samsar.one/v1/video/image_list_to_video \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image_urls": [
        { "image_url": "https://cdn.example.com/frame1.png", "title": "Blue Lagoon Tour" },
        { "image_url": "https://cdn.example.com/frame2.png", "title": "Sunset Dinner" }
      ],
      "prompt": "Travel offer reel with concise scene CTAs",
      "metadata": { "brand": "Guidestination", "offer": "Bookable Bangkok experiences" },
      "video_model": "RUNWAYML",
      "aspect_ratio": "9:16",
      "language": "en",
      "enable_subtitles": true,
      "font_key": "Poppins",
      "express_cta_generation": true,
      "cta_url": "https://example.com/book"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_img_a1b2c3",
  "session_id": "vid_img_a1b2c3"
}

Error responses

400 invalid or missing image_urls.
401 invalid API key.

POST /external_users/text_to_video and /external_users/image_list_to_video

External-user video creation routes accept the same input parameters as /video/text_to_video and /video/image_list_to_video, including generated QR outros (generate_outro_image, cta_url, CTA text/logo fields), image-list express CTA generation (express_cta_generation with cta_url), provided outro images, footer QR sections (add_footer_animation, footer_metadata), subtitle/font options, and image-list video_model / aspect_ratio, limit_single_narrator, and add_narrator_avatar.

Wrap the request with an external_user object. Responses return an external request/session id; either the returned extreq_... id or the normalized external id can be used with /external_users/status, /external_users/add_outro_image, /external_users/update_outro_image, /external_users/update_footer_image, /external_users/translate_video, and /external_users/join_videos.

External user records store a stable unique_key. If unique_key is not provided, Samsar uses external_user_id as the key. V2 clients can create and later reference an external user through POST /v2/user/create_external_user.

Repeated video routes also perform server-side compatibility routing. If a main /video/* route receives an external request id, normalized external id, or external-owned upstream session id, it is processed through the external-user billing path. If an /external_users/* route receives a normal internal GlobalSession/video session id owned by the authenticated account and no external user context is supplied, it is processed through the internal billing path.

{
  "external_user": {
    "provider": "guidestination",
    "unique_key": "traveler_123",
    "external_user_id": "traveler_123"
  },
  "input": {
    "image_urls": [
      { "image_url": "https://cdn.example.com/frame1.png", "title": "Blue Lagoon Tour" }
    ],
    "video_model": "RUNWAYML",
    "generate_outro_image": true,
    "cta_url": "https://example.com/book",
    "add_footer_animation": true,
    "footer_metadata": [
      { "url": "https://example.com/book", "title": "Book now" }
    ]
  },
  "webhookUrl": "https://example.com/webhook"
}

POST /video/add_outro_image

Clone an existing session, then add or replace the outro image in the cloned session and queue frame/video generation.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "outro_image_url": "https://cdn.example.com/outro.png",
    "add_outro_animation": true,
    "add_outro_focus_area": true,
    "outro_focust_area": { "x": 240, "y": 140, "width": 720, "height": 420 }
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must belong to the API key.
outro_image_url required; URL (or data URL) for the outro image.
add_outro_animation optional boolean; when true, adds a fade-to-black overlay in the final outro layer.
add_outro_focus_area optional boolean; requires add_outro_animation and valid outro_focust_area.
outro_focust_area optional; { x, y, width, height }, validated against the session canvas.
Behavior:
- If the last layer is already the outro, it replaces that outro.
- If the last layer is not an outro, it appends a new outro layer.
- In both cases, a 0.5s fade-in transition of the outro image is applied to the end of the prior layer so it leads into the outro start frame.
Credits are billed at 75 credits per request.

Sample request

curl -X POST https://api.samsar.one/v1/video/add_outro_image \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4",
      "outro_image_url": "https://cdn.example.com/outro.png",
      "add_outro_animation": true,
      "add_outro_focus_area": true,
      "outro_focust_area": { "x": 240, "y": 140, "width": 720, "height": 420 }
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_outro_a1b2c3",
  "session_id": "vid_outro_a1b2c3"
}

Error responses

400 invalid or missing fields.
401 invalid API key.
402 insufficient credits.
404 session not found.

POST /video/update_outro_image

Clone an existing session that already has an outro layer, update that outro layer, and queue only the frame/video regeneration stages. This route does not rerun prompt, image, speech, music, or AI video generation.

Use one of two modes:

Provided outro image mode: pass outro_image_url (or outroImageUrl, new_outro_image_url, newOutroImageUrl) as an HTTP(S) URL or image data URL.
Generated CTA outro mode: pass generate_outro_image: true with cta_url, or provide cta_url without an outro_image_url. Samsar builds a QR-code outro from the existing session image layers, places the QR focus crop and optional CTA text above the fade overlay, and derives the focus area server-side.

Provided outro image request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "outro_image_url": "https://cdn.example.com/outro.png",
    "add_outro_animation": true,
    "add_outro_focus_area": true,
    "outro_focust_area": { "x": 240, "y": 140, "width": 720, "height": 420 }
  },
  "webhookUrl": "https://example.com/webhook"
}

Generated CTA outro request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "generate_outro_image": true,
    "cta_url": "https://example.com/book",
    "cta_text_top": "Scan to book",
    "cta_text_bottom": "Limited availability",
    "add_outro_animation": true
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must belong to the API key.
outro_image_url required unless generate_outro_image is true.
generate_outro_image optional boolean; when true, cta_url is required and outro_image_url must be omitted. If cta_url is provided without outro_image_url, generated CTA outro mode is inferred.
cta_url required for generated CTA outro mode; must be HTTP(S). It is converted into a scannable QR code.
cta_text_top optional; rendered near the top of the outro layer above the fade overlay.
cta_text_bottom optional; rendered near the bottom of the outro layer above the fade overlay.
cta_logo optional and accepted for compatibility with generated-outro requests.
add_outro_animation optional boolean. In generated CTA outro mode it defaults to true; when true, Samsar adds a black overlay that fades from 60% opacity to 0% while the QR focus crop and CTA text stay above it.
add_outro_focus_area optional for provided outro image mode; requires add_outro_animation and valid outro_focust_area. Generated CTA outro mode calculates the focus area server-side.
Credits are billed at 75 credits per request.

Sample request: update with generated CTA outro

curl -X POST https://api.samsar.one/v1/video/update_outro_image \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4",
      "generate_outro_image": true,
      "cta_url": "https://example.com/book",
      "cta_text_top": "Scan to book",
      "cta_text_bottom": "Limited availability"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_outro_update_a1b2c3",
  "session_id": "vid_outro_update_a1b2c3"
}

POST /video/update_footer_image

Clone an existing video session, update or remove the scene footer CTA, and queue only footer image creation when needed plus frame/video regeneration. This route does not rerun prompt, image, speech, music, or AI video generation.

Use remove_footer: true to remove the footer from all scenes in the cloned rerender. Otherwise provide at least one CTA field and Samsar applies the same minimal footer layout to each scene.

Update footer request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "cta_text": "Scan to book",
    "cta_logo": "https://cdn.example.com/logo-white.png",
    "cta_url": "https://example.com/book"
  },
  "webhookUrl": "https://example.com/webhook"
}

Remove footer request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "remove_footer": true
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must belong to the API key.
remove_footer optional boolean; defaults to false. When true, cta_text, cta_logo, and cta_url are ignored and all scene footer metadata is cleared.
cta_text optional string; rendered in the bottom-left footer area.
cta_logo optional HTTP(S) URL or image data URL; rendered below the CTA text in the bottom-left footer area.
cta_url optional HTTP(S) URL; converted into a scannable QR code on the right side of the footer.
At least one of cta_text, cta_logo, or cta_url is required unless remove_footer is true.
Credits are billed at 75 credits per request.

Sample request

curl -X POST https://api.samsar.one/v1/video/update_footer_image \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4",
      "cta_text": "Scan to book",
      "cta_logo": "https://cdn.example.com/logo-white.png",
      "cta_url": "https://example.com/book"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_footer_update_a1b2c3",
  "session_id": "vid_footer_update_a1b2c3"
}

POST /external_users/add_outro_image

External-user equivalent of /video/add_outro_image. Pass the external user identity and an external request/session id such as extreq_df04419ab0cf426e9b30891da71a9293; Samsar resolves it to the upstream video session, charges the external user's credits, clones the session, and queues only frame/video regeneration.

Request body

{
  "external_user": {
    "provider": "guidestination",
    "external_user_id": "traveler_123"
  },
  "input": {
    "request_id": "extreq_df04419ab0cf426e9b30891da71a9293",
    "outro_image_url": "https://cdn.example.com/outro.png",
    "add_outro_animation": true,
    "add_outro_focus_area": true,
    "outro_focust_area": { "x": 240, "y": 140, "width": 720, "height": 420 }
  },
  "webhookUrl": "https://example.com/webhook"
}

request_id / session_id required; use the external request id returned by /external_users/text_to_video or /external_users/image_list_to_video.
outro_image_url required; URL or data URL for the outro image.
add_outro_animation, add_outro_focus_area, and outro_focust_area match /video/add_outro_image.
Credits are billed at 75 credits per request against the external user.

POST /external_users/update_outro_image

External-user equivalent of /video/update_outro_image. Use this endpoint when the source video was created through /external_users/text_to_video or /external_users/image_list_to_video; pass either the returned extreq_... id or the normalized external id.

Generated CTA outro request body

{
  "external_user": {
    "provider": "guidestination",
    "external_user_id": "traveler_123"
  },
  "input": {
    "request_id": "extreq_df04419ab0cf426e9b30891da71a9293",
    "generate_outro_image": true,
    "cta_url": "https://example.com/book",
    "cta_text_top": "Scan to book",
    "cta_text_bottom": "Limited availability",
    "add_outro_animation": true
  },
  "webhookUrl": "https://example.com/webhook"
}

request_id / session_id required; use the external request id returned by an external-user video route.
Supports the same provided-outro and generated CTA outro modes as /video/update_outro_image.
Generated CTA outro mode derives add_outro_focus_area and outro_focust_area server-side.
Credits are billed at 75 credits per request against the external user.

Success response (200)

{
  "request_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "session_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "external_request_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "status_endpoint": "/v1/external_users/status?request_id=extreq_9b30891da71a9293df04419ab0cf426e",
  "creditsCharged": 75
}

POST /external_users/update_footer_image

External-user equivalent of /video/update_footer_image. Use this endpoint when the source video was created through /external_users/text_to_video or /external_users/image_list_to_video; pass either the returned extreq_... id or the normalized external id.

Request body

{
  "external_user": {
    "provider": "guidestination",
    "external_user_id": "traveler_123"
  },
  "input": {
    "request_id": "extreq_df04419ab0cf426e9b30891da71a9293",
    "cta_text": "Scan to book",
    "cta_logo": "https://cdn.example.com/logo-white.png",
    "cta_url": "https://example.com/book"
  },
  "webhookUrl": "https://example.com/webhook"
}

request_id / session_id required; use the external request id returned by an external-user video route.
Supports the same remove_footer, cta_text, cta_logo, and cta_url fields as /video/update_footer_image.
Credits are billed at 75 credits per request against the external user.

Success response (200)

{
  "request_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "session_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "external_request_id": "extreq_9b30891da71a9293df04419ab0cf426e",
  "status_endpoint": "/v1/external_users/status?request_id=extreq_9b30891da71a9293df04419ab0cf426e",
  "creditsCharged": 75
}

POST /video/clone

Deep-copy a completed video session into a new session and queue only the final video render stage. Use this when you need a distinct session id and a distinct rendered video URL, but the same timeline, resources, audio, overlays, subtitle settings, footer/outro metadata, and generated assets.

POST /v2/video/clone exposes the same operation on the V2 route surface.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4"
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must be a completed video session that belongs to the authenticated user.
The clone copies the source session data and local generated resources into the new session.
Upstream generation stages are marked complete; only video_generation is queued so the renderer creates a new video/output/video-<new_session_id>_*.mp4 file and new CDN URL.
This endpoint currently does not charge additional credits.

Sample request

curl -X POST https://api.samsar.one/v1/video/clone \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_clone_a1b2c3",
  "session_id": "vid_clone_a1b2c3",
  "status": "PENDING",
  "type": "video",
  "creditsCharged": 0
}

Poll GET /status?request_id=<new_session_id> or GET /v2/status?request_id=<new_session_id> until the standard video status response returns status: "COMPLETED" with result_url, result_urls, has_subtitles, and result_language.

Error responses

400 invalid/missing fields or source session has no completed video URL
401 invalid API key
404 session not found

POST /video/translate_video

Translate an existing video session into a new language. This creates a new session and runs only the required stages (speech translation, lip sync, optional transcription, final render) to produce a translated video.

POST /video/retranslate_video is available as an alias for the same operation.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "language": "en | es | fr | ja | th | zh | bn | hi | sa | la",
    "enable_subtitles": false,
    "translate_outro": true,
    "translate_footer": true
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must be a video session that belongs to the API key.
language required; pass a supported language code.
enable_subtitles optional boolean; defaults to false. When true, Samsar generates translated transcript/subtitle text for the cloned session.
translate_outro optional boolean; defaults to true. When enabled, stored generated-outro top and bottom CTA text are translated and reused in the cloned outro.
translate_footer optional boolean; defaults to true. When enabled, stored footer CTA text is translated per footer-enabled layer and reused in the cloned footer overlay.
outro_image_url is no longer part of the translate payload. Use POST /video/update_outro_image before or after translation when the outro image itself needs to change.
Credits are billed at 3 credits/sec using the duration of the source session.

Sample request

curl -X POST https://api.samsar.one/v1/video/translate_video \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4",
      "language": "es",
      "enable_subtitles": false,
      "translate_outro": true,
      "translate_footer": true
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_tr_a1b2c3",
  "session_id": "vid_tr_a1b2c3"
}

Error responses

400 invalid/missing fields (unknown session id, unsupported language, etc.)
401 invalid API key
402 insufficient credits

POST /video/join_videos

Join multiple completed video sessions into a single session by appending their timelines in order. This creates a new session and queues transcription, frame generation, and final render to produce the joined video.

Request body

{
  "input": {
    "session_ids": ["vid_a1b2c3d4", "vid_e5f6g7h8"],
    "blend_scenes": true
  },
  "webhookUrl": "https://example.com/webhook"
}

session_ids required; array of 2+ unique video session ids.
blend_scenes optional boolean (default false). When true, joins apply scene-boundary blending: previous outro image is carried into the next scene with a 1s fade-out, and background music layers are adjusted around boundaries (+0.5s) for smoother transitions.
All sessions must belong to the API key, and must have the same aspect_ratio and framesPerSecond.
Credits are billed at 3 credits/sec using the joined duration (sum of session durations).

Sample request

curl -X POST https://api.samsar.one/v1/video/join_videos \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "session_ids": ["vid_a1b2c3d4", "vid_e5f6g7h8"],
      "blend_scenes": true
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_join_a1b2c3",
  "session_id": "vid_join_a1b2c3"
}

Error responses

400 invalid/missing fields (unknown session id, incompatible sessions, etc.)
401 invalid API key
402 insufficient credits
404 one or more sessions not found

POST /video/remove_subtitles

Clone an existing session, remove all subtitle/transcript text overlays (type: "text" items in layer activeItemList), and queue only frame + video generation for the new session.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4"
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must be a video session that belongs to the API key.
Creates a new session_id; the source session remains unchanged.
The cloned session is configured to skip transcription and other generation stages, and run only frame/video generation.
This endpoint currently does not charge additional credits.

Sample request

curl -X POST https://api.samsar.one/v1/video/remove_subtitles \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_nosub_a1b2c3",
  "session_id": "vid_nosub_a1b2c3"
}

Error responses

400 invalid/missing fields (invalid session id format, missing session id, etc.)
401 invalid API key
404 session not found

POST /video/add_subtitles

Clone an existing session, add subtitle/transcript text overlays, and queue the stages required to produce a subtitled video in a new session.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4"
  },
  "webhookUrl": "https://example.com/webhook"
}

videoSessionId required; must be a video session that belongs to the API key.
Creates a new session_id; the source session remains unchanged.
The cloned session is saved with has_subtitles: true and preserves the session language/aspect ratio.
This endpoint currently does not charge additional credits.

Sample request

curl -X POST https://api.samsar.one/v1/video/add_subtitles \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4"
    },
    "webhookUrl": "https://example.com/video-webhook"
  }'

Success response (200)

{
  "request_id": "vid_sub_a1b2c3",
  "session_id": "vid_sub_a1b2c3"
}

Error responses

400 invalid/missing fields (invalid session id format, missing session id, etc.)
401 invalid API key
404 session not found

POST /video/cancel_render

Cancel an in-progress render for an existing session. This sets the session to a cancelled state and stops queued render tasks for that session.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4"
  }
}

videoSessionId required; must belong to the API key.
This endpoint does not create a new session.
This endpoint currently does not charge additional credits.

Sample request

curl -X POST https://api.samsar.one/v1/video/cancel_render \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "videoSessionId": "vid_a1b2c3d4"
    }
  }'

Success response (200)

{
  "request_id": "vid_a1b2c3d4",
  "session_id": "vid_a1b2c3d4",
  "status": "CANCELLED",
  "cancelled": true,
  "message": "Render cancellation requested."
}

Error responses

400 invalid/missing session id
401 invalid API key
404 session not found

GET /video/fetch_latest_version

Fetch the latest available render URL for a given video session_id.

Request

curl "https://api.samsar.one/v1/video/fetch_latest_version?session_id=vid_a1b2c3d4" \
  -H "Authorization: Bearer $SAMSAR_API_KEY"

Completed (200)

{
  "session_id": "vid_a1b2c3d4",
  "result_url": "https://cdn.samsar.one/videos/vid_a1b2c3d4.mp4",
  "has_subtitles": true,
  "result_language": "en"
}

has_subtitles is true, false, or null when subtitle state is unknown for older sessions.
result_language is the language code saved on the video session.

Pending (202)

{
  "session_id": "vid_a1b2c3d4",
  "status": "PENDING",
  "message": "Render not ready yet."
}

Failed (200)

{
  "session_id": "vid_a1b2c3d4",
  "status": "FAILED",
  "message": "Video generation failed."
}

Cancelled (200)

{
  "session_id": "vid_a1b2c3d4",
  "status": "CANCELLED",
  "message": "Render was cancelled."
}

Error responses

400 missing/invalid session_id
401 invalid API key
403 session does not belong to the API key
404 session not found

GET /video/list_completed_video_sessions

List completed video sessions for the authenticated API key, including each session language and final URL.

Request

curl "https://api.samsar.one/v1/video/list_completed_video_sessions" \
  -H "Authorization: Bearer $SAMSAR_API_KEY"

Optional query params:

limit (number): maximum number of sessions to return (server-capped to 5000).

Success response (200)

[
  {
    "session_id": "vid_a1b2c3d4",
    "langauge": "en",
    "result_language": "en",
    "has_subtitles": true,
    "result_url": "https://static.samsar.one/video/vid_a1b2c3d4/final.mp4"
  },
  {
    "session_id": "vid_e5f6g7h8",
    "langauge": "es",
    "result_language": "es",
    "has_subtitles": false,
    "result_url": "https://static.samsar.one/video/vid_e5f6g7h8/final.mp4"
  }
]

Returns only sessions that have a final video URL available.
langauge is returned as a normalized language code (lowercase).
result_language is the same normalized language code returned with the corrected field name.
has_subtitles is true, false, or null when subtitle state is unknown for older sessions.

Error responses

400 missing API key/auth header
401 invalid API key

GET /status

Poll the status for any request_id returned by the video endpoints (or /image/* endpoints).

Request

curl "https://api.samsar.one/v1/status?request_id=vid_a1b2c3d4" \
  -H "Authorization: Bearer $SAMSAR_API_KEY"

Queued / processing

{
  "session_id": "vid_a1b2c3d4",
  "request_id": "vid_a1b2c3d4",
  "status": "PENDING",
  "type": "video",
  "provider": "RUNWAYML",
  "expressGenerationStatus": {
    "prompt_generation": "PENDING",
    "video_generation": "IN_PROGRESS"
  }
}

Completed

{
  "session_id": "vid_a1b2c3d4",
  "request_id": "vid_a1b2c3d4",
  "status": "COMPLETED",
  "type": "video",
  "provider": "RUNWAYML",
  "result_url": "https://cdn.samsar.one/videos/vid_a1b2c3d4.mp4",
  "result_urls": [
    "https://cdn.samsar.one/videos/vid_a1b2c3d4.mp4"
  ],
  "has_subtitles": true,
  "result_language": "en",
  "videoLink": "https://cdn.samsar.one/videos/vid_a1b2c3d4.mp4",
  "remoteURL": "https://cdn.samsar.one/videos/vid_a1b2c3d4.mp4"
}

result_urls may be present when multiple assets are produced; videoLink or remoteURL can also contain the download URL.
Completed video responses include has_subtitles and result_language when session metadata is available.
expressGenerationStatus is present while individual stages are running; expressGenerationError/message is present on failure.
404 is returned when the request_id is unknown; 401 when the API key is invalid.

GET /supported_fonts

Fetch the supported subtitle fonts by language code. Use this to validate font_key or text overlay choices before submitting video requests. This endpoint does not require authentication.

Request

curl "https://api.samsar.one/v1/supported_fonts"

Success response (200)

{
  "fontsByLanguage": {
    "default": ["Rampart One", "Montserrat", "Arial", "sans-serif"],
    "en": ["Poppins", "Montserrat", "Arial", "sans-serif"],
    "ja": ["Noto Sans JP", "M PLUS Rounded 1c", "Hiragino Sans", "Yu Gothic UI", "sans-serif"],
    "ko": ["Noto Sans KR", "Pretendard", "Apple SD Gothic Neo", "Malgun Gothic", "sans-serif"]
  }
}

default is used when a language code has no explicit mapping.
Font previews: visit /fonts for light/dark samples with keys.

V2 API

The /v2 omni routes now live in V2 API, with left-nav sections for authentication, user credits, app keys, media generation, assistant utilities, status, and publishing routes.

Pricing​

GET /video/supported_models​

POST /video/text_to_video​

POST /video/image_list_to_video​

POST /external_users/text_to_video and /external_users/image_list_to_video​

POST /video/add_outro_image​

POST /video/update_outro_image​

POST /video/update_footer_image​

POST /external_users/add_outro_image​

POST /external_users/update_outro_image​

POST /external_users/update_footer_image​

POST /video/clone​

POST /video/translate_video​

POST /video/join_videos​

POST /video/remove_subtitles​

POST /video/add_subtitles​

POST /video/cancel_render​

GET /video/fetch_latest_version​

GET /video/list_completed_video_sessions​

GET /status​

GET /supported_fonts​

V2 API​

Pricing

GET /video/supported_models

POST /video/text_to_video

POST /video/image_list_to_video

POST /external_users/text_to_video and /external_users/image_list_to_video

POST /video/add_outro_image

POST /video/update_outro_image

POST /video/update_footer_image

POST /external_users/add_outro_image

POST /external_users/update_outro_image

POST /external_users/update_footer_image

POST /video/clone

POST /video/translate_video

POST /video/join_videos

POST /video/remove_subtitles

POST /video/add_subtitles

POST /video/cancel_render

GET /video/fetch_latest_version

GET /video/list_completed_video_sessions

GET /status

GET /supported_fonts

V2 API