Skip to main content

Hub API 端点

我们提供开放的端点，你可以使用它们从 Hub 检索信息以及执行某些操作，例如创建模型、数据集或 Space 仓库。我们提供了一个 Python 包装客户端 huggingface_hub 和一个 JS 客户端 huggingface.js，可以轻松访问这些端点。我们还提供 webhooks 来接收关于仓库的实时增量信息。享受吧！

下面这些端点的基础 URL 是 https://huggingface.co。例如，要构造下面的 /api/models 调用，可以调用 URL https://huggingface.co/api/models

Hub API playground​

想试试我们的 API 吗？ 立即在我们的基于 OpenAPI 的 Playground 上试试吧！

你也可以直接访问 OpenAPI 规范：https://huggingface.co/.well-known/openapi.json

所有 API 调用都受 HF 范围内的速率限制约束。如果你需要提升的大规模访问，请升级你的账户。

note

本页的其余部分是我们一些 API 端点的部分列表。但请注意，完整的参考是我们的 OpenAPI 文档。 它更加完整，并保证始终是最新的。

仓库列表 API​

以下端点有助于获取存储在 Hub 上的模型、数据集和 Spaces 的信息。

tip

在进行 API 调用以检索关于仓库的信息时，createdAt 属性表示相应仓库的创建时间。需要注意的是，有一个唯一值 2022-03-02T23:29:04.000Z 被分配给所有在我们开始存储创建日期之前创建的仓库。

GET /api/models​

获取 Hub 中所有模型的信息。响应是分页的，使用 Link 标头获取下一页。你可以指定其他参数以获得更具体的结果。

  • search：基于仓库及其用户名的子字符串进行筛选，例如 resnet 或 microsoft
  • author：按作者或组织筛选模型，例如 huggingface 或 microsoft
  • filter：基于标签进行筛选，例如 text-classification 或 spacy。
  • sort：排序时使用的属性，例如 downloads 或 author。
  • direction：排序方向，例如 -1 表示降序，其他值表示升序。
  • limit：限制获取的模型数量。
  • full：是否获取大部分模型数据，例如所有标签、文件等。
  • config：是否同时获取仓库配置。

Payload:

params = {
    "search":"search",
    "author":"author",
    "filter":"filter",
    "sort":"sort",
    "direction":"direction",
    "limit":"limit",
    "full":"full",
    "config":"config"
}

这等价于 huggingface_hub.list_models()。

GET /api/models/{repo_id} 或 /api/models/{repo_id}/revision/{revision}​

获取特定模型的所有信息。

这等价于 huggingface_hub.model_info(repo_id, revision)。

GET /api/models-tags-by-type​

获取 Hub 中托管的所有可用模型标签。

这等价于 huggingface_hub.get_model_tags()。

GET /api/datasets​

获取 Hub 中所有数据集的信息。响应是分页的，使用 Link 标头获取下一页。你可以指定其他参数以获得更具体的结果。

  • search：基于仓库及其用户名的子字符串进行筛选，例如 pets 或 microsoft
  • author：按作者或组织筛选数据集，例如 huggingface 或 microsoft
  • filter：基于标签进行筛选，例如 task_categories:text-classification 或 languages:en。
  • sort：排序时使用的属性，例如 downloads 或 author。
  • direction：排序方向，例如 -1 表示降序，其他值表示升序。
  • limit：限制获取的数据集数量。
  • full：是否获取大部分数据集数据，例如所有标签、文件等。

Payload:

params = {
    "search":"search",
    "author":"author",
    "filter":"filter",
    "sort":"sort",
    "direction":"direction",
    "limit":"limit",
    "full":"full",
    "config":"config"
}

这等价于 huggingface_hub.list_datasets()。

GET /api/datasets/{repo_id} 或 /api/datasets/{repo_id}/revision/{revision}​

获取特定数据集的所有信息。

  • full：是否获取大部分数据集数据，例如所有标签、文件等。

