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

# Search Public — by Text

> Semantic text search across the public TikTok / YouTube / Instagram video library.

<Info>
  **Product**: Visual Search
  **Use case**: Upload videos and images, auto-index them, then search by natural language, image, or transcript phrase
  **Host**: `https://api.memories.ai/serve/api/v1`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

Use a natural-language query to find relevant clips or audio moments from the pre-indexed public social-media library — no upload required. For image queries see [Search Public — by Image](/visual-search/search-public-by-image); for exact-phrase transcript search see [Search Public — by Transcript](/visual-search/search-public-by-transcript).

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).

## Request Example

```python theme={null}
import requests

headers = {"Authorization": "sk-mavi-..."}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search_public",
    headers=headers,
    json={
        "search_param": "sprint race with Usain Bolt",
        "search_type": "BY_VIDEO",
        "type": "TIKTOK",
        "top_k": 10,
        "filtering_level": "medium"
    }
)
print(response.json())
```

## Parameters

<ParamField body="search_param" type="string" required>
  Natural-language search query. Must be non-empty.
</ParamField>

<ParamField body="search_type" type="string" default="BY_VIDEO">
  What to search. The server-side enum is `[BY_CLIP, BY_VIDEO, BY_AUDIO, BY_IMAGE]`; only the first three are meaningful here (`BY_IMAGE` is exposed via the dedicated [Search Public — by Image](/visual-search/search-public-by-image) endpoint).

  * `BY_VIDEO` — video clips (default). `BY_CLIP` is an accepted alias.
  * `BY_AUDIO` — spoken-word transcripts (semantic, not exact-match). `audio_ts` is only populated in the response for this mode.

  Unknown values are rejected with `code: "0003"` and a JSON deserialization error listing the live enum values.
</ParamField>

<ParamField body="type" type="string" default="TIKTOK">
  Platform to search. One of `TIKTOK`, `YOUTUBE`, `INSTAGRAM`. The server **does not validate** this string — passing an unknown value silently falls back to a default rather than returning an error, so prefer one of the documented values explicitly.
</ParamField>

<ParamField body="top_k" type="integer" default="100">
  Maximum results to return. Range: **1 – 1000**.
</ParamField>

<ParamField body="filtering_level" type="string">
  Minimum similarity score threshold:

  * `low` — score ≥ 0.15
  * `medium` — score ≥ 0.225
  * `high` — score ≥ 0.4

  When omitted, no score filter is applied.
</ParamField>

## Response

```json theme={null}
{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "videoNo": "PI-600947902470296459",
            "videoName": "They played in their OPPONENTS jerseys?!?",
            "startTime": "23",
            "endTime": "27",
            "audio_ts": "...matched transcript text...",
            "score": 0.7350679636001586,
            "video_bucket": "mavi-public-video",
            "video_blob": "<scraper-id>.mp4",
            "keyframe_bucket": "mavi-public-keyframe",
            "keyframe_blob": "<uuid>/keyframe-000023.jpg"
        }
    ],
    "success": true,
    "failed": false
}
```

<ResponseField name="data[].videoNo" type="string">Public video identifier (typically prefixed with `PI-`).</ResponseField>
<ResponseField name="data[].videoName" type="string">Public video title or name.</ResponseField>
<ResponseField name="data[].startTime" type="string">Matched segment start time, in seconds.</ResponseField>
<ResponseField name="data[].endTime" type="string">Matched segment end time, in seconds.</ResponseField>
<ResponseField name="data[].audio_ts" type="string">Transcript text of the segment. Populated for `BY_AUDIO` searches.</ResponseField>
<ResponseField name="data[].score" type="number">Relevance score. Higher is more relevant.</ResponseField>
<ResponseField name="data[].video_bucket" type="string">GCS bucket of our cached copy of the public video. Omitted when the storage location cannot be resolved.</ResponseField>
<ResponseField name="data[].video_blob" type="string">GCS blob (object) path of the cached video. Use it with `video_bucket` at `GET /serve/api/v2/download?bucket=&blob=` to fetch the file directly.</ResponseField>
<ResponseField name="data[].keyframe_bucket" type="string">GCS bucket of the matched keyframe image (`BY_CLIP` only).</ResponseField>
<ResponseField name="data[].keyframe_blob" type="string">GCS blob (object) path of the matched keyframe image.</ResponseField>

