Hugging Face

Hugging Face 是领先的开源与开放科学 AI 平台,核心包括模型/数据/Spaces 的 Hugging Face Hub、推理与托管(Inference Providers 与 Inference Endpoints)、以及丰富的开源库(Transformers、Diffusers、Datasets、Tokenizers、Accelerate、PEFT、TRL、Safetensors、Transformers.js、smolagents、TGI 等)。平台支持文本、图像、音频、视频与 3D 等多模态,提供 Python、JavaScript 与 REST/OpenAI 兼容端点的统一接入。

基础 URL
https://router.huggingface.co/v1
认证
Bearer / Authorization: Bearer hf_XXXXXXXXXXXXXXXXXXXX
官方 SDK
Python, JavaScript
🔑 API Key 获取
前置要求:若使用专用 Inference Endpoints,请在账户或组织的计费页面添加有效支付方式。
入口:https://huggingface.co/settings/tokens
说明:在 Hugging Face 令牌页面生成访问令牌(建议选择 fine-grained 并授予“Make calls to Inference Providers”权限),用于调用 Inference Providers/Hub API/Endpoints。

支持模型

API 接口列表

GET /api/models Docs

分页返回 Hub 中的模型信息,支持 `search`、`author`、`filter`、`sort`、`direction`、`limit`、`full`、`config` 等查询参数。

认证
频率限制60/min
计费模式免费列举;调用不计费
GET /api/models/{repo_id} Docs

返回指定模型仓库的详细信息。支持 `revision` 版本号。

认证
频率限制60/min
计费模式免费查询;调用不计费
GET /api/datasets Docs

分页返回 Hub 中的数据集信息,支持与模型类似的过滤与排序参数。

认证
频率限制60/min
计费模式免费列举;调用不计费
GET /api/spaces Docs

分页返回 Hub 中的 Spaces 应用信息。

认证
频率限制60/min
计费模式免费列举;调用不计费
POST https://router.huggingface.co/v1/chat/completions Docs

OpenAI 兼容聊天补全。`model` 需包含提供商后缀或使用 `:auto`/`:fastest`/`:cheapest` 策略;支持在消息中包含 `image_url`。官方声明当前仅覆盖 Chat Completions。

认证
频率限制60/min
计费模式按提供商透传单价计费;月度赠额后按需付费
{
  "model": "deepseek-ai/DeepSeek-R1:fastest",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}
POST https://router.huggingface.co/v1/responses Docs

(如适用)OpenAI 兼容 Responses API,用于更高级的事件流、结构化输出与工具调用(例如 gpt-oss 系列)。

认证
频率限制60/min
计费模式按提供商透传单价计费;月度赠额后按需付费
{
  "model": "openai/gpt-oss-120b:cerebras",
  "input": "Tell me a fun fact about the Eiffel Tower."
}
POST https://api-inference.huggingface.co/models/{model_id} Docs

无服务器 Inference API 执行指定模型的推理,请求/响应结构取决于任务类型(文本生成、图像生成、ASR 等)。

认证
频率限制60/min
计费模式按执行时间计费;性能随模型与资源而变
curl -s -H 'Authorization: Bearer $HF_TOKEN' -H 'Content-Type: application/json' https://api-inference.huggingface.co/models/{model_id}
POST https://{your-endpoint-subdomain}.endpoints.huggingface.cloud/v1/chat/completions Docs

专用 Inference Endpoints(TGI)上的 OpenAI 兼容聊天补全,需使用该端点的 `hf_...` API key。

认证
频率限制60/min
计费模式按计算实例小时计费(自动扩缩)
{
  "model": "meta-llama/Meta-Llama-3-8B-Instruct",
  "messages": [
    {
      "role": "user",
      "content": "Explain transformers in one sentence."
    }
  ]
}
POST https://api-inference.huggingface.co/models/black-forest-labs/FLUX.1-dev Docs

图像生成示例(文本到图像)。请求为文本提示,返回图像二进制或 base64。

认证
频率限制60/min
计费模式按执行时间或提供商计费
{
  "inputs": "A steampunk airship in the clouds"
}
POST https://api-inference.huggingface.co/models/openai/whisper-large-v3 Docs

语音识别示例(ASR)。上传音频或字节流,返回转录文本。

认证
频率限制60/min
计费模式按执行时间或提供商计费
curl -s -H 'Authorization: Bearer $HF_TOKEN' -H 'Content-Type: audio/wav' --data-binary @sample.wav https://api-inference.huggingface.co/models/openai/whisper-large-v3
GET /.well-known/openapi.json Docs

Hub API 的 OpenAPI 规范,可用于生成客户端与查看所有端点。

认证
频率限制60/min
计费模式免费查询;调用不计费