Hugging Face

The Hugging Face provider offers access to thousands of language models through Hugging Face Inference Providers, including models from Meta, DeepSeek, Qwen, and more. Use 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.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5.5',
  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:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

The current Gateway provider list 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:

pnpm add ai @ai-sdk/huggingface

npm install ai @ai-sdk/huggingface

yarn add ai @ai-sdk/huggingface

bun add ai @ai-sdk/huggingface

Set your Hugging Face API credential in the HUGGINGFACE_API_KEY environment variable:

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.

API keys can be obtained from Hugging Face Settings.

Provider Instance

You can import the default provider instance huggingFace from @ai-sdk/huggingface:

import { huggingFace } from '@ai-sdk/huggingface';

For custom configuration, you can import createHuggingFace and create a provider instance with your settings:

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

  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.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation.

Language Models

You can create language models using a provider instance:

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:

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).

You can explore the latest and trending models with their capabilities, context size, throughput and pricing on the Hugging Face Inference Models page.

Provider Options

Hugging Face language models support provider-specific options that you can pass via providerOptions.huggingface:

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<string, string>

  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:

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:

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:

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:

{
  type: 'file',
  mediaType: 'image',
  data: 'https://example.com/image.png',
}

Model Capabilities