Video API

View llms.txt

Live testing

Try it in Playground

Video endpoints

Queue a sample video request with your API key and watch status updates without leaving the docs.

Open playground

• 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/reroll-layers bills the selected image-generation requests plus the selected layers' AI-video stage credits. /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
COSMOS3SUPERI2V (Nvidia Cosmos 3)	20	5, 10, 15
SEEDANCEI2V (Seedance 1.5)	30	5, 10
KLINGIMGTOVID3PRO	36	5, 10
KLINGIMGTOVIDTURBO	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
COSMOS3SUPERI2V	4	4	2	2	2	2	4	20
SEEDANCEI2V	4	4	2	2	2	2	14	30
KLINGIMGTOVID3PRO	4	4	2	2	2	2	20	36
KLINGIMGTOVIDTURBO	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.

Reroll layers formula credits = selected_layer_count × image_generation_price + selected_layer_duration_seconds × ai_video_stage_rate. Quote-only requests do not charge 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": "NanoBanana Pro", "value": "NANOBANANAPRO", "basePrice": 15 },
    { "label": "SEEDREAM", "value": "SEEDREAM", "basePrice": 15 }
  ],
  "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": "Nvidia Cosmos 3",
      "value": "COSMOS3SUPERI2V",
      "basePrice": 20,
      "pricingDistribution": {
        "pipeline": 4,
        "inference": 4,
        "image_gen_edit": 2,
        "speech": 2,
        "music": 2,
        "effects_and_lipsync": 2,
        "video": 4,
        "total": 20,
        "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": "KLINGIMGTOVIDTURBO",
      "value": "KLINGIMGTOVIDTURBO",
      "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.1 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 | NANOBANANAPRO | SEEDREAM",
    "video_model": "VEO3.1I2V | VEO3.1I2VFAST | COSMOS3SUPERI2V | SEEDANCEI2V | KLINGIMGTOVID3PRO | KLINGIMGTOVIDTURBO | 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",
    "backingtrack_model": "LYRIA3 | ELEVENLABS_MUSIC",
    "tts_model": "ELEVENLABS | OPENAI | GOOGLE",
    "speakerOptions": { "openAISpeakers": ["nova"] },
    "inference_model": "gpt-5.5 | gemini-3.1-pro",
    "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",
    "outro_cta_image": {
      "top_text": "Shop the drop",
      "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
      "bottom_text": "Limited availability"
    },
    "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.
• backingtrack_model optional; selects the express backing track generator. Use LYRIA3 for Google Lyria 3 Pro native music generation or ELEVENLABS_MUSIC for ElevenLabs Music. Compatibility aliases include backing_track_model, backingTrackModel, music_provider, and musicProvider; legacy LYRIA2 requests are treated as LYRIA3.
• tts_model optional; selects the speaker library used for text-to-speech assignment. Use ELEVENLABS, OPENAI, or GOOGLE. Compatibility aliases include ttsModel, tts_provider, and ttsProvider. When omitted, Samsar uses the default speaker assignment behavior.
• speakerOptions optional; compatibility alias: speaker_options. Use it with tts_model to constrain assignment to openAISpeakers, elevenLabsSpeakers, or googleSpeakers. When provided, request speaker options override account speaker settings for that request. Google TTS requests should include googleSpeakerDetails entries with value or voiceId, languageCode or languageCodes, and gender metadata such as Gender or ssmlGender.
• inference_model optional; selects the inference model used for render planning. Use gpt-5.5 for GPT 5.5 or gemini-3.1-pro for Gemini 3.1 Pro. Compatibility alias: inferenceModel. When omitted, Samsar uses the account default inference model.
• 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 either cta_url for a QR center image or outro_cta_image for a supplied center logo/CTA image. outro_cta_image uses { "top_text", "middle_image", "bottom_text" }; middle_image accepts a public URL ({ "url" }, { "image_url" }) or image data ({ "data_url" }, { "image_data", "mime_type" }). Top-level cta_text_top and cta_text_bottom remain supported for generated outros. 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).
• video_model_sub_type is not part of the request shape; describe style direction in prompt and tone.
• 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" }
      ]
    }
  }'

