Skip to main content
GET
/
pictoryapis
/
v1
/
media
/
search
Search Videos and Images
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/media/search \
  --header 'Authorization: <authorization>'
import requests

url = "https://api.pictory.ai/pictoryapis/v1/media/search"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pictory.ai/pictoryapis/v1/media/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/media/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.pictory.ai/pictoryapis/v1/media/search"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "<authorization>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.pictory.ai/pictoryapis/v1/media/search")
.header("Authorization", "<authorization>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.pictory.ai/pictoryapis/v1/media/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body
{
  "data": {
    "page": 1,
    "searchResults": [
      {
        "assetId": 10900066,
        "duration": 15,
        "id": 10900066,
        "keyword": "business",
        "mediaDescription": "Young Team Brainstorming Ideas On Sticky Notes. Colleagues Approve. Business Success Concept.",
        "mediaType": "video",
        "preview": {
          "jpg": "https://dm0qx8t0i9gc9.cloudfront.net/thumbnails/video/V1xq1AADx/videoblocks-young-business-team-brainstorming-ideas-on-sticky-notes_thumbnail-180_02.jpg",
          "url": "https://dm0qx8t0i9gc9.cloudfront.net/watermarks/video/V1xq1AADx/videoblocks-young-business-team_P480.mp4"
        },
        "searchLibrary": "story_blocks",
        "thumbnail": {
          "jpg": "https://dm0qx8t0i9gc9.cloudfront.net/thumbnails/video/V1xq1AADx/videoblocks-young-business-team_thumbnail-180_02.jpg",
          "url": "https://dm0qx8t0i9gc9.cloudfront.net/watermarks/video/V1xq1AADx/videoblocks-young-business-team_P180.mp4"
        }
      }
    ]
  }
}
{
  "error": {
    "error_code": "INVALID_REQUEST",
    "error_message": "Request validation failed.",
    "fields": [
      {
        "errors": "keyword is required",
        "name": "keyword"
      }
    ]
  },
  "success": false
}
{
  "message": "Unauthorized"
}

Overview

Search through Pictory’s integrated stock media libraries to find relevant videos and images for your projects. Results include preview URLs, thumbnails, duration information, and descriptive metadata from sources like StoryBlocks and Getty Images.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/media/search

Request Parameters

Headers

Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

Query Parameters

keyword
string
required
Search keyword for which media (video/image) results are requiredExample: business, technology, nature
category
string
Filter results by category. Accepted values:
  • Agriculture and Forestry
  • Arts and Entertainment
  • Autos and Vehicles
  • Beauty and Fitness
  • Biological Sciences
  • Books and Literature
  • Business and Industrial
  • Computers and Electronics
  • Finance
  • Food and Drink
  • Games
  • Health
  • Home and Garden
  • Internet and Telecom
  • Jobs and Education
  • People and Society
  • Pets and Animals
  • Real Estate
  • Science
  • Sports
  • Travel
language
string
default:"en"
Language of the search keyword. Defaults to en (English)

Response

data
object

Response Examples

{
  "data": {
    "page": 1,
    "searchResults": [
      {
        "assetId": 10900066,
        "duration": 15,
        "id": 10900066,
        "keyword": "business",
        "mediaDescription": "Young Team Brainstorming Ideas On Sticky Notes. Colleagues Approve. Business Success Concept.",
        "mediaType": "video",
        "preview": {
          "jpg": "https://dm0qx8t0i9gc9.cloudfront.net/thumbnails/video/V1xq1AADx/videoblocks-young-business-team-brainstorming-ideas-on-sticky-notes_thumbnail-180_02.jpg",
          "url": "https://dm0qx8t0i9gc9.cloudfront.net/watermarks/video/V1xq1AADx/videoblocks-young-business-team_P480.mp4"
        },
        "searchLibrary": "story_blocks",
        "thumbnail": {
          "jpg": "https://dm0qx8t0i9gc9.cloudfront.net/thumbnails/video/V1xq1AADx/videoblocks-young-business-team_thumbnail-180_02.jpg",
          "url": "https://dm0qx8t0i9gc9.cloudfront.net/watermarks/video/V1xq1AADx/videoblocks-young-business-team_P180.mp4"
        }
      }
    ]
  }
}
{
  "error": {
    "error_code": "INVALID_REQUEST",
    "error_message": "Request validation failed.",
    "fields": [
      {
        "errors": "keyword is required",
        "name": "keyword"
      }
    ]
  },
  "success": false
}
{
  "message": "Unauthorized"
}

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/media/search?keyword=business&language=en' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool
import requests

# Search for business-related videos
url = "https://api.pictory.ai/pictoryapis/v1/media/search"
headers = {
    "Authorization": "YOUR_API_KEY",
    "accept": "application/json"
}
params = {
    "keyword": "business meeting",
    "category": "Business and Industrial",
    "language": "en"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

# Process the results
for result in data["data"]["searchResults"]:
    print(f"Asset ID: {result['assetId']}")
    print(f"Type: {result['mediaType']}")
    print(f"Description: {result['mediaDescription']}")
    print(f"Duration: {result.get('duration', 'N/A')} seconds")
    print(f"Preview URL: {result['preview']['url']}")
    print("---")
// Search for business-related videos
const searchMedia = async (keyword, category) => {
  const url = new URL('https://api.pictory.ai/pictoryapis/v1/media/search');
  url.searchParams.append('keyword', keyword);
  url.searchParams.append('category', category);
  url.searchParams.append('language', 'en');

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'accept': 'application/json'
    }
  });

  const data = await response.json();

  // Process the results
  data.data.searchResults.forEach(result => {
    console.log(`Asset ID: ${result.assetId}`);
    console.log(`Type: ${result.mediaType}`);
    console.log(`Description: ${result.mediaDescription}`);
    console.log(`Duration: ${result.duration || 'N/A'} seconds`);
    console.log(`Preview URL: ${result.preview.url}`);
    console.log('---');
  });

  return data.data.searchResults;
};

