> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Videos and Images

> Search for stock videos and images from integrated media libraries. Returns preview URLs, thumbnails, and metadata for matching media assets.

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

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/media/search
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

### Query Parameters

<ParamField query="keyword" type="string" required>
  Search keyword for which media (video/image) results are required

  Example: `business`, `technology`, `nature`
</ParamField>

<ParamField query="category" type="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`
</ParamField>

<ParamField query="language" type="string" default="en">
  Language of the search keyword. Defaults to `en` (English)
</ParamField>

***

## Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="integer">
      Current page number of search results
    </ResponseField>

    <ResponseField name="searchResults" type="array">
      Array of media search results

      <Expandable title="searchResult item">
        <ResponseField name="assetId" type="integer">
          Unique identifier for the media asset
        </ResponseField>

        <ResponseField name="mediaType" type="string">
          Type of media: `video` or `image`
        </ResponseField>

        <ResponseField name="duration" type="integer">
          Duration of the media in seconds (for video assets)
        </ResponseField>

        <ResponseField name="mediaDescription" type="string">
          Descriptive text about the media content
        </ResponseField>

        <ResponseField name="preview" type="object">
          Preview URLs for the media

          <Expandable title="properties">
            <ResponseField name="url" type="string">
              URL of the preview video or image
            </ResponseField>

            <ResponseField name="jpg" type="string">
              URL of the preview thumbnail image (JPEG)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="thumbnail" type="object">
          Thumbnail URLs for the media

          <Expandable title="properties">
            <ResponseField name="url" type="string">
              URL of the thumbnail video or image
            </ResponseField>

            <ResponseField name="jpg" type="string">
              URL of the thumbnail image (JPEG)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="keyword" type="string">
          The search keyword that matched this result
        </ResponseField>

        <ResponseField name="searchLibrary" type="string">
          Source library for the media (e.g., `story_blocks`)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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"
          }
        }
      ]
    }
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": {
      "error_code": "INVALID_REQUEST",
      "error_message": "Request validation failed.",
      "fields": [
        {
          "errors": "keyword is required",
          "name": "keyword"
        }
      ]
    },
    "success": false
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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("---")
  ```

  ```javascript JavaScript / Node.js theme={null}
  // 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 PHP theme={null}
  <?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";
  }
  ?>
  ```

  ```go Go theme={null}
  // 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("---")
      }
  }
  ```
</CodeGroup>

***

## Usage Notes

<Note>
  **Media Sources**: Search results are sourced from integrated stock media libraries including StoryBlocks and Getty Images. All preview URLs include watermarks for copyright protection.
</Note>

<Tip>
  Use the `category` parameter to filter results by topic and receive more relevant media that matches your specific use case and content theme.
</Tip>

<Warning>
  Preview URLs contain time-sensitive security tokens that expire. Access or download media assets promptly after retrieval to avoid broken links.
</Warning>