# Hugging Face Model

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/huggingface/model` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/huggingface-model |

## Description

Read one public Hugging Face model by an id such as google-bert/bert-base-uncased.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/huggingface/model' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### bert-base-uncased

```json
{
  "id": "google-bert/bert-base-uncased",
  "sha": "86b5e0934494bd15c9632b12f734a8a67f723594",
  "url": "https://huggingface.co/google-bert/bert-base-uncased",
  "tags": [
    "transformers",
    "pytorch",
    "tf",
    "jax",
    "rust",
    "coreml",
    "onnx",
    "safetensors",
    "bert",
    "fill-mask",
    "exbert",
    "en",
    "dataset:bookcorpus",
    "dataset:wikipedia",
    "arxiv:1810.04805",
    "license:apache-2.0",
    "endpoints_compatible",
    "deploy:sagemaker",
    "deploy:azure",
    "region:us"
  ],
  "gated": false,
  "likes": 3060,
  "author": "google-bert",
  "license": "apache-2.0",
  "private": false,
  "datasets": [
    "bookcorpus",
    "wikipedia"
  ],
  "disabled": false,
  "language": [
    "en"
  ],
  "downloads": 29160167,
  "created_at": "2022-03-02T23:29:04.000Z",
  "mask_token": "[MASK]",
  "library_name": "transformers",
  "pipeline_tag": "fill-mask",
  "last_modified": "2024-02-19T11:06:12.000Z",
  "trending_score": null
}
```

## Documentation

## Overview

Read one public model from the Hugging Face models API. Pass `owner/name` from search, or the model page URL. The response is a flat record. For `google-bert/bert-base-uncased` the id, likes, and downloads match the search card for that same id.

## Quickstart

```
GET https://api.piloterr.com/v2/huggingface/model?query=google-bert/bert-base-uncased
GET https://api.piloterr.com/v2/huggingface/model?query=https://huggingface.co/google-bert/bert-base-uncased
```

GET and POST take the same `query`. The record is `fill-mask` on `transformers`, license `apache-2.0`, language `en`, mask token `[MASK]`, datasets `bookcorpus` and `wikipedia`.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `google-bert/bert-base-uncased` |

`query` is required. A model URL on `huggingface.co` is reduced to the id. Suffixes such as `/discussions` or `/tree/main` are removed. The first path segment cannot be a reserved site section (`models`, `datasets`, `spaces`, `docs`, and similar). Another host returns 400.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `id` | string | Model id, `owner/name` |
| `author` | string or null | Owner |
| `url` | string | `https://huggingface.co/` plus the id |
| `pipeline_tag` | string or null | Task, such as `fill-mask` |
| `library_name` | string or null | Library, such as `transformers` |
| `likes` | number or null | Likes. Same value as the search card when both calls see the same revision |
| `downloads` | number or null | Downloads |
| `trending_score` | number or null | Trending score |
| `private` | boolean or null | Private flag |
| `gated` | boolean, string, or null | Gated-access flag. `false` on bert-base-uncased |
| `disabled` | boolean or null | Disabled flag |
| `sha` | string or null | Revision |
| `last_modified` | string or null | Last update |
| `created_at` | string or null | Creation time |
| `license` | string or null | License from the model card, such as `apache-2.0` |
| `language` | array or null | Languages. A single card value becomes a one-item array |
| `datasets` | array | Datasets named on the card. Empty array when none are listed |
| `tags` | array | Tags |
| `mask_token` | string or null | Mask token when the model exposes one, such as `[MASK]` |

There is no `results` wrapper.

## Use cases

- Check `apache-2.0` and `fill-mask` on `google-bert/bert-base-uncased` before a download.
- Read `mask_token` `[MASK]` and `language` `["en"]` for a fill-mask pipeline.
- Compare `likes` and `downloads` with the search card for the same id.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty query, a reserved path, or a domain outside huggingface.co |
| `401` | Missing API key |
| `404` | No model with that id |
| `500` | The fetch failed |

## Related endpoints

[Hugging Face Search](https://www.piloterr.com/library/huggingface-search)