7. ALEM module

The ALEM module provides access to the models of the Alem.Cloud platform. The module is compatible with the OpenAI API and Anthropic Messages API formats, which allows the official SDKs of these providers to be used by replacing the base address and the key.

The module is available with an API token that includes the ALEM module and with a student access token that has the qairu.alem.read scope. Unlike data modules, the ALEM module accepts POST requests at the paths listed in this section.

7.1. Connecting an SDK

The module address is specified as the SDK base address and the token as the key:

https://api.bbx.kz/os/v1/alem

• OpenAI SDK: the base_url parameter (Python) or baseURL (JavaScript);
• Anthropic SDK: the same address; the SDK appends the /v1/messages path itself.

7.2. Text generation

A response is generated by the POST /os/v1/alem/chat/completions request in the OpenAI format. The POST /os/v1/alem/completions and POST /os/v1/alem/responses operations are also supported.

curl https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain supervised learning in two sentences."}
    ],
    "max_tokens": 512
  }'

Requests in the Anthropic Messages API format are sent to POST /os/v1/alem/v1/messages.

curl https://api.bbx.kz/os/v1/alem/v1/messages \
  -H "x-api-key: qos_YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "Explain supervised learning in two sentences."}
    ]
  }'

7.3. Streaming

When the "stream": true parameter is set, the response is transmitted as a text/event-stream event stream as it is generated. A stream in the OpenAI format ends with the line data: [DONE]. If the client has not set the stream_options parameter, a final chunk with token usage information usage is added to the stream; the choices array in this chunk is empty.

curl -N https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a short abstract about computer vision."}
    ]
  }'

7.4. Embeddings

Vector representations of texts are returned by the POST /os/v1/alem/embeddings request. The input parameter accepts a string or an array of strings.

curl https://api.bbx.kz/os/v1/alem/embeddings \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": ["Neural networks", "Gradient descent"]
  }'

7.5. Reranking

The POST /os/v1/alem/rerank request orders documents by their relevance to a query. The request and response format follows the Cohere Rerank format: the response contains a results array with the document number index and the relevance score relevance_score. The official OpenAI and Anthropic SDKs do not support this operation, therefore the request is made with an HTTP client.

curl https://api.bbx.kz/os/v1/alem/rerank \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "How is the final grade calculated?",
    "documents": [
      "The final grade combines coursework and the examination.",
      "The library is open from 9 a.m. to 8 p.m.",
      "Coursework accounts for sixty percent of the final grade."
    ],
    "top_n": 2
  }'

7.6. Audio transcription

Transcription is performed by the POST /os/v1/alem/audio/transcriptions request in the multipart/form-data format. The file field contains the audio recording and the model field contains the identifier of the speech recognition model. With response_format=verbose_json the response additionally contains text segments with timestamps. The file size must not exceed 100 MB.

curl https://api.bbx.kz/os/v1/alem/audio/transcriptions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -F model=openai/whisper-large-v3 \
  -F response_format=verbose_json \
  -F file=@lecture.mp3

7.7. Disabling reasoning

Some models produce reasoning before the answer, which consumes the max_tokens budget. With a small max_tokens value such a model may return an empty content field with "finish_reason": "length". To disable reasoning, the "chat_template_kwargs": {"enable_thinking": false} parameter is added to the request body; in the OpenAI SDK for Python it is passed through extra_body. Some models do not take this parameter into account.

curl https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "messages": [{"role": "user", "content": "List three sorting algorithms."}],
    "max_tokens": 256,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

7.8. Model selection and unsupported operations

• the model parameter is mandatory for all operations of the module; model identifiers should be taken from the GET /os/v1/alem/models response;
• a request to a model that is not in the list is rejected with the code model_not_found; a request to a model not permitted by the token, with the code model_not_allowed;
• image generation, speech synthesis, moderation, and operations with files, vector stores and batch jobs are not supported by the module; requests to such paths are rejected with the code not_found;
• errors with the codes 400, 404, 413, 422 and 429 returned by a model while processing a request are passed to the client unchanged; a failure or unavailability of the Alem.Cloud platform is returned as a 502 response with the code upstream_error.

The available models are listed in the “List of models” section.