kymaapi-com Chat API

openapi: 3.2.0
info:
  title: Kymaapi Com Chat 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 Chat 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: Chat
  description: Chat completion endpoints (OpenAI + Anthropic format)
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      description: Generate a chat response from a model. OpenAI-compatible format. Supports streaming, tool calling, structured outputs, and prompt caching.
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              description: Server-sent events stream (when stream=true)
          headers:
            X-Kyma-Model:
              description: Actual model used for this request
              schema:
                type: string
            X-Kyma-Alias:
              description: Alias that was resolved (if alias was used)
              schema:
                type: string
            X-Kyma-Fallback:
              description: Whether a fallback provider was used
              schema:
                type: boolean
            X-Kyma-Fallback-Layer:
              description: Fallback layer used (1=same model different provider, 3=different model)
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /messages:
    post:
      operationId: createMessage
      summary: Create message (Anthropic format)
      description: Generate a response using the Anthropic Messages API format. Same models and pricing as /chat/completions.
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessageRequest'
      responses:
        '200':
          description: Message response in Anthropic format
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
components:
  schemas:
    PaymentRequired:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              enum:
              - billing_error
              description: Always `billing_error`, on every surface.
            code:
              type: string
              enum:
              - model_requires_paid
              - insufficient_credits
              description: The rule that refused.
            param:
              type: string
              nullable: true
            retryable:
              type: boolean
            request_id:
              type: string
            doc_url:
              type: string
        type:
          type: string
          enum:
          - error
          description: Anthropic-compat envelope marker. Only on /v1/messages.
        topup:
          type: string
          description: Machine top-up endpoint. An agent with a wallet and no human can pay here; it is a hint in the body, never a payment challenge.
          example: https://api.kymaapi.com/v1/topup
        need_usd:
          type: number
          description: Worst-case cost of this request, USD. `insufficient_credits` only.
        have_usd:
          type: number
          description: Spendable credit at the moment of the refusal, USD. `insufficient_credits` only.
        balance:
          type: number
          description: Mirror of `details.balance`.
        required:
          type: number
          description: 'Mirror of `details.required`. Zero on `model_requires_paid`: no top-up amount makes a premium model callable on signup credit.'
        topup_url:
          type: string
          description: Billing page for a human. Mirror of `details.topup_url`.
          example: https://kymaapi.com/billing
        details:
          type: object
          properties:
            balance:
              type: number
            required:
              type: number
            topup_url:
              type: string
            hint:
              type: string
            endpoint_id:
              type: string
              description: The model the caller asked for.
          description: The nested envelope the media, audio and Anthropic-compat surfaces emit. Read this first; the top-level mirrors exist for older parsers. (/v1/embeddings emits the same envelope for a low balance, but it has its own check rather than this gate, so it carries neither code.)
      description: 402 — the access gate refused. `model_requires_paid` (signup credit is a free tier, not the whole catalogue) or `insufficient_credits` (the balance does not cover the request).
    ChatCompletionRequest:
      type: object
      properties:
        model:
          type: string
          description: Exact model ID, e.g. qwen-3.6-plus. See GET /v1/models for the list.
          examples:
          - qwen-3.6-plus
          - qwen-3-coder
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of messages in the conversation
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: Sampling temperature. Lower = more focused, higher = more creative
        max_tokens:
          type: integer
          description: Maximum tokens to generate. Default 4096. Forwarded directly to model with no gateway cap
        stream:
          type: boolean
          default: false
          description: Stream response as server-sent events
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling parameter
        tools:
          type: array
          items:
            type: object
            properties: {}
          description: List of tools/functions the model can call. Supported on 15/16 models
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
              - text
              - json_object
          required:
          - type
          description: Force output format. Use json_object for structured outputs
      required:
      - model
      - messages
    Message:
      type: object
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          anyOf:
          - type: string
          - type: array
            items:
              type: object
              properties: {}
            description: Multimodal content (text + images)
        tool_calls:
          type: array
          items:
            type: object
            properties: {}
          description: Tool calls made by the assistant
        tool_call_id:
          type: string
          description: ID of the tool call this message is responding to
      required:
      - role
      - content
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 'One sentence: what happened and what to do next.'
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - billing_error
              - permission_error
              - not_found_error
              - request_too_large
              - rate_limit_error
              - timeout_error
              - upstream_error
              - api_error
              description: The category. On /v1/messages, Anthropic's error type for the same condition.
            code:
              type: string
              enum:
              - missing_api_key
              - invalid_api_key
              - invalid_login
              - password_reset_required
              - invalid_google_token
              - permission_denied
              - voice_not_owned
              - session_required
              - csrf_failed
              - route_refused
              - content_refused
              - invalid_json
              - missing_parameter
              - invalid_parameter
              - wrong_endpoint
              - unsupported_content
              - unsupported_media_type
              - request_rejected
              - no_speech_detected
              - segments_unsupported
              - method_not_allowed
              - captcha_failed
              - invalid_signature
              - account_exists
              - request_too_large
              - request_exceeds_tier_limit
              - endpoint_not_found
              - endpoint_retired
              - model_not_found
              - model_retired
              - job_not_found
              - model_requires_paid
              - insufficient_credits
              - tier_required
              - payment_required
              - rate_limit_exceeded
              - concurrency_limit_exceeded
              - media_rate_exceeded
              - queue_full
              - too_many_sessions
              - too_many_attempts
              - signup_paused
              - upstream_rate_limited
              - provider_unavailable
              - model_unavailable
              - upstream_invalid_response
              - upstream_timeout
              - stream_interrupted
              - upload_timeout
              - media_paused
              - service_unavailable
              - internal_error
              - signup_failed
              - settle_failed
              description: 'Stable machine code: added, never renamed or removed. Each has an entry at https://docs.kymaapi.com/api-reference/errors'
            param:
              type: string
              nullable: true
              description: The request field at fault, or null.
            retryable:
              type: boolean
              description: Whether the same request can succeed if sent again (after `Retry-After`). Also sent as the `x-should-retry` header.
            request_id:
              type: string
              description: Same value as the `x-request-id` header. Quote it to support.
              example: req_7f3c2a9e0b1d4c6f8a2e5b7d9c1f3a5e
            doc_url:
              type: string
              description: This code's entry on the errors page.
              example: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
          required:
          - message
          - type
          - code
      required:
      - error
      description: 'Every error body. On /v1/messages the same object sits in Anthropic''s envelope: `type: "error"` on top, an Anthropic `error.type`, and `request_id` also at the top level.'
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - chat.completion
        created:
          type: integer
        model:
          type: string
          description: Actual model used
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/Message'
              finish_reason:
                type: string
                enum:
                - stop
                - length
                - tool_calls
            required:
            - index
            - message
            - finish_reason
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
            cached_tokens:
              type: integer
              description: Number of prompt tokens served from cache
            cost:
              type: number
              description: Cost in USD for this request
            cache_discount:
              type: number
              description: Amount saved from prompt caching in USD
          required:
          - prompt_tokens
          - completion_tokens
          - total_tokens
      required:
      - id
      - object
      - created
      - model
      - choices
      - usage
    AnthropicMessageRequest:
      type: object
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            type: object
            properties: {}
        max_tokens:
          type: integer
        system:
          type: string
        stream:
          type: boolean
        tools:
          type: array
          items:
            type: object
            properties: {}
      required:
      - model
      - messages
      - max_tokens
  responses:
    NotFound:
      description: Unknown model (`model_not_found`, `model_retired` with `did_you_mean`) or endpoint.
      headers:
        x-request-id:
          description: Request id, on every response. Quote it to support.
          schema:
            type: string
        x-should-retry:
          description: '`true` when the same request can succeed if retried.'
          schema:
            type: string
            enum:
            - 'true'
            - 'false'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The model or Kyma is unavailable right now (`provider_unavailable`, `model_unavailable`, `service_unavailable`). Retry after `Retry-After`.
      headers:
        x-request-id:
          description: Request id, on every response. Quote it to support.
          schema:
            type: string
        x-should-retry:
          description: '`true` when the same request can succeed if retried.'
          schema:
            type: string
            enum:
            - 'true'
            - 'false'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: 'Valid key, but this request is not allowed (for example `route_refused`: every route for the model refused the content).'
      headers:
        x-request-id:
          description: Request id, on every response. Quote it to support.
          schema:
            type: string
        x-should-retry:
          description: '`true` when the same request can succeed if retried.'
          schema:
            type: string
            enum:
            - 'true'
            - 'false'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayloadTooLarge:
      description: Request body over the endpoint limit (`request_too_large`).
      headers:
        x-request-id:
          description: Request id, on every response. Quote it to support.
          schema:
            type: string
        x-should-retry:
          description: '`true` when the same request can succeed if retried.'
          schema:
            type: string
            enum:
            - 'true'
            - 'false'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds until the rate limit resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: 'Payment required. One gate decides every refusal and `error.code` names the rule that fired: `model_requires_paid` (the account has never deposited and this model is outside the free tier, which `free_tier` on `GET /v1/models` states in advance) or `insufficient_credits` (the balance does not cover the request; `need_usd` and `have_usd` say by how much). `error.type` is `billing_error` on every surface, /v1/messages included. `topup` is the machine endpoint an agent can pay without a human; `topup_url` is the page for a human.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          examples:
            model_requires_paid:
              summary: Never funded, premium model — /chat/completions, /completions
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            insufficient_credits:
              summary: Balance below the worst case — /chat/completions, /completions
              value:
                need_usd: 0.012562
                have_usd: 0.0004
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.0004
                required: 0.012562
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.01 of credit; you have $0.0004. Top up at https://kymaapi.com/billing or lower max_tokens.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.0004
                  required: 0.012562
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.02 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: deepseek-v3
            model_requires_paid_messages:
              summary: Never funded, premium model — /messages (Anthropic-compat envelope)
              value:
                type: error
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            model_requires_paid_media:
              summary: Never funded, premium SKU — media and audio surfaces (D3 envelope)
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: 'gpt-image-2 is not in the free tier; add credits to use it. Free-tier media: gemini-3.5-transcribe, gpt-4o-mini-transcribe-2025-12-15, gpt-transcribe, minimax-image-01, whisper-v3-turbo.'
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
            insufficient_credits_media:
              summary: Balance below the job estimate — media and audio surfaces (D3 envelope)
              value:
                need_usd: 0.054
                have_usd: 0.01
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.01
                required: 0.054
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.05 of credit; you have $0.01. Top up at https://kymaapi.com/billing.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.01
                  required: 0.054
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.06 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
  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