Videos endpoint

Search for videos using AI-powered query understanding

The videos endpoint allows you to search for videos using AI to understand and refine your query based on conversation context.

Endpoint

POST /api/videos

http://localhost:3000/api/videos

Replace localhost:3000 with your Perplexica instance URL if running on a different host or port.

Request body

query · string · required

The video search query.

chatModel · object · required

Defines the chat model to be used for understanding and refining the query. Get available providers and models from the /api/providers endpoint.

Show properties

providerId · string · required

The UUID of the provider. You can get this from the /api/providers endpoint response.

key · string · required

The model key/identifier (e.g., gpt-4o-mini, llama3.1:latest). Use the key value from the provider’s chatModels array.

chatHistory · array

An array of message pairs representing the conversation history. Each pair consists of a role (either human or assistant) and the message content.

Example:

[
  ["human", "Show me videos about space exploration"],
  ["assistant", "Here are some videos about space exploration..."]
]

Response

videos · array

A list of video search results. The structure of each video object depends on the search provider’s response format.

Request example

cURL

curl -X POST http://localhost:3000/api/videos \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to train a dog",
    "chatModel": {
      "providerId": "550e8400-e29b-41d4-a716-446655440000",
      "key": "gpt-4o-mini"
    },
    "chatHistory": []
  }'

Response example

{
  "videos": [
    {
      "url": "https://www.youtube.com/watch?v=example1",
      "title": "Complete Dog Training Guide",
      "thumbnail": "https://example.com/thumb1.jpg",
      "duration": "15:30"
    },
    {
      "url": "https://www.youtube.com/watch?v=example2",
      "title": "How to Train Your Puppy - Beginner's Guide",
      "thumbnail": "https://example.com/thumb2.jpg",
      "duration": "22:45"
    }
  ]
}

The AI model processes your query and conversation history to refine the search and return more relevant results.

Error responses

500 · Internal Server Error

Returned if an error occurs while searching videos.