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 required preset_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.

Introduction Object formats