Hugging Face provider

You can proxy requests to Hugging Face AI models through AI Gateway by creating AI Model Provider and AI Model entities. This reference documents all supported AI capabilities, configuration requirements, and provider-specific details needed for proper integration.

AI Gateway automatically routes requests to the appropriate Hugging Face API endpoints. The following table shows the upstream paths used for each capability.

The following tables show the AI capabilities supported by the Hugging Face provider when configuring AI Models.

By default, AI Gateway uses the path templates shown in the tables below (e.g., /chat/completions, /embeddings, etc.). To customize these paths, configure the config.paths field in your AI Model entity. Custom paths take the form {configured_path}/{template_path} — for example, if you set a custom path of /v2, requests to /embeddings would be routed to /v2/embeddings.

Text generation

Support for Hugging Face text generation capabilities:

Embeddings

Support for Hugging Face embeddings generation:

Audio

Support for Hugging Face audio capabilities (speech synthesis, transcription, and translation):

For requests with large payloads, consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Supported audio formats, voices, and parameters vary by model. Refer to your provider’s documentation for available options.

Image

Support for Hugging Face image generation and editing capabilities:

For requests with large payloads, consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Supported image sizes and formats vary by model. Refer to your provider’s documentation for allowed dimensions and requirements.

Video

Support for Hugging Face video generation capabilities:

For requests with large payloads (video generation), consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

The base URL is https://api-inference.huggingface.co.

AI Gateway uses this URL automatically. You only need to configure a URL if you’re using a self-hosted or Hugging Face-compatible endpoint, in which case set the upstream_url option in your AI Model configuration.

By default, AI Gateway uses OpenAI-compatible request formats. Configure a native format in your AI Model to use Hugging Face-specific APIs and features.

The following native Hugging Face formats are supported:

To use Hugging Face with AI Gateway, configure a new AI Model Provider. You can then access supported AI Models from Hugging Face.

Here’s a minimal configuration for chat completions:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Huggingface Production",
      "name": "my-huggingface-account",
      "type": "huggingface",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "Authorization",
              "value": "'$HUGGINGFACE_TOKEN'"
            }
          ]
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-huggingface-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Huggingface Production
    name: my-huggingface-account
    type: huggingface
    config:
      auth:
        type: basic
        headers:
        - name: Authorization
          value: !secret {source: !env HUGGINGFACE_TOKEN}