KeepBal Models API

openapi: 3.2.0
info:
  title: KeepBal Models API
  version: 0.1.0
  summary: One key and one prepaid wallet for agent tools.
  description: 'Hosted MCP: https://keepbal.com/mcp (Streamable HTTP, bearer key). Setup: https://keepbal.com/docs/mcp.

    Search for a tool, inspect its price, and run it with a KeepBal key.

    Tool search status: live. Model inference status: live.

    Read /catalog.json for status and available on each model, tool, and operation.

    Signup includes $1 free credit, once. Top up $10, $20, $50, or $100 in Console Wallet with Paddle.

    Top-up fee: 8% of the credit, rounded up to the cent, + $0.35 before tax.

    Only the credit amount is added to your wallet. No subscription.

    Fixed tools show the per-call price; variable tools bill provider price plus 35%. Inspect returns pricing metadata, not a quote.

    Fixed tools charge the published per-call price. Variable tools charge the provider''s reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.

    Charges settle after calls. Daily limits are not available. Catalog calls support max_cost_usd spending caps.

    Model charges require returned token usage. Chat Completions, Responses and Messages support SSE on configured live routes. Catalog streams may be buffered until usage settlement is durable. Embeddings do not stream. Image pricing is not implemented.

    MCP is live via Streamable HTTP; A2A transport is not live. Request formats and current availability: /llms.txt and /SKILL.md.

    KeepBal errors use the OpenAI error format. Upstream error bodies may differ.

    Authenticate protected requests with Authorization: Bearer dgk_live_...

    KeepBal error envelope: {"error":{"message","type","code","param","request_id"}}.

    A 503 provider_unavailable is never billed.

    Use x-keepbal-request-id and x-keepbal-cost-micros when present. Catalog responses omit private routing and provider-mode headers.

    Streaming responses have no final cost header; check Usage after the call is recorded.

    Approximate x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and retry-after headers are exposed to browsers.

    Primary public host: https://keepbal.com. See /llms-full.txt for the technical reference.'
  contact:
    name: KeepBal
    url: https://keepbal.com
    email: hello@keepbal.com
servers:
- url: https://keepbal.com
  description: KeepBal (canonical public origin)
security:
- bearerAuth: []
tags:
- name: Models
  description: OpenAI-compatible inference (`/v1`). Billed per token from the KeepBal catalog.
paths:
  /v1/models:
    get:
      tags:
      - Models
      summary: List callable models only (free; an empty data array means none are available)
      responses:
        '200':
          description: OpenAI-style list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getV1Models
      x-operation-id-source: derived
  /v1/chat/completions:
    post:
      tags:
      - Models
      summary: Chat completion (OpenAI-compatible, streaming supported)
      description: 'Only live catalog model IDs are accepted; all others return 404 model_not_found. A preflight estimate uses input characters / 4 plus the requested output token limit (4096 when omitted), at catalog prices; insufficient balance returns 402. An omitted output limit is injected as 4096 tokens: max_completion_tokens for GPT-5 Chat Completions, max_tokens for other Chat Completions and Messages, and max_output_tokens for Responses. Embeddings do not receive an output limit. Explicit limits are validated and may be clamped to the route maximum. Request/response shapes follow the OpenAI Chat Completions API. For `stream: true`

        the gateway forces `stream_options.include_usage` so the final chunk carries token

        counts; the response is passed through as `text/event-stream`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - messages
              properties:
                model:
                  type: string
                  example: gpt-5.4-mini
                messages:
                  type: array
                  items:
                    type: object
                    required:
                    - role
                    - content
                    properties:
                      role:
                        type: string
                        enum:
                        - system
                        - user
                        - assistant
                        - tool
                      content: {}
                stream:
                  type: boolean
                  default: false
                temperature:
                  type: number
                max_tokens:
                  type: integer
              additionalProperties: true
      responses:
        '200':
          description: Completion. Non-streaming responses include x-keepbal-cost-micros; streaming usage is settled asynchronously.
          headers:
            x-keepbal-cost-micros:
              description: Final cost in integer micro-USD for non-streaming responses.
              schema:
                type: integer
            x-keepbal-request-id:
              description: KeepBal request identifier.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1ChatCompletions
      x-operation-id-source: derived
  /v1/embeddings:
    post:
      tags:
      - Models
      summary: Embeddings (OpenAI-compatible)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - input
              properties:
                model:
                  type: string
                  example: jina-embeddings-v3
                input: {}
              additionalProperties: true
      responses:
        '200':
          description: Embeddings
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      operationId: postV1Embeddings
      x-operation-id-source: derived
  /v1/messages:
    post:
      tags:
      - Models
      summary: Anthropic Messages-compatible endpoint
      responses:
        '200':
          description: Message
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postV1Messages
      x-operation-id-source: derived
  /v1/images/generations:
    post:
      tags:
      - Models
      summary: Image generation (OpenAI-compatible)
      responses:
        '200':
          description: Images
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postV1ImagesGenerations
      x-operation-id-source: derived
  /v1/completions:
    post:
      tags:
      - Models
      summary: Text completions (check catalog availability)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              properties:
                model:
                  type: string
              additionalProperties: true
      responses:
        '200':
          description: Provider response; billing only when token usage can be extracted
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postV1Completions
      x-operation-id-source: derived
  /v1/responses:
    post:
      tags:
      - Models
      summary: Model responses (check catalog availability)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              properties:
                model:
                  type: string
              additionalProperties: true
      responses:
        '200':
          description: Provider response; billing only when token usage can be extracted
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postV1Responses
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: Missing/invalid/revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: Wallet below the minimum balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ProviderUnavailable:
      description: No upstream configured for this route. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: API key scope denied or account access suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key requests/minute exceeded (`retry-after` plus `x-ratelimit-*` headers)
      headers:
        retry-after:
          schema:
            type: integer
        x-ratelimit-limit:
          schema:
            type: integer
        x-ratelimit-remaining:
          schema:
            type: integer
        x-ratelimit-reset:
          schema:
            type: integer
          description: Unix seconds when the current minute window ends
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: Invalid input, missing required parameters, or an invalid/conflicting spend cap
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
              enum:
              - unauthorized
              - account_exists
              - invalid_api_key
              - missing_api_key
              - key_revoked
              - scope_denied
              - insufficient_credits
              - rate_limited
              - invalid_request
              - model_not_found
              - not_found
              - method_not_allowed
              - not_implemented
              - provider_unavailable
              - upstream_error
              - console_disabled
              - forbidden
              - internal_error
            param:
              type:
              - string
              - 'null'
            request_id:
              type: string
              description: Same value as the x-keepbal-request-id response header.
    ModelsList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              object:
                type: string
                const: model
              created:
                type: integer
              owned_by:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dgk_live_...