Sample request: generate CTA image outro with a center logo

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 launch teaser for a new product line",
      "duration": 20,
      "image_model": "GPTIMAGE2",
      "video_model": "RUNWAYML",
      "aspect_ratio": "9:16",
      "generate_outro_image": true,
      "outro_cta_image": {
        "top_text": "Shop the drop",
        "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
        "bottom_text": "Limited availability"
      }
    }
  }'

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, COSMOS3SUPERI2V, SEEDANCEI2V, KLINGIMGTOVID3PRO, KLINGIMGTOVIDTURBO, 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 | COSMOS3SUPERI2V | SEEDANCEI2V | KLINGIMGTOVID3PRO | KLINGIMGTOVIDTURBO | HAPPYHORSEI2V | RUNWAYML",
    "image_model": "GPTIMAGE2 | NANOBANANA2 | NANOBANANAPRO | SEEDREAM",
    "aspect_ratio": "16:9 | 9:16",
    "language": "auto | en | es | fr | de | pt | it | nl | sv | hi | ar | ru | ja | ko | th | zh",
    "backingtrack_model": "LYRIA3 | ELEVENLABS_MUSIC",
    "tts_model": "ELEVENLABS | OPENAI | GOOGLE",
    "speakerOptions": { "openAISpeakers": ["nova"] },
    "inference_model": "gpt-5.5 | gemini-3.1-pro",
    "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",
    "outro_cta_image": {
      "top_text": "Shop the drop",
      "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
      "bottom_text": "Limited availability"
    },
    "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, COSMOS3SUPERI2V, SEEDANCEI2V, KLINGIMGTOVID3PRO, KLINGIMGTOVIDTURBO, 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.
• backingtrack_model optional; selects the express backing track generator. Use LYRIA3 for Google Lyria 3 Pro native music generation or ELEVENLABS_MUSIC for ElevenLabs Music. Compatibility aliases include backing_track_model, backingTrackModel, music_provider, and musicProvider; legacy LYRIA2 requests are treated as LYRIA3.
• tts_model optional; selects the speaker library used for text-to-speech assignment. Use ELEVENLABS, OPENAI, or GOOGLE. Compatibility aliases include ttsModel, tts_provider, and ttsProvider. When omitted, Samsar uses the default speaker assignment behavior.
• speakerOptions optional; compatibility alias: speaker_options. Use it with tts_model to constrain assignment to openAISpeakers, elevenLabsSpeakers, or googleSpeakers. When provided, request speaker options override account speaker settings for that request. Google TTS requests should include googleSpeakerDetails entries with value or voiceId, languageCode or languageCodes, and gender metadata such as Gender or ssmlGender.
• inference_model optional; selects the inference model used for render planning. Use gpt-5.5 for GPT 5.5 or gemini-3.1-pro for Gemini 3.1 Pro. Compatibility alias: inferenceModel. When omitted, Samsar uses the account default inference model.
• 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 either cta_url for a QR center image or outro_cta_image for a supplied center logo/CTA image. outro_cta_image uses { "top_text", "middle_image", "bottom_text" }; middle_image accepts a public URL ({ "url" }, { "image_url" }) or image data ({ "data_url" }, { "image_data", "mime_type" }). Top-level cta_text_top and cta_text_bottom remain supported for generated outros. 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).
• video_model_sub_type is not part of the request shape; describe style direction in prompt.
• 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, COSMOS3SUPERI2V is 20 credits/sec, SEEDANCEI2V is 30 credits/sec, KLINGIMGTOVID3PRO is 36 credits/sec, KLINGIMGTOVIDTURBO 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: generate CTA image outro with a center logo

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": "Product launch teaser with a branded CTA outro",
      "video_model": "RUNWAYML",
      "aspect_ratio": "9:16",
      "generate_outro_image": true,
      "outro_cta_image": {
        "top_text": "Shop the drop",
        "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
        "bottom_text": "Limited availability"
      }
    },
    "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 CTA outros (generate_outro_image with cta_url for a QR center image or outro_cta_image for a supplied center logo/CTA image), 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, optional speakerOptions, optional inference_model, 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. Use a provided full outro image, or ask Samsar to generate the outro from existing session image layers with either a QR center image or supplied center logo/CTA 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"
}

