Hugging Face Inference Providers API

openapi: 3.1.0
info:
  title: Hugging Face Inference Providers API
  description: >-
    Unified proxy layer providing access to 15+ inference partners through a
    single OpenAI-compatible endpoint. Route requests to providers like AWS,
    Google, Azure, Together, Fireworks, and more through a consistent API with
    automatic model routing and provider selection.
  version: 1.0.0
  termsOfService: https://huggingface.co/terms-of-service
  contact:
    name: Hugging Face Support
    url: https://huggingface.co/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://router.huggingface.co
  description: Hugging Face Inference Providers router
security:
- bearerAuth: []
tags:
- name: Chat Completions
  description: OpenAI-compatible chat completion endpoints
- name: Text Generation
  description: Text generation endpoints
- name: Embeddings
  description: Text embedding endpoints
- name: Image Generation
  description: Text-to-image generation
- name: Audio
  description: Speech-to-text and text-to-speech
- name: Models
  description: Model listing and information
paths:
  /v1/chat/completions:
    post:
      summary: Create Chat Completion
      description: >-
        Create a chat completion using an OpenAI-compatible API. Supports
        conversational LLMs and Vision-Language Models (VLMs). Requests are
        routed to the optimal inference provider automatically.
      operationId: createChatCompletion
      tags:
      - Chat Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              CreatechatcompletionRequestExample:
                summary: Default createChatCompletion request
                x-microcks-default: true
                value:
                  model: example_value
                  messages:
                  - role: system
                    content: example_value
                    name: Example Title
                    tool_calls:
                    - {}
                    tool_call_id: '500123'
                  frequency_penalty: 42.5
                  logprobs: true
                  max_tokens: 10
                  presence_penalty: 42.5
                  reasoning_effort: example_value
                  response_format: example_value
                  seed: 10
                  stop:
                  - example_value
                  stream: true
                  stream_options:
                    include_usage: true
                  temperature: 42.5
                  tool_choice: example_value
                  tool_prompt: example_value
                  tools:
                  - type: example_value
                    function:
                      name: Example Title
                      description: A sample description.
                      parameters: example_value
                  top_logprobs: 10
                  top_p: 42.5
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              examples:
                Createchatcompletion200Example:
                  summary: Default createChatCompletion 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    object: example_value
                    created: 10
                    model: example_value
                    system_fingerprint: example_value
                    choices:
                    - index: 10
                      message:
                        role: example_value
                        content: example_value
                        tool_calls: {}
                      finish_reason: stop
                      logprobs:
                        content: {}
                    usage:
                      prompt_tokens: 10
                      completion_tokens: 10
                      total_tokens: 10
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionStreamResponse'
              examples:
                Createchatcompletion200Example:
                  summary: Default createChatCompletion 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    object: example_value
                    created: 10
                    model: example_value
                    system_fingerprint: example_value
                    choices:
                    - index: 10
                      delta:
                        role: example_value
                        content: example_value
                        tool_calls: {}
                      finish_reason: example_value
                      logprobs:
                        content: {}
                    usage:
                      prompt_tokens: 10
                      completion_tokens: 10
                      total_tokens: 10
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchatcompletion400Example:
                  summary: Default createChatCompletion 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchatcompletion401Example:
                  summary: Default createChatCompletion 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
        '404':
          description: Model not found or not available through any provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchatcompletion404Example:
                  summary: Default createChatCompletion 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchatcompletion429Example:
                  summary: Default createChatCompletion 429 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
        '502':
          description: Provider error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchatcompletion502Example:
                  summary: Default createChatCompletion 502 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/completions:
    post:
      summary: Create Text Completion
      description: >-
        Create a text completion for a given prompt. Supports standard
        completion parameters compatible with the OpenAI API format.
      operationId: createCompletion
      tags:
      - Text Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
            examples:
              CreatecompletionRequestExample:
                summary: Default createCompletion request
                x-microcks-default: true
                value:
                  model: example_value
                  prompt: example_value
                  max_tokens: 10
                  temperature: 42.5
                  top_p: 42.5
                  stop:
                  - example_value
                  stream: true
                  seed: 10
      responses:
        '200':
          description: Text completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
              examples:
                Createcompletion200Example:
                  summary: Default createCompletion 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    object: example_value
                    created: 10
                    model: example_value
                    choices:
                    - text: example_value
                      index: 10
                      finish_reason: example_value
                    usage:
                      prompt_tokens: 10
                      completion_tokens: 10
                      total_tokens: 10
            text/event-stream:
              schema:
                $ref: '#/components/schemas/CompletionStreamResponse'
              examples:
                Createcompletion200Example:
                  summary: Default createCompletion 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    object: example_value
                    created: 10
                    model: example_value
                    choices:
                    - text: example_value
                      index: 10
                      finish_reason: example_value
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createcompletion400Example:
                  summary: Default createCompletion 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/embeddings:
    post:
      summary: Create Embeddings
      description: >-
        Create embedding vectors for input text. Returns dense vector
        representations useful for semantic search, clustering, and
        classification tasks.
      operationId: createEmbeddings
      tags:
      - Embeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
            examples:
              CreateembeddingsRequestExample:
                summary: Default createEmbeddings request
                x-microcks-default: true
                value:
                  model: example_value
                  input: example_value
                  encoding_format: float
      responses:
        '200':
          description: Embedding response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
              examples:
                Createembeddings200Example:
                  summary: Default createEmbeddings 200 response
                  x-microcks-default: true
                  value:
                    object: example_value
                    data:
                    - object: example_value
                      index: 10
                      embedding:
                      - {}
                    model: example_value
                    usage:
                      prompt_tokens: 10
                      total_tokens: 10
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createembeddings400Example:
                  summary: Default createEmbeddings 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/images/generations:
    post:
      summary: Generate Images
      description: >-
        Generate images from text prompts using diffusion models available
        through inference providers.
      operationId: createImageGeneration
      tags:
      - Image Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
            examples:
              CreateimagegenerationRequestExample:
                summary: Default createImageGeneration request
                x-microcks-default: true
                value:
                  model: example_value
                  prompt: example_value
                  n: 10
                  size: 256x256
                  response_format: url
                  negative_prompt: example_value
                  num_inference_steps: 10
                  guidance_scale: 42.5
      responses:
        '200':
          description: Generated images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
              examples:
                Createimagegeneration200Example:
                  summary: Default createImageGeneration 200 response
                  x-microcks-default: true
                  value:
                    created: 10
                    data:
                    - url: https://www.example.com
                      b64_json: example_value
                      revised_prompt: example_value
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createimagegeneration400Example:
                  summary: Default createImageGeneration 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/audio/transcriptions:
    post:
      summary: Transcribe Audio
      description: >-
        Transcribe audio to text using automatic speech recognition models.
      operationId: createTranscription
      tags:
      - Audio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - model
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file to transcribe
                model:
                  type: string
                  description: Model ID to use for transcription
                  example: openai/whisper-large-v3
                language:
                  type: string
                  description: Language of the audio in ISO 639-1 format
                prompt:
                  type: string
                  description: Optional text to guide transcription
                response_format:
                  type: string
                  enum:
                  - json
                  - text
                  - srt
                  - verbose_json
                  - vtt
                  default: json
                temperature:
                  type: number
                  format: float
            examples:
              CreatetranscriptionRequestExample:
                summary: Default createTranscription request
                x-microcks-default: true
                value:
                  file: example_value
                  model: example_value
                  language: example_value
                  prompt: example_value
                  response_format: json
                  temperature: 42.5
      responses:
        '200':
          description: Transcription result
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: Transcribed text
              examples:
                Createtranscription200Example:
                  summary: Default createTranscription 200 response
                  x-microcks-default: true
                  value:
                    text: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/audio/speech:
    post:
      summary: Generate Speech
      description: Generate audio speech from text input.
      operationId: createSpeech
      tags:
      - Audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - input
              properties:
                model:
                  type: string
                  description: Model ID for speech generation
                input:
                  type: string
                  description: Text to generate audio for
                  maxLength: 4096
                voice:
                  type: string
                  description: Voice to use for generation
                response_format:
                  type: string
                  enum:
                  - mp3
                  - opus
                  - aac
                  - flac
                  - wav
                  default: mp3
                speed:
                  type: number
                  format: float
                  minimum: 0.25
                  maximum: 4.0
                  default: 1.0
            examples:
              CreatespeechRequestExample:
                summary: Default createSpeech request
                x-microcks-default: true
                value:
                  model: example_value
                  input: example_value
                  voice: example_value
                  response_format: mp3
                  speed: 42.5
      responses:
        '200':
          description: Generated audio
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
              examples:
                Createspeech200Example:
                  summary: Default createSpeech 200 response
                  x-microcks-default: true
                  value: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/models:
    get:
      summary: List Available Models
      description: >-
        List models available through inference providers. Returns model IDs
        and basic metadata.
      operationId: listModels
      tags:
      - Models
      responses:
        '200':
          description: List of available models
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Model ID
                        object:
                          type: string
                          const: model
                        created:
                          type: integer
                          description: Unix timestamp of creation
                        owned_by:
                          type: string
                          description: Model owner
              examples:
                Listmodels200Example:
                  summary: Default listModels 200 response
                  x-microcks-default: true
                  value:
                    object: example_value
                    data:
                    - id: abc123
                      object: example_value
                      created: 10
                      owned_by: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/models/{model_id}:
    get:
      summary: Get Model Information
      description: Get information about a specific model available through inference providers.
      operationId: getModel
      tags:
      - Models
      parameters:
      - name: model_id
        in: path
        required: true
        description: The model ID
        schema:
          type: string
        example: meta-llama/Llama-3-70b-chat-hf
      responses:
        '200':
          description: Model information
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                    const: model
                  created:
                    type: integer
                  owned_by:
                    type: string
              examples:
                Getmodel200Example:
                  summary: Default getModel 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    object: example_value
                    created: 10
                    owned_by: example_value
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getmodel404Example:
                  summary: Default getModel 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      type: example_value
                      code: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: HF Token
      description: >-
        Hugging Face API token with Inference Providers permission. Generate
        from https://huggingface.co/settings/tokens
  schemas:
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: >-
            Model ID to use. Can be a Hugging Face model ID (e.g.,
            meta-llama/Llama-3-70b-chat-hf) or a provider-specific identifier.
          example: meta-llama/Llama-3-70b-chat-hf
        messages:
          type: array
          description: List of messages comprising the conversation
          items:
            type: object
            required:
            - role
            properties:
              role:
                type: string
                enum:
                - system
                - user
                - assistant
                - tool
                description: The role of the message author
              content:
                oneOf:
                - type: string
                - type: array
                  items:
                    oneOf:
                    - type: object
                      required:
                      - type
                      - text
                      properties:
                        type:
                          type: string
                          const: text
                        text:
                          type: string
                    - type: object
                      required:
                      - type
                      - image_url
                      properties:
                        type:
                          type: string
                          const: image_url
                        image_url:
                          type: object
                          required:
                          - url
                          properties:
                            url:
                              type: string
                description: Message content (string or array for multimodal)
              name:
                type: string
                description: Optional name for the participant
              tool_calls:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - type
                  - function
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                    function:
                      type: object
                      required:
                      - name
                      properties:
                        name:
                          type: string
                        arguments:
                          type: string
                        description:
                          type: string
              tool_call_id:
                type: string
                description: Tool call ID for tool responses
          example: []
        frequency_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
          default: 0
          description: Penalize tokens based on frequency in text so far
          example: 42.5
        logprobs:
          type: boolean
          default: false
          description: Whether to return log probabilities
          example: true
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate
          example: 10
        presence_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
          default: 0
          description: Penalize tokens based on presence in text so far
          example: 42.5
        reasoning_effort:
          type: string
          description: >-
            Constrains effort on reasoning for models that support it. Common
            values are none, minimal, low, medium, high, xhigh.
          example: example_value
        response_format:
          oneOf:
          - type: object
            properties:
              type:
                type: string
                const: text
          - type: object
            required:
            - type
            - json_schema
            properties:
              type:
                type: string
                const: json_schema
              json_schema:
                type: object
                required:
                - name
                properties:
                  name:
                    type: string
                  description:
                    type: string
                  schema:
                    type: object
                  strict:
                    type: boolean
          - type: object
            properties:
              type:
                type: string
                const: json_object
          example: example_value
        seed:
          type: integer
          description: Random seed for reproducibility
          example: 10
        stop:
          type: array
          items:
            type: string
          maxItems: 4
          description: Up to 4 sequences where generation will stop
          example: []
        stream:
          type: boolean
          default: false
          description: Whether to stream partial responses using SSE
          example: true
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
              description: Include usage statistics in stream
          example: example_value
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1.0
          description: Sampling temperature
          example: 42.5
        tool_choice:
          oneOf:
          - type: string
            enum:
            - auto
            - none
            - required
          - type: object
            required:
            - function
            properties:
              function:
                type: object
                required:
                - name
                properties:
                  name:
                    type: string
          description: Controls tool usage
          example: example_value
        tool_prompt:
          type: string
          description: Prompt prepended before tools
          example: example_value
        tools:
          type: array
          items:
            type: object
            required:
            - type
            - function
            properties:
              type:
                type: string
              function:
                type: object
                required:
                - name
                properties:
                  name:
                    type: string
                  description:
                    type: string
                  parameters:
                    type: object
          description: List of tools the model may call
          example: []
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 5
          description: Number of most likely tokens to return per position
          example: 10
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1.0
          description: Nucleus sampling parameter
          example: 42.5
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique completion identifier
          example: abc123
        object:
          type: string
          const: chat.completion
          example: example_value
        created:
          type: integer
          description: Unix timestamp
          example: 10
        model:
          type: string
          description: Model used
          example: example_value
        system_fingerprint:
          type: string
          example: example_value
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                  tool_calls:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                        function:
                          type: object
                          properties:
                            name:
                              type: string
                            arguments:
                              type: string
              finish_reason:
                type: string
                enum:
                - stop
                - length
                - tool_calls
                - content_filter
              logprobs:
                type: object
                properties:
                  content:
                    type: array
        

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face/refs/heads/main/openapi/hugging-face-inference-providers-api.yml