Skip to main content

API Docs

Base URL​

Base URL: https://api.samsar.one/v1/video/

POST /create_movie
GET  /status

Authentication​

All requests must include an Authorization: Bearer {API_KEY} header.

For example:

Authorization: Bearer YOUR_ACTUAL_KEY_HERE

Get your API key from the settings in the dashboard.

If the API_KEY is missing, empty, or invalid, the server will respond with an error status:

  • 400 Bad Request if the API_KEY is missing or empty.
  • 401 Unauthorized if the API_KEY is invalid.

Endpoints​

POST /create_movie​

Creates a cinematic movie-generation session based on a single prompt. Pricing is calculated at 10 credits/second of generated video. For eg. a 60 second request would incur 600 credits. You need to sign-up for a Creator's plan to send API requests. Creator's plan comes with 5k credits/month.

Request Headers​

  • Authorization: Bearer {API_KEY}: String. (Required)

Request Body​

{
  "input": {
    "prompt": "string", 
    "aspect_ratio": "string",
    "image_model": "string",
    "video_model": "string",
    "duration": 30
  },
  "webhookUrl": "https://your-webhook-url.com"
}
FieldTypeRequiredDescription
promptstringYesThe text prompt for generating the movie. Cannot exceed 500 characters.
aspect_ratiostringNoDesired aspect ratio (e.g., "16:9" or "9:16").
image_modelstringYesImage model key (must be one of FLUX1.1PRO or IMAGEN3).
video_modelstringYesVideo model key. Options include:
- LUMA
- KLINGIMGTOVIDPRO
- PIXVERSEI2V
- WAN2.1
- VEOI2V (See pricing for VEOI2V)
Recommendations:
- For 9:16 aspect ratio: KLINGIMGTOVIDPRO, PIXVERSEI2V
- For 16:9 aspect ratio: Choose any model depending on cinematic style
durationnumberYesDuration in seconds. Must be a valid number ≤ 120.
webhookUrlstringNoIf provided, the system may send callbacks to this URL with status updates or final results.

Validation Rules​

  • prompt is required and cannot be empty or exceed 500 characters.
  • image_model must be among the recognized image-generation models and typically flagged isExpressModel: true.
  • video_model must be a valid model from the list.
  • duration must be a number and cannot exceed 120 seconds.
  • If any validations fail, returns a 400 Bad Request with an error message.

Response​

A 200 OK response with JSON:

{
  "request_id": "Request ID received as response from the /create_movie request"
}
  • request_id: A unique identifier for the movie-generation request. Use this ID to query status via the /status endpoint.

GET /status​

Retrieves the current status of a previously created session.

Request Headers​

  • Authorization: Bearer {API_KEY}: String. (Required)

Query Parameters​

  • request_id: Required. The unique ID you received from /create_movie.

Example request:

GET /status?request_id={requestId}

Response​

On success, returns HTTP 200 with a JSON structure:

{
  "status": "PENDING" | "COMPLETED" | "FAILED",
  "details": "Progress details array",
  "result": { 
    "url": "Remote download link" 
  }
}
  • status: A string indicating the request’s state (common values might be "PENDING", "COMPLETED", or "FAILED").
  • details: Task process details.
  • result: If status is "COMPLETED" then result will typically include: 
    {
      "status": "COMPLETED",
      "url": "Remote response URL"
    }

If request_id is missing, returns a 400 Bad Request:

{
  "message": "request_id query parameter is missing."
}

If an internal error occurs while fetching the status, returns a 500 Internal Server Error with an error message.

Common Errors​

  • 400 Bad Request
    Occurs if required fields are missing or invalid (e.g., missing prompt, exceeding length limits, invalid model keys, missing request_id query parameter).

  • 401 Unauthorized
    Occurs if the supplied API_KEY is invalid.

  • 500 Internal Server Error
    Occurs if an unexpected error happens on the server (e.g., database issue, unhandled exception).

Webhook Usage​

If you supply a webhookUrl in the request body (/create_movie), the server may send asynchronous callbacks (HTTP POST) to that URL with status updates. The exact payload of these callbacks is determined by your system’s implementation, but typically includes:

  • request_id (for correlating to your original request)
  • status
  • progress
  • (Once finished) a result payload with the final output or any relevant data

Ensure your webhook endpoint is accessible externally and can handle JSON POST requests.

Additional Notes​

  • You can also use the request_id to post-process your renditions in the Studio. Go to https://app.samsar.one/video/{requestId}
  • Always validate your input prior to calling these endpoints to avoid failed runs and wasted credits.
  • The request_id you receive can be used to poll /status or to match incoming webhook callbacks.
  • The valid models (image_model, video_model, etc.) are configured within the application (see IMAGE_GENERATION_MODEL_TYPES and VIDEO_GENERATION_MODEL_TYPES for examples). Some models may not be immediately supported or may require special permissions.

Last Updated: March 2, 2025