Hub API로 모델·제공자 조회하기

허브(Hub)는 Inference Providers와 상호작용하기 위한 몇 가지 API를 제공해요. 목록을 살펴볼게요.

모델 목록 조회

특정 제공자가 서빙하는 모델을 나열하려면 inference_provider 쿼리 파라미터를 쓰세요:

# List all models served by Fireworks AI
~ curl -s https://huggingface.co/api/models?inference_provider=fireworks-ai | jq ".[].id"
"deepseek-ai/DeepSeek-V3-0324"
"deepseek-ai/DeepSeek-R1"
"Qwen/QwQ-32B"
"deepseek-ai/DeepSeek-V3"
...

다른 필터와 결합해서 예를 들어 text-to-image 모델만 고를 수도 있어요:

# List text-to-image models served by Fal AI
~ curl -s https://huggingface.co/api/models?inference_provider=fal-ai&pipeline_tag=text-to-image | jq ".[].id"

"black-forest-labs/FLUX.1-dev"
"stabilityai/stable-diffusion-3.5-large"
"black-forest-labs/FLUX.1-schnell"
"stabilityai/stable-diffusion-3.5-large-turbo"
...

쉼표로 구분한 제공자 목록을 넘기면 여러 제공자를 선택할 수 있어요:

# List image-text-to-text models served by Novita or Nscale
~ curl -s https://huggingface.co/api/models?inference_provider=nscale,novita&pipeline_tag=image-text-to-text | jq ".[].id"

"meta-llama/Llama-3.2-11B-Vision-Instruct"
"meta-llama/Llama-3.2-90B-Vision-Instruct"
"Qwen/Qwen2-VL-72B-Instruct"

마지막으로, 적어도 하나의 inference 제공자가 서빙하는 모든 모델을 선택할 수도 있어요:

# List text-to-video models served by any provider
~ curl -s https://huggingface.co/api/models?inference_provider=all&pipeline_tag=text-to-video | jq ".[].id"

"Wan-AI/Wan2.1-T2V-14B"
"Lightricks/LTX-Video"
"tencent/HunyuanVideo"
"Wan-AI/Wan2.1-T2V-1.3B"
"THUDM/CogVideoX-5b"
"genmo/mochi-1-preview"
"BagOu22/Lora_HKLPAZ"

같은 필터는 터미널의 hf CLI에서도 쓸 수 있어요:

# List models served by at least one inference provider
hf models ls --warm

# Search served models for GLM-5.2
hf models ls --warm --search GLM-5.2

# List text-to-image models served by Fal AI
hf models ls --inference-provider fal-ai --pipeline-tag text-to-image

# List models served by Fireworks AI, most downloaded first
hf models ls --inference-provider fireworks-ai --sort downloads

--inference-provider를 반복해서 여러 제공자 중 어느 하나라도 서빙하는 모델을 매칭할 수 있어요. --expand inferenceProviderMapping을 추가하면 어떤 제공자가 각 모델을 서빙하는지와 제공자별 모델 id를 볼 수 있고, --json은 기계가 읽기 좋은 출력을 줍니다.

모델 상태 조회

특정 모델에 어떤 inference 제공자가 있는지 찾으려면 모델 정보 엔드포인트에서 inference 속성을 요청하세요:

# Get google/gemma-3-27b-it inference status (warm)
~ curl -s https://huggingface.co/api/models/google/gemma-3-27b-it?expand[]=inference
{
"_id": "67c35b9bb236f0d365bf29d3",
"id": "google/gemma-3-27b-it",
"inference": "warm"
}

huggingface_hub에서는 expand 파라미터와 함께 model_info를 써요:

>>> from huggingface_hub import model_info

>>> info = model_info("google/gemma-3-27b-it", expand="inference")
>>> info.inference
'warm'

Inference 상태는 "warm"이거나 정의되지 않아요:

# Get inference status (no inference)
~ curl -s https://huggingface.co/api/models/manycore-research/SpatialLM-Llama-1B?expand[]=inference
{
"_id": "67d3b141d8b6e20c6d009c8b",
"id": "manycore-research/SpatialLM-Llama-1B"
}

huggingface_hub에서는:

>>> from huggingface_hub import model_info

>>> info = model_info("manycore-research/SpatialLM-Llama-1B", expand="inference")
>>> info.inference
None

OpenAI 호환 모델 목록 조회

라우터는 Inference Providers가 서빙하는 채팅 완성 모델 목록을, 라우팅·비교에 쓰는 제공자 메타데이터와 함께 반환하는 OpenAI 호환 엔드포인트를 노출해요:

~ curl -s https://router.huggingface.co/v1/models | jq '.data'
{
  "id": "deepseek-ai/DeepSeek-V4-Pro",
  "object": "model",
  "created": 1776837885,
  "owned_by": "deepseek-ai",
  "architecture": {
    "input_modalities": [
      "text"
    ],
    "output_modalities": [
      "text"
    ]
  },
  "providers": [
    {
      "provider": "novita",
      "status": "live",
      "context_length": 1048576,
      "pricing": {
        "input": 1.69,
        "output": 3.38
      },
      "supports_tools": true,
      "supports_structured_output": false,
      "first_token_latency_ms": 1490,
      "throughput": 24.69124008437934,
      "is_model_author": false
    },
    {
      "provider": "together",
      "status": "live",
      "context_length": 512000,
      "pricing": {
        "input": 2.1,
        "output": 4.4
      },
      "supports_tools": true,
      "supports_structured_output": true,
      "first_token_latency_ms": 611,
      "throughput": 40.13113557470821,
      "is_model_author": false
    },
    {
      "provider": "fireworks-ai",
      "status": "live",
      "context_length": 1048576,
      "supports_tools": true,
      "supports_structured_output": true,
      "first_token_latency_ms": 588.4,
      "throughput": 45.42948747753918,
      "is_model_author": false
    },
    {
      "provider": "featherless-ai",
      "status": "live",
      "is_model_author": false
    },
    {
      "provider": "deepinfra",
      "status": "live",
      "context_length": 65536,
      "pricing": {
        "input": 1.74,
        "output": 3.48
      },
      "supports_tools": true,
      "supports_structured_output": true,
      "first_token_latency_ms": 525.8,
      "throughput": 34.615908579189465,
      "is_model_author": false
    }
  ]
}
...

단일 모델을 가져오려면 모델 id를 엔드포인트에 붙이세요:

~ curl -s https://router.huggingface.co/v1/models/deepseek-ai/DeepSeek-V4-Pro | jq '.'

각 제공자 항목에는 다음 필드가 있을 수 있어요:

Field	Type	Description
`provider`	string	Provider identifier
`status`	string	`live` or `error`
`context_length`	number	Maximum context length supported by this provider for the model, when available
`pricing`	object	`input` and `output` prices in USD per million tokens, when available
`is_free`	boolean	Whether the model is currently free of charge on this provider (temporary promo), when applicable
`supports_tools`	boolean	Whether the provider supports tool calling, when available
`supports_structured_output`	boolean	Whether the provider supports structured output, when available
`first_token_latency_ms`	number	Time to first token in milliseconds from the latest validation probe, when available
`throughput`	number	Output throughput in tokens per second from the latest validation probe, when available
`is_model_author`	boolean	Whether the model was published by this provider

이 지표들은 제공자 비교 표에 표시되는 것과 같은 제공자 성능 신호예요. 일부 제공자·모델에는 최신 프로브 데이터가 없을 수 있어서 전부 선택 사항입니다.

모델 제공자 조회

특정 모델에 관심이 있고 어떤 제공자가 서빙하는지 확인하고 싶다면, 모델 정보 엔드포인트에서 inferenceProviderMapping 속성을 요청하세요:

# List google/gemma-3-27b-it providers
~ curl -s https://huggingface.co/api/models/google/gemma-3-27b-it?expand[]=inferenceProviderMapping
{
    "_id": "67c35b9bb236f0d365bf29d3",
    "id": "google/gemma-3-27b-it",
    "inferenceProviderMapping": {
        featherless-ai: {
            status: live,
            providerId: google/gemma-3-27b-it,
            task: conversational,
            isModelAuthor: false
        },
        scaleway: {
            status: live,
            providerId: gemma-3-27b-it,
            task: conversational,
            isModelAuthor: false
        }
    }
}

huggingface_hub에서는 expand 파라미터와 함께 model_info를 써요:

>>> from huggingface_hub import model_info

>>> info = model_info("google/gemma-3-27b-it", expand="inferenceProviderMapping")
>>> info.inference_provider_mapping
{
    'featherless-ai': InferenceProviderMapping(status='live', provider_id='google/gemma-3-27b-it', task='conversational'),
    'scaleway': InferenceProviderMapping(status='live', provider_id='google/gemma-3-27b-it-fast', task='conversational'),
}

각각 모델을 서빙하는 제공자는 상태(staging 또는 live), 관련 작업(여기선 conversational), providerId를 보여줘요. 실무에서는 이 정보가 JS·Python 클라이언트에 유용합니다.

더 알아보기 (Learn more)

Inference Providers 개요

출처: 공식문서