MaxKB and the OpenAI-Compatible API, Both Directions
MaxKB has two separate places where "OpenAI-compatible" appears, and they point in opposite directions.
Inbound: MaxKB can use an OpenAI-compatible endpoint as its model backend. That is under model providers, and it is how you point a self-hosted knowledge base at a gateway instead of at a first-party vendor.
Outbound: a MaxKB application exposes its own OpenAI-compatible endpoint, so anything that speaks the OpenAI SDK can call your knowledge base as though it were a model. That is under the application's API access page.
The two use the same protocol, the same word, and different base URLs. Confusing them produces a request that goes the wrong way, which is why the failure is confusing: everything is configured, and the answer comes from the model rather than from the knowledge base, or vice versa.
https://aicomp.ai/v1).
Create one free →
Inbound: pointing MaxKB at your endpoint
Add a model under the model provider settings and pick the OpenAI provider type. Six fields matter.
| Field | What it is | Where it goes wrong |
|---|---|---|
| Model name | your label inside MaxKB | arbitrary, but it is what you select later |
| Permission | private or public | private is visible only to you; public is shared but not editable by others |
| Model type | LLM, embedding, ASR, TTS, vision, image | wrong type puts the model in the wrong picker |
| Base model | the provider's model ID | validated against the provider |
| API domain | the base URL | must include the version segment |
| API key | the credential |
Base model is the field that rejects you. It is a dropdown of common names with free text allowed, and the free text is validated: a name the provider does not recognise fails the save. So this is the opposite arrangement from most tools, where the model field is free text sent verbatim and a typo only fails at call time. Here it fails at configuration time, which is better, but it means a gateway model ID that is not in the dropdown must still be spelled exactly right when typed.
API domain is the version root. The default for OpenAI itself is https://api.openai.com/v1, and for a proxy or gateway the documented shape is proxy-address/v1. Include the version segment; do not include the operation path.
Outbound: calling a MaxKB application
A MaxKB application is reachable through a standard OpenAI-shaped route, which means any OpenAI SDK client can treat the knowledge base as a model.
curl https://maxkb.example.com/chat/api/<application-id>/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer agent-<key>" \
-d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "…"}]}'Three details are load-bearing:
- The URL shape is
Base URL/chat/completions. The base URL is your MaxKB host plus the application path, and the operation is appended to it. This is the same convention as every other OpenAI-compatible client, so a client that works against a gateway works here by changing the base URL. - The key is an application API key, created in the application's own API page, not a model provider key. It is scoped to that application.
- The
modelfield is ignored. MaxKB answers with the application's configured model regardless of what the caller puts there, so a client that validates model names against a list will reject the request before it is sent even though the server would have accepted it.
That last point is the one that surprises people. A generic OpenAI client often insists on a model it can find in a list, and a MaxKB application serves no model list at all.
Which direction am I configuring
The reliable test is which URL you are editing.
| You are editing | Direction | Base URL |
|---|---|---|
| Model provider settings | MaxKB consumes | the model endpoint, e.g. https://gw.example.com/v1 |
| Application API access | MaxKB serves | your MaxKB host plus the application path |
If a request returns a model answer with no citations and no knowledge base grounding, you have configured the outbound base URL as if it were inbound, and the caller reached the model directly.
Where the tokens go
MaxKB's cost shape is a knowledge base shape: retrieval on the input side, one answer on the output side.
Each question embeds the query, retrieves chunks, and sends the question plus every retrieved chunk plus the conversation history to the model. So the input side follows the retrieval settings, and raising the top-k raises every turn rather than one.
A day on this page's workload is 190k input and 35k output tokens: 3.8M input and 0.7M output across 20 working days. Retrieval depth is the lever, and it is cheaper to turn down than to compensate for with a more expensive model.
See output vs input pricing for why a retrieval-heavy workload is dominated by the input rate, and prompt caching savings for the effect of keeping the retrieved set stable across turns.
| Model | Gateway rate in / out per 1M tokens | One day | 20 days |
|---|---|---|---|
| gpt-5.6-terra | $1.00 / $6.00 | $0.40 | $8.00 |
| claude-sonnet-5 | $1.00 / $5.00 | $0.36 | $7.30 |
| deepseek-v4-pro | $0.66 / $1.98 | $0.19 | $3.89 |
| qwen3.8-max | $1.00 / $3.00 | $0.30 | $5.90 |
| glm-5.3 | $0.70 / $2.2 | $0.21 | $4.20 |
One day = 190k input + 35k output on this page's workload. 20 days = 3.8M input and 0.7M output. Rates checked 2026-10-14, gateway rates move with upstream promotions, so verify the current number in your dashboard before committing to a budget.
Verifying the route
- Decide the direction first. Model provider settings means MaxKB consumes; application API means MaxKB serves.
- Include the version segment in the inbound API domain and stop there.
- Spell the base model exactly, because it is validated at save time rather than at call time.
- Set the model type to match how you will use it, so it appears in the right picker.
- Create an application API key for outbound calls, separate from any model provider key.
- Do not rely on the
modelfield in an outbound call; it is ignored and a validating client may refuse to send it.
FAQ
FAQ
Why does adding a model fail with a validation error?
The base model name does not match what the provider exposes. It is checked when you save rather than when you call, so free-typed IDs have to be exact.
Does the API domain need /v1?
Yes. The documented shape is the host plus the version segment, and for a gateway that means gateway-address/v1. Do not append the operation path.
What is the difference between the two API keys?
The model provider key authenticates MaxKB to your model endpoint. An application API key authenticates a caller to a MaxKB application. They are created in different places and are not interchangeable.
Why does my outbound call get an answer with no citations?
The base URL points at the model endpoint instead of the application path, so the request reached the model directly and bypassed retrieval.
Why does my OpenAI client refuse to call MaxKB?
A MaxKB application serves no model list, and some clients require one before sending. The model value is ignored by MaxKB, so any placeholder the client accepts will do.
Can I use one gateway for several MaxKB models?
Yes. Add each model as its own entry, sharing the API domain and key, and select the one you want per application.
Related
- RAGFlow with a custom endpoint, the same provider-plus-model-name validation, with a different field layout
- OpenAI-compatible endpoints — the request shape both directions rely on
- Official vs gateway prices — how the two price columns on this site are measured
- Base URL not working (the doubled path failure), in general form
- AnythingLLM with a custom endpoint — another knowledge base pointed at a gateway
- Tools that take one endpoint — the full matrix