• videoSessionId required; must belong to the API key.
• outro_image_url required unless generate_outro_image is true; URL (or data URL) for a full outro image.
• generate_outro_image optional boolean; when true, provide either cta_url or outro_cta_image and omit outro_image_url.
• cta_url optional for generated outro mode; when provided, it is converted into a scannable QR code in the center image area.
• outro_cta_image optional for generated outro mode; uses { "top_text", "middle_image", "bottom_text" } and places middle_image directly in the same center area used by QR outros, resized without changing aspect ratio.
• 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"
  }'

Sample request: add generated CTA image outro

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",
      "generate_outro_image": true,
      "outro_cta_image": {
        "top_text": "Shop the drop",
        "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
        "bottom_text": "Limited availability"
      }
    },
    "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 either cta_url or outro_cta_image, or provide cta_url / outro_cta_image without an outro_image_url. With cta_url, Samsar builds a QR-code outro. With outro_cta_image, Samsar places the supplied logo/CTA image in the same center area, resized without changing aspect ratio. In both cases it derives the focus area server-side and keeps optional top/bottom CTA text above the fade overlay.

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"
}

Generated CTA image outro request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "generate_outro_image": true,
    "outro_cta_image": {
      "top_text": "Shop the drop",
      "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
      "bottom_text": "Limited availability"
    }
  },
  "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 or outro_cta_image is required and outro_image_url must be omitted. If cta_url or outro_cta_image is provided without outro_image_url, generated CTA outro mode is inferred.
• cta_url optional for generated CTA outro mode; must be HTTP(S). It is converted into a scannable QR code.
• outro_cta_image optional for generated CTA outro mode; uses { "top_text", "middle_image", "bottom_text" }. middle_image accepts a public URL ({ "url" }, { "image_url" }) or image data ({ "data_url" }, { "image_data", "mime_type" }).
• 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 QR 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 generated center image 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.
• Supports the same provided-outro and generated CTA outro modes as /video/add_outro_image.
• Generated CTA outro mode accepts cta_url for a QR center image or outro_cta_image for a supplied center logo/CTA 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,
    "outro_cta_image": {
      "top_text": "Shop the drop",
      "middle_image": { "url": "https://cdn.example.com/drop-logo.png" },
      "bottom_text": "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 accepts cta_url for a QR center image or outro_cta_image for a supplied center logo/CTA image, then 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/reroll-layers

Reroll selected 1-based layers in an owned completed video session. The selected layers restart at image generation, then AI-video and lip-sync/sound-effect work runs as needed for those layers. Frame generation, generated outro tiles when present, and final video generation rerun for the whole session.

POST /v2/reroll-layers and POST /v2/video/reroll-layers expose the same operation on the V2 route surface.

Request body

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "layer_indexes": [3, 6, 11]
  },
  "webhookUrl": "https://example.com/webhook"
}

• videoSessionId required; must be a video session that belongs to the authenticated user and is not currently rendering.
• layer_indexes required; accepts positive 1-based layer indexes.
• The route updates the same session in place and does not clone the video.
• Quote-only requests with quote_only: true return the credit estimate without charging or queuing work.

Quote-only request

{
  "input": {
    "videoSessionId": "vid_a1b2c3d4",
    "layer_indexes": [3, 6],
    "quote_only": true
  }
}

Success response (200)

{
  "request_id": "vid_a1b2c3d4",
  "session_id": "vid_a1b2c3d4",
  "status": "PENDING",
  "layer_indexes": [3, 6, 11],
  "creditQuote": {
    "layerCount": 3,
    "totalCredits": 164,
    "imageCredits": 92,
    "aiVideoCredits": 72
  },
  "creditsCharged": 164
}

Error responses

• 400 invalid/missing fields, unsupported layer indexes, or missing image prompts
• 401 invalid API key
• 402 insufficient credits
• 404 session not found
• 409 session is currently rendering or paused

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.