topxea-com Type Safe API

openapi: 3.2.0
info:
  title: TopxAI Type Safe API
  version: '2026-10-25'
  summary: One OpenAI- and Anthropic-compatible endpoint for Claude, GPT, Grok, GLM, Kimi, DeepSeek and Jev.
  description: 'TopxAI relays requests to the model providers at fixed USD prices on prepaid credit. The request body is forwarded unchanged and the response is returned unchanged, except where a request in another format has to be converted for the model (for example /v1/messages to a model other than Claude), on /v1/responses, where the echoes of the request and members the upstream adds are rewritten, and on /v1/chat/completions, where provider_specific_fields, a member some upstream capacity adds, is removed; parameters not listed here pass through to the provider. A request without a system prompt that reaches the GPT provider''s Responses API (gpt-6.1-sol on every endpoint, gpt-6-astra on /v1/responses) is sent the instructions "You are a helpful assistant.", so the provider does not add its own longer prompt; a request with its own system prompt or instructions is forwarded as sent. Base URL for OpenAI-style SDKs: https://ai.topxea.com/v1. Base URL for the Anthropic SDK: https://ai.topxea.com. Prompts, completions and files are relayed in memory and never stored. Prices: https://ai.topxea.com/pricing and https://ai.topxea.com/api/pricing.'
  termsOfService: https://ai.topxea.com/user-agreement
  contact:
    name: TopxAI support
    email: support@topxea.com
    url: https://ai.topxea.com/docs
  x-logo:
    url: https://ai.topxea.com/favicon.svg
  license:
    name: Terms of use
    url: https://ai.topxea.com/user-agreement
servers:
- url: https://ai.topxea.com
  description: Production
security:
- bearerAuth: []
tags:
- name: TypeSafe
  description: 'System One: typed questions about a state, answered with probabilities.'
paths:
  /v1/systemone:
    post:
      tags:
      - TypeSafe
      operationId: systemOne
      summary: System One (Jev)
      description: 'TypeSafe''s System One: typed questions about a state, answered with probabilities (or, for Box, the edges of a box in an image) instead of text. Model jev-1.14.0; jev-latest and jev-preview are accepted and answered by jev-1.14.0. $0.04494 per 1M input tokens, image tokens included, output free. /v1/system_one is accepted as a second spelling. The body must carry model, state and a non-empty questions object; state and questions together are at most 1 MiB, the whole body at most 32 MiB, and assets at most 1,024 images with reference strings of at most 1,024 bytes each and 64 KiB together. Images (PNG or JPEG) are listed once in assets under a reference string and placed by writing that reference in the state, an instruction or a criterion; send them base64-encoded in the JSON body or as file parts of a multipart/form-data body whose first part, named request, holds the JSON. Images and Box questions are an experimental TypeSafe feature: the relay adds the TypeSafe-Danger-Zone-Images header the provider requires, so it is optional here.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemOneRequest'
            example:
              model: jev-1.14.0
              state: I have asked three times now. Can I please just talk to a real person?
              questions:
                is_human_escalation:
                  type: noul
                  instructions: Is the customer asking for a human agent?
          multipart/form-data:
            schema:
              type: object
              required:
              - request
              properties:
                request:
                  $ref: '#/components/schemas/SystemOneRequest'
                  description: The JSON body; must be the first part. Each asset names its file part in part.
              additionalProperties:
                type: string
                format: binary
                description: One image file part (image/png, image/jpeg or application/octet-stream) per asset, under the name its asset gives in part.
            encoding:
              request:
                contentType: application/json
      responses:
        '200':
          description: TypeSafe's answers, unchanged, with usage. usage.input_tokens includes the tokens of every image (about ceil(width/28) x ceil(height/28) x 2 per use).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemOneResponse'
              example:
                model: jev-1.14.0
                answers:
                  is_human_escalation:
                    type: noul
                    noul: 0.99
                usage:
                  input_tokens: 43
                  output_tokens: 20
        '422':
          description: TypeSafe's validation detail, as written. Nothing is charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemOneProviderError'
        '400':
          description: 'The body failed the relay''s checks (Error), or TypeSafe rejected it: an image it cannot read or outside its size limits, an asset nobody references, a request over the context length (SystemOneProviderError). Nothing is charged.'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Error'
                - $ref: '#/components/schemas/SystemOneProviderError'
        '413':
          description: The body is over 32 MiB (Error), or TypeSafe found an image or all images together over its size limits (SystemOneProviderError). Nothing is charged.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Error'
                - $ref: '#/components/schemas/SystemOneProviderError'
        '401':
          description: The key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The balance is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The model is not sold here, is not on this key's route, or is excluded by the key's model limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited; Retry-After gives the wait in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: No line can serve the model right now, or the provider is overloaded; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: TypeSafe-Danger-Zone-Images
        in: header
        required: false
        description: 'TypeSafe''s opt-in for images and Box questions. Optional on TopxAI: the relay sends it whenever the request carries assets or a Box question.'
        schema:
          type: string
          enum:
          - 'true'
