kymaapi-com Models API

openapi: 3.2.0
info:
  title: Kymaapi Com Models API
  version: 1.0.0
  contact:
    name: Kyma API
    url: https://kymaapi.com
    email: support@kymaapi.com
  license:
    name: Proprietary
  termsOfService: https://kymaapi.com/terms
  description: 'Operations tagged Models across 2 of this provider''s published API definitions: kymaapi-com-openapi.json, kymaapi-com-v1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://kymaapi.com/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Models
  description: Model catalog, recommendations, and filtering
paths:
  /models:
    get:
      operationId: listModels
      summary: List all models
      description: Returns all available models with pricing, capabilities, context windows, and recommendations. No authentication required.
      tags:
      - Models
      security: []
      parameters:
      - name: type
        in: query
        description: 'Filter by model type (comma-separated = OR, since a model has exactly one type). Values: language, image, video, embedding, reranking, transcription, realtime, speech'
        schema:
          type: string
      - name: tags
        in: query
        description: 'Filter by capability tag (comma-separated = AND). Values: tool-use, reasoning, vision, implicit-caching, explicit-caching, file-input, web-search, image-generation, video-generation, websocket-realtime, websocket-transcription, fast'
        schema:
          type: string
      - name: use_cases
        in: query
        description: 'Filter by use case (comma-separated = AND). Values: write-code, build-agents, chat, write-content, translate, research-web, analyse-documents, solve-math, generate-images, edit-images, generate-video, transcribe-audio, generate-speech'
        schema:
          type: string
      - name: recommended_for
        in: query
        description: DEPRECATED — alias of use_cases, kept for existing callers. Accepts the pre-2026-07-27 vocabulary (coding, agent, general, image, video, transcribe, …) and resolves it to the use_cases equivalent. Prefer use_cases for new integrations.
        schema:
          type: string
        deprecated: true
      - name: tools
        in: query
        description: Filter to models supporting tool calling
        schema:
          type: boolean
      - name: vision
        in: query
        description: Filter to models supporting image input
        schema:
          type: boolean
      - name: reasoning
        in: query
        description: Filter to models with reasoning capabilities
        schema:
          type: boolean
      - name: structured_outputs
        in: query
        description: Filter to models supporting structured outputs / JSON mode
        schema:
          type: boolean
      - name: latency_tier
        in: query
        description: Filter by latency tier
        schema:
          type: string
          enum:
          - fast
          - medium
          - slow
      - name: cost_tier
        in: query
        description: Filter by cost tier
        schema:
          type: string
          enum:
          - cheap
          - balanced
          - premium
      - name: quality_tier
        in: query
        description: Filter by quality tier
        schema:
          type: string
          enum:
          - efficient
          - strong
          - frontier-open
      - name: min_context_window
        in: query
        description: Minimum context window size in tokens
        schema:
          type: integer
      - name: max_input_price
        in: query
        description: Maximum input price per 1M tokens
        schema:
          type: number
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /models/recommend:
    get:
      operationId: recommendModel
      summary: Get model recommendation
      description: Get a model recommendation by use case or specific agent. Returns config examples. No authentication required.
      tags:
      - Models
      security: []
      parameters:
      - name: agent
        in: query
        description: 'Agent name for specific config. Supported: cline, roo-code, openclaw, claude-code, aider, opencode, cursor, kilo-code'
        schema:
          type: string
      - name: usecase
        in: query
        description: 'Use case for recommendation. Values: coding, reasoning, general, agent, vision, long-context, cheap, fast'
        schema:
          type: string
      - name: for
        in: query
        description: Alias for usecase parameter
        schema:
          type: string
      responses:
        '200':
          description: Model recommendation with config example
    servers:
    - url: https://kymaapi.com/v1
      description: Production
