Hugging Face Chat Completions API

openapi: 3.2.0
info:
  title: Hugging Face Inference Providers Chat Completions 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
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
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            type:
              type: string
              description: Error type
            code:
              type: string
              description: Error code
          example: example_value
    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
                    items:
                      type: object
                      properties:
                        token:
                          type: string
                        logprob:
                          type: number
                        top_logprobs:
                          type: array
                          items:
                            type: object
                            properties:
                              token:
                                type: string
                              logprob:
                                type: number
          example: []
        usage:
          $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt
          example: 10
        completion_tokens:
          type: integer
          description: Number of tokens in the completion
          example: 10
        total_tokens:
          type: integer
          description: Total tokens used
          example: 10
    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
    ChatCompletionStreamResponse:
      type: object
      properties:
        id:
          type: string
          example: abc123
        object:
          type: string
          const: chat.completion.chunk
          example: example_value
        created:
          type: integer
          example: 10
        model:
          type: string
          example: example_value
        system_fingerprint:
          type: string
          example: example_value
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              delta:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                  tool_calls:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        index:
                          type: integer
                        type:
                          type: string
                        function:
                          type: object
                          properties:
                            name:
                              type: string
                            arguments:
                              type: string
              finish_reason:
                type: string
              logprobs:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        token:
                          type: string
                        logprob:
                          type: number
                        top_logprobs:
                          type: array
                          items:
                            type: object
                            properties:
                              token:
                                type: string
                              logprob:
                                type: number
          example: []
        usage:
          $ref: '#/components/schemas/Usage'
  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