openapi: 3.2.0
info:
  description: The LocalAI Rest API.
  title: LocalAI Images API
  contact:
    name: LocalAI
    url: https://localai.io
  license:
    name: MIT
    url: https://raw.githubusercontent.com/mudler/LocalAI/master/LICENSE
  version: 2.0.0
servers:
- url: /
tags:
- name: images
paths:
  /v1/images/generations:
    post:
      tags:
      - images
      summary: Creates an image given a prompt.
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.OpenAIResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schema.OpenAIRequest'
        description: query params
        required: true
  /v1/images/inpainting:
    post:
      description: Perform image inpainting. Accepts multipart/form-data with `image` and `mask` files.
      tags:
      - images
      summary: Image inpainting
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.OpenAIResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: Model identifier
                prompt:
                  type: string
                  description: Text prompt guiding the generation
                steps:
                  type: integer
                  description: Number of inference steps (default 25)
                image:
                  type: string
                  description: Original image file
                  format: binary
                mask:
                  type: string
                  description: Mask image file (white = area to inpaint)
                  format: binary
              required:
              - model
              - prompt
              - image
              - mask
  /v1/images/upscale:
    post:
      description: Upscale an image using a specified model (e.g. stable-diffusion-x4-upscaler). Accepts multipart/form-data.
      tags:
      - images
      summary: Image upscaling
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.OpenAIResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: Upscaler model identifier (e.g. stable-diffusion-x4-upscaler)
                image:
                  type: string
                  description: Input image file
                  format: binary
                scale:
                  type: integer
                  description: 'Upscale factor: 2 or 4 (default 2)'
              required:
              - model
              - image
