openapi: 3.1.0 info: title: 'kai API - mconnect' description: 'OpenAI-compatible API gateway for AI services. Use standard OpenAI SDKs with your kai API key.' version: 1.0.0 contact: name: 'kai Support' email: support@kaino.at servers: - url: 'https://mconnect.kai.kaino.io' tags: - name: Chat description: '' - name: Audio description: '' - name: Documents description: '' - name: Models description: '' - name: Usage description: '' components: securitySchemes: default: type: http scheme: bearer description: 'Contact office@kaino.io to obtain an API key.' security: - default: [] paths: /api/v1/chat/completions: post: summary: 'Create a chat completion.' operationId: createAChatCompletion description: "Generates a model response for the given conversation. Follows the OpenAI chat\ncompletions format. Token usage is included in successful responses and counted\ntoward your billing period.\n\nStreaming is not currently supported — set `stream` to `false` or omit it." parameters: [] responses: 200: description: 'Successful completion' content: application/json: schema: type: object properties: id: type: string examples: - chatcmpl-kai-abc123 object: type: string examples: - chat.completion model: type: string examples: - Meta-Llama-3_3-70B-Instruct choices: type: array items: type: object properties: index: type: integer examples: - 0 message: type: object properties: role: type: string examples: - assistant content: type: string examples: - 'Hello! How can I help you today?' finish_reason: type: string examples: - stop examples: - - index: 0 message: role: assistant content: 'Hello! How can I help you today?' finish_reason: stop usage: type: object properties: prompt_tokens: type: integer examples: - 25 completion_tokens: type: integer examples: - 12 total_tokens: type: integer examples: - 37 examples: - id: chatcmpl-kai-abc123 object: chat.completion model: Meta-Llama-3_3-70B-Instruct choices: - index: 0 message: role: assistant content: 'Hello! How can I help you today?' finish_reason: stop usage: prompt_tokens: 25 completion_tokens: 12 total_tokens: 37 tags: - Chat requestBody: required: true content: application/json: schema: type: object properties: messages: type: array description: 'The messages to generate chat completions for. Must have at least 1 items.' items: type: object properties: role: type: string description: 'The role of the message author. Must be `system`, `user`, or `assistant`.' enum: - system - user - assistant examples: - user content: type: string description: 'The content of the message. Must be at least 1 character.' examples: - Hello! required: - role - content examples: - - role: system content: 'You are a helpful assistant.' - role: user content: Hello! model: type: - string - 'null' description: 'The model to use for completion. Use `GET /v1/models` to list available models. If omitted, the default model for your plan is used.' examples: - '' temperature: type: - number - 'null' description: 'Sampling temperature between 0 and 2. Higher values make output more random. Must be at least 0. Must not be greater than 2.' examples: - 0.7 max_tokens: type: - integer - 'null' description: 'Maximum number of tokens to generate. Range: 1-32768. Must be at least 1. Must not be greater than 32768.' examples: - 1024 top_p: type: - number - 'null' description: 'Nucleus sampling probability. Range: 0-1. Must be at least 0. Must not be greater than 1.' examples: - 1.0 stream: type: - boolean - 'null' description: 'Streaming is not currently supported. Must be `false` or omitted.' examples: - false 'n': type: - integer - 'null' description: 'Number of completions. Accepted for compatibility but always returns 1. Must be at least 1. Must not be greater than 10.' examples: - 1 stop: type: - string - 'null' description: 'Stop sequences. Accepted for compatibility but not supported.' examples: - null presence_penalty: type: - number - 'null' description: 'Presence penalty (-2 to 2). Accepted for compatibility but not supported. Must be at least -2. Must not be greater than 2.' examples: - 0.0 frequency_penalty: type: - number - 'null' description: 'Frequency penalty (-2 to 2). Accepted for compatibility but not supported. Must be at least -2. Must not be greater than 2.' examples: - 0.0 required: - messages /api/v1/audio/transcriptions: post: summary: 'Transcribe audio or video.' operationId: transcribeAudioOrVideo description: "Transcribes speech from an audio or video file. For video uploads, the audio track\nis automatically extracted before transcription. The file must contain at least one\naudio stream.\n\nCompatible with the OpenAI Whisper API format." parameters: [] responses: 200: description: 'Successful transcription' content: application/json: schema: type: object properties: text: type: string examples: - 'Der Patient berichtet über anhaltende Kopfschmerzen seit zwei Wochen.' examples: - text: 'Der Patient berichtet über anhaltende Kopfschmerzen seit zwei Wochen.' tags: - Audio requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: 'The audio or video file to transcribe. Max file size depends on your product plan. Supported formats: mp3, m4a, wav, webm, ogg, flac, aac (audio), mp4, webm, mov, avi, mkv (video with audio track). Must be a file. Must not be greater than 25600 kilobytes.' model: type: - string - 'null' description: 'The transcription model to use. Use `GET /v1/models` to list available models. If omitted, the default model for your plan is used.' enum: - whisper-1 examples: - '' language: type: - string - 'null' description: 'The language of the audio in ISO-639-1 format (e.g., `de`, `en`). Optional. Must be 2 characters.' examples: - de prompt: type: - string - 'null' description: "Optional text to guide the model's style. Max 1000 characters. Must not be greater than 1000 characters." examples: - 'This is a medical consultation.' response_format: type: - string - 'null' description: 'The format of the transcript output: `json`, `text`, `srt`, `verbose_json`, or `vtt`.' enum: - json - text - srt - verbose_json - vtt examples: - json temperature: type: - number - 'null' description: 'Sampling temperature between 0 and 1. Lower is more deterministic. Must be at least 0. Must not be greater than 1.' examples: - 0.0 required: - file /api/v1/documents/anonymize: post: summary: 'Anonymize documents by detecting and replacing PII with placeholders.' operationId: anonymizeDocumentsByDetectingAndReplacingPIIWithPlaceholders description: "Upload 1 file (PDF, DOCX, images, plain text). The API extracts text\n(with OCR fallback for scanned documents), detects personally identifiable\ninformation, and replaces it with numbered placeholders like\n`[[NAME_1]]`, `[[EMAIL_2]]`.\n\nReturns the sanitized text, a sanitized filename, and a mapping of placeholders\nto their original values.\n\nRequires the `documents_anonymize` permission on your API token's product." parameters: [] responses: 200: description: 'Successful anonymization' content: application/json: schema: type: object properties: object: type: string examples: - list data: type: array items: type: object properties: original_filename: type: string examples: - patient_report.pdf sanitized_filename: type: string examples: - patient_report.pdf sanitized_text: type: string examples: - "Patient: [[NAME_1]]\nDiagnose: [[MEDICAL_1]]" placeholders: type: object properties: '[[NAME_1]]': type: string examples: - 'Max Mustermann' '[[MEDICAL_1]]': type: string examples: - 'Diabetes Typ 2' metadata: type: object properties: extraction_method: type: string examples: - pdf_parser used_ocr: type: boolean examples: - false page_count: type: integer examples: - 2 strategy: type: string examples: - ai examples: - - original_filename: patient_report.pdf sanitized_filename: patient_report.pdf sanitized_text: "Patient: [[NAME_1]]\nDiagnose: [[MEDICAL_1]]" placeholders: '[[NAME_1]]': 'Max Mustermann' '[[MEDICAL_1]]': 'Diabetes Typ 2' metadata: extraction_method: pdf_parser used_ocr: false page_count: 2 strategy: ai examples: - object: list data: - original_filename: patient_report.pdf sanitized_filename: patient_report.pdf sanitized_text: "Patient: [[NAME_1]]\nDiagnose: [[MEDICAL_1]]" placeholders: '[[NAME_1]]': 'Max Mustermann' '[[MEDICAL_1]]': 'Diabetes Typ 2' metadata: extraction_method: pdf_parser used_ocr: false page_count: 2 strategy: ai tags: - Documents requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array description: 'Array containing 1 document file to anonymize. Max file size depends on your product plan. Supported formats: PDF, DOCX, PPTX, PPT, XLSX, XLS, CSV, JSON, PNG, JPEG, TIFF, TXT. Must be a file. Must not be greater than 25600 kilobytes.' items: type: string format: binary pii_types: type: array description: 'Optional array of PII types to detect. If omitted or empty, all 26 types are detected. Valid types: `name`, `email`, `phone`, `dob`, `address`, `insurance`, `iban`, `company`, `medical`, `credit_card`, `passport`, `vehicle`, `ip_address`, `url`, `username`, `vat_number`, `company_register`, `healthcare_number`, `tax_id`, `age`, `nationality`, `gender`, `religion`, `occupation`, `birth_year`, `linkedin`.' items: type: string enum: - name - email - phone - dob - address - insurance - iban - company - medical - credit_card - passport - vehicle - ip_address - url - username - vat_number - company_register - healthcare_number - tax_id - age - nationality - gender - religion - occupation - birth_year - linkedin examples: - - name required: - files /api/v1/documents/strip-metadata: post: summary: 'Strip metadata from a document and return the cleaned file.' operationId: stripMetadataFromADocumentAndReturnTheCleanedFile description: "Upload a single file (PDF, image, DOCX, XLSX, XLS, or text).\nMetadata (EXIF, author, company, timestamps, etc.) is removed\nand the cleaned file is returned as a binary download.\n\nRequires the `documents_strip_metadata` permission on your API token's product." parameters: - in: header name: X-Metadata-Stripped description: '' schema: type: string examples: - 'true' - in: header name: X-Strip-Method description: '' schema: type: string examples: - imagemagick - in: header name: X-Stripped-Fields description: '' schema: type: string examples: - 'EXIF,IPTC,XMP,ICC' - in: header name: X-Original-Size description: '' schema: type: string examples: - '245760' - in: header name: X-Sanitized-Size description: '' schema: type: string examples: - '101500' responses: 200: description: 'Cleaned file as binary download' content: text/plain: schema: type: string examples: - '<>' 400: description: 'Metadata stripping failed' content: application/json: schema: type: object properties: error: type: object properties: message: type: string examples: - "Failed to strip metadata from 'photo.jpg'" type: type: string examples: - invalid_request_error param: type: string examples: - file code: type: string examples: - metadata_stripping_failed examples: - error: message: "Failed to strip metadata from 'photo.jpg'" type: invalid_request_error param: file code: metadata_stripping_failed tags: - Documents requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: '1 document file to strip metadata from. Max file size depends on your product plan. Supported formats: PDF, DOCX, PPTX, XLSX, XLS, CSV, JSON, PNG, JPEG, TIFF, WebP, BMP, TXT. Must be a file. Must not be greater than 25600 kilobytes.' required: - file /api/v1/models: get: summary: 'List available models.' operationId: listAvailableModels description: "Returns models available for your API token. Use the model `id` values\nwhen calling chat or audio endpoints." parameters: [] responses: 200: description: 'Available models' content: application/json: schema: type: object properties: object: type: string examples: - list data: type: array items: type: object properties: id: type: string examples: - Meta-Llama-3_3-70B-Instruct object: type: string examples: - model created: type: integer examples: - 1700000000 owned_by: type: string examples: - kai examples: - - id: Meta-Llama-3_3-70B-Instruct object: model created: 1700000000 owned_by: kai - id: mistral-nemo-instruct-2407 object: model created: 1700000000 owned_by: kai - id: whisper-large-v3-turbo object: model created: 1700000000 owned_by: kai examples: - object: list data: - id: Meta-Llama-3_3-70B-Instruct object: model created: 1700000000 owned_by: kai - id: mistral-nemo-instruct-2407 object: model created: 1700000000 owned_by: kai - id: whisper-large-v3-turbo object: model created: 1700000000 owned_by: kai tags: - Models /api/v1/usage: get: summary: 'Get current billing period usage statistics.' operationId: getCurrentBillingPeriodUsageStatistics description: "Returns token status, product info, and usage counts for the current month.\nThe `status` field indicates whether the token is currently usable (`active`)\nor not (`inactive`)." parameters: [] responses: 200: description: 'Usage statistics' content: application/json: schema: type: object properties: status: type: string examples: - active is_free: type: boolean description: 'Whether this is an anonymous free product key (no user account associated).' examples: - false is_trial: type: boolean examples: - false trial_ends_at: type: - string - 'null' examples: - null period: type: string examples: - 2025-01 product: type: string examples: - aegis-pro product_label: type: string examples: - 'Aegis PRO' usage_label: type: string examples: - 'API Requests' total_requests: type: integer examples: - 42 total_ok: type: integer examples: - 40 total_errors: type: integer examples: - 2 total_tokens_in: type: integer examples: - 12500 total_tokens_out: type: integer examples: - 3200 rate_limit_per_minute: type: integer description: 'Maximum requests per minute for this token.' examples: - 10 max_concurrent_requests: type: integer description: 'Maximum simultaneous POST requests allowed.' examples: - 1 monthly_usage_cap: type: - integer - 'null' description: 'Maximum successful requests per month. Null if unlimited.' examples: - 100 usage_remaining: type: - integer - 'null' description: 'Remaining requests in current month. Null if unlimited.' examples: - 60 trial_usage_limit: type: - string - 'null' description: 'Total requests allowed during trial. Null if not on trial or no trial limit.' examples: - null trial_usage_remaining: type: - string - 'null' description: 'Remaining trial requests. Null if not on trial or no trial limit.' examples: - null max_file_size: type: integer examples: - 26214400 addons: type: array examples: - [] enabled_features: type: array examples: - [] enabled_endpoints: type: array items: type: string examples: - - chat_completions - audio_transcriptions - documents_anonymize required: - is_free - rate_limit_per_minute - max_concurrent_requests examples: - status: active is_free: false is_trial: false trial_ends_at: null period: 2025-01 product: aegis-pro product_label: 'Aegis PRO' usage_label: 'API Requests' total_requests: 42 total_ok: 40 total_errors: 2 total_tokens_in: 12500 total_tokens_out: 3200 rate_limit_per_minute: 10 max_concurrent_requests: 1 monthly_usage_cap: 100 usage_remaining: 60 trial_usage_limit: null trial_usage_remaining: null max_file_size: 26214400 addons: [] enabled_features: [] enabled_endpoints: - chat_completions - audio_transcriptions - documents_anonymize tags: - Usage