Payload:

params = {"full": "full"}

这等价于 huggingface_hub.dataset_info(repo_id, revision)。

GET /api/datasets/{repo_id}/parquet​

获取自动转换的 parquet 文件列表。

将 subset 和 split 追加到 URL 以获取特定 subset 和 split 的文件列表：

  • GET /api/datasets/\{repo_id\}/parquet/\{subset\}
  • GET /api/datasets/\{repo_id\}/parquet/\{subset\}/\{split\}

GET /api/datasets/{repo_id}/parquet/{subset}/{split}/{n}.parquet​

获取自动转换的 parquet 文件的第 n 个分片，用于特定的 subset（也称为"config"）和 split。

GET /api/datasets/{repo_id}/croissant​

获取 Croissant 元数据。更多详细信息请访问 https://huggingface.co/docs/datasets-server/croissant。

GET /api/datasets-tags-by-type​

获取 Hub 中托管的所有可用数据集标签。

这等价于 huggingface_hub.get_dataset_tags()。

GET /api/spaces​

获取 Hub 中所有 Spaces 的信息。响应是分页的，使用 Link 标头获取下一页。你可以指定其他参数以获得更具体的结果。

  • search：基于仓库及其用户名的子字符串进行筛选，例如 resnet 或 microsoft
  • author：按作者或组织筛选模型，例如 huggingface 或 microsoft
  • filter：基于标签进行筛选，例如 text-classification 或 spacy。
  • sort：排序时使用的属性，例如 downloads 或 author。
  • direction：排序方向，例如 -1 表示降序，其他值表示升序。
  • limit：限制获取的模型数量。
  • full：是否获取大部分模型数据，例如所有标签、文件等。

Payload:

params = {
    "search":"search",
    "author":"author",
    "filter":"filter",
    "sort":"sort",
    "direction":"direction",
    "limit":"limit",
    "full":"full",
    "config":"config"
}

这等价于 huggingface_hub.list_spaces()。

GET /api/spaces/{repo_id} 或 /api/spaces/{repo_id}/revision/{revision}​

获取特定 Space 的所有信息。

这等价于 huggingface_hub.space_info(repo_id, revision)。

仓库 API​

以下端点管理仓库设置，例如创建和删除仓库。

POST /api/repos/create​

创建仓库。默认情况下是模型仓库。

参数：

  • type：仓库类型（dataset 或 space；默认为 model）。
  • name：仓库名称。
  • organization：组织名称（可选）。
  • private：仓库是否为私有。
  • sdk：当类型为 space 时（gradio、docker 或 static）

Payload:

payload = {
    "type":"model",
    "name":"name",
    "organization": "organization",
    "private":"private",
    "sdk": "sdk"
}

这等价于 huggingface_hub.create_repo()。

DELETE /api/repos/delete​

删除仓库。默认情况下是模型仓库。

参数：

  • type：仓库类型（dataset 或 space；默认为 model）。
  • name：仓库名称。
  • organization：组织名称（可选）。

Payload:

payload = {
    "type": "model",
    "name": "name",
    "organization": "organization",
}

这等价于 huggingface_hub.delete_repo()。

PUT /api/repos/{repo_type}/{repo_id}/settings​

更新仓库可见性。

Payload:

payload = {
    "private": "private",
}

这等价于 huggingface_hub.update_repo_settings()。

POST /api/repos/move​

移动仓库（在同一命名空间内重命名或从用户转移到组织）。

参数：

  • fromRepo：要重命名的仓库。
  • toRepo：仓库的新名称。
  • type：仓库类型（dataset 或 space；默认为 model）。

Payload:

payload = {
    "fromRepo" : "namespace/repo_name",
    "toRepo" : "namespace2/repo_name2",
    "type": "model",
}

这等价于 huggingface_hub.move_repo()。

用户 API​

以下端点获取有关用户的信息。

GET /api/whoami-v2​