components:
  schemas:
    SystemOneAsset:
      type: object
      properties:
        type:
          type: string
          enum:
          - image
        format:
          type: string
          enum:
          - png
          - jpg
          - jpeg
          description: Required with data_base64.
        data_base64:
          type: string
          description: 'The image file, standard base64 with padding, no data: prefix. PNG or JPEG, 280 to 1568 pixels on each side as measured on 2026-10-16 (TypeSafe documents 256).'
        part:
          type: string
          description: In a multipart body, the name of the file part holding the image.
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Ends with a request id to quote to support@topxea.com.
            type:
              type: string
            code:
              type:
              - string
              - integer
              - 'null'
    SystemOneRequest:
      type: object
      required:
      - model
      - state
      - questions
      properties:
        model:
          type: string
          enum:
          - jev-1.14.0
          - jev-latest
          - jev-preview
        state:
          description: 'What the questions are about: a string, or structured JSON such as a record or a chat log; image references may appear in it. Default limits: 64k tokens per request and 32k per question, the state included.'
          oneOf:
          - type: string
          - type: object
          - type: array
        questions:
          type: object
          minProperties: 1
          additionalProperties:
            $ref: '#/components/schemas/SystemOneQuestion'
        assets:
          type: object
          description: Images keyed by reference string. Every reference must appear in the state, an instruction or a criterion; each appearance adds the image again.
          additionalProperties:
            $ref: '#/components/schemas/SystemOneAsset'
      additionalProperties: true
    SystemOneResponse:
      type: object
      properties:
        model:
          type: string
        answers:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
      additionalProperties: true
    SystemOneQuestion:
      type: object
      required:
      - type
      - instructions
      properties:
        type:
          type: string
          enum:
          - noul
          - choice
          - score
          - box
          description: 'noul (probability of yes), choice (one option of criteria, with a probability per option), score (a value across ordered criteria levels) or box (where the target is in an image: top, bottom, left and right as fractions of the image).'
        instructions:
          description: The question, or for box what to find and in which image. A string, or an object or array that holds the question and data it refers to; may contain image references.
          oneOf:
          - type: string
          - type: object
          - type: array
        criteria:
          description: 'noul: optional {true, false} definitions. choice: object of option name to description (or null), at most 255 options. score: ordered array of 2 to 10 level descriptions. box: none. Descriptions may contain image references.'
          oneOf:
          - type: object
          - type: array
      additionalProperties: true
    SystemOneProviderError:
      type: object
      description: TypeSafe's own error body, passed through as written (the channel key and upstream hosts removed).
      properties:
        detail:
          description: An object with error_type and message, or a list of field errors.
          oneOf:
          - type: object
          - type: array
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A TopxAI API key (sk-...) as Authorization: Bearer <key>. Keys are created at https://ai.topxea.com/keys.'
    anthropicKey:
      type: apiKey
      in: header
      name: x-api-key
      description: The same TopxAI key, the way the Anthropic SDK sends it.
externalDocs:
  description: Documentation
  url: https://ai.topxea.com/docs