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 操場

想嘗試我們的 API 嗎？現在就在我們的操場上試試吧！

倉庫列表 API

以下端點用於獲取 Hub 中儲存的模型、資料集和 Space 的資訊。

GET /api/models

獲取 Hub 中所有模型的資訊。響應是分頁的，使用 Link 頭 獲取下一頁。您可以指定額外的引數以獲得更具體的結果。

• search：根據倉庫及其使用者名稱的子字串進行過濾，例如 resnet 或 microsoft
• author：按作者或組織過濾模型，例如 huggingface 或 microsoft
• filter：根據標籤過濾，例如 text-classification 或 spacy。
• sort：用於排序的屬性，例如 downloads 或 author。
• direction：排序方向，例如 -1 表示降序，其他表示升序。
• limit：限制獲取的模型數量。
• full：是否獲取大部分模型資料，例如所有標籤、檔案等。
• config：是否同時獲取倉庫配置。

有效負載

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：是否獲取大部分資料集資料，例如所有標籤、檔案等。

有效負載

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：是否獲取大部分資料集資料，例如所有標籤、檔案等。

有效負載

params = {"full": "full"}

這等同於 huggingface_hub.dataset_info(repo_id, revision)。

GET /api/datasets/{repo_id}/parquet

獲取自動轉換的 parquet 檔案列表。

在 URL 中追加子集和拆分以獲取特定子集和拆分的檔案列表

• 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 個分片，適用於特定子集（也稱為“配置”）和拆分。

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：是否獲取大部分模型資料，例如所有標籤、檔案等。

有效負載

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}

獲取特定模型的所有資訊。

這等同於 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 = {
    "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 = {
    "type": "model",
    "name": "name",
    "organization": "organization",
}

這等同於 huggingface_hub.delete_repo()。

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

更新倉庫可見性。

有效負載

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

這等同於 huggingface_hub.update_repo_settings()。

POST /api/repos/move

移動倉庫（在同一名稱空間內重新命名或從使用者轉移到組織）。

引數量

• fromRepo：要重新命名的倉庫。
• toRepo：倉庫的新名稱。
• type：倉庫型別（dataset 或 space；預設為 model）。

有效負載

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

這等同於 huggingface_hub.move_repo()。

使用者 API

以下端點獲取使用者的資訊。

GET /api/whoami-v2

獲取使用者名稱和使用者所屬的組織。

有效負載

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

這等同於 huggingface_hub.whoami()。

組織 API

以下端點獲取組織成員列表。

GET /api/organizations/{organization_name}/members

獲取組織成員。

有效負載

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

這等同於 huggingface_hub.list_organization_members()。

資源組 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 = {
    "name": "name",
    "description": "description",
    "users": [
        {
            "user": "username",
            "role": "admin" // or "write" or "read"
        }
    ],
    "repos": [
        {
            "type": "dataset",
            "name": "huggingface/repo"
        }
    ]
}

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

更新資源組的元資料。

引數量

• name：資源組的新名稱（可選）
• description：資源組的新描述（可選）

有效負載

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

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

更新資源組設定。

有效負載

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

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

刪除資源組。

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

向資源組新增使用者。

有效負載

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

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

將使用者從資源組中移除。

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

更新使用者在資源組中的角色。

有效負載

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

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

更新資源組的倉庫。

有效負載

payload = {
    "resourceGroupId": "6771d4700000000000000000" // (allow `null` for removing the repo's resource group)
}

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。您也可以傳遞月份，例如 https://huggingface.co/api/daily_papers?month=2025-04 或周，例如 https://huggingface.co/api/daily_papers/week/2025-W16。

集合 API

使用集合可以在專用頁面上對 Hub 中的倉庫（模型、資料集、Spaces 和論文）進行分組。

您可以在集合指南中瞭解更多資訊。集合也可以使用 Python 客戶端管理（參見指南）。

POST /api/collections

在 Hub 上建立一個新的集合，包含標題、描述（可選）和第一個專案（可選）。專案由型別（model、dataset、space 或 paper）和 ID（Hub 上的 repo_id 或 paper_id）定義。

有效負載

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（字串）：篩選特定使用者或組織建立的集合。
• item（字串）：篩選包含特定專案的集合。值必須是 item_type 和 item_id 的串聯。示例："models/teknium/OpenHermes-2.5-Mistral-7B"、"datasets/rajpurkar/squad" 或 "papers/2311.12983"。
• sort（字串）：對返回的集合進行排序。支援的值有 "lastModified"、"trending"（預設）和 "upvotes"。
• limit（整數）：每頁集合的最大數量（100）。
• q（字串）：根據標題和描述的子字串進行篩選。

如果沒有設定引數，則返回所有集合。

響應是分頁的。要獲取所有集合，您必須遵循 Link header。

有效負載

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 = {
    "title": "My cool models",
    "description": "Here is a shortlist of models I've trained.",
    "private": false,
    "position": 0, // position of the collection on your profile
    "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 = {
    "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()。