Project & Clip Endpoints

A project is one long video the user clipped, together with the clips Klap made from it. Project endpoints live under /tasks: every path that starts with /tasks manages projects.

Create Project from Video

Start clipping a long video into short clips. Klap finds the best moments, reframes them and adds captions using the user’s default style in Klap.

Endpoint: POST /tasks/video-to-shorts

Request

POST /tasks/video-to-shorts
Authorization: Bearer <access_token>
Content-Type: application/json
 
{
  "source_video_url": "https://www.youtube.com/watch?v=s2bVToRdY6A",
  "max_clip_count": 5,
  "target_duration": 30,
  "min_duration": 20,
  "language": "en",
  "curation_prompt": "Every tip about pricing",
  "dimensions": {
    "width": 1080,
    "height": 1920
  }
}

Request Parameters

Send only the parameters you want to set.

Dimensions

Common values: 1080 x 1920 (9:16 vertical), 1080 x 1080 (1:1 square), 1080 x 1350 (4:5 portrait), 1920 x 1080 (16:9 landscape).

Limitations

• Minimum video length: 10 seconds
• Maximum video length: 3 hours on paid plans (4 hours otherwise)

Response

Returns the new project’s record. Read its id, then call Get Project to get the Project Object. The other fields of this response are internal and may change.

{
  "id": "Jx7kQp2LmN4vR8tA",
  "type": "video-to-shorts",
  "status": "processing",
  "created_at": "2026-10-07T12:00:00.000Z",
  ...
}

Notes

• Slow response: Klap checks the video before answering (it reads the YouTube metadata or probes the file), which can take 5 to 60 seconds. Use a request timeout of at least 90 seconds.
• Not idempotent: Each successful call creates a new project and counts toward the user’s plan. Don’t retry automatically after a timeout: the first request may have succeeded. Check List Projects first.
• Processing time: Clipping takes several minutes. Poll Get Project until status is ready (estimated_ready_at tells you roughly when), then call List Project Clips.
• Errors: A video Klap can’t use returns 422 with an error_code, and plan limits return 402. See Errors.

Get Project

Get a project and its status.

Endpoint: GET /tasks/{project_id}

Request

GET /tasks/{project_id}
Authorization: Bearer <access_token>

Path Parameters

Response

Returns a Project Object:

{
  "id": "Jx7kQp2LmN4vR8tA",
  "status": "ready",
  "error_code": null,
  "name": "My podcast ep. 12",
  "source_url": "https://www.youtube.com/watch?v=s2bVToRdY6A",
  "thumbnail_url": "https://img.youtube.com/vi/s2bVToRdY6A/hqdefault.jpg",
  "created_at": "2026-10-07T12:00:00.000Z",
  "estimated_ready_at": "2026-10-07T12:12:00.000Z",
  "folder_id": "aB3dE5fG",
  "url": "https://klap.app/spaces/aB3dE5fG"
}

Possible Status Values

Returns 404 if the project doesn’t exist, belongs to another user, or was deleted in Klap.

List Projects

List the user’s most recent projects, newest first. Includes projects created in the Klap web app and through other apps.

Endpoint: GET /tasks

Request

GET /tasks?limit=10
Authorization: Bearer <access_token>

Query Parameters

Response

Returns an array of Project Objects, newest first (by created_at):

[
  {
    "id": "Jx7kQp2LmN4vR8tA",
    "status": "processing",
    "error_code": null,
    "name": "My podcast ep. 12",
    "source_url": "https://www.youtube.com/watch?v=s2bVToRdY6A",
    "thumbnail_url": "https://img.youtube.com/vi/s2bVToRdY6A/hqdefault.jpg",
    "created_at": "2026-10-07T12:00:00.000Z",
    "estimated_ready_at": "2026-10-07T12:12:00.000Z",
    "folder_id": "aB3dE5fG",
    "url": "https://klap.app/spaces/aB3dE5fG"
  },
  {
    "id": "Pq4wE8rT2yU6iO0a",
    "status": "ready",
    "error_code": null,
    "name": "Product demo",
    "source_url": "https://www.dropbox.com/scl/fi/abc123/demo.mp4?dl=0",
    "thumbnail_url": null,
    "created_at": "2026-10-06T09:30:00.000Z",
    "estimated_ready_at": "2026-10-06T09:38:00.000Z",
    "folder_id": "Zx9cV7bN",
    "url": "https://klap.app/spaces/Zx9cV7bN"
  }
]

Notes

• There is no pagination and no filtering.
• The response can contain fewer than limit projects: projects the user deleted in Klap are left out.
• To detect projects that just finished, poll this endpoint and compare each project’s status with the previous poll.

List Project Clips

List the clips of a project, best first.

Endpoint: GET /tasks/{project_id}/clips

Request

GET /tasks/{project_id}/clips
Authorization: Bearer <access_token>

Path Parameters

Response

Returns an array of Clip Objects, sorted by virality_score, highest first:

[
  {
    "id": "hT4kq9ZpW2xe",
    "name": "Why most startups fail",
    "virality_score": 87,
    "virality_score_explanation": "Strong hook in the first seconds and a clear, quotable takeaway.",
    "duration_seconds": 42,
    "width": 1080,
    "height": 1920,
    "thumbnail_url": "https://api.klap.app/projects/hT4kq9ZpW2xe/thumbnail",
    "embed_url": "https://klap.app/embed/hT4kq9ZpW2xe",
    "editor_url": "https://klap.app/editor/hT4kq9ZpW2xe",
    "created_at": "2026-10-07T12:11:30.000Z"
  }
]

Clips are listed once the project’s status is ready. While it is processing, the array is empty.

Get a Clip’s Project

Get the project a clip comes from.

Endpoint: GET /projects/{clip_id}/task

Request

GET /projects/{clip_id}/task
Authorization: Bearer <access_token>

Path Parameters

Response

Returns the Project Object the clip belongs to, in the same format as Get Project.

Returns 404 if the clip isn’t in the user’s account or doesn’t come from a project.