components:
  schemas:
    Model:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        context_window:
          type: integer
        max_output_tokens:
          type: integer
        best_for:
          type: string
        speed:
          type: string
        recommended:
          type: boolean
        hot:
          type: boolean
        input_modalities:
          type: array
          items:
            type: string
            enum:
            - text
            - image
            - audio
            - video
            - file
        output_modalities:
          type: array
          items:
            type: string
            enum:
            - text
            - audio
            - image
        supported_parameters:
          type: array
          items:
            type: string
        supports_tools:
          type: boolean
        supports_vision:
          type: boolean
        supports_reasoning:
          type: boolean
        supports_structured_outputs:
          type: boolean
        latency_tier:
          type: string
          enum:
          - fast
          - medium
          - slow
        cost_tier:
          type: string
          enum:
          - cheap
          - balanced
          - premium
        quality_tier:
          type: string
          enum:
          - efficient
          - strong
          - frontier-open
        free_tier:
          type: boolean
          description: 'Whether an account that has never deposited may call this model. `cost_tier` and `tier` are editorial labels; this is the rule the API enforces — a request for a model with `free_tier: false` from a never-funded key is refused with 402 `model_requires_paid`. Derived from the published price (see the free-tier section of https://docs.kymaapi.com/pricing), so it moves with the catalogue rather than from a hand-kept list.'
          example: true
        release_stage:
          type: string
          enum:
          - stable
          - preview
          - limited
        release_date:
          type: string
          nullable: true
          description: Day the creator publicly released this model, `YYYY-MM-DD`. Null when the creator never stated one. Not to be confused with `created`, which timestamps this response.
          example: '2026-07-28'
        type:
          type: string
          enum:
          - language
          - image
          - video
          - embedding
          - reranking
          - transcription
          - audio-understanding
          - realtime
          - speech
          - decisions
        tags:
          type: array
          items:
            type: string
            enum:
            - tool-use
            - reasoning
            - vision
            - implicit-caching
            - explicit-caching
            - file-input
            - web-search
            - image-generation
            - video-generation
            - websocket-realtime
            - websocket-transcription
            - fast
        use_cases:
          type: array
          items:
            type: string
        recommended_for:
          type: array
          items:
            type: string
          description: Deprecated alias of use_cases.
        pricing:
          type: object
          properties:
            mode:
              type: string
            input:
              type: number
            output:
              type: number
            per_image_usd:
              type: number
            per_second_usd:
              type: number
            per_video_usd:
              type: number
            per_minute_usd:
              type: number
            per_kchar_usd:
              type: number
            per_song_usd:
              type: number
            per_call_usd:
              type: number
          description: What this model costs TODAY — the promotional rate while a promotion is running, the list rate otherwise. Token rates are USD per 1M tokens.
        list_price:
          type: object
          properties:
            mode:
              type: string
            input:
              type: number
            output:
              type: number
            per_image_usd:
              type: number
            per_second_usd:
              type: number
            per_video_usd:
              type: number
            per_minute_usd:
              type: number
            per_kchar_usd:
              type: number
            per_song_usd:
              type: number
            per_call_usd:
              type: number
          description: The stable rate a promotion returns to. Always present, and equal to `pricing` when no promotion is running, so a client can read one field unconditionally.
        promotion:
          type: object
          nullable: true
          properties:
            input:
              type: number
            output:
              type: number
            list_input:
              type: number
            list_output:
              type: number
            percent_off:
              type: integer
            ends:
              type: string
          required:
          - input
          - output
          - list_input
          - list_output
          - percent_off
          - ends
          description: The promotion in force, or null. `input`/`output` repeat `pricing`; `list_input`/`list_output` repeat `list_price`; `ends` is the inclusive `YYYY-MM-DD` date the promotional rate is promised through.
        gateway_output_limit:
          type: 'null'
          description: Always null. Kyma does not impose output limits
        max_tokens_passthrough:
          type: boolean
          enum:
          - true
          description: Always true. max_tokens is forwarded directly to the model
    ModelList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        aliases:
          type: object
          additionalProperties:
            type: string
          description: 'Always empty: Kyma publishes no model aliases. Kept for client compatibility.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Kyma API key (starts with ky-) or session token (starts with ks-)
x-refined-from:
- kymaapi-com-openapi.json
- kymaapi-com-v1-openapi.json