> This page is for 平台, version 旧版.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 旧版: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 搜索资产

# 概述

Frame.io 的 API 支持对整个帐户中的资产进行深度、多方面搜索，这与 Web 应用程序中的功能相对应。虽然最常用的筛选条件是“团队”、“项目”和“状态”，但筛选和排序能以独特的方式组合，从而生成由 API 驱动且非常具体的集合。总体而言，除了 `account_id`、`q`（查询）和 `sort` 之外，所有筛选条件都遵循相同的结构，具体说明如下。<img alt="search-filters.png" src="/_fern-img/d468e3a3b48184af611e5af020bee1474a328ab3fc5090df704dfd6c9b603ba7.webp" />
<Warning title="请求的页面大小与返回的页面大小不匹配">
  


截至 2022 年 3 月，搜索 API 的分页功能存在一个已知缺陷。在该缺陷修复之前，我们不建议使用搜索 API 来迭代多页结果（即超过 100 个资产），因为请求的页面大小可能与实际返回的资产数量不符。



</Warning>


## 默认值





触发搜索的 API 请求始终相同：





它始终是同一个请求

向 `https://api.frame.io/v2/search/library` 发起 `POST` 请求

如果未显式提供，搜索调优的默认值如下：




| 属性 | 默认值 | 描述 |
|:--------|:------------|:----------|
| `page_size` | 10 | 每页将返回 10 个资产。 |
| `page` | 1 | 查询将返回响应的第一页。 |
| `sort` | `relevance` | “相关性”尝试基于一组经过特别调优的属性对资产进行排序。在没有查询的情况下，相关性会严重倾向于上传时间较近的资产。 |




## 关于本指南




本指南将逐步介绍如何构建一个匹配以下条件的搜索查询：




* 帐户内的资产
* 匹配查询 `&quot;moon&quot;`
* 在特定项目中
* 上传时间介于 2020 年 4 月 1 日至 4 月 30 日之间
* 且状态为“已批准”




我们最终的搜索请求体将如下所示：





```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-30T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    },
    "page_size": 10,
    "page": 1
}
```





### 帐户、查询和排序

帐户 (`account_id`)、查询 (`q`) 和排序 `sort` 是搜索查询中三个最基本的构建块，它们位于任何 `filter` 属性之外。

#### 帐户上下文

从技术上讲，执行搜索所需的唯一属性是 `account_id`。这样做会简单提取帐户上的每个资产（包括文件夹），并使用默认分页值（每页 10 个资产，从第 1 页开始）。

```json
{
    "account_id": "<account_id>"
}
```





#### 搜索查询

下一个最常见（也最有帮助）要包含的属性就是查询本身。注意：由于 Frame.io 的 API 搜索接受空查询，因此无需使用通配符 (`*`) 查询。您要么是在搜索某些内容，要么是在请求对帐户中的所有资产进行（可能经过筛选的）排序。

在我们的示例中，我们将搜索“moon”这个词。





```json
{
    "account_id": "<account_id>",
    "q": "moon"
}
```





### 排序

<img alt="sort.png" src="/_fern-img/bd057586bfc5499df0b46d41ae74d90e53beb6500bb87f639a730545ccb3f1c8.webp" />

Frame.io 支持多种不同的排序选项。排序顺序的语法在各个选项之间都是类似的：




* 每个选项都有一个默认的排序方向
* 要反转该方向，请在排序值前加上负号 `-`

例如，要按字母逆序（Z 到 A）排序，您可以声明 `&quot;sort&quot;: &quot;-name&quot;`。默认的排序操作是“相关性”。因此，它不需要声明；如果未提供 `sort` 属性，系统将默认使用相关性排序。
| 排序选项 | 属性 | 默认方向 |
|:----------|:--------|:----------------|
| **相关性** | 不适用 | 不适用 |
| **上传日期** | `inserted_at` | 最旧在前 |
| **名称** | `name` | A 至 Z |
| **大小** | `filesize` | 最小在前 |
| **上传者** | `creator.name` | A 至 Z |
因此，在我们构建查询时，现在可以在 `sort` 中添加按 `name`（A 到 Z）排序：

```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name"
}
```





### 筛选条件和分页

筛选条件既是 Frame.io 资产搜索中最复杂的部分，但也是最强大的功能。筛选条件被编写在一个单独的 `filter` 对象内，并且都遵循相同的模式：一个操作 (`op`) 和一个值 (`value`)。筛选条件将使用以下常见缩写，除“等于”之外的等效选项仅用于日期和大小查询：
* `eq` -- 等于
* `lt` -- 小于
* `gt` -- 大于
* `lte` -- 小于或等于
* `gte` -- 大于或等于
* `match` -- 精确匹配，仅用于“上传者”和“文件类型”筛选条件

例如，用于匹配已知 `project_id` 的 `filter` 将按如下方式构建：

```json
{
    "filter": {
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        }
    }
}
```





### 选项和操作





下表描述了与每种筛选条件类型相关的选项和操作。




| 筛选选项 | 属性 | 支持的操作 | 支持的值 |
|:------------|:--------|:-------------------|:---------------|
| **已存档** | `archived` | `eq` | `true`、`false` |
| **上传日期** | `inserted_at` | `eq`、`lt`、`gt`、`lte`、`gte` | `<datetime></datetime>` (ISO-8601, UTC) |
| **已删除** | `deleted` | `eq` | `true`、`false` |
| **文件类型** | `filetype` | `match` | `<mime type=""></mime>` |
| **私有** | `private` | `eq` | `true`、`false` |
| **项目** | `project_id` | `eq` | `<project_id></project_id>` |
| **大小** | `filesize` | `eq`、`lt`、`gt`、`lte`、`gte` | `size`（以字节为单位） |
| **状态** | `label` | `eq` | `none`、`in_progress`、`needs_review`、`approved` |
| **团队** | `team_id` | `eq` | `<team_id></team_id>` |
| **类型** | `asset_type` | `eq` | `audio`、`document`、`folder`、`image`、`other`、`stream`、`video` |
| **上传者** | `creator.name` | `match` | `<name></name>` |



<Warning title="上传者必须是活跃的帐户成员才能填充索引">
  


搜索那些已不再是帐户成员的创作者将无法生效，因为该用户已不在用户搜索索引中。



</Warning>


为了继续构建我们的查询，我们现在可以添加一个筛选条件，用于筛选满足以下条件的资产：




* 在特定项目中
* 上传时间介于 2020 年 4 月 1 日至 4 月 30 日之间
* 标记为“已批准”




```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-28T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    }
}
```




<Note title="分页">
  搜索端点的分页方式与任何其他端点完全相同，通过位于请求体最外层的 `page_size` 和 `page` 属性来实现。有关分页的更多详细信息，请参阅[此处](/platform/v2/key-concepts#pagination)的单独指南。
</Note>