API de Inferência do Hugging Face: Como Funciona, Quanto Custa e Quando Usá-la

A API de Inferência do Hugging Face oferece aos desenvolvedores acesso REST a centenas de modelos de código aberto — LLMs, modelos de incorporação (embedding), geradores de imagens, modelos de fala e classificadores — sem necessidade de provisionar qualquer infraestrutura. Você se autentica com um único token do HF, envia solicitações à camada de roteamento do Hugging Face e esta as encaminha ao provedor subjacente que tiver o modelo pré-carregado e pronto para uso. A partir de 2025, esse serviço é oficialmente chamado de Provedores de InferênciaProvedores de Inferência

O Que É a API de Inferência do Hugging Face (e O Que Mudou)

Originalmente, a "API de Inferência" referia-se a um serviço serverless hospedado pelo Hugging Face em api-inference.huggingface.co que carregava modelos sob demanda. Esse serviço ainda existe como o provedor hf-inference hf-inference

Para inferência acelerada por GPU — LLMs grandes, geração de imagens, processamento de fala — o Hugging Face agora roteia solicitações por meio de provedores parceiros: Groq, Together AI, Fireworks, Cerebras, DeepInfra, Replicate, Fal AI e outros. A interface permanece inalterada: um único token, uma única URL base e formato de solicitação compatível com OpenAI. A URL do roteador é https://router.huggingface.co/v1router.huggingface.co/v1 api-inference.huggingface.co A antiga URL hf-inferenceapi-inference.huggingface.co

Como o Roteador Funciona

Quando você envia uma solicitação para router.huggingface.coo Hugging Face seleciona um provedor com base em uma política que você anexa ao ID do modelo:

Anexe diretamente a política à string do ID do modelo: "deepseek-ai/DeepSeek-R1:cheapest". A ausência de sufixo implica o comportamento padrão :fastest:fastest

Autenticação e Sua Primeira Solicitação

Ir para huggingface.co/settings/tokenscrie um token granular e habilite a permissão Efetuar chamadas aos Provedores de Inferência . Defina-o como HF_TOKEN em seu ambiente.

Python — huggingface_hub

pip install huggingface_hub

import os
from huggingface_hub import InferenceClient

client = InferenceClient()  # lê o HF_TOKEN do ambiente

completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3-0324",
    messages=[{"role": "user", "content": "Explique a tokenização em duas frases."}],
)
print(completion.choices[0].message.content)

Python — substituto compatível com OpenAI

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3-0324:fastest",
    messages=[{"role": "user", "content": "Explique a tokenização em duas frases."}],
)
print(completion.choices[0].message.content)

cURL

curl https://router.huggingface.co/v1/chat/completions 
  -H "Authorization: Bearer $HF_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "deepseek-ai/DeepSeek-V3-0324:fastest",
    "messages": [{"role": "user", "content": "Explique a tokenização em duas frases."}]
  }'

O endpoint compatível com OpenAI cobre apenas conclusões de chat. Para outras tarefas — como texto para imagem, embeddings e reconhecimento de fala — use a biblioteca huggingface_hub em Python ou o SDK JavaScript @huggingface/inference , que formatam automaticamente as solicitações conforme os requisitos específicos de cada provedor.

Camada Gratuita, Créditos e Próximos Passos

Toda conta do Hugging Face recebe uma cota mensal de créditos, aplicada automaticamente às solicitações roteadas:

Assim que seus créditos se esgotarem, o acesso não é interrompido — você pode adquirir créditos adicionais para continuar. O Hugging Face cobra exatamente a mesma taxa cobrada pelo provedor, sem nenhuma taxa adicional. O custo de uma determinada solicitação depende do modelo e do provedor; você pode acompanhar os gastos por modelo e por provedor em huggingface.co/settings/inference-providers/overview.

Se você já possui contas com um provedor específico, pode configurar uma chave personalizada do provedor nas configurações do HF. As solicitações ainda são roteadas pelo HF, mas o provedor emite a fatura diretamente para você, e seus créditos mensais do HF não se aplicam. Antes de comprometer-se com um volume maior, utilize a Calculadora de custos de API calculadora de custos para projetar seus gastos mensais por modelo e volume de chamadas.

