用于 collection 管理与管理 API 共用基础 URL：https://management-api.x.ai/。你必须使用 xAI 管理 API 密钥，并通过请求头 Authorization: Bearer <your xAI Management API key>。

请求体

collection_namestring

（字符串，必需）— 用于新集合的名称。

响应体

collection_idstring

（字符串）— UUIDv4，表示集合的 ID。

collection_namestring

（字符串）— 集合的名称。

created_atstring

（字符串）— 创建文档时的 Unix 时间戳。

index_configurationobject

（对象）

chunk_configurationobject

（对象）

documents_countinteger

（整数）— 集合包含多少个文件。

field_definitionsarray<object>

（对象数组）— 此集合中文档的字段定义。定义文档可包含哪些字段及其约束。

collection_descriptionstring

（字符串）— 集合的可选说明。

{
  "collection_name": "SEC Filings",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true
  },
  "collection_description": "Filings from the SEC for financial analysis"
}

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

查询参数

team_idstring

（字符串）— 拥有所列出的集合的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

limitinteger

（整数）— 要返回的对象数量的限制。每个请求最多 100 个项目。如果未提供，请将默认值设置为 100 项。

order"ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING"

对返回的集合进行排序的顺序。如果未提供，则默认顺序为降序。

sort_by"COLLECTIONS_SORT_BY_NAME" | "COLLECTIONS_SORT_BY_AGE"

集合排序所依据的参数。如果未提供，则默认按 `collection_name` 排序。

pagination_tokenstring

（字符串）— 用于检索下一页的可选 token，由之前的 `ListCollectionsResponse` 中的 `pagination_token` 提供。

filterstring

（字符串）— 用于缩小结果范围的过滤表达式。支持按以下字段过滤：collection_id、collection_name（部分字符串匹配）、created_at、documents_count 示例： - 'collection_id = "collection_123"' - 'collection_name:"SEC" AND documents_count:>10' - 'collection_name = "report"'（部分匹配） - 'created_at:>2025-01-01T00:00:00Z'

响应体

collectionsarray<object>

集合列表。

pagination_tokenstring

（字符串）— 要发送到下一个 `ListCollectionsRequest` 的 `pagination_token`，用于检索下一页的 token。

No parameters.

{
  "collections": [
    {
      "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
      "collection_name": "SEC Filings",
      "created_at": "2025-09-16T18:36:09.790629Z",
      "index_configuration": {
        "model_name": "grok-embedding-small"
      },
      "chunk_configuration": {
        "tokens_configuration": {
          "max_chunk_size_tokens": 1024,
          "chunk_overlap_tokens": 200,
          "encoding_name": "o200k_base"
        },
        "strip_whitespace": true,
        "inject_name_into_chunks": false
      },
      "documents_count": 0,
      "collection_type": "text",
      "collection_description": "Filings from the SEC for financial analysis"
    }
  ]
}

获取集合元数据

/v1/collections/{collection_id}

获取集合的元数据。

路径参数

collection_idstring

要请求的集合的 ID。

查询参数

team_idstring

（字符串）— 拥有该集合的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

响应体

collection_idstring

（字符串）— UUIDv4，表示集合的 ID。

collection_namestring

（字符串）— 集合的名称。

created_atstring

（字符串）— 创建文档时的 Unix 时间戳。

index_configurationobject

（对象）

chunk_configurationobject

（对象）

documents_countinteger

（整数）— 集合包含多少个文件。

field_definitionsarray<object>

（对象数组）— 此集合中文档的字段定义。定义文档可包含哪些字段及其约束。

collection_descriptionstring

（字符串）— 集合的可选说明。

No parameters.

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

删除集合

/v1/collections/{collection_id}

删除特定集合。

路径参数

collection_idstring

（字符串，必需）— 要删除的集合的 ID。

查询参数

team_idstring

（字符串）— 拥有该集合的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

No parameters.

{}

更新集合配置

/v1/collections/{collection_id}

更新集合的配置。

路径参数

collection_idstring

（字符串，必需）— 要更新的集合的 ID。

请求体

响应体

collection_idstring

（字符串）— UUIDv4，表示集合的 ID。

collection_namestring

（字符串）— 集合的名称。

created_atstring

（字符串）— 创建文档时的 Unix 时间戳。

index_configurationobject

（对象）

chunk_configurationobject

（对象）

documents_countinteger

（整数）— 集合包含多少个文件。

field_definitionsarray<object>

（对象数组）— 此集合中文档的字段定义。定义文档可包含哪些字段及其约束。

collection_descriptionstring

（字符串）— 集合的可选说明。

{
  "collectionName": "SEC Filings (New)",
  "chunkConfiguration": {
    "tokensConfiguration": {
      "maxChunkSizeTokens": 1024,
      "chunkOverlapTokens": 200,
      "encodingName": "o200k_base"
    },
    "stripWhitespace": true,
    "injectNameIntoChunks": false
  },
  "collectionDescription": "Updated description of the collection"
}

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

将现有文档添加到集合

/v1/collections/{collection_id}/documents/{file_id}

将文档添加到集合中。

路径参数

collection_idstring

