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

​
Endpoint

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.
​
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 -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.

Build docs developers (and LLMs) love

Get started for freeTalk to us