components:
  schemas:
    functions.Item:
      type: object
      properties:
        properties:
          type: object
          additionalProperties: {}
        type:
          type: string
    functions.Tool:
      type: object
      properties:
        function:
          $ref: '#/components/schemas/functions.Function'
        type:
          type: string
    schema.ToolCall:
      type: object
      properties:
        function:
          $ref: '#/components/schemas/schema.FunctionCall'
        id:
          type: string
        index:
          type: integer
        type:
          type: string
    functions.Function:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
        parameters:
          type: object
          additionalProperties: {}
        strict:
          type: boolean
    schema.OpenAIRequest:
      type: object
      required:
      - file
      properties:
        backend:
          type: string
        batch:
          description: Custom parameters - not present in the OpenAI API
          type: integer
        clip_skip:
          description: Diffusers
          type: integer
        echo:
          type: boolean
        encoding_format:
          description: 'Embedding encoding format: "float" (default) or "base64" (OpenAI Node.js SDK default)'
          type: string
        file:
          description: whisper
          type: string
        files:
          description: Multiple input images for img2img or inpainting
          type: array
          items:
            type: string
        frequency_penalty:
          type: number
        function_call:
          description: might be a string or an object
        functions:
          description: A list of available functions to call
          type: array
          items:
            $ref: '#/components/schemas/functions.Function'
        grammar:
          description: A grammar to constrain the LLM output
          type: string
        grammar_json_functions:
          $ref: '#/components/schemas/functions.JSONFunctionStructure'
        ignore_eos:
          type: boolean
        input: {}
        instruction:
          description: Edit endpoint
          type: string
        language:
          description: Also part of the OpenAI official spec
          type: string
        logit_bias:
          description: Map of token IDs to bias values (-100 to 100)
          type: object
          additionalProperties:
            type: number
            format: float64
        logprobs:
          description: 'OpenAI API logprobs parameters

            logprobs: boolean - if true, returns log probabilities of each output token

            top_logprobs: integer 0-20 - number of most likely tokens to return at each token position'
          allOf:
          - $ref: '#/components/schemas/schema.LogprobsValue'
        max_completion_tokens:
          description: 'MaxCompletionTokens is the modern alias for max_tokens

            (OpenAI deprecated max_tokens; gpt-5 / o-series reject it).

            Accepted on the wire so up-to-date clients can use the new

            name; the request middleware collapses it into Maxtokens so

            internal code reads exactly one field.'
          type: integer
        max_tokens:
          type: integer
        messages:
          description: Messages is read only by chat/completion API calls
          type: array
          items:
            $ref: '#/components/schemas/schema.Message'
        metadata:
          type: object
          additionalProperties:
            type: string
        min_p:
          type: number
        model:
          type: string
        model_base_name:
          type: string
        n:
          description: Also part of the OpenAI official spec. use it for returning multiple results
          type: integer
        n_keep:
          type: integer
        negative_prompt:
          type: string
        negative_prompt_scale:
          type: number
        pooling:
          description: 'Pooling is a LocalAI extension for /v1/embeddings: how the backend''s

            per-token vectors are reduced to a single embedding. "" or "backend"

            leaves pooling to the inference backend (the pre-existing behavior);

            "mean", "last" and "decayed_mean" pool Go-side from raw per-token

            vectors (the backend must run with the "pooling:none" option, which

            model configs get automatically when this is set).'
          type: string
        pooling_half_life_tokens:
          description: 'PoolingHalfLifeTokens is a LocalAI extension for /v1/embeddings: the

            half-life (in tokens) of the "decayed_mean" pooling scheme — a token''s

            weight halves every this-many positions counting back from the end of

            the conversation. Defaults to 256 when unset.'
          type: integer
        presence_penalty:
          type: number
        prompt:
          description: Prompt is read only by completion/image API calls
        quality:
          description: Image (not supported by OpenAI)
          type: string
        reasoning_effort:
          type: string
        ref_images:
          description: Reference images for models that support them (e.g., Flux Kontext)
          type: array
          items:
            type: string
        repeat_last_n:
          type: integer
        repeat_penalty:
          type: number
        response_format:
          description: whisper/image
        rope_freq_base:
          type: number
        rope_freq_scale:
          type: number
        seed:
          type: integer
        size:
          description: image
          type: string
        step:
          type: integer
        stop: {}
        stream:
          type: boolean
        stream_options:
          description: StreamOptions opts into OpenAI streaming extensions, e.g. include_usage.
          allOf:
          - $ref: '#/components/schemas/schema.StreamOptions'
        temperature:
          type: number
        tfz:
          type: number
        tokenizer:
          description: RWKV (?)
          type: string
        tool_choice: {}
        tools:
          type: array
          items:
            $ref: '#/components/schemas/functions.Tool'
        top_k:
          type: integer
        top_logprobs:
          description: Number of top logprobs per token (0-20)
          type: integer
        top_p:
          description: Common options between all the API calls, part of the OpenAI spec
          type: number
        translate:
          description: Only for audio transcription
          type: boolean
        typical_p:
          type: number
    schema.LogprobsValue:
      type: object
      properties:
        enabled:
          description: true if logprobs should be returned
          type: boolean
    schema.InputTokensDetails:
      type: object
      properties:
        image_tokens:
          type: integer
        text_tokens:
          type: integer
    schema.Choice:
      type: object
      properties:
        delta:
          $ref: '#/components/schemas/schema.Message'
        finish_reason:
          type: string
        index:
          type: integer
        logprobs:
          $ref: '#/components/schemas/schema.Logprobs'
        message:
          $ref: '#/components/schemas/schema.Message'
        text:
          type: string
    schema.OpenAIResponse:
      type: object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/schema.Choice'
        created:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/schema.Item'
        id:
          type: string
        model:
          type: string
        object:
          type: string
        usage:
          description: 'Usage is intentionally a pointer with omitempty: per the OpenAI

            chat-completion streaming spec, intermediate chunks must not carry

            a `usage` field. Marshalling a value-typed usage would emit

            `"usage":{"prompt_tokens":0,...}` on every chunk and break

            OpenAI-SDK consumers that filter on a truthy `result.usage`

            (continuedev/continue, Kilo Code, Roo Code, etc.).'
          allOf:
          - $ref: '#/components/schemas/schema.OpenAIUsage'
    schema.Message:
      type: object
      properties:
        content:
          description: The message content
        function_call:
          description: A result of a function call
        name:
          description: The message name (used for tools calls)
          type: string
        reasoning:
          description: Reasoning content extracted from <thinking>...</thinking> tags
          type: string
        role:
          description: The message role
          type: string
        tool_call_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/schema.ToolCall'
    functions.JSONFunctionStructure:
      type: object
      properties:
        $defs:
          type: object
          additionalProperties: {}
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/functions.Item'
        oneOf:
          type: array
          items:
            $ref: '#/components/schemas/functions.Item'
    schema.LogprobContent:
      type: object
      properties:
        bytes:
          type: array
          items:
            type: integer
        id:
          type: integer
        logprob:
          type: number
        token:
          type: string
        top_logprobs:
          type: array
          items:
            $ref: '#/components/schemas/schema.LogprobContent'
    schema.Item:
      type: object
      properties:
        b64_json:
          type: string
        index:
          type: integer
        object:
          type: string
        url:
          description: Images
          type: string
    schema.OpenAIUsage:
      type: object
      properties:
        completion_tokens:
          type: integer
        compression_meta:
          $ref: '#/components/schemas/schema.CompressionMetadata'
        input_tokens:
          description: Fields for image generation API compatibility
          type: integer
        input_tokens_details:
          $ref: '#/components/schemas/schema.InputTokensDetails'
        output_tokens:
          type: integer
        prompt_tokens:
          type: integer
        timing_prompt_processing:
          description: Extra timing data, disabled by default as is't not a part of OpenAI specification
          type: number
        timing_token_generation:
          type: number
        total_tokens:
          type: integer
    schema.StreamOptions:
      type: object
      properties:
        include_usage:
          type: boolean
    schema.FunctionCall:
      type: object
      properties:
        arguments:
          type: string
        name:
          type: string
    schema.Logprobs:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/schema.LogprobContent'
    schema.CompressionMetadata:
      type: object
      properties:
        compressed_tokens:
          type: integer
        compressor:
          type: string
        dropped_turns:
          type: integer
        original_tokens:
          type: integer
        overflow_recoveries:
          type: integer
        summary_tokens:
          type: integer
  securitySchemes:
    BearerAuth:
      type: apiKey
      name: Authorization
      in: header