Setup Open API Key/Secret

Visla provides an API key and secret for secure access to the OpenAPI. These credentials must be included in your API request headers using an encrypted format. For detailed authentication and encryption guidelines, see authenticated interactions

Video Creation Methods

Visla’s OpenAPI supports multiple ways to create videos depending on your input type — webpage, text script, or document.

Webpage to Video

Provide a webpage URL in your request, and Visla will automatically extract the content and generate a video. This is the simplest way to create videos directly from online articles or landing pages. For full request and response details, see webpage to video

Script to Video

Submit your own text script to generate a video. Visla uses your provided text as narration and visual guidance to create a cohesive video automatically. For full request and response details, see script to video

Document to Video

For document-based video creation, the process involves three steps:

Get Upload URL

The first step is to obtain a pre-signed URL for file upload. This URL will be used to securely upload your document file to S3.

Parameters:
- mediaType: Document type ("pdf" or "ppt")
- suffix: File extension ("pdf", "pptx", "ppt")
Purpose: Generate a secure, temporary URL for file upload
Response: Returns upload URL and asset ID

Upload File to S3

Once you have the upload URL, you must upload your document file directly to S3 using HTTP PUT method

Method: HTTP PUT
URL: Use the exact uploadUrl from step 1 response
Headers:
- Content-Type: Set appropriate MIME type (application/octet-stream, application/pdf, application/vnd.ms-powerpoint, etc.)
- Do NOT include authentication headers for S3 upload
Body: Raw binary file data
Timeout: Complete upload within 10 minutes (URL expires after 600 seconds)
Security: Uses pre-signed URL for secure, time-limited access

# Correct way to upload to S3

with open("document.pdf", "rb") as file:
    response = requests.put(
        upload_url,  # URL from step 1
        data=file.read(),  # Raw binary data
        headers={
            "Content-Type": "application/octet-stream"
        }
    )
    
if response.status_code == 200:
    print("Upload successful")
else:
    print(f"Upload failed: {response.status_code}")

File Constraints

PDF: 100MB file size
PPTX: 100MB file size
Supported formats: PDF, PPTX, PPT

Create Video from Document

The third step creates a video project using the uploaded document URL

doc_usage options

page_by_page_walkthrough (default)
- Equivalent to: Visla AI agent "Present Your Visuals".
- Scenes: One scene per page. The target video duration is determined by the number of pages and user-defined pacing.
- Narration: AI explains each page based on its visuals and text content.
- Footage: The page image only (no stock footage).
content_source
- Equivalent to: Visla AI agent "Convert Text to Video".
- Scenes: AI composes scenes based on user-defined target video’s duration and pacing.
- Narration: Document text is the content source for the voiceover script.
- Footage: Mix of relevant page images and stock footage.

📘
PPT override: For .ppt / .pptx files, page_by_page_walkthrough is always applied. Any value provided for doc_usage is ignored.

speaker_notes_verbatim

If the input source is a PowerPoint (PPT) file and speaker notes are provided, the notes will be read verbatim in the video narration. Default is false.

Key Workflow Steps

Step	Endpoint	Purpose	Wait Time
1	`GET /openapi/v1/project/get-asset-upload-url`	Get S3 upload URL	Instant
2	`PUT {uploadUrl}`	Upload PDF to S3	10s–2min
3	`POST /openapi/v1/project/doc-to-video`	Create project & wait for editing status	2–10min
4	`POST /openapi/v1/project/{projectUuid}/export-video`	Export video	Async via webhook

📘
video_duration_in_seconds applies to create video from script, webpage and doc when doc_usage = content_source. In other modes (e.g., page_by_page_walkthrough), it may be ignored and the system will choose the length.

Video Status Lifecycle

Understanding the project status is crucial for successful integration:

Status	Description	Next Action
`init`	Project created; initial setup in progress. AI is analyzing document content.	Wait (typically 1–2 minutes)
`preparation`	Basic configuration is being set (sound, avatar, subtitles, etc.) and initial video generation begins.	Wait while video is generated (typically 3–10 minutes)
`generated_videos`	Video content is being created.	Wait 5–15 minutes
`editing`	Project is ready for preview.	Proceed with editing or exporting
`error`	The process failed.

After creating a video project, the Get Project Info API should be called repeatedly in a loop to check the project’s status. Once the status shows editing, it indicates that the project has finished being created and is ready for further actions.

Clip Status Lifecycle

After exporting a project, monitoring the clip status lifecycle ensures you know exactly when the video is ready for use:

Status	Description	Typical Use Case
`init`	Clip just created; initial setup in progress	Immediately after export request
`downloading`	Downloading source content	Processing remote assets
`uploading`	Uploading to storage	File transfer in progress
`processing`	Video processing in progress	Encoding, compression, etc.
`publishing`	Finalizing and publishing	Making clip available
`completed`	Clip ready for download or viewing	Fully processed and available
`failed`	Processing failed	An error occurred during processing

Once a project is exported to a clip, the clip goes through a series of statuses that reflect its progress. The Get Clip Info API should be called repeatedly to monitor these statuses. The lifecycle ends when the status reaches completed, indicating that the video is fully processed and ready for use.