--- title: Hugging Face description: Learn how to use Hugging Face with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/huggingface" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). The [Hugging Face](https://huggingface.co/) provider offers access to thousands of language models through [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index), including models from Meta, DeepSeek, Qwen, and more. Use [AI Gateway](/providers/ai-sdk-providers/ai-gateway) for the shared models shown below, served by Gateway's supported providers, or use `@ai-sdk/huggingface` to send requests directly to Hugging Face. Gateway does not currently route requests to Hugging Face. ```ts provider="huggingface" model="meta/llama-3.3-70b" import { generateText } from 'ai'; const { text } = await generateText({ model: "meta/llama-3.3-70b", prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); console.log(text); ``` ## Using AI Gateway The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. The current [Gateway provider list](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options#available-providers) does not include Hugging Face as an inference provider. The Gateway tab calls models also available from Hugging Face, but Gateway routes them through its supported inference providers. It does not send the request to Hugging Face. Use the direct tab to call Hugging Face; do not set `providerOptions.gateway.order` to an unsupported provider slug. ## Using `@ai-sdk/huggingface` For direct access to Hugging Face, install `ai` and `@ai-sdk/huggingface`: ```bash pnpm add ai @ai-sdk/huggingface ``` Set your Hugging Face API credential in the `HUGGINGFACE_API_KEY` environment variable: ```bash export HUGGINGFACE_API_KEY=your_api_key_here ``` Use `@ai-sdk/huggingface` to authenticate with your Hugging Face account and call its platform APIs directly. The Gateway alternative above uses a supported inference provider instead. The following sections document the direct `@ai-sdk/huggingface` provider, including its model factories and settings. Gateway model and feature availability can differ. API keys can be obtained from [Hugging Face Settings](https://huggingface.co/settings/tokens). ## Provider Instance You can import the default provider instance `huggingFace` from `@ai-sdk/huggingface`: ```ts import { huggingFace } from '@ai-sdk/huggingface'; ``` For custom configuration, you can import `createHuggingFace` and create a provider instance with your settings: ```ts import { createHuggingFace } from '@ai-sdk/huggingface'; const huggingFace = createHuggingFace({ apiKey: process.env.HUGGINGFACE_API_KEY ?? '', }); ``` You can use the following optional settings to customize the Hugging Face provider instance: - **baseURL** *string* Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is `https://router.huggingface.co/v1`. - **apiKey** *string | PromiseLike\ | (() => string | PromiseLike\)* Pass a function to resolve credentials before each request, including when keys rotate. The function can return a string or a promise. Credential caching and refresh are managed by the function. API key that is being sent using the `Authorization` header. It defaults to the `HUGGINGFACE_API_KEY` environment variable. You can get your API key from [Hugging Face Settings](https://huggingface.co/settings/tokens). - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation. ## Language Models You can create language models using a provider instance: ```ts import { huggingFace } from '@ai-sdk/huggingface'; import { generateText } from 'ai'; const { text } = await generateText({ model: huggingFace('deepseek-ai/DeepSeek-V3-0324'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); ``` You can also use the `.responses()` or `.languageModel()` factory methods: ```ts const model = huggingFace.responses('deepseek-ai/DeepSeek-V3-0324'); // or const model = huggingFace.languageModel('moonshotai/Kimi-K2-Instruct'); ``` Hugging Face language models can be used in the `streamText` function (see [AI SDK Core](/docs/ai-sdk-core)). You can explore the latest and trending models with their capabilities, context size, throughput and pricing on the [Hugging Face Inference Models](https://huggingface.co/inference/models) page. ### Provider Options Hugging Face language models support provider-specific options that you can pass via `providerOptions.huggingface`: ```ts import { huggingFace } from '@ai-sdk/huggingface'; import { generateText } from 'ai'; const { text } = await generateText({ model: huggingFace('deepseek-ai/DeepSeek-R1'), prompt: 'Explain the theory of relativity.', providerOptions: { huggingface: { reasoningEffort: 'high', instructions: 'Respond in a clear and educational manner.', }, }, }); ``` The following provider options are available: - **metadata** *Record\* Additional metadata to include with the request. - **instructions** *string* Instructions for the model. Can be used to provide additional context or guidance. - **strictJsonSchema** *boolean* Whether to use strict JSON schema validation for structured outputs. Defaults to `false`. - **reasoningEffort** *string* Controls the reasoning effort for reasoning models like DeepSeek-R1. Higher values result in more thorough reasoning. ### Reasoning Output For reasoning models like `deepseek-ai/DeepSeek-R1`, you can control the reasoning effort and access the model's reasoning process in the response: ```ts import { huggingFace } from '@ai-sdk/huggingface'; import { streamText } from 'ai'; const result = streamText({ model: huggingFace('deepseek-ai/DeepSeek-R1'), prompt: 'How many r letters are in the word strawberry?', providerOptions: { huggingface: { reasoningEffort: 'high', }, }, }); for await (const part of result.stream) { if (part.type === 'reasoning') { console.log(`Reasoning: ${part.textDelta}`); } else if (part.type === 'text-delta') { process.stdout.write(part.textDelta); } } ``` For non-streaming calls with `generateText`, the reasoning content is available in the `reasoning` field of the response: ```ts import { huggingFace } from '@ai-sdk/huggingface'; import { generateText } from 'ai'; const result = await generateText({ model: huggingFace('deepseek-ai/DeepSeek-R1'), prompt: 'What is 25 * 37?', providerOptions: { huggingface: { reasoningEffort: 'medium', }, }, }); console.log('Reasoning:', result.reasoning); console.log('Answer:', result.text); ``` ### Image Input For vision-capable models like `Qwen/Qwen2.5-VL-7B-Instruct`, you can pass images as part of the message content: ```ts import { huggingFace } from '@ai-sdk/huggingface'; import { generateText } from 'ai'; import { readFileSync } from 'fs'; const result = await generateText({ model: huggingFace('Qwen/Qwen2.5-VL-7B-Instruct'), messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe this image in detail.' }, { type: 'file', mediaType: 'image', data: readFileSync('./image.png'), }, ], }, ], }); ``` You can also pass image URLs: ```ts { type: 'file', mediaType: 'image', data: 'https://example.com/image.png', } ``` ## Model Capabilities | Model | Image Input | Object Generation | Tool Usage | Tool Streaming | | ----------------------------------------------- | ----------- | ----------------- | ---------- | -------------- | | `meta-llama/Llama-3.1-8B-Instruct` | ✗ | ✓ | ✓ | ✓ | | `meta-llama/Llama-3.1-70B-Instruct` | ✗ | ✓ | ✓ | ✓ | | `meta-llama/Llama-3.3-70B-Instruct` | ✗ | ✓ | ✓ | ✓ | | `meta-llama/Llama-4-Maverick-17B-128E-Instruct` | ✗ | ✓ | ✓ | ✓ | | `deepseek-ai/DeepSeek-V3.1` | ✗ | ✓ | ✓ | ✓ | | `deepseek-ai/DeepSeek-V3-0324` | ✗ | ✓ | ✓ | ✓ | | `deepseek-ai/DeepSeek-R1` | ✗ | ✓ | ✓ | ✓ | | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | ✗ | ✓ | ✓ | ✓ | | `Qwen/Qwen3-32B` | ✗ | ✓ | ✓ | ✓ | | `Qwen/Qwen3-Coder-480B-A35B-Instruct` | ✗ | ✓ | ✓ | ✓ | | `Qwen/Qwen2.5-VL-7B-Instruct` | ✓ | ✓ | ✓ | ✓ | | `google/gemma-3-27b-it` | ✗ | ✓ | ✓ | ✓ | | `moonshotai/Kimi-K2-Instruct` | ✗ | ✓ | ✓ | ✓ | The table above lists popular models. You can explore all available models on the [Hugging Face Inference Models](https://huggingface.co/inference/models) page. The capabilities depend on the specific model you're using. Check the model documentation on Hugging Face Hub for detailed information about each model's features. ## Provider Option Reference The following option definitions are generated from the provider catalog. | Operation | Option | Description | | --------- | ------------------ | ---------------- | | language | `metadata` | metadata | | language | `instructions` | instructions | | language | `strictJsonSchema` | strictJsonSchema | | language | `reasoningEffort` | reasoningEffort | --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)