Keural API

Calls a model registered in Keural in OpenAI Chat Completions format.

The Base URL has the form https://<public API domain for each environment>/llm/v1. The public API domain differs by environment, so check it with your administrator.

Paths for embeddings, image generation, voice, and the Responses API are not supported. Requests sent to these paths return 404.

Usage flowCopy Anchor Link

PrerequisitesCopy Anchor Link

Issuing an API keyCopy Anchor Link

1. Open Settings → API from the account menu. In the desktop and mobile apps, it is in the Tools section.
2. On the API keys tab, choose the key owner (personal workspace or organization workspace) and the Model ID.
3. If needed, set the New key expiration. If you leave it blank, the key does not expire until it is revoked.
4. Press Issue key, then copy the key with Copy key and store it somewhere safe. The full key is displayed only once.

• A key is connected to the chosen workspace and to one model. Usage is attributed to the person who issued the key.
• A workspace can have only one usable key per model. To get a new key, reissue or revoke the existing key.
• If you lose a key, reissue it. The previous key becomes invalid immediately after reissue.
• If no model is available for issuing, ask your administrator to check the model's public setting, your plan, and the organization API permission.

Organization member API permissionsCopy Anchor Link

This section is for organization owners and admins. For members to get keys in an organization workspace, an admin must allow it first. The default for all members is blocked.

Organization management → Organization API consists of the following three sections. If the menu does not appear, the API feature is turned off or the account does not have organization management permission.

When a member leaves or is removed from the organization, the keys that the member received from the organization are revoked automatically.

Connecting to a clientCopy Anchor Link

Enter the following three values into an OpenAI API-compatible app (chat client, IDE extension, automation tool, and so on).

1. In the app settings, add an OpenAI-compatible connection.
2. Enter the Base URL and API Key, then save.
3. Choose a model from the model list. The list shows only the one model connected to the key.
4. Send a short message and check the response.

The request format is as follows.

First requestCopy Anchor Link

export KEURAL_API_KEY='your_issued_key'
export KEURAL_BASE_URL='https://<public API domain for each environment>/llm/v1'
export MODEL_ID='Model ID from the issue screen'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello.\"}]}"

The model in the request body must match the model ID connected to the key. If a path prefix such as provider/model-ID is attached, compare the part after the last /. If they differ, 403 is returned. The model in the response always contains the key's model ID.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Hello."}],
)
print(res.choices[0].message.content)

Supported request fieldsCopy Anchor Link

Only the 18 top-level fields below are accepted. If any other field is sent, 400 is returned. Optional fields whose value is null are treated as not sent.

MessagesCopy Anchor Link

• A tool message answers each id in the preceding tool_calls only once.
• Image parts (image_url) go only in user messages for models that accept images. Use an http or https address, or a base64 data URI in PNG, JPEG, GIF, or WebP. detail is auto, low, or high.

BodyCopy Anchor Link

Breaking a body rule returns 400, and param is body.

StreamingCopy Anchor Link

If you include "stream": true in the request, the response is sent as SSE. Chunks are sent as data: ... events, and data: [DONE] is sent at the end. If you include "stream_options": {"include_usage": true}, one additional token usage chunk is sent just before [DONE].

When include_usage is included, every chunk contains usage: null, and the final usage chunk has an empty choices array. A non-streaming response contains usage only when both input and output tokens are confirmed.

The response id has the form chatcmpl-<x-request-id>. Every response header includes x-request-id.

If an error occurs during streaming, a data: event containing the error JSON is sent, and the connection ends without [DONE]. If a chunk exceeds 1 MiB or the response exceeds 16 MiB, the response ends with 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Usage limitsCopy Anchor Link

Requests are limited per user, organization, and model by the number of concurrent requests, requests per minute (RPM), and tokens per minute (TPM). The actual values differ by environment.

Tokens per minute are deducted when a request is received. Input is counted as 1 token per 4 English characters, other characters as 1 token per character, and one image as 2,000 tokens. Output is deducted up to max_tokens (maximum 4,096), so setting the output limit only as high as you need leaves more room under the limit.

Key managementCopy Anchor Link

Under Settings → API → API keys, check the status of issued keys (valid, expired, or revoked), and reissue or revoke them.

A key is a 51-character string that starts with krl_llm_. Each key owner can have one key. If a key already exists, reissue it instead of issuing a new one. The expiration date can be set only to a date after today.

Checking usageCopy Anchor Link

Check API requests and the tokens they used in the following two places.

Search conditionsCopy Anchor Link

Set the conditions and press Search. To reflect requests you just sent, press Refresh.

Values on screenCopy Anchor Link

• Applied time range (KST): The time range actually searched. If the start or end time was left blank or the range exceeded 90 days, the adjusted range is shown.
• Requests and the totals of Input tokens · Output tokens · Total tokens: Only confirmed values are added. Tokens not yet confirmed are shown as Unconfirmed.
• Request list: Each request shows its request time, Model ID, request state, and input, output, and total tokens. 20 items are shown per page. Move between pages with Previous and Next.

Press Request details on a row to show the following values.

Usage is recorded for streaming requests even if you do not include stream_options.include_usage. If a request is interrupted partway through, it may remain as Partially confirmed or Unconfirmed.

Error formatCopy Anchor Link

Errors are returned in OpenAI-compatible format.

{
  "error": {
    "message": "Human-readable error description",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type is determined by the status code, and code distinguishes the cause.

TroubleshootingCopy Anchor Link

If the problem persists, contact your administrator with the information below. Do not send the full key or the prompt content.

• Time the problem occurred
• Model ID used
• Name and version of the client app
• x-request-id in the response headers
• Error message shown on screen