## Notes & Limits

* **Rate limiting**: Exceeding the per-account rate limit returns an error. See [Rate limits](/visual-search/rate-limits).
* **Billing**: Each successful call deducts credits from your account balance.


## OpenAPI

````yaml POST /serve/api/v1/search_public
openapi: 3.1.0
info:
  title: Memories Platform API (Docs Mapping)
  version: v1
  description: OpenAPI mapping used by Mintlify Try it for the platform docs.
servers:
  - url: https://api.memories.ai
security:
  - ApiKeyAuth: []
paths:
  /serve/api/v1/search_public:
    post:
      summary: Search from Public Video Sources
      operationId: search_public_library
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPublicRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchPublicResponse'
components:
  schemas:
    SearchPublicRequest:
      type: object
      properties:
        search_param:
          type: string
          example: Find sprint race with Usain Bolt
          description: Natural-language search query. Must be non-empty.
        search_type:
          type: string
          enum:
            - BY_VIDEO
            - BY_AUDIO
          default: BY_CLIP
          example: BY_VIDEO
          description: >-
            Search modality. Only BY_VIDEO and BY_AUDIO are accepted here;
            BY_CLIP and BY_IMAGE are explicitly rejected. BY_VIDEO is treated as
            BY_CLIP internally.
        type:
          type: string
          enum:
            - TIKTOK
            - YOUTUBE
            - INSTAGRAM
          default: TIKTOK
          description: Source platform to search within.
        top_k:
          type: integer
          default: 100
          minimum: 1
          maximum: 1000
          description: Maximum number of results to return. Range 1-1000.
        filtering_level:
          type: string
          enum:
            - low
            - medium
            - high
          example: medium
          description: Similarity-score filter. low=0.15, medium=0.225, high=0.4.
      required:
        - search_param
    SearchPublicResponse:
      type: object
      properties:
        code:
          type: string
          example: '0000'
        msg:
          type: string
          example: success
        data:
          type: array
          items:
            type: object
            properties:
              videoNo:
                type: string
                example: PI-600947902470296459
              videoName:
                type: string
                example: They played in their OPPONENTS jerseys?!?
              startTime:
                type: string
                example: '23'
              endTime:
                type: string
                example: '27'
              audio_ts:
                type: string
                description: Matched audio transcript (populated for BY_AUDIO).
              score:
                type: number
                format: double
                example: 0.7350679636001586
              video_bucket:
                type: string
                description: >-
                  GCS bucket of our cached copy of the public video. Omitted
                  when the storage location cannot be resolved.
              video_blob:
                type: string
                description: >-
                  GCS blob path of the cached video. Use with video_bucket at
                  GET /serve/api/v2/download to fetch the file directly.
              keyframe_bucket:
                type: string
                description: GCS bucket of the matched keyframe image (BY_CLIP only).
              keyframe_blob:
                type: string
                description: GCS blob path of the matched keyframe image.
        success:
          type: boolean
          example: true
        failed:
          type: boolean
          example: false
      example:
        code: '0000'
        msg: success
        data:
          - videoNo: PI-600947902470296459
            videoName: They played in their OPPONENTS jerseys?!?
            startTime: '23'
            endTime: '27'
            audio_ts: ...matched transcript text...
            score: 0.7350679636001586
            video_bucket: mavi-public-video
            video_blob: <scraper-id>.mp4
            keyframe_bucket: mavi-public-keyframe
            keyframe_blob: <uuid>/keyframe-000023.jpg
        success: true
        failed: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````