Quickstart - tl;dw

Get started with AI video intelligence in less than 5 minutes. This guide helps you:

Obtain your API key
Create a collection
Upload a video for indexing
Query the video or an entire collection

By the end, you’ll have made your first successful API calls and received AI-driven insights.

Prerequisites

A command-line tool like curl (installed by default on most Unix-based systems)
An API key from your account settings. Click here to get one.

Set your API key:

export token="3726e6ad1c6ce2eb643a268ea2f4682686c9ce33e28561ped915cbf1dbe7ab52"

Create a Collection

A collection is a container for your videos. Let’s create one named My First Collection.

Request

curl --request POST \
  --url https://api.trytldw.ai/v1/collections/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "New Collection"
}'

Response

{
  "id": "c1a2b3c4-1a2b-3c4d-5e6f-7g8h9i0j1k2l"
}

Upload a Video to the Collection

Provide the video’s URL and the collection ID. The AI will index this video so it can be queried later. Note: the URL must point directly at a video file (eg the url ends in a video file extension) Feel free to use this video: https://storage.googleapis.com/tldr-public/static/never_gonna_give_you_up.mp4

Request

curl --request POST \
  --url https://api.trytldw.ai/v1/media/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "collection_id": "c1a2b3c4-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
  "media_list": {
    "external_id": "video_1",
    "title": "My Video1",
    "url": "https//example.com/video1.mp4"
  }
}'

Response

{
  "media_list": [
    {
      "id": "c1a2b3c4-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
      "external_id": "video_12345",
      "status": "PENDING"
    }
  ]
}

Check Video Indexing Progress

Indexing might take a moment. Check the status with the collection ID.

Request

curl --request GET \
  --url https://api.trytldw.ai/v1/media/{media_id} \
  --header 'Authorization: Bearer <token>'

Response

{
  "id": "c1a2b3c4-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
  "external_id": "video_12345",
  "status": "COMPLETED",
  "collection_id": "c1a2b3c4-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
  "title": "My Video",
  "segments": [
    {
      "start_ms": 0,
      "end_ms": 1000,
      "embedding": [
        123
      ],
      "description": "People walking in the park"
    }
  ]
}

Query Video Collection

Ask questions like “What topics are discussed at 10 minutes?” by providing the media_ids array with a single video’s ID.

Request

curl --request POST \
  --url https://api.trytldw.ai/v1/search/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "collection_id": "<string>",
  "media_ids": [],
  "search_term": "<string>",
  "similarity_threshold": 0.28,
  "offset": 0,
  "limit": 30,
  "configs": {
    "smart_remove_false_positive": false
  }
}'

Response

{
  "scenes": [
    {
      "media_id": "<string>",
      "external_id": "<string>",
      "start_ms": 123,
      "end_ms": 123,
      "max_similarity": 123,
      "fragments": [
        {
          "uuid": "<string>",
          "start_ms": 123,
          "end_ms": 123,
          "similarity": 123,
          "description": "<string>"
        }
      ]
    }
  ],
  "metadata": {}
}

Next Steps

Congratulations! Explore our Full API Reference for more endpoint details.

​Prerequisites

​Create a Collection

​Upload a Video to the Collection

​Check Video Indexing Progress

​Query Video Collection

​Next Steps

Prerequisites

Create a Collection

Upload a Video to the Collection

Check Video Indexing Progress

Query Video Collection

Next Steps