API Endpoints
1. Generate shorts from video
API Documentation
This API allows you to transform videos into multiple short clips (shorts), manage generated shorts, and export projects with specific styling presets. Below is the detailed documentation for each endpoint, including request payloads and return values.
Endpoints
1. Generate Shorts from Video
Endpoint
POST /tasks/video-to-shorts
Description
Transforms a source video into multiple short clips based on specified options.
Request Payload Schema
- source_video_url
(string, required)
: The URL of the video to be processed. - language
(string, optional)
: The language of the source video. - translate_to
(string, optional)
: The target language for translation. - name
(string, optional, default: "Upload")
: A name for the upload. - target_clip_count
(integer, optional, default: 10)
: The desired number of clips to generate. - max_clip_count
(integer, optional, default: 10)
: The maximum number of clips that can be generated. - editing_options
(object, optional)
: Options for editing the video (see Editing Options Schema). - dimensions
(object, optional)
: The dimensions for the generated clips (see Dimensions Schema). - style_preset_id
(string, optional)
: An optional style preset identifier. - min_duration
(integer, optional, default: 1, range: 1-120)
: Minimum duration for the clips in seconds. - max_duration
(integer, optional, default: 180, range: 1-180)
: Maximum duration for the clips in seconds. - target_duration
(integer, optional, default: 60, range: 1-120)
: Target duration for the clips in seconds.
Editing Options Schema
- captions
(boolean, optional, default: true)
: Include captions in the shorts. - reframe
(boolean, optional, default: true)
: Reframe the video content. - emojis
(boolean, optional, default: true)
: Include emojis in the shorts. - remove_silences
(boolean, optional, default: false)
: Remove silences from the video.
Dimensions Schema
- width
(integer, optional, default: 1080)
: The width of the clips. - height
(integer, optional, default: 1920)
: The height of the clips.
Example Request Payload
{
"source_video_url": "https://example.com/videos/source.mp4",
"language": "en",
"translate_to": "es",
"name": "My Video",
"target_clip_count": 5,
"max_clip_count": 10,
"editing_options": {
"captions": true,
"reframe": true,
"emojis": false,
"remove_silences": true
},
"dimensions": {
"width": 720,
"height": 1280
},
"style_preset_id": "preset123",
"min_duration": 15,
"max_duration": 60,
"target_duration": 30
}
Return Value
A Task Object representing the created task.
Example Response
{
"id": "task_001",
"type": "video_to_shorts",
"status": "pending",
"created_at": "2023-10-01T12:00:00Z",
"output_type": "project",
"output_id": "project_001"
}
2. Get Status of Task
Endpoint
GET /tasks/:task_id
Description
Retrieves the status of a specific task.
URL Parameters
- task_id
(string)
: The ID of the task.
Return Value
A Task Object with the current status of the task.
Example Response
{
"id": "task_001",
"type": "video_to_shorts",
"status": "completed",
"created_at": "2023-10-01T12:00:00Z",
"output_type": "project",
"output_id": "project_001"
}
3. List Generated Shorts
Endpoint
GET /projects/:folder_id
Description
Lists all generated shorts (projects) within a specified folder.
URL Parameters
- folder_id
(string)
: The ID of the folder containing the projects.
Return Value
An array of Project Objects.
Example Response
[
{
"id": "project_001",
"author_id": "user_123",
"folder_id": "folder_001",
"name": "My Video",
"created_at": "2023-10-01T12:05:00Z",
"virality_score": 0.85,
"virality_score_explanation": "High engagement predicted."
},
{
"id": "project_002",
"author_id": "user_123",
"folder_id": "folder_001",
"name": "Another Video",
"created_at": "2023-10-02T08:30:00Z",
"virality_score": 0.75,
"virality_score_explanation": "Moderate engagement predicted."
}
]
4. Export a Project
Endpoint
POST /projects/:folder_id/:project_id/exports
Description
Exports a project using a specified styling preset.
URL Parameters
- folder_id
(string)
: The ID of the folder containing the project. - project_id
(string)
: The ID of the project to export.
Payload Fields
- preset_id
(string, required)
: The ID of the styling preset to use for the export.
Example Request Payload
{
"preset_id": "preset123"
}
Return Value
An Export Object representing the export task.
Example Response
{
"id": "export_001",
"status": "pending",
"src_url": null,
"project_id": "project_001",
"created_at": "2023-10-02T09:00:00Z",
"finished_at": null,
"name": "Exported Video",
"author_id": "user_123",
"folder_id": "folder_001",
"descriptions": "Exporting project with preset preset123."
}
5. Get Project Export Status
Endpoint
GET /projects/:folder_id/:project_id/exports/:export_id
Description
Retrieves the status of a specific project export.
URL Parameters
- folder_id
(string)
: The ID of the folder containing the project. - project_id
(string)
: The ID of the project. - export_id
(string)
: The ID of the export task.
Return Value
An Export Object with the current status of the export.
Example Response
{
"id": "export_001",
"status": "completed",
"src_url": "https://example.com/exports/export_001.mp4",
"project_id": "project_001",
"created_at": "2023-10-02T09:00:00Z",
"finished_at": "2023-10-02T09:15:00Z",
"name": "Exported Video",
"author_id": "user_123",
"folder_id": "folder_001",
"descriptions": "Export completed successfully."
}
Data Object Definitions
Task Object
Represents a processing task.
Fields
- id
(string)
: Unique identifier of the task. - type
(string)
: Type of task (e.g.,"video_to_shorts"
). - status
(string)
: Current status of the task (e.g.,"pending"
,"in_progress"
,"completed"
,"failed"
). - created_at
(string, ISO 8601 datetime)
: Timestamp when the task was created. - output_type
(string)
: Type of output generated (e.g.,"project"
). - output_id
(string)
: Identifier of the output resource (e.g., project ID).
Project Object
Represents a project containing generated shorts.
Fields
- id
(string)
: Unique identifier of the project. - author_id
(string)
: ID of the user who created the project. - folder_id
(string)
: ID of the folder containing the project. - name
(string)
: Name of the project. - created_at
(string, ISO 8601 datetime)
: Timestamp when the project was created. - virality_score
(number)
: Predicted virality score of the project (range: 0 to 1). - virality_score_explanation
(string)
: Explanation of the virality score.
Export Object
Represents an export task for a project.
Fields
- id
(string)
: Unique identifier of the export task. - status
(string)
: Current status of the export (e.g.,"pending"
,"in_progress"
,"completed"
,"failed"
). - src_url
(string or null)
: URL of the exported file.null
until the export is completed. - project_id
(string)
: ID of the project being exported. - created_at
(string, ISO 8601 datetime)
: Timestamp when the export was initiated. - finished_at
(string, ISO 8601 datetime or null)
: Timestamp when the export was completed.null
if not yet completed. - name
(string)
: Name of the export task. - author_id
(string)
: ID of the user who initiated the export. - folder_id
(string)
: ID of the folder containing the project. - descriptions
(string)
: Description or notes about the export.
Additional Notes
- Status Values: The
status
field in both Task and Export objects can have the following values:"pending"
: Task has been created and is awaiting processing."in_progress"
: Task is currently being processed."completed"
: Task has been successfully completed."failed"
: Task has failed to complete.
- Time Format: All timestamps are in ISO 8601 format (e.g.,
"2023-10-01T12:00:00Z"
). - Error Handling: Error responses are not detailed here. Handle errors according to standard HTTP status codes and messages.
Example Workflows
Generating Shorts from a Video
-
Initiate Task
Send a POST request to
/tasks/video-to-shorts
with the required payload. -
Check Task Status
Periodically send a GET request to
/tasks/:task_id
to check if the task is completed. -
Retrieve Generated Projects
Once the task is completed, send a GET request to
/projects/:folder_id
to list the generated shorts.
Exporting a Project
-
Initiate Export
Send a POST request to
/projects/:folder_id/:project_id/exports
with the requiredpreset_id
. -
Check Export Status
Periodically send a GET request to
/projects/:folder_id/:project_id/exports/:export_id
to check if the export is completed. -
Access Exported File
Once the export is completed, the
src_url
field will contain the URL to download the exported file.
Conclusion
This documentation provides detailed information about each API endpoint, including request payloads and return values. Use this guide to integrate the API into your application effectively.