Inicializações Frias (Cold Starts) e o Provedor hf-inference

O antigo provedor hf-inference Os provedores carregam modelos sob demanda. Quando um modelo não foi chamado recentemente e entrou em estado ocioso, a primeira solicitação dispara o carregamento do modelo antes que a resposta possa começar — trata-se de um 'cold start' (inicialização fria). Isso acrescenta latência perceptível à primeira chamada.

A partir de julho de 2025, hf-inference o roteador concentra-se na inferência em CPU: modelos de embeddings, classificadores, reconhecimento de entidades nomeadas (NER) e modelos de texto menores. Os 'cold starts' são particularmente relevantes nesse contexto.

Para cargas de trabalho aceleradas por GPU — grandes LLMs e geração de imagens — o roteador encaminha as solicitações a provedores terceirizados, como Groq ou Together AI, que operam GPUs compartilhadas pré-carregadas ('warm'). Nesses casos, os 'cold starts' não representam um problema da mesma forma, embora você compartilhe a capacidade disponível e não tenha garantia de vazão durante picos de tráfego.

Se a latência causada por 'cold starts' ou a variabilidade na vazão forem inaceitáveis — por exemplo, para um endpoint de produção sensível à latência — a solução ideal é um Endpoint de Inferência dedicado.

API de Inferência vs. Pontos de Extremidade de Inferência (Inference Endpoints)

A plataforma Hugging Face oferece dois produtos distintos para inferência. Ambos compartilham o mesmo sistema de tokens e o Model Hub, mas operam de maneira muito diferente:

Os Endpoints de Inferência são cobrados por minuto apenas enquanto estiverem no estado de execução ou inicialização — endpoints pausados não geram custos. As opções de GPU da AWS variam desde uma T4 por US$ 0,50/hora (14 GB de VRAM) até uma H200 por US$ 5,00/hora por placa (141 GB de VRAM). As opções da GCP incluem a H100 por US$ 10,00/hora por placa (80 GB de VRAM). Antes de selecionar uma camada, utilize a Calculadora de VRAM calculadora de compatibilidade de hardware para verificar se seu modelo cabe na GPU-alvo.

Como os Preços se Comparam com Outros Provedores

Como o Hugging Face roteia para os mesmos provedores subjacentes — Together AI, Fireworks, DeepInfra e Groq — que também podem ser acessados diretamente ou por meio do OpenRouter, as taxas por token para um dado modelo são, em geral, idênticas. O HF não aplica nenhuma margem adicional.

As diferenças práticas:

• Créditos gratuitos: A Hugging Face concede automaticamente US$ 0,10–US$ 2,00/mês em uso gratuito. O OpenRouter e os provedores diretos não oferecem nenhum equivalente a essa cota mensal.
• Variedade de modelos: Os Provedores de Inferência da HF concentram-se em modelos de pesos abertos provenientes do Hub. O OpenRouter também abrange modelos fechados (GPT-4o, Claude, Gemini). Se você precisa de uma roteador que suporte tanto modelos abertos quanto proprietários, o OpenRouter cobre um espectro mais amplo.
• Tarefas não conversacionais: Incorporações (embeddings), geração de imagens e síntese de fala estão disponíveis por meio do SDK da HF. A maioria dos roteadores concorrentes oferece apenas suporte a conclusões de chat.
• Consolidação de cobrança: Uma única conta da HF abrange todos os provedores, com um painel unificado de uso. Contas de provedores diretos exigem relações de cobrança separadas para cada um.

Para uma comparação completa de modelos quanto a preço e capacidade, consulte a Banco de dados de modelos de IA que abrange especificações e preços de principais modelos.

Quando Pontos de Extremidade Dedicados ou Hospedagem Própria São Mais Adequados

