Hugging Face Chat API

openapi: 3.1.0
info:
  title: Hugging Face Dataset Viewer Audio Chat API
  description: Query and visualize datasets stored on the Hugging Face Hub through a lightweight REST API. Get dataset splits, preview rows, search and filter data, access Parquet files, retrieve size statistics, and obtain Croissant metadata - all without downloading the entire dataset.
  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://datasets-server.huggingface.co
  description: Hugging Face Dataset Viewer production server
security:
- {}
- bearerAuth: []
tags:
- name: Chat
  description: OpenAI-compatible chat completion endpoints
paths:
  /v1/chat/completions:
    post:
      summary: Create Chat Completion (openai Compatible)
      description: Create a chat completion using the OpenAI-compatible Messages API. Supports conversations, tool calling, structured output via JSON schema, and multi-modal inputs (text + images). Fully compatible with OpenAI client libraries.
      operationId: chatCompletions
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              ChatcompletionsRequestExample:
                summary: Default chatCompletions request
                x-microcks-default: true
                value:
                  model: example_value
                  messages:
                  - role: system
                    content: example_value
                    tool_calls:
                    - {}
                    tool_call_id: '500123'
                    name: Example Title
                  frequency_penalty: 42.5
                  logprobs: true
                  max_tokens: 10
                  presence_penalty: 42.5
                  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:
                Chatcompletions200Example:
                  summary: Default chatCompletions 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: {}
                        tool_call_id: '500123'
                      finish_reason: stop
                      logprobs:
                        content: {}
                    usage:
                      prompt_tokens: 10
                      completion_tokens: 10
                      total_tokens: 10
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionStreamResponse'
              examples:
                Chatcompletions200Example:
                  summary: Default chatCompletions 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: {}
                        tool_call_id: '500123'
                      finish_reason: example_value
                      logprobs:
                        content: {}
                    usage:
                      prompt_tokens: 10
                      completion_tokens: 10
                      total_tokens: 10
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Chatcompletions400Example:
                  summary: Default chatCompletions 400 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Chatcompletions422Example:
                  summary: Default chatCompletions 422 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
        '429':
          description: Model overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Chatcompletions429Example:
                  summary: Default chatCompletions 429 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          example: 10
        completion_tokens:
          type: integer
          example: 10
        total_tokens:
          type: integer
          example: 10
    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
                  tool_call_id:
                    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'
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: Model identifier (can be tgi or a model ID)
          example: tgi
        messages:
          type: array
          description: Conversation messages
          items:
            type: object
            required:
            - role
            properties:
              role:
                type: string
                enum:
                - system
                - user
                - assistant
                - tool
              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
              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
              name:
                type: string
          example: []
        frequency_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
          example: 42.5
        logprobs:
          type: boolean
          example: true
        max_tokens:
          type: integer
          description: Maximum tokens to generate
          example: 10
        presence_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
          example: 42.5
        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
          example: 10
        stop:
          type: array
          items:
            type: string
          maxItems: 4
          example: []
        stream:
          type: boolean
          default: false
          example: true
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
          example: example_value
        temperature:
          type: number
          minimum: 0
          maximum: 2
          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
          example: example_value
        tool_prompt:
          type: string
          description: Prompt appended 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
          example: []
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 5
          example: 10
        top_p:
          type: number
          minimum: 0
          maximum: 1
          example: 42.5
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: example_value
        error_type:
          type: string
          description: Error type classification
          example: example_value
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          example: abc123
        object:
          type: string
          const: chat.completion
          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
              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
                            description:
                              type: string
                  tool_call_id:
                    type: string
              finish_reason:
                type: string
                enum:
                - stop
                - length
                - tool_calls
              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: Optional Hugging Face API token. Required for private and gated datasets.