获取用户名和用户所属的组织。

Payload:

headers = { "authorization" :  "Bearer $token" }

这等价于 huggingface_hub.whoami()。

组织 API​

以下端点处理组织相关操作，例如获取组织概览、列出成员和关注者。

GET /api/organizations/{organization_name}/overview​

获取组织概览。

Payload:

headers = { "authorization" :  "Bearer $token" }

这等价于 huggingface_hub.get_organization_overview()。

GET /api/organizations/{organization_name}/members​

获取组织成员。

Payload:

headers = { "authorization" :  "Bearer $token" }

这等价于 huggingface_hub.list_organization_members()。

GET /api/organizations/{organization_name}/followers​

获取组织关注者。

Payload:

headers = { "authorization" :  "Bearer $token" }

这等价于 huggingface_hub.list_organization_followers()。

资源组 API​

以下端点管理资源组。资源组是企业功能。

GET /api/organizations/{name}/resource-groups​

获取已认证用户有权查看的组织中的所有资源组。

GET /api/organizations/{name}/resource-groups/{resourceGroupId}​

获取特定资源组的详细信息。

POST /api/organizations/{name}/resource-groups​

在组织中创建新的资源组。

参数：

  • name：资源组名称（必需）
  • description：资源组描述（可选）
  • users：资源组中的用户及其角色列表（可选）
  • repos：仓库列表（可选）
  • autoJoin：自动加入用户的设置（可选）

Payload:

payload = {
    "name": "name",
    "description": "description",
    "users": [
        {
            "user": "username",
            "role": "admin" // 或 "write" 或 "read"
        }
    ],
    "repos": [
        {
            "type": "dataset",
            "name": "huggingface/repo"
        }
    ]
}

PATCH /api/organizations/{name}/resource-groups/{resourceGroupId}​

更新资源组的元数据。

参数：

  • name：资源组的新名称（可选）
  • description：资源组的新描述（可选）

Payload:

payload = {
    "name": "name",
    "description": "description"
}

POST /api/organizations/{name}/resource-groups/{resourceGroupId}/settings​

更新资源组的设置。

Payload:

payload = {
    "autoJoin": {
        "enabled": true,
        "role": "read" // 或 "write" 或 "admin"
    }
}

DELETE /api/organizations/{name}/resource-groups/{resourceGroupId}​

删除资源组。

POST /api/organizations/{name}/resource-groups/{resourceGroupId}/users​

向资源组添加用户。

Payload:

payload = {
    "users": [
        {
            "user": "username",
            "role": "admin" // 或 "write" 或 "read"
        }
    ]
}

DELETE /api/organizations/{name}/resource-groups/{resourceGroupId}/users/{username}​

从资源组中移除用户。

PATCH /api/organizations/{name}/resource-groups/{resourceGroupId}/users/{username}​

更新用户在资源组中的角色。

Payload:

payload = {
    "role": "admin" // 或 "write" 或 "read"
}

POST /api/(models|spaces|datasets)/{namespace}/{repo}/resource-group​

更新资源组的仓库。

Payload:

payload = {
    "resourceGroupId": "6771d4700000000000000000" // （允许 `null` 以移除仓库的资源组）
}

GET /api/(models|spaces|datasets)/{namespace}/{repo}/resource-group​

获取仓库的详细资源组信息

论文页面 API​

以下端点获取有关论文的信息。

GET /api/papers/{arxiv_id}​

获取论文页面的 API 等价信息，即元数据，如作者、摘要和讨论评论。

GET /api/arxiv/{arxiv_id}/repos​

获取引用论文的所有模型、数据集和 Spaces。

GET /api/daily_papers​

获取由 AK 和社区策划的每日论文。这等价于 https://huggingface.co/papers。

要按特定日期筛选，只需传递日期，如下所示：https://huggingface.co/api/daily_papers?date=2025-03-31。

集合 API​

