openapi: 3.1.0
info:
  title: KosCompute API
  description: OpenAI-compatible REST API with Responses and Anthropic Messages compatibility.
    The advertised surface is generated from the classified public contract. Capabilities
    are model-dependent; query GET /v1/models before using optional features.
  version: '2026-08-17T12:48:31+00:00'
  contact:
    email: api@koscompute.com
servers:
- url: https://api.koscompute.com/v1
  description: Production API
paths:
  /models:
    get:
      tags:
      - Models
      summary: List available models
      description: Returns publicly available models with capabilities, pricing, and
        metadata. No authentication required.
      operationId: listModels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
      security: []
  /chat/completions:
    post:
      tags:
      - Chat Completions
      summary: Create a chat completion
      description: Creates a model response for the given chat conversation. Supports
        vision image_url inputs, reasoning, tool calling, and structured outputs when
        declared by the model. Vision processor limits are model-specific. Compatible
        with OpenAI's chat completions API.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400': &id001
          $ref: '#/components/responses/BadRequest'
        '401': &id002
          $ref: '#/components/responses/Unauthorized'
        '403': &id003
          $ref: '#/components/responses/Forbidden'
        '404': &id004
          $ref: '#/components/responses/NotFound'
        '413': &id005
          $ref: '#/components/responses/RequestTooLarge'
        '429': &id006
          $ref: '#/components/responses/RateLimit'
        '502': &id008
          $ref: '#/components/responses/BadGateway'
        '503': &id009
          $ref: '#/components/responses/ServiceUnavailable'
        '504': &id010
          $ref: '#/components/responses/GatewayTimeout'
        '500': &id007
          $ref: '#/components/responses/InternalServerError'
      security:
      - BearerAuth: []
  /responses:
    post:
      tags:
      - Responses
      summary: Create a response
      description: Stateless, zero-data-retention Responses API compatibility for
        text generation. Supports message input, streaming SSE, local function tools,
        structured text formats, and model-dependent reasoning controls. store=true
        and non-null previous_response_id are rejected; clients must resend conversation
        context in input.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
      responses:
        '200':
          description: Completed JSON response or a canonical Responses SSE stream
            when stream=true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
      - BearerAuth: []
  /messages:
    post:
      tags:
      - Messages
      summary: Create a message (Anthropic Messages compatibility)
      description: 'Anthropic Messages API compatibility endpoint. Accepts Anthropic-format
        requests and returns Anthropic-format responses. Supports tools, system prompts,
        and streaming. Authenticate with either Authorization: Bearer or x-api-key
        header.'
      operationId: createMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicMessageResponse'
        '400': *id001
        '401': *id002
        '403': *id003
        '404': *id004
        '413': *id005
        '429': *id006
        '500': *id007
        '529':
          description: Anthropic-compatible provider unavailable or upstream failure
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicError'
      security:
      - BearerAuth: []
  /audio/transcriptions:
    post:
      tags:
      - Audio
      summary: Transcribe audio to text
      description: 'Transcribes audio to text using speech-to-text models. Accepts
        audio files via multipart form upload. Available models: openai/whisper-large-v3,
        openai/whisper-large-v3-turbo'
      operationId: createTranscription
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AudioTranscriptionRequest'
      responses:
        '200':
          description: Transcription result
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: string
            text/srt:
              schema:
                type: string
            text/vtt:
              schema:
                type: string
        '400': *id001
        '401': *id002
        '403': *id003
        '404': *id004
        '413': *id005
        '429': *id006
        '502': *id008
        '503': *id009
        '504': *id010
        '500': *id007
      security:
      - BearerAuth: []
  /audio/speech:
    post:
      tags:
      - Audio
      summary: Synthesize speech from text
      description: 'Converts text to speech. Returns audio binary. Available models:
        kosmik/tts-kokoro-quality, kosmik/tts-piper-fast'
      operationId: createSpeech
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioSpeechRequest'
      responses:
        '200':
          description: Audio binary response
          content:
            audio/wav:
              schema:
                type: string
                format: binary
        '400': *id001
        '401': *id002
        '403': *id003
        '404': *id004
        '413': *id005
        '429': *id006
        '502': *id008
        '503': *id009
        '504': *id010
        '500': *id007
      security:
      - BearerAuth: []
  /health:
    get:
      tags:
      - Health
      summary: Health check
      description: Returns service status. No authentication required.
      operationId: healthCheck
      servers:
      - url: https://api.koscompute.com
        description: Production host
      responses:
        '200':
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
      security: []
  /:
    head:
      tags:
      - Health
      summary: Probe the API host
      description: Returns 204 with no response body. No authentication required.
      operationId: probeApiHost
      servers:
      - url: https://api.koscompute.com
        description: Production host
      responses:
        '204':
          description: API host is reachable
      security: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API-Key
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              description: 'Error category: invalid_request_error, authentication_error,
                etc.'
            code:
              type: string
              description: Machine-readable error code
            param:
              type:
              - string
              - 'null'
              description: Parameter that triggered the error
            metadata:
              type: object
              description: Retry and capacity details. A vision-capacity 429 includes
                retry_after plus modality, state, active_requests, total_concurrency,
                and available_concurrency.
          required:
          - message
          - type
      required:
      - error
    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - model
        created:
          type: integer
        owned_by:
          type: string
        name:
          type: string
        kind:
          type: string
          enum:
          - chat
          - audio-transcription
          - audio-speech
          - image
          - image-edit
          - embedding
          - rerank
        task:
          type: string
        supported_endpoints:
          type: array
          items:
            type: string
        input_modalities:
          type: array
          items:
            type: string
        output_modalities:
          type: array
          items:
            type: string
        context_length:
          type: integer
        modality_context_lengths:
          type: object
          description: Context limits by input modality when they differ.
          additionalProperties:
            type: integer
            minimum: 0
        max_output_length:
          type: integer
        capacity_tpm:
          type: integer
          description: Published approximate token capacity per minute
        capacity:
          type: object
          description: Sanitized live admission capacity at response time
          properties:
            available_concurrency:
              type: integer
              minimum: 0
            total_concurrency:
              type: integer
              minimum: 0
            active_requests:
              type: integer
              minimum: 0
            utilization_percent:
              type: number
              minimum: 0
              maximum: 100
            unit:
              type: string
              enum:
              - concurrent_requests
            updated_at:
              type: integer
              description: Unix timestamp
            modalities:
              type: object
              description: Live concurrency split by text and vision pools.
              additionalProperties:
                type: object
                properties:
                  available_concurrency:
                    type: integer
                    minimum: 0
                  total_concurrency:
                    type: integer
                    minimum: 0
                  active_requests:
                    type: integer
                    minimum: 0
                  utilization_percent:
                    type: number
                    minimum: 0
                    maximum: 100
          required:
          - available_concurrency
          - total_concurrency
          - active_requests
          - utilization_percent
          - unit
          - updated_at
        vision:
          type: object
          description: Public vision limits and normalization policy.
          properties:
            max_image_edge:
              type: integer
              description: Recommended maximum client-side longest edge.
            max_pixels:
              type: integer
              description: Enforced multimodal processor pixel budget.
            max_tokens:
              type: integer
              description: Maximum generated tokens for a vision request.
            context_length:
              type: integer
              description: Vision backend context limit.
            retry_after_seconds:
              type: integer
              description: Normal retry delay when vision capacity is full.
        pricing:
          type: object
        supported_features:
          type: array
          items:
            type: string
        is_ready:
          type: boolean
    ListModelsResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
      required:
      - object
      - data
    ChatContentPart:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - text
          text:
            type: string
        required:
        - type
        - text
      - type: object
        description: Vision input. Supports HTTPS URLs and JPEG, PNG, or WebP data
          URLs. Processor pixel and edge guidance is model-specific and published
          by GET /v1/models.
        properties:
          type:
            type: string
            enum:
            - image_url
          image_url:
            oneOf:
            - type: string
              format: uri
            - type: object
              properties:
                url:
                  type: string
                detail:
                  type: string
                  enum:
                  - auto
                  - low
                  - high
              required:
              - url
        required:
        - type
        - image_url
    ChatMessage:
      type: object
      properties:
        role:
          type: string
          enum:
          - system
          - developer
          - user
          - assistant
          - tool
        content:
          oneOf:
          - type: string
          - type: 'null'
          - type: array
            items:
              $ref: '#/components/schemas/ChatContentPart'
        name:
          type: string
        tool_call_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
      required:
      - role
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
          required:
          - name
          - arguments
      required:
      - id
      - type
      - function
    ToolDefinition:
      type: object
      properties:
        type:
          type: string
          enum:
          - function
        function:
          type: object
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object
            strict:
              type: boolean
          required:
          - name
      required:
      - type
      - function
    ResponseFormat:
      oneOf:
      - type: object
        properties:
          type:
            enum:
            - text
        required:
        - type
      - type: object
        properties:
          type:
            enum:
            - json_object
        required:
        - type
      - type: object
        properties:
          type:
            enum:
            - json_schema
          json_schema:
            type: object
        required:
        - type
        - json_schema
    ChatCompletionRequest:
      type: object
      properties:
        model:
          type: string
          description: Canonical model ID from GET /v1/models
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
          minItems: 1
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          minimum: 0
        min_p:
          type: number
          minimum: 0
          maximum: 1
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
        repetition_penalty:
          type: number
          minimum: 0.1
          maximum: 2
        max_tokens:
          type: integer
          minimum: 0
          description: Legacy alias for max_completion_tokens. It limits all completion
            tokens, including reasoning. If both fields are present, their values
            must match.
        max_completion_tokens:
          type: integer
          minimum: 0
          description: Hard maximum for all completion tokens, including reasoning
            and visible output.
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        seed:
          type: integer
        logit_bias:
          type: object
        logprobs:
          type: boolean
        top_logprobs:
          type: integer
        stream:
          type: boolean
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
        response_format:
          $ref: '#/components/schemas/ResponseFormat'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolDefinition'
        tool_choice:
          oneOf:
          - type: string
            enum:
            - auto
            - required
            - none
          - type: object
        reasoning:
          type: object
          description: Reasoning controls. The reasoning sub-budget never increases
            max_completion_tokens.
          properties:
            enabled:
              type: boolean
            effort:
              type: string
              enum:
              - none
              - low
              - medium
              - high
              - xhigh
            max_tokens:
              type: integer
              minimum: 0
              description: Reasoning sub-budget bounded by the total completion limit.
            exclude:
              type: boolean
              description: Exclude reasoning from response (still used internally)
        reasoning_effort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - xhigh
          description: Top-level alias for reasoning.effort. Model-specific canonical
            effort sets are published per-model in GET /v1/models (model_info.supported_reasoning_efforts).
        include_reasoning:
          type: boolean
        user:
          type: string
      required:
      - model
      - messages
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        completion_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
            visible_tokens:
              type: integer
        total_tokens:
          type: integer
        reasoning_tokens:
          type: integer
        cache_read_tokens:
          type: integer
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          description: length means the total completion budget was exhausted, including
            during reasoning; stop means normal completion.
          type:
          - string
          - 'null'
          enum:
          - stop
          - length
          - tool_calls
          - content_filter
          - reasoning
          - null
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    ResponsesContentPart:
      type: object
      properties:
        type:
          type: string
          enum:
          - input_text
          - output_text
        text:
          type: string
      required:
      - type
      - text
    ResponsesInputItem:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - message
          role:
            type: string
            enum:
            - system
            - developer
            - user
            - assistant
          content:
            oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesContentPart'
        required:
        - role
        - content
      - type: object
        properties:
          type:
            type: string
            enum:
            - function_call
          call_id:
            type: string
          name:
            type: string
          arguments:
            type: string
            description: JSON-encoded arguments
        required:
        - type
        - call_id
        - name
        - arguments
      - type: object
        properties:
          type:
            type: string
            enum:
            - function_call_output
          call_id:
            type: string
          output:
            type: string
        required:
        - type
        - call_id
        - output
    ResponsesFunctionTool:
      type: object
      description: A local function declaration. The nested Chat Completions-compatible
        function shape is also accepted.
      properties:
        type:
          type: string
          enum:
          - function
        name:
          type: string
        description:
          type: string
        parameters:
          type: object
        strict:
          type: boolean
        function:
          type: object
      required:
      - type
    CreateResponseRequest:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Public model ID returned by GET /models
        input:
          oneOf:
          - type: string
          - type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/ResponsesInputItem'
        stream:
          type: boolean
          default: false
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          exclusiveMinimum: 0
          maximum: 1
        max_output_tokens:
          type: integer
          minimum: 1
        tools:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/ResponsesFunctionTool'
        tool_choice:
          oneOf:
          - type: string
            enum:
            - auto
            - required
            - none
          - type: object
        parallel_tool_calls:
          type: boolean
        text:
          type: object
          properties:
            format:
              type: object
        reasoning:
          type: object
          description: Model-dependent reasoning controls; public reasoning text is
            not exposed.
        metadata:
          type: object
        store:
          type: boolean
          enum:
          - false
          default: false
        previous_response_id:
          type: 'null'
        prompt_cache_key:
          type: 'null'
      required:
      - model
      - input
    ResponsesUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens:
          type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        total_tokens:
          type: integer
      required:
      - input_tokens
      - output_tokens
      - total_tokens
    ResponseObject:
      type: object
      properties:
        id:
          type: string
          pattern: ^resp_
        object:
          type: string
          enum:
          - response
        created_at:
          type: integer
        status:
          type: string
          enum:
          - completed
          - incomplete
          - in_progress
        error:
          type:
          - object
          - 'null'
        incomplete_details:
          type:
          - object
          - 'null'
        model:
          type: string
        output:
          type: array
          items:
            type: object
        parallel_tool_calls:
          type: boolean
        previous_response_id:
          type: 'null'
        metadata:
          type: object
        usage:
          oneOf:
          - $ref: '#/components/schemas/ResponsesUsage'
          - type: 'null'
      required:
      - id
      - object
      - created_at
      - status
      - model
      - output
    AudioTranscriptionRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: Audio file (multipart)
        model:
          type: string
        language:
          type: string
        response_format:
          type: string
          enum:
          - json
          - text
          - srt
          - verbose_json
          - vtt
        temperature:
          type: number
        timestamp_granularities:
          type: array
          items:
            type: string
            enum:
            - word
            - segment
      required:
      - file
      - model
    AudioSpeechRequest:
      type: object
      properties:
        model:
          type: string
        input:
          type: string
          description: Text to synthesize
        voice:
          type: string
          description: Voice identifier
        response_format:
          type: string
          enum:
          - wav
          - mp3
          - flac
          - opus
          - pcm
          default: wav
        speed:
          type: number
          default: 1.0
      required:
      - model
      - input
    AnthropicMessageRequest:
      type: object
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                - user
                - assistant
              content:
                oneOf:
                - type: string
                - type: array
                  items:
                    type: object
            required:
            - role
            - content
        max_tokens:
          type: integer
        system:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
        temperature:
          type: number
        top_p:
          type: number
        top_k:
          type: integer
        stop_sequences:
          type: array
          items:
            type: string
        tools:
          type: array
        tool_choice:
          type: object
        metadata:
          type: object
      required:
      - model
      - messages
      - max_tokens
    AnthropicMessageResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - message
        role:
          type: string
          enum:
          - assistant
        content:
          type: array
          items:
            type: object
        model:
          type: string
        stop_reason:
          type:
          - string
          - 'null'
        stop_sequence:
          type:
          - string
          - 'null'
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
    AnthropicError:
      type: object
      properties:
        type:
          type: string
          enum:
          - error
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - permission_error
              - not_found_error
              - request_too_large
              - rate_limit_error
              - api_error
              - overloaded_error
            message:
              type: string
          required:
          - type
          - message
      required:
      - type
      - error
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
  responses:
    BadRequest:
      description: Bad request — invalid parameters or payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Model not allowed for this API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimit:
      description: Rate limit or admission capacity is full. The message states when
        to retry; vision saturation also reports active/total vision concurrency.
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Public model not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RequestTooLarge:
      description: Request body exceeds the limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: Invalid or failed upstream response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: No healthy route
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    GatewayTimeout:
      description: Backend generation timeout
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
security:
- BearerAuth: []
tags:
- name: Models
  description: Model catalog
- name: Chat Completions
  description: OpenAI-compatible chat completions
- name: Responses
  description: OpenAI Responses API compatibility for stateless text generation
- name: Messages
  description: Anthropic Messages compatibility
- name: Audio
  description: Speech recognition and synthesis
- name: Health
  description: Service health check