Use os Provedores de Inferência ao fazer protótipos, quando sua carga for variável ou imprevisível e quando precisar acessar um amplo catálogo público de modelos sem gerenciar servidores.

Mude para um Endpoint de Inferência dedicado quando:

• Você precisar implantar um modelo ajustado (fine-tuned) ou privado que não esteja disponível no Hub público.
• A consistência de latência for um requisito — provedores compartilhados podem apresentar tempos de resposta variáveis sob carga.
• Você precisar de throughput garantido para atender a um SLA de produção.

Considere hospedagem própria quando seu volume de chamadas for suficientemente alto para que os custos por token superem o custo amortizado de possuir hardware, ou quando requisitos de privacidade de dados impedirem o envio de entradas a APIs de terceiros. Acalculadora de ponto de equilíbrio entre hospedagem local e uso de API fornece uma comparação concreta de custos com base em seu volume de solicitações e tamanho do modelo. Para recomendações de hardware, caso opte por essa abordagem, consulte a melhores GPUs para executar LLMs localmente.

Perguntas frequentes

Qual é a diferença entre a API de Inferência e os Endpoints de Inferência?

A API de Inferência (atualmente denominada Provedores de Inferência) é um serviço compartilhado, pago por requisição, que roteia para provedores parceiros de GPUs e para a infraestrutura própria de CPUs da HF. Já os Endpoints de Inferência são instâncias dedicadas de GPU que você provisiona em uma região de nuvem; eles executam continuamente um único modelo e são cobrados por minuto de tempo ativo. Use a API para prototipagem e cargas de trabalho variáveis; use os Endpoints para garantias de latência em produção, bem como para modelos privados ou ajustados.

Preciso de uma assinatura Pro para usar a API de Inferência?

Não. Uma conta gratuita inclui US$ 0,10/mês em créditos, o que é suficiente para experimentação leve. Assinantes PRO recebem US$ 2,00/mês. Ambos os níveis permitem a compra sob demanda de créditos adicionais após esgotar a cota mensal. A principal vantagem da assinatura PRO no contexto de inferência é o valor maior da cota mensal, não acesso restrito a modelos ou provedores.

Por que minha primeira solicitação é muito mais lenta do que as subsequentes?

Se você estiver roteando para o provedor hf-inference , os modelos são carregados sob demanda. Um modelo que ficou ocioso deve ser carregado na memória antes que sua solicitação seja concluída, acrescentando latência à primeira chamada. Isso não se aplica a provedores de GPU, como Groq ou Together AI, que operam infraestruturas compartilhadas pré-carregadas (warm). Especificar :fastest ou um provedor nomeado de GPU no identificador do modelo eliminará totalmente esse atraso.

A API de Inferência da HF é compatível com o SDK Python da OpenAI?

Sim, para conclusões de chat. Defina base_url="https://router.huggingface.co/v1" e passe seu token da HF como api_key. O bloco /v1/chat/completions e /v1/models endpoints são compatíveis com a OpenAI. Para outros tipos de tarefa — incorporações (embeddings), geração de imagens e síntese de fala — você precisa usar o huggingface_hub em Python ou o SDK JavaScript @huggingface/inference SDK JavaScript; essas funcionalidades não são cobertas pelo endpoint compatível com a OpenAI.

Posso disponibilizar um modelo ajustado (fine-tuned) por meio da API de Inferência?

Não pelos Provedores de Inferência — eles só disponibilizam modelos disponíveis no catálogo público do Hub e compatíveis com algum provedor parceiro. Para um modelo privado ou ajustado, implante um Endpoint de Inferência dedicado, que suporta repositórios privados do Hub e permite trazer seus próprios pesos de modelo para uma instância de GPU sob seu controle.

Como acompanho e controlo meus custos?

O detalhamento do seu uso por modelo e provedor está disponível em huggingface.co/settings/inference-providers/overview. Administradores de equipes e de planos Enterprise podem definir limites de gastos e desabilitar provedores específicos na página de configurações da organização. Para estimativas prospectivas de custos antes de iniciar o desenvolvimento, utilize a Calculadora de custos de API.