使用集合在专用页面上对 Hub 中的仓库（模型、数据集、Spaces 和论文）进行分组。

你可以在集合指南中了解更多信息。也可以使用 Python 客户端管理集合（参见指南）。

POST /api/collections​

在 Hub 上创建一个新集合，包含标题、描述（可选）和第一个项目（可选）。项目由类型（model、dataset、space 或 paper）和 id（Hub 上的 repo_id 或 paper_id）定义。

Payload:

payload = {
    "title": "My cool models",
    "namespace": "username_or_org",
    "description": "Here is a shortlist of models I've trained.",
    "item" : {
        "type": "model",
        "id": "username/cool-model",
    }
    "private": false,

}

这等价于 huggingface_hub.create_collection()。

GET /api/collections/{namespace}/{slug}-{id}​

返回有关集合的信息。

这等价于 huggingface_hub.get_collection()。

GET /api/collections​

根据某些条件列出 Hub 中的集合。支持的参数包括：

  • owner (string)：筛选由特定用户或组织创建的集合。
  • item (string)：筛选包含特定项目的集合。值必须是 item_type 和 item_id 的连接。示例："models/teknium/OpenHermes-2.5-Mistral-7B"、"datasets/rajpurkar/squad" 或 "papers/2311.12983"。
  • sort (string)：对返回的集合进行排序。支持的值有 "lastModified"、"trending"（默认）和 "upvotes"。
  • limit (int)：每页的最大集合数（100）。
  • q (string)：基于标题和描述的子字符串进行筛选。

如果未设置任何参数，则返回所有集合。

响应是分页的。要获取所有集合，你必须遵循 Link 标头。

warning

列出集合时，每个集合的项目列表最多截断为 4 个项目。要检索集合中的所有项目，你需要使用其集合 slug 进行额外调用。

Payload:

params = {
    "owner": "TheBloke",
    "item": "models/teknium/OpenHermes-2.5-Mistral-7B",
    "sort": "lastModified",
    "limit" : 1,
}

这等价于 huggingface_hub.list_collections()。

PATCH /api/collections/{namespace}/{slug}-{id}​

更新 Hub 上集合的元数据。你不能使用此方法添加或修改集合的项目。Payload 的所有字段都是可选的。

Payload:

payload = {
    "title": "My cool models",
    "description": "Here is a shortlist of models I've trained.",
    "private": false,
    "position": 0, // 集合在你个人资料中的位置
    "theme": "green",
}

这等价于 huggingface_hub.update_collection_metadata()。

DELETE /api/collections/{namespace}/{slug}-{id}​

删除集合。这是一个不可逆的操作。已删除的集合无法恢复。

这等价于 huggingface_hub.delete_collection()。

POST /api/collections/{namespace}/{slug}-{id}/item​

向集合添加项目。项目由类型（model、dataset、space 或 paper）和 id（Hub 上的 repo_id 或 paper_id）定义。也可以将注释附加到项目（可选）。

Payload:

payload = {
    "item" : {
        "type": "model",
        "id": "username/cool-model",
    }
    "note": "Here is the model I trained on ...",
}

这等价于 huggingface_hub.add_collection_item()。

PATCH /api/collections/{namespace}/{slug}-{id}/items/{item_id}​

更新集合中的项目。你必须知道项目对象 id，它与将项目添加到集合时提供的 repo_id/paper_id 不同。可以通过获取集合来检索 item_id。

你可以更新附加到项目的注释或项目在集合中的位置。这两个字段都是可选的。

payload = {
    "position": 0,
    "note": "Here is the model I trained on ...",
}

这等价于 huggingface_hub.update_collection_item()。

DELETE /api/collections/{namespace}/{slug}-{id}/items/{item_id}​

从集合中移除项目。你必须知道项目对象 id，它与将项目添加到集合时提供的 repo_id/paper_id 不同。可以通过获取集合来检索 item_id。

这等价于 huggingface_hub.delete_collection_item()。

Last updated on