openapi: 3.1.0
info:
  title: Ollama Blobs Generate API
  description: Ollama provides a REST API for running and managing large language models locally. The API supports text generation, chat completions, embeddings, model management, and streaming responses. It serves as the primary interface for interacting with models running on the Ollama inference engine at localhost:11434.
  version: 0.1.0
  contact:
    name: Ollama Team
    url: https://ollama.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://ollama.com/terms
servers:
- url: http://localhost:11434
  description: Local Ollama Server
tags:
- name: Generate
  description: Generate text completions from a prompt using a specified model.
paths:
  /api/generate:
    post:
      operationId: generateCompletion
      summary: Ollama Generate a completion
      description: Generate a response for a given prompt with a provided model. This is a streaming endpoint that returns a sequence of JSON objects by default. The final response object includes statistics about the generation. Set stream to false to receive a single response object.
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: Successful generation response. Returns a stream of JSON objects when streaming is enabled, or a single JSON object when disabled.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Logprob:
      type: object
      description: Log probability information for a generated token.
      properties:
        token:
          type: string
          description: The token text.
        logprob:
          type: number
          description: The log probability of the token.
        bytes:
          type: array
          description: The byte representation of the token.
          items:
            type: integer
        top_logprobs:
          type: array
          description: The most likely alternative tokens and their log probabilities at this position.
          items:
            type: object
            properties:
              token:
                type: string
                description: The alternative token text.
              logprob:
                type: number
                description: The log probability of the alternative token.
              bytes:
                type: array
                description: The byte representation of the alternative token.
                items:
                  type: integer
    GenerateRequest:
      type: object
      description: Request body for generating a text completion from a prompt.
      required:
      - model
      properties:
        model:
          type: string
          description: The name of the model to use for generation.
        prompt:
          type: string
          description: The text prompt to generate a response from.
        suffix:
          type: string
          description: Text that appears after the model response, used for fill-in-the-middle generation.
        images:
          type: array
          description: A list of base64-encoded images for multimodal models that support vision input.
          items:
            type: string
            format: byte
        format:
          description: The format to return a response in. Accepts the string json for simple JSON mode, or a JSON Schema object for structured output.
          oneOf:
          - type: string
            enum:
            - json
          - type: object
        system:
          type: string
          description: System message to set the behavior and context of the model.
        stream:
          type: boolean
          description: When true, returns a stream of partial responses as newline-delimited JSON. When false, returns a single response object.
          default: true
        think:
          description: When true, returns separate thinking output in addition to the generated content. Can also be set to a string value of high, medium, or low to control thinking verbosity.
          oneOf:
          - type: boolean
          - type: string
            enum:
            - high
            - medium
            - low
        raw:
          type: boolean
          description: When true, returns the raw response from the model without applying prompt templating.
          default: false
        keep_alive:
          description: How long the model stays loaded in memory after the request. Accepts a duration string like 5m or a number of seconds. Set to 0 to unload immediately after use.
          oneOf:
          - type: string
          - type: number
        options:
          $ref: '#/components/schemas/ModelOptions'
        logprobs:
          type: boolean
          description: Whether to return log probabilities of the output tokens.
        top_logprobs:
          type: integer
          description: Number of most likely tokens to return at each token position, along with their log probabilities.
          minimum: 0
    GenerateResponse:
      type: object
      description: Response object from a text generation request. When streaming, partial objects are returned until done is true.
      properties:
        model:
          type: string
          description: The model that generated the response.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the response was created.
        response:
          type: string
          description: The generated text response. In streaming mode, contains the partial response for each chunk.
        thinking:
          type: string
          description: The model's thinking output when think is enabled.
        done:
          type: boolean
          description: Indicates whether the generation has completed. The final response in a stream has done set to true.
        done_reason:
          type: string
          description: The reason the generation stopped. Common values include stop and length.
        total_duration:
          type: integer
          description: Total time spent generating the response in nanoseconds.
        load_duration:
          type: integer
          description: Time spent loading the model in nanoseconds.
        prompt_eval_count:
          type: integer
          description: Number of tokens in the prompt that were evaluated.
        prompt_eval_duration:
          type: integer
          description: Time spent evaluating the prompt in nanoseconds.
        eval_count:
          type: integer
          description: Number of tokens generated in the response.
        eval_duration:
          type: integer
          description: Time spent generating output tokens in nanoseconds.
        logprobs:
          type: array
          description: Log probability information for generated tokens when logprobs is enabled.
          items:
            $ref: '#/components/schemas/Logprob'
    ErrorResponse:
      type: object
      description: An error response returned when a request fails.
      properties:
        error:
          type: string
          description: A human-readable error message describing the problem.
    ModelOptions:
      type: object
      description: Runtime options that control text generation behavior. These override the model's default parameter values.
      properties:
        seed:
          type: integer
          description: Random seed for reproducible generation. Set to a specific value for deterministic output.
        temperature:
          type: number
          description: Controls the creativity of responses. Higher values produce more varied output. Range 0.0 to 2.0.
          minimum: 0.0
          maximum: 2.0
        top_k:
          type: integer
          description: Limits token selection to the top K most probable tokens. Lower values produce more focused output.
          minimum: 0
        top_p:
          type: number
          description: Nucleus sampling probability cutoff. Limits selection to the smallest set of tokens whose cumulative probability exceeds this value.
          minimum: 0.0
          maximum: 1.0
        min_p:
          type: number
          description: Minimum probability threshold relative to the most likely token. Tokens below this threshold are filtered out.
          minimum: 0.0
          maximum: 1.0
        stop:
          type: array
          description: A list of stop sequences. Generation halts when any of these strings are produced.
          items:
            type: string
        num_ctx:
          type: integer
          description: The maximum context window size in tokens.
        num_predict:
          type: integer
          description: The maximum number of tokens to generate in the response.
        repeat_penalty:
          type: number
          description: Penalty applied to repeated tokens to reduce repetition.
        repeat_last_n:
          type: integer
          description: Number of recent tokens to consider for repeat penalty.
        tfs_z:
          type: number
          description: Tail-free sampling parameter. Higher values reduce the impact of less probable tokens.
        mirostat:
          type: integer
          description: Enable Mirostat sampling for perplexity control. 0 is disabled, 1 uses Mirostat, 2 uses Mirostat 2.0.
          enum:
          - 0
          - 1
          - 2
        mirostat_tau:
          type: number
          description: Target entropy for Mirostat sampling.
        mirostat_eta:
          type: number
          description: Learning rate for Mirostat sampling.
externalDocs:
  description: Ollama API Documentation
  url: https://docs.ollama.com/api/introduction