---
title: "Search assets (images and icons)"
method: GET
path: "/v3/assets/search"
tags: ["Assets"]
---

# Search assets (images and icons)

`GET /v3/assets/search`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/assets/search`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Semantically search re-hosted public images and icons by natural-language description, e.g. 'pepperoni pizza on a wooden table' or 'minimalist rocket icon'. Returns assets ranked by similarity, each with a stable public URL, plus cursor-based pagination.

## Query parameters

- `query` string, required
- `limit` integer
- `token` string
- `type` 'image' | 'icon', required
- `scope` 'public' | 'personal'

## Response `200`

Successful response

- object
  - `data` AssetSearchItem[]
    - union
      - ImageAssetItem: A photographic image result.
        - `id` string, required: Opaque identifier for this search result.
        - `url` string, required: Direct URL to the asset. For the current public-library results this is a stable, long-lived URL.
        - `width` integer, nullable: Pixel width, when known.
        - `height` integer, nullable: Pixel height, when known.
        - `orientation` string, nullable: 'landscape', 'portrait', or 'square', when known.
        - `is_transparent` boolean, nullable: Whether the asset has visible transparency (e.g. an icon or cut-out), when known.
        - `type` 'image': Result type discriminator. Always 'image'.
      - IconAssetItem: An icon result — typically a transparent vector cutout.
        - `id` string, required: Opaque identifier for this search result.
        - `url` string, required: Direct URL to the asset. For the current public-library results this is a stable, long-lived URL.
        - `width` integer, nullable: Pixel width, when known.
        - `height` integer, nullable: Pixel height, when known.
        - `orientation` string, nullable: 'landscape', 'portrait', or 'square', when known.
        - `is_transparent` boolean, nullable: Whether the asset has visible transparency (e.g. an icon or cut-out), when known.
        - `type` 'icon': Result type discriminator. Always 'icon'.
  - `has_more` boolean: Whether more pages are available
  - `next_token` string, nullable: Opaque cursor for the next page

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `429`: Rate limit exceeded
- `503`: Temporarily unavailable — the request did not complete and is safe to retry.

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/assets/search/get.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)