Hugging Face Text Generation API

openapi: 3.2.0
info:
  title: Hugging Face Text Generation API
  version: 1.0.0
  contact:
    name: Hugging Face Support
    url: https://huggingface.co/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://huggingface.co/terms-of-service
  description: 'Operations tagged Text Generation across 2 of this provider''s published API definitions: hugging-face-inference-providers-api.yml, hugging-face-text-generation-inference-api.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://router.huggingface.co
  description: Hugging Face Inference Providers router
- url: https://api-inference.huggingface.co
  description: Hugging Face hosted TGI server
- url: http://localhost:8080
  description: Local TGI server (self-hosted)
security:
- bearerAuth: []
tags:
- name: Text Generation
  description: Text generation endpoints
paths:
  /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
    servers:
    - url: https://router.huggingface.co
      description: Hugging Face Inference Providers router
  /generate:
    post:
      summary: Generate Text
      description: Generate text from a prompt using the loaded model. Returns the full generated text in a single response.
      operationId: generate
      tags:
      - Text Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            examples:
              GenerateRequestExample:
                summary: Default generate request
                x-microcks-default: true
                value:
                  inputs: example_value
                  parameters:
                    max_new_tokens: 10
                    temperature: 42.5
                    top_p: 42.5
                    top_k: 10
                    repetition_penalty: 42.5
                    do_sample: true
                    seed: 10
                    stop:
                    - example_value
                    watermark: true
                    return_full_text: true
                    decoder_input_details: true
                    details: true
                    truncate: 10
                    typical_p: 42.5
                    best_of: 10
                    grammar:
                      type: json
                      value: example_value
      responses:
        '200':
          description: Generated text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
              examples:
                Generate200Example:
                  summary: Default generate 200 response
                  x-microcks-default: true
                  value:
                    generated_text: example_value
                    details:
                      finish_reason: length
                      generated_tokens: 10
                      seed: 10
                      prefill:
                      - id: abc123
                        text: example_value
                        logprob: 42.5
                      tokens:
                      - id: abc123
                        text: example_value
                        logprob: 42.5
                        special: true
                      best_of_sequences:
                      - {}
          headers:
            x-compute-type:
              schema:
                type: string
              description: Compute backend used
            x-compute-characters:
              schema:
                type: integer
              description: Number of input characters
            x-total-time:
              schema:
                type: number
              description: Total inference time in milliseconds
            x-validation-time:
              schema:
                type: number
              description: Input validation time in milliseconds
            x-queue-time:
              schema:
                type: number
              description: Queue wait time in milliseconds
            x-inference-time:
              schema:
                type: number
              description: Model inference time in milliseconds
            x-time-per-token:
              schema:
                type: number
              description: Average time per generated token in milliseconds
            x-prompt-tokens:
              schema:
                type: integer
              description: Number of prompt tokens
            x-generated-tokens:
              schema:
                type: integer
              description: Number of generated tokens
        '400':
          description: Invalid input - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Generate400Example:
                  summary: Default generate 400 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
        '422':
          description: Generation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Generate422Example:
                  summary: Default generate 422 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
        '429':
          description: Model is overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Generate429Example:
                  summary: Default generate 429 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api-inference.huggingface.co
      description: Hugging Face hosted TGI server
    - url: http://localhost:8080
      description: Local TGI server (self-hosted)
  /generate_stream:
    post:
      summary: Generate Text With Streaming
      description: Generate text from a prompt using Server-Sent Events (SSE) streaming. Tokens are returned incrementally as they are generated.
      operationId: generateStream
      tags:
      - Text Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            examples:
              GeneratestreamRequestExample:
                summary: Default generateStream request
                x-microcks-default: true
                value:
                  inputs: example_value
                  parameters:
                    max_new_tokens: 10
                    temperature: 42.5
                    top_p: 42.5
                    top_k: 10
                    repetition_penalty: 42.5
                    do_sample: true
                    seed: 10
                    stop:
                    - example_value
                    watermark: true
                    return_full_text: true
                    decoder_input_details: true
                    details: true
                    truncate: 10
                    typical_p: 42.5
                    best_of: 10
                    grammar:
                      type: json
                      value: example_value
      responses:
        '200':
          description: Stream of generated tokens
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/StreamResponse'
              examples:
                Generatestream200Example:
                  summary: Default generateStream 200 response
                  x-microcks-default: true
                  value:
                    token:
                      id: abc123
                      text: example_value
                      logprob: 42.5
                      special: true
                    generated_text: example_value
                    details:
                      finish_reason: example_value
                      generated_tokens: 10
                      seed: 10
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Generatestream400Example:
                  summary: Default generateStream 400 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
        '429':
          description: Model is overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Generatestream429Example:
                  summary: Default generateStream 429 response
                  x-microcks-default: true
                  value:
                    error: example_value
                    error_type: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api-inference.huggingface.co
      description: Hugging Face hosted TGI server
    - url: http://localhost:8080
      description: Local TGI server (self-hosted)
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
    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
    CompletionStreamResponse:
      type: object
      properties:
        id:
          type: string
          example: abc123
        object:
          type: string
          const: text_completion
          example: example_value
        created:
          type: integer
          example: 10
        model:
          type: string
          example: example_value
        choices:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              index:
                type: integer
              finish_reason:
                type: string
          example: []
    CompletionRequest:
      type: object
      required:
      - model
      - prompt
      properties:
        model:
          type: string
          description: Model ID to use
          example: example_value
        prompt:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Prompt(s) to generate completions for
          example: example_value
        max_tokens:
          type: integer
          default: 16
          example: 10
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1.0
          example: 42.5
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1.0
          example: 42.5
        stop:
          type: array
          items:
            type: string
          maxItems: 4
          example: []
        stream:
          type: boolean
          default: false
          example: true
        seed:
          type: integer
          example: 10
    CompletionResponse:
      type: object
      properties:
        id:
          type: string
          example: abc123
        object:
          type: string
          const: text_completion
          example: example_value
        created:
          type: integer
          example: 10
        model:
          type: string
          example: example_value
        choices:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              index:
                type: integer
              finish_reason:
                type: string
          example: []
        usage:
          $ref: '#/components/schemas/Usage'
    Usage_2:
      type: object
      properties:
        prompt_tokens:
          type: integer
          example: 10
        completion_tokens:
          type: integer
          example: 10
        total_tokens:
          type: integer
          example: 10
    GenerateResponse:
      type: object
      properties:
        generated_text:
          type: string
          description: The generated text
          example: example_value
        details:
          type: object
          properties:
            finish_reason:
              type: string
              enum:
              - length
              - eos_token
              - stop_sequence
              description: Reason generation stopped
            generated_tokens:
              type: integer
              description: Number of generated tokens
            seed:
              type: integer
              description: Sampling seed used
            prefill:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  text:
                    type: string
                  logprob:
                    type: number
              description: Prefill token details
            tokens:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  text:
                    type: string
                  logprob:
                    type: number
                  special:
                    type: boolean
              description: Generated token details
            best_of_sequences:
              type: array
              items:
                type: object
              description: Best-of sequences details
          example: example_value
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: example_value
        error_type:
          type: string
          description: Error type classification
          example: example_value
    CompletionRequest_2:
      type: object
      required:
      - model
      - prompt
      properties:
        model:
          type: string
          example: example_value
        prompt:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          example: example_value
        max_tokens:
          type: integer
          default: 16
          example: 10
        temperature:
          type: number
          example: 42.5
        top_p:
          type: number
          example: 42.5
        stop:
          type: array
          items:
            type: string
          example: []
        stream:
          type: boolean
          default: false
          example: true
        seed:
          type: integer
          example: 10
        suffix:
          type: string
          description: Suffix to append after generated text
          example: example_value
    GenerateRequest:
      type: object
      required:
      - inputs
      properties:
        inputs:
          type: string
          description: Input prompt text
          example: What is deep learning?
        parameters:
          type: object
          properties:
            max_new_tokens:
              type: integer
              description: Maximum number of tokens to generate
              default: 20
              example: 100
            temperature:
              type: number
              format: float
              description: Sampling temperature (higher = more random)
              minimum: 0
              example: 0.7
            top_p:
              type: number
              format: float
              description: Nucleus sampling probability threshold
              minimum: 0
              maximum: 1
              example: 0.95
            top_k:
              type: integer
              description: Top-k sampling parameter
              minimum: 0
              example: 50
            repetition_penalty:
              type: number
              format: float
              description: Repetition penalty (1.0 = no penalty)
              example: 1.1
            do_sample:
              type: boolean
              description: Whether to use sampling vs greedy decoding
              default: false
            seed:
              type: integer
              description: Random seed for reproducibility
            stop:
              type: array
              items:
                type: string
              description: Stop sequences
            watermark:
              type: boolean
              description: Whether to add a watermark to generated text
              default: false
            return_full_text:
              type: boolean
              description: Include the input prompt in the response
              default: false
            decoder_input_details:
              type: boolean
              description: Return decoder input token details
              default: false
            details:
              type: boolean
              description: Return generation details (tokens, logprobs, etc.)
              default: false
            truncate:
              type: integer
              description: Truncate input to this many tokens
            typical_p:
              type: number
              format: float
              description: Typical decoding probability threshold
            best_of:
              type: integer
              description: Generate this many sequences and return the best
              minimum: 1
            grammar:
              type: object
              description: Grammar constraints for generation
              properties:
                type:
                  type: string
                  enum:
                  - json
                  - regex
                value:
                  type: string
                  description: Grammar specification (JSON schema or regex)
          example: example_value
    StreamResponse:
      type: object
      properties:
        token:
          type: object
          properties:
            id:
              type: integer
            text:
              type: string
            logprob:
              type: number
            special:
              type: boolean
          example: example_value
        generated_text:
          type: string
          description: Full generated text (only in the last event)
          example: example_value
        details:
          type: object
          description: Generation details (only in the last event)
          properties:
            finish_reason:
              type: string
            generated_tokens:
              type: integer
            seed:
              type: integer
          example: example_value
  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
x-refined-from:
- hugging-face-inference-providers-api.yml
- hugging-face-text-generation-inference-api.yml