（字符串，必需）— 要将该文档添加到的集合 ID。

file_idstring

（字符串，必需）— 用于此请求的文档的 ID。

请求体

{
  "fields": {
    "type": "10-Q"
  }
}

{}

列出集合中的文档

/v1/collections/{collection_id}/documents

列出集合中的文档。

路径参数

collection_idstring

（字符串，必需）— 用于列出文档的集合的 ID。

查询参数

team_idstring

（字符串）— 拥有文档的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

limitinteger

（整数）— 要返回的对象数量的限制。每个请求最多 100 个项目。如果未提供，请将默认值设置为 100 项。

order"ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING"

对返回文档进行排序的顺序。如果未提供，则默认顺序为降序。

sort_by"DOCUMENTS_SORT_BY_NAME" | "DOCUMENTS_SORT_BY_SIZE" | "DOCUMENTS_SORT_BY_AGE"

文档排序所依据的参数。如果未提供，则默认按 `name` 排序。

pagination_tokenstring

（字符串）— 用于检索下一页的可选 token，由之前的 `ListDocumentsResponse` 中的 `pagination_token` 提供。

namestring

（字符串）— 要获取的文档名称。已弃用：请改用值为 "name:value" 的 filter 字段。

filterstring

过滤表达式以缩小结果范围。支持对文件元数据进行过滤（name、content_type、size_bytes、created_at）和文档字段（status、fields.{key}）示例： - 'status:DOCUMENT_STATUS_PROCESSED' - 'name:"quarterly" AND status:!DOCUMENT_STATUS_FAILED' - 'fields.isbn:"978-1-234567-89-0"' - 'size_bytes:>5000000 AND content_type:application/pdf'

响应体

documentsarray<object>

文档列表。

pagination_tokenstring

（字符串）— 要发送到下一个 `ListDocumentsRequest` 的 `pagination_token`，用于检索下一页的 token。

No parameters.

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {
        "type": "10-Q"
      },
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

获取文档元数据

/v1/collections/{collection_id}/documents/{file_id}

检索集合中的文档元数据。

路径参数

collection_idstring

该文档所属集合的 ID。

file_idstring

（字符串，必需）— 用于此请求的文档的 ID。

查询参数

team_idstring

（字符串）— 文档所属团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

响应体

file_metadataobject

（对象）— 已上传文件的元数据。

fieldsobject

（对象）

status"DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED"

（“DOCUMENT_STATUS_UNKNOWN”|“DOCUMENT_STATUS_PROCESSING”|“DOCUMENT_STATUS_PROCESSED”|“DOCUMENT_STATUS_FAILED”）

error_messagestring

（字符串）— 处理时发生的任何错误。

last_indexed_atstring

（字符串）— 上次索引该文档的时间戳。如果没有则为空。

No parameters.

{
  "file_metadata": {
    "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
    "name": "tsla-20250630.txt",
    "size_bytes": "119237",
    "content_type": "text/plain",
    "created_at": "2025-09-16T19:06:53.472088Z",
    "expires_at": null,
    "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
  },
  "fields": {
    "type": "10-Q"
  },
  "status": "DOCUMENT_STATUS_PROCESSED",
  "error_message": ""
}

重新生成指定文档的索引

/v1/collections/{collection_id}/documents/{file_id}

重新生成给定文档的索引。

路径参数

collection_idstring

（字符串，必需）— 包含文档的集合的 ID。

file_idstring

（字符串，必需）— 要更新的文件的 ID。

查询参数

team_idstring

（字符串）— 拥有该文档的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

No parameters.

{}

从集合中移除文档

/v1/collections/{collection_id}/documents/{file_id}

从集合中删除文档。

路径参数

collection_idstring

（字符串，必需）— 将从中删除文档的集合的 ID。

file_idstring

（字符串，必需）— 用于此请求的文档的文件 ID。

查询参数

team_idstring

（字符串）— 拥有该集合的团队的 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

No parameters.

{}

批量获取文档元数据

/v1/collections/{collection_id}/documents:batchGet

在批量请求中获取文档元数据。

路径参数

collection_idstring

（字符串，必需）— 包含文档的集合的 ID。

查询参数

team_idstring

（字符串）— 拥有该文档的团队的 ID。如果 `None`，团队 ID 将从您的请求凭据中派生。

file_idsarray<string>

（字符串数组，必需）— 要从中检索文档元数据的文件 ID。

响应体

documentsarray<object>

（对象数组）— 所请求的文档元数据。

No parameters.

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {},
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

最后更新：2026 年 6 月 11 日

集合 API

集合管理

创建集合

请求体

响应体

列出所有集合

查询参数

响应体

获取集合元数据

路径参数

查询参数

响应体

删除集合

路径参数

查询参数

更新集合配置

路径参数

请求体

响应体

将现有文档添加到集合

路径参数

请求体

列出集合中的文档

路径参数

查询参数

响应体

获取文档元数据

路径参数

查询参数

响应体

重新生成指定文档的索引

路径参数

查询参数

从集合中移除文档

路径参数

查询参数

批量获取文档元数据

路径参数

查询参数

响应体