API Reference

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.

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.
intro_title (boolean, optional, default: true): Include a hook title for the beginning of the video.
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."
}

6. Get Exports

Endpoint

GET /exports

Description

Retrieve all exports

Query Parameters

folder_id (string): A specific folder id.
project_id (string): A specific project_id.

Note: If no query params is passed, all users exports will be returned.

Return Value

An array of Export Object.

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

Introduction Object formats