// Use the function
await searchMedia('business meeting', 'Business and Industrial');
<?php
// Replace 'YOUR_API_KEY' with your actual API key

function searchMedia($apiKey, $keyword, $category = null, $language = 'en') {
    $url = 'https://api.pictory.ai/pictoryapis/v1/media/search?keyword=' . urlencode($keyword) . '&language=' . urlencode($language);

    if ($category) {
        $url .= '&category=' . urlencode($category);
    }

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: ' . $apiKey,
        'accept: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception('Request failed with status ' . $httpCode);
    }

    return json_decode($response, true);
}

// Usage
try {
    $data = searchMedia('YOUR_API_KEY', 'business meeting', 'Business and Industrial');

    // Process the results
    foreach ($data['data']['searchResults'] as $result) {
        echo "Asset ID: " . $result['assetId'] . "\n";
        echo "Type: " . $result['mediaType'] . "\n";
        echo "Description: " . $result['mediaDescription'] . "\n";
        echo "Duration: " . ($result['duration'] ?? 'N/A') . " seconds\n";
        echo "Preview URL: " . $result['preview']['url'] . "\n";
        echo "---\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
// Replace "YOUR_API_KEY" with your actual API key

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
)

type Preview struct {
    URL string `json:"url"`
    JPG string `json:"jpg"`
}

type SearchResult struct {
    AssetID          int     `json:"assetId"`
    MediaType        string  `json:"mediaType"`
    Duration         int     `json:"duration,omitempty"`
    MediaDescription string  `json:"mediaDescription"`
    Preview          Preview `json:"preview"`
    Thumbnail        Preview `json:"thumbnail"`
    Keyword          string  `json:"keyword"`
    SearchLibrary    string  `json:"searchLibrary"`
}

type SearchResponse struct {
    Data struct {
        Page          int            `json:"page"`
        SearchResults []SearchResult `json:"searchResults"`
    } `json:"data"`
}

func searchMedia(apiKey, keyword, category, language string) (*SearchResponse, error) {
    baseURL := "https://api.pictory.ai/pictoryapis/v1/media/search"

    params := url.Values{}
    params.Add("keyword", keyword)
    params.Add("language", language)
    if category != "" {
        params.Add("category", category)
    }

    fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())

    req, err := http.NewRequest("GET", fullURL, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("Authorization", apiKey)
    req.Header.Set("accept", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
    }

    var result SearchResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

// Usage
func main() {
    data, err := searchMedia("YOUR_API_KEY", "business meeting", "Business and Industrial", "en")
    if err != nil {
        panic(err)
    }

    // Process the results
    for _, result := range data.Data.SearchResults {
        fmt.Printf("Asset ID: %d\n", result.AssetID)
        fmt.Printf("Type: %s\n", result.MediaType)
        fmt.Printf("Description: %s\n", result.MediaDescription)
        if result.Duration > 0 {
            fmt.Printf("Duration: %d seconds\n", result.Duration)
        }
        fmt.Printf("Preview URL: %s\n", result.Preview.URL)
        fmt.Println("---")
    }
}

Usage Notes

Media Sources: Search results are sourced from integrated stock media libraries including StoryBlocks and Getty Images. All preview URLs include watermarks for copyright protection.
Use the category parameter to filter results by topic and receive more relevant media that matches your specific use case and content theme.
Preview URLs contain time-sensitive security tokens that expire. Access or download media assets promptly after retrieval to avoid broken links.