All instructions

Lehmus AI: Using the APIs

Back to top

Lehmus AI language models can be used from your own applications via OpenAI-compatible APIs. 

The Lehmus AI Model Gateway provides a common interface for the models and routes requests to the appropriate model. 

What you need before you start 

You will need: 

  • Access to Lehmus AI 
  • An API key 
  • The API URL 
  • The Public Model ID of the model you wish to use 

API address 

You can copy the Lehmus AI API address directly from API URL in the portal’s left-hand sidebar, or use https://api.lehmus-ai.oulu.fi 

When using OpenAI-compatible services, the Model Gateway base URL is formed by adding /v1 to the API URL. 

https://api.lehmus-ai.oulu.fi/v1

Supported APIs 

Model Gateway provides the following APIs: 

  • POST /v1/chat/completions – Chat Completions 
  • POST /v1/responses – Responses API 
  • POST /v1/embeddings – text embeddings 
  • POST /v1/audio/transcriptions – converting speech to text 
  • GET /v1/models – listing the available models 

Model Gateway supports a documented subset of OpenAI-compatible API functionality, not automatically every OpenAI API operation or parameter. 

Authentication 

Each Model Gateway request uses an API key created in Lehmus AI as a bearer token. The API key must have invoke permission for the model being used. 

See Lehmus AI: Creating and managing API keys.  

Model identifier 

Specify the model to use in the request’s model field. Use the model’s Public Model ID, which you can copy, for example, from the Models tab in the Lehmus AI portal. 

Chat completions 

The traditional OpenAI-compatible chat API is: 

POST /v1/chat/completions 

It can be used, for example, in OpenAI-compatible applications and development tools. 

Responses API 

The newer Responses API uses the following endpoint: 

POST /v1/responses 

The Responses API supports text generation, streaming, conversations and tool use by models. 

The Responses API can also use the RAG and MCP tools provided by Model Gateway. The Gateway can execute a tool call and return the result to the model within the same request. 

Listing models 

You can retrieve the available chat models using: 

GET /v1/models 

By default, the list contains chat-type models that the caller has permission to use. 

Existing guides to using Lehmus AI language models 

You can find instructions for connecting Lehmus AI language models to other applications: 

Example API call 

You can test the connection using, for example, a curl command (Command prompt -compatible): 

curl -sS "https://api.lehmus-ai.oulu.fi/v1/chat/completions" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"model\":\"PUBLIC_MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"

Replace YOUR_API_KEY with your own API key and PUBLIC_MODEL_ID with the identifier of the language model you are using. 

Error conditions 

Model Gateway uses the following HTTP error codes, among others: 

  • 400: the request is invalid or contains an unknown operation 
  • 401/403: authentication failed or the API key lacks the required permission 
  • 404: the model cannot be found or is not ready for use 
  • 413: the request exceeds the 32 MB limit 
  • 501: the requested feature has not been implemented 
  • 502: the model’s backend service failed or could not be reached 

Troubleshooting 

If an API call fails, first check the following: 

  • The base URL of the OpenAI-compatible application is https://api.lehmus-ai.oulu.fi/v1. 
  • The request uses an API key created in Lehmus AI as a bearer token, and the key has invoked permission for the model being used. 
  • The request model field contains the correct Public Model ID for the model. 
  • The API and parameters you are using are supported. 

See also the Error conditions section of this guide, which explains the meanings of the most common HTTP error codes. 

Further information and support 

If the problem persists, contact ai@oulu.fi or ict@oulu.fi. In your support request, state the application you are using, the model’s Public Model ID, the API called, the error code, and when the problem occurred. Do not include your API key or confidential material in the support request. 

You can find more detailed API descriptions and usage examples in ConfidentialMind’s Model Gateway documentation. Check that the feature you are using is also supported in the Lehmus AI environment. 

Topics:

Back to top