{ "openapi": "3.1.0", "info": { "title": "Klok API", "version": "2026-11", "summary": "Skena Klok, Skena AI's reasoning model, behind an OpenAI-compatible chat API.", "description": "Klok answers OpenAI-format chat completions: text, images and tool calls, with or without streaming. Guides: https://skena.ai/docs/klok.\n\nOne base for every Skena API: https://api.skena.ai (OpenAI's SDKs take https://api.skena.ai/v1 as their base URL). Authenticate with a Skena API key you make on the dashboard (one per app or server): `Authorization: Bearer skl_…`. Every key calls Kvick too. Every call with your API key is paid from Skena AI credit, whatever plan the account has. Without credit, a call is refused before it runs and costs nothing.\n\nEvery request must declare its Content-Length, at most 32 MiB. Stream long answers: Cloudflare, in front of Skena Cloud, closes a call that has not started answering within 100 seconds.\n\nThere is no uptime guarantee yet, and the API may change.", "termsOfService": "https://skena.ai/terms", "contact": { "name": "Skena Labs", "email": "hello@skena.ai", "url": "https://skena.ai/docs" } }, "servers": [ { "url": "https://api.skena.ai", "description": "Skena Cloud: the one base for every Skena API" } ], "security": [ { "apiKey": [] } ], "externalDocs": { "description": "Klok API guide", "url": "https://skena.ai/docs/klok" }, "paths": { "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "summary": "Chat with Klok", "description": "When Klok is busy the call waits its turn, up to 45 seconds, before 503 inference-queue-expired. Before it runs, Skena Cloud sets a hold aside on your credit: the whole context as input plus max_tokens as output.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional: up to 128 bytes, a new one for each call. A call that reuses a key answers `409 inference-request-already-recorded` and is neither run nor charged, so a retry can never charge a call twice. The 409 does not repeat the first answer.", "schema": { "type": "string", "maxLength": 128, "description": "At most 128 bytes." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "examples": { "quickstart": { "summary": "One question", "value": { "model": "klok-1", "messages": [ { "role": "user", "content": "In one sentence, why is the sky blue?" } ], "max_tokens": 4000 } }, "stream": { "summary": "A streamed answer", "value": { "model": "klok-1", "messages": [ { "role": "user", "content": "How does a French press work?" } ], "stream": true } }, "image": { "summary": "A question about an image (truncated base64)", "value": { "model": "klok-1", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is the total on this receipt?" }, { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..." } } ] } ], "max_tokens": 2000 } }, "tools": { "summary": "Tool calling", "value": { "model": "klok-1", "messages": [ { "role": "user", "content": "What is the weather in Stockholm?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "The current weather in a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } } ], "max_tokens": 2000 } }, "effort": { "summary": "Less reasoning", "value": { "model": "klok-1", "messages": [ { "role": "user", "content": "Plan a three-day trip to Gotland." } ], "chat_template_kwargs": { "reasoning_effort": "low" }, "max_tokens": 4000 } } } } } }, "responses": { "200": { "description": "The answer: JSON, or with stream true, server-sent events ending with a piece that carries usage and no choices, then `data: [DONE]`. Lines starting with `:` are keepalive comments.", "headers": { "X-Skena-Usage-Id": { "description": "The call's entry in your credit history.", "schema": { "type": "string" } }, "X-Skena-Dispatch": { "description": "When present: started, the call reached Klok.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "example": { "id": "chatcmpl-…", "object": "chat.completion", "created": 1793750400, "model": "klok-1", "choices": [ { "index": 0, "message": { "role": "assistant", "reasoning_content": "The user wants one sentence. Rayleigh scattering…", "content": "Air molecules scatter short blue wavelengths of sunlight far more than long red ones, so blue light reaches your eyes from every part of the sky." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 22, "completion_tokens": 318, "total_tokens": 340 } } }, "text/event-stream": { "schema": { "type": "string", "description": "data: lines holding ChatCompletionChunk objects." } } } }, "400": { "description": "`invalid-json`: The body is not a JSON object.\n\n`unsupported-request-field`: The body has a field Skena Cloud does not accept.\n\n`unknown-model`: `model` is missing or is not \"klok-1\".\n\n`invalid-messages`: `messages` is missing, empty, over 4,096, or holds something that is not an object.\n\n`invalid-content`: A message's `content` is neither a string nor an array of parts.\n\n`unsupported-content-type`: A content part is neither `text` nor `image_url`.\n\n`embedded-images-required`: An `image_url` is not a base64 data URL of a PNG, JPEG, WebP or GIF image (`data:image/png|jpeg|webp|gif;base64,`). Links are refused, never fetched.\n\n`invalid-output-limit`: `max_tokens` is not a whole number from 1 to 32,000.\n\n`ambiguous-output-limit`: The body has both `max_tokens` and `max_completion_tokens`.\n\n`one-completion-required`: `n` is not 1.\n\n`invalid-stream-mode`: `stream` is not `true` or `false`.\n\n`response-storage-unavailable`: `store` is not `false`.\n\n`invalid-credit-request-id`: The Idempotency-Key header is longer than 128 bytes, or holds a line break or a NUL.\n\n`inference-request-rejected`: Klok's server refused the request as sent, for example a prompt longer than the context. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid-inference-key`: No key, a malformed key, a revoked key, or a device key from Skena Builder or Skena Servant (the API takes Skena API keys only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`ai-credit-unavailable`: Nothing is left to pay for the call: the welcome gift is used up or expired, and the account has no other credit (403 while the welcome gift is paused).\n\n`ai-credit-insufficient`: Your available credit does not cover the call's hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "ai-credit-insufficient", "type": "skena_inference_error", "code": "ai-credit-insufficient" } } } } }, "403": { "description": "`account-unverified`: The account's email is not verified.\n\n`account-suspended`: The account is suspended.\n\n`ai-credit-required`: The account has no Skena AI credit. The API is paid from credit alone, whatever plan the account has.\n\n`ai-credit-unavailable`: Nothing is left to pay for the call: the welcome gift is used up or expired, and the account has no other credit (403 while the welcome gift is paused).\n\n`ai-credit-activation-required`: Only the welcome gift is left, and no computer has activated it yet. Refused before the call waits or uploads, so it costs nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`unknown-endpoint`: the base serves no such path or method (answered by Skena Cloud's edge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "error": { "message": "unknown-endpoint", "type": "skena_api_error", "code": "unknown-endpoint" } } } } }, "408": { "description": "`inference-upload-timeout`: The body did not arrive within 30 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`inference-request-already-recorded`: The call reused an Idempotency-Key this account already sent, whatever happened to that first call. Sent with `x-should-retry: false`.\n\n`inference-ticket-config-changed`: Klok's configuration changed while the call waited or uploaded (409 if it was uploading). Nothing ran.", "headers": { "x-should-retry": { "description": "false: do not retry.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "411": { "description": "`inference-length-required`: The body did not declare its length (a chunked upload), or it is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`inference-request-too-large`: The body is over 32 MiB.\n\n`inference-request-exceeds-memory-budget`: The body is too large for Skena Cloud to hold while it waits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`inference-attempt-limit`: Calls paid from credit, Klok and Kvick together: over 120 in the last minute (on the welcome gift, also 5,000 in the last 24 hours). The error carries `resetsAt`.\n\n`inference-queue-full`: More than 8 of your calls are waiting, you queued 120 in the last minute, or Skena Cloud's queue is full.\n\n`inference-concurrency-limit`: The account already runs as many calls as it may at once (see Calls at a time).\n\n`inference-admission-rate-limit`: Skena Cloud is taking in too many calls at once, from this account or from everyone.\n\n`inference-memory-limit`: Skena Cloud has no room to hold the call right now.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`inference-queue-expired`: The call waited 45 seconds for its turn and Klok was still busy.\n\n`inference-draining`: Skena Cloud is not taking new calls for a moment, for maintenance.\n\n`inference-ticket-config-changed`: Klok's configuration changed while the call waited or uploaded (409 if it was uploading). Nothing ran.\n\n`inference-backend-unavailable`: Klok could not be reached, or failed.\n\n`inference-response-incomplete`: Klok's answer broke off, or was over 16 MiB without streaming.\n\n`inference-response-invalid`: Klok's answer could not be read.\n\n`inference-stream-invalid`: Klok did not answer with a stream.\n\n`inference-cache-isolation-unavailable`: A temporary problem on our side.\n\n`inference-pricing-unavailable`: A temporary problem on our side.\n\n`inference-account-store-unavailable`: A temporary problem on our side.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "List every model the key can call", "description": "Lists every model your key can call, in one answer with two shapes: OpenAI's data (what OpenAI's SDKs read) and the Jev API's models (what Jev clients read, Kvick only). A model is listed only while Skena Cloud serves it. It needs a valid key on an account with credit, and never wakes a model. Its refusals use the skena_inference_error envelope, for Kvick too.", "responses": { "200": { "description": "The models, in OpenAI's shape (data) and the Jev API's (models).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "example": { "object": "list", "data": [ { "id": "klok-1", "object": "model", "owned_by": "skena", "name": "Skena Klok", "context_window": 262144 }, { "id": "kvick-1", "object": "model", "owned_by": "skena", "name": "Skena Kvick" } ], "models": [ { "name": "kvick-1", "description": "Skena Kvick: calibrated System One decisions (Jev-compatible)." } ] } } } }, "401": { "description": "`invalid-inference-key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsError" } } } }, "402": { "description": "`ai-credit-unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsError" } } } }, "403": { "description": "`account-unverified`, `account-suspended`, `ai-credit-required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsError" } } } }, "404": { "description": "`unknown-endpoint`: the base serves no such path or method (answered by Skena Cloud's edge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "error": { "message": "unknown-endpoint", "type": "skena_api_error", "code": "unknown-endpoint" } } } } }, "503": { "description": "`inference-account-store-unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsError" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A Skena API key (skl_…) you make on the dashboard's API key page. Every key calls Klok and Kvick." } }, "schemas": { "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "additionalProperties": false, "description": "Any field not listed here is refused with 400 unsupported-request-field.", "properties": { "model": { "type": "string", "const": "klok-1", "description": "Send \"klok-1\". The answer names the model you sent." }, "messages": { "type": "array", "minItems": 1, "maxItems": 4096, "items": { "$ref": "#/components/schemas/Message" } }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000, "default": 32000, "description": "The most tokens Klok may write, its reasoning included. It sets the call's hold. Send this or max_completion_tokens, not both." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "maximum": 32000, "description": "The same as max_tokens. Send one of the two." }, "stream": { "type": "boolean", "default": false, "description": "Server-sent events. Recommended for long answers." }, "stream_options": { "type": "object", "description": "Accepted. When streaming, Skena Cloud sets it so usage always arrives as the last piece." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "OpenAI's tool definitions, passed to Klok as sent." }, "tool_choice": { "description": "OpenAI's tool_choice, passed to Klok as sent." }, "parallel_tool_calls": { "type": "boolean", "description": "Passed to Klok as sent." }, "chat_template_kwargs": { "type": "object", "description": "Arguments for Klok's chat template. Skena Cloud sets reasoning_effort to \"medium\" when the request names no effort.", "properties": { "reasoning_effort": { "enum": [ "low", "medium", "xhigh" ] } } }, "reasoning_effort": { "type": "string", "description": "Accepted and passed on as sent; when present, Skena Cloud adds no effort of its own. Klok's template reads the effort from chat_template_kwargs." }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "min_p": { "type": "number" }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "repetition_penalty": { "type": "number" }, "repeat_penalty": { "type": "number" }, "seed": { "type": "integer" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "response_format": { "type": "object", "description": "Passed to Klok as sent." }, "logprobs": { "type": "boolean" }, "top_logprobs": { "type": "integer" }, "n": { "const": 1, "description": "One answer per call." }, "store": { "const": false, "description": "There is no stored-completions API." } } }, "Message": { "type": "object", "required": [ "role" ], "description": "OpenAI's chat message: system, user, assistant (with tool_calls) or tool (with tool_call_id).", "properties": { "role": { "type": "string" }, "content": { "oneOf": [ { "type": "string" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" } } ] } } }, "ContentPart": { "oneOf": [ { "$ref": "#/components/schemas/TextPart" }, { "$ref": "#/components/schemas/ImagePart" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextPart", "image_url": "#/components/schemas/ImagePart" } } }, "TextPart": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string" } } }, "ImagePart": { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^data:image/(png|jpeg|webp|gif);base64,", "description": "A base64 data URL. Links are refused, never fetched." } } } } }, "Usage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "description": "What Klok read. Credit pays for every one, cached or not." }, "completion_tokens": { "type": "integer", "description": "What Klok wrote, its reasoning included." }, "total_tokens": { "type": "integer" } } }, "ChatCompletion": { "type": "object", "required": [ "model", "choices", "usage" ], "properties": { "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string", "description": "The id you sent." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": [ "string", "null" ] }, "reasoning_content": { "type": [ "string", "null" ], "description": "Klok's reasoning, apart from the answer." }, "tool_calls": { "type": "array", "items": { "type": "object" } } } }, "finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ModelList": { "type": "object", "required": [ "object", "data", "models" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "description": "OpenAI's shape: every model the key can call.", "items": { "type": "object", "required": [ "id", "object", "owned_by" ], "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "owned_by": { "type": "string" }, "name": { "type": "string" }, "context_window": { "type": "integer" } } } }, "models": { "type": "array", "description": "The Jev API's shape: the models it speaks (Kvick).", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "ModelsError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "type" ], "properties": { "code": { "enum": [ "invalid-inference-key", "ai-credit-unavailable", "account-unverified", "account-suspended", "ai-credit-required", "inference-account-store-unavailable" ] }, "message": { "type": "string" }, "type": { "const": "skena_inference_error" } } } } }, "EdgeError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "type" ], "properties": { "code": { "const": "unknown-endpoint" }, "message": { "type": "string" }, "type": { "const": "skena_api_error" } } } } }, "Error": { "type": "object", "required": [ "error" ], "description": "A refusal from Skena Cloud.", "properties": { "error": { "type": "object", "required": [ "code", "message", "type" ], "properties": { "code": { "type": "string", "enum": [ "invalid-inference-key", "account-unverified", "account-suspended", "ai-credit-required", "ai-credit-unavailable", "ai-credit-activation-required", "ai-credit-insufficient", "invalid-json", "unsupported-request-field", "unknown-model", "invalid-messages", "invalid-content", "unsupported-content-type", "embedded-images-required", "invalid-output-limit", "ambiguous-output-limit", "one-completion-required", "invalid-stream-mode", "response-storage-unavailable", "invalid-credit-request-id", "inference-request-rejected", "inference-upload-timeout", "inference-request-already-recorded", "inference-length-required", "inference-request-too-large", "inference-request-exceeds-memory-budget", "inference-attempt-limit", "inference-queue-full", "inference-concurrency-limit", "inference-admission-rate-limit", "inference-memory-limit", "inference-queue-expired", "inference-draining", "inference-ticket-config-changed", "inference-backend-unavailable", "inference-response-incomplete", "inference-response-invalid", "inference-stream-invalid", "inference-cache-isolation-unavailable", "inference-pricing-unavailable", "inference-account-store-unavailable" ] }, "message": { "type": "string", "description": "The same as code." }, "type": { "const": "skena_inference_error" }, "resetsAt": { "type": "string", "format": "date-time", "description": "When a limit with a reset time frees up (inference-attempt-limit)." } } } } } } } }