kymaapi-com Completions API

openapi: 3.2.0
info:
  title: Kymaapi Com Completions 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 Completions 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: Completions
paths:
  /completions:
    post:
      summary: Create a completion (legacy)
      description: 'OpenAI''s deprecated text-completion shape, served for compatibility with older SDK pins and scripts. Prefer `POST /v1/chat/completions` for anything new.


        Takes `prompt` instead of `messages` and returns `choices[].text` instead of `choices[].message.content`. Everything else — models, pricing, streaming, failover — is identical, because this is an adapter over the chat endpoint rather than a separate path.


        Not supported: `suffix` (fill-in-the-middle), a multi-element `prompt` array, and `echo` together with `stream`. Each returns 400 naming the alternative rather than silently returning something that looks right.'
      operationId: createCompletion
      deprecated: true
      tags:
      - Completions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - prompt
              properties:
                model:
                  type: string
                  example: qwen3.7-flash
                prompt:
                  type: string
                  description: The text to complete. A single-element array is accepted; more than one is refused.
                  example: Write a haiku about routing
                max_tokens:
                  type: integer
                temperature:
                  type: number
                stream:
                  type: boolean
                  default: false
                echo:
                  type: boolean
                  default: false
                  description: Prepend the prompt to the completion. Cannot be combined with `stream`.
                stop:
                  description: Up to 4 stop sequences.
                  oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
      responses:
        '200':
          description: A legacy `text_completion` object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                    example: text_completion
                  created:
                    type: integer
                  model:
                    type: string
                  choices:
                    type: array
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                        index:
                          type: integer
                        logprobs:
                          type: 'null'
                        finish_reason:
                          type: string
                          example: stop
                  usage:
                    type: object
                    description: Identical to the chat endpoint, including `usage.cost`.
        '400':
          description: Missing `prompt`, a multi-prompt array, `suffix`, or `echo` with `stream`.
        '401':
          description: Missing or invalid API key.
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Unknown model.
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '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).
    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.'
  responses:
    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'
    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