huggingface-tool-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugging Face API Tool Builder

Hugging Face API 工具构建器

Your purpose is now is to create reusable command line scripts and utilities for using the Hugging Face API, allowing chaining, piping and intermediate processing where helpful. You can access the API directly, as well as use the

hf

command line tool. Model and Dataset cards can be accessed from repositories directly.

你现在的任务是生成可复用的命令行脚本和工具，用于调用Hugging Face API，在需要的场景下支持链路串联、管道传输和中间处理。你可以直接访问API，也可以使用

hf

命令行工具。模型和数据集卡片可以直接从代码仓库获取。

Script Rules

脚本规则

Make sure to follow these rules:

Scripts must take a
```
--help
```
command line argument to describe their inputs and outputs
Non-destructive scripts should be tested before handing over to the User
Shell scripts are preferred, but use Python or TSX if complexity or user need requires it.
IMPORTANT: Use the
```
HF_TOKEN
```
environment variable as an Authorization header. For example:
```
curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/
```
. This provides higher rate limits and appropriate authorization for data access.
Investigate the shape of the API results before commiting to a final design; make use of piping and chaining where composability would be an advantage - prefer simple solutions where possible.
Share usage examples once complete.

Be sure to confirm User preferences where there are questions or clarifications needed.

请务必遵循以下规则：

脚本必须支持
```
--help
```
命令行参数，用于描述其输入和输出
非破坏性脚本在交付给用户前必须完成测试
优先使用Shell脚本，若复杂度较高或用户有明确需求，可使用Python或TSX
重要提示：使用
```
HF_TOKEN
```
环境变量作为授权头。示例：
```
curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/
```
。这种方式可以获得更高的请求频率限制，以及数据访问的对应授权。
在确定最终设计前，先调研API返回结果的结构；在可组合性有优势的场景下优先使用管道和链路串联，尽可能选择简单的解决方案
脚本完成后提供使用示例

如果存在疑问或需要澄清的内容，务必确认用户的偏好。

Sample Scripts

示例脚本

Paths below are relative to this skill directory.

Reference examples:

```
references/hf_model_papers_auth.sh
```
— uses
```
HF_TOKEN
```
automatically and chains trending → model metadata → model card parsing with fallbacks; it demonstrates multi-step API usage plus auth hygiene for gated/private content.
```
references/find_models_by_paper.sh
```
— optional
```
HF_TOKEN
```
usage via
```
--token
```
, consistent authenticated search, and a retry path when arXiv-prefixed searches are too narrow; it shows resilient query strategy and clear user-facing help.
```
references/hf_model_card_frontmatter.sh
```
— uses the
```
hf
```
CLI to download model cards, extracts YAML frontmatter, and emits NDJSON summaries (license, pipeline tag, tags, gated prompt flag) for easy filtering.

Baseline examples (ultra-simple, minimal logic, raw JSON output with

HF_TOKEN

header):

```
references/baseline_hf_api.sh
```
— bash
```
references/baseline_hf_api.py
```
— python
```
references/baseline_hf_api.tsx
```
— typescript executable

Composable utility (stdin → NDJSON):

```
references/hf_enrich_models.sh
```
— reads model IDs from stdin, fetches metadata per ID, emits one JSON object per line for streaming pipelines.

Composability through piping (shell-friendly JSON output):

references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'

references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'

printf '%s\n' openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s 'map({id, license, has_extra_gated_prompt})'

以下路径均相对于该Skill的目录。

参考示例：

```
references/hf_model_papers_auth.sh
```
— 自动使用
```
HF_TOKEN
```
，串联了热门榜单→模型元数据→模型卡片解析的全流程并提供降级方案；展示了多步API调用，以及访问受限/私有内容的授权规范。
```
references/find_models_by_paper.sh
```
— 支持通过
```
--token
```
参数可选传入
```
HF_TOKEN
```
，提供一致的鉴权搜索能力，以及当arXiv前缀搜索范围过窄时的重试路径；展示了健壮的查询策略和清晰的用户帮助说明。
```
references/hf_model_card_frontmatter.sh
```
— 使用
```
hf
```
CLI下载模型卡片，提取YAML头信息，输出NDJSON格式的摘要（许可证、流水线标签、标签、受限访问提示标识），便于过滤处理。

基础示例（极简、逻辑最少、携带

HF_TOKEN

头的原始JSON输出）：

```
references/baseline_hf_api.sh
```
— bash
```
references/baseline_hf_api.py
```
— python
```
references/baseline_hf_api.tsx
```
— typescript 可执行文件

可组合工具（标准输入→NDJSON）：

```
references/hf_enrich_models.sh
```
— 从标准输入读取模型ID，拉取每个ID对应的元数据，每行输出一个JSON对象，适配流式处理流水线。

通过管道实现可组合性（适配Shell的JSON输出）：

references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'

references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'

printf '%s\n' openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s 'map({id, license, has_extra_gated_prompt})'

High Level Endpoints

核心API端点

The following are the main API endpoints available at

https://huggingface.co

/api/datasets
/api/models
/api/spaces
/api/collections
/api/daily_papers
/api/notifications
/api/settings
/api/whoami-v2
/api/trending
/oauth/userinfo

以下是

https://huggingface.co

下的主要API端点：

/api/datasets
/api/models
/api/spaces
/api/collections
/api/daily_papers
/api/notifications
/api/settings
/api/whoami-v2
/api/trending
/oauth/userinfo

Accessing the API

访问API

The API is documented with the OpenAPI standard at

https://huggingface.co/.well-known/openapi.json

IMPORTANT: DO NOT ATTEMPT to read

https://huggingface.co/.well-known/openapi.json

directly as it is too large to process.

IMPORTANT Use

jq

to query and extract relevant parts. For example,

Command to Get All 160 Endpoints

bash

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'

Model Search Endpoint Details

bash

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'

You can also query endpoints to see the shape of the data. When doing so constrain results to low numbers to make them easy to process, yet representative.

该API遵循OpenAPI规范，文档地址为

https://huggingface.co/.well-known/openapi.json

。

重要提示：请勿直接读取
https://huggingface.co/.well-known/openapi.json
，因为文件体积过大，无法处理。

重要提示 使用

jq

来查询和提取相关部分。例如：

获取全部160个端点的命令

bash

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'

模型搜索端点详情

bash

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'

你也可以直接请求端点查看数据结构。请求时请限制返回结果的数量，既方便处理，又能保证结果的代表性。

Using the HF command line tool

使用HF命令行工具

The

hf

command line tool gives you further access to Hugging Face repository content and infrastructure.

bash

❯ hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --help                Show this message and exit.

Commands:
  auth                 Manage authentication (login, logout, etc.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  discussions          Manage discussions and pull requests on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  upload               Upload a file or a folder to the Hub.
  upload-large-folder  Upload a large folder to the Hub.
  version              Print information about the hf version.
  webhooks             Manage webhooks on the Hub.

The

hf

CLI command has replaced the now deprecated

huggingface-cli

command.

hf

命令行工具可以让你进一步访问Hugging Face仓库内容和基础设施。

bash

❯ hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --help                Show this message and exit.

Commands:
  auth                 Manage authentication (login, logout, etc.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  discussions          Manage discussions and pull requests on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  upload               Upload a file or a folder to the Hub.
  upload-large-folder  Upload a large folder to the Hub.
  version              Print information about the hf version.
  webhooks             Manage webhooks on the Hub.

hf

CLI命令已经替代了现已废弃的

huggingface-cli

命令。