Documentation
API documentation
NeuraMind speaks the OpenAI API. Point any OpenAI SDK at one base URL, send your key, and you're running.
https://zanusneuramind.ai/api/v1
- Works with
- Any OpenAI SDK, unchanged
- Your key
sk-zanus-…, sent as a bearer token- Served from
- Our own servers in the United States. Prompts are never stored.
Quickstart #
Install the OpenAI SDK for your language and point it at NeuraMind. Your key decides which model you may use, so ask the API for it instead of writing it into your code.
from openai import OpenAI
client = OpenAI(
base_url="https://zanusneuramind.ai/api/v1",
api_key="sk-zanus-...",
)
# the model your key may use
model = client.models.list().data[0].id
stream = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Hello"}],
# off, low, medium, or high
reasoning_effort="high",
stream=True,
)
for chunk in stream:
# the last chunk carries usage only
if not chunk.choices:
continue
delta = chunk.choices[0].delta
thinking = getattr(delta, "reasoning_content", None)
print(thinking or delta.content or "", end="")
With curl, list your models first, then send the id you get back:
curl https://zanusneuramind.ai/api/v1/models \
-H "Authorization: Bearer sk-zanus-..."
curl https://zanusneuramind.ai/api/v1/chat/completions \
-H "Authorization: Bearer sk-zanus-..." \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "Hello"}],
"reasoning_effort": "off"
}'
Authentication #
Send your key as a bearer token on every request:
Authorization: Bearer sk-zanus-...
Each key has a name that its usage is recorded under, a list of models it may use, and optionally its own concurrency ceiling. Keys are checked at the edge, and a disabled key stops working within seconds.
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization header. |
| 401 | invalid_api_key | Unknown or disabled key. |
| 403 | model_not_allowed | The key may not use the model named in the request. |
Models #
GET /v1/models lists the models your key may use, and GET /v1/models/{id} describes one. Send the id exactly as listed; an unknown one returns 404 model_not_found.
What the chat model does today:
- A 64K context window, prompt and output together
- Text, image, and video input
- Reasoning, on by default
- Tool calls
- JSON output that matches the schema you send
Chat completions #
POST /v1/chat/completions takes the standard OpenAI request.
400 that names it, so a typo never silently does nothing.When you leave them out, the server fills in max_tokens, temperature, top_p, top_k, presence_penalty, and reasoning_effort.
A reply without streaming carries the same usage object and, when the model reasoned, message.reasoning_content beside message.content.
Streaming #
Set "stream": true to receive server-sent events, in this order:
- Chunks carrying
delta.reasoning_content,delta.content, ordelta.tool_calls. - A chunk with
finish_reasonset. - A last chunk with an empty
choiceslist and theusageobject. data: [DONE].
Usage is always included; you don't need stream_options.
data: {"choices":[{"index":0,"delta":{"reasoning_content":"The user wants..."},"finish_reason":null}],...}
data: {"choices":[{"index":0,"delta":{"content":"Here"},"finish_reason":null}],...}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],...}
data: {"choices":[],"usage":{"prompt_tokens":19,"completion_tokens":42,"total_tokens":61,
"prompt_tokens_details":{"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":30}},...}
data: [DONE]
If a stream fails after output has started, the last frame is a single error chunk followed by [DONE]. A stream is never cut off silently.
Reasoning #
The model thinks before it answers. The thinking comes back in its own field, reasoning_content, never mixed into content, and is counted in completion_tokens_details.reasoning_tokens. Reasoning is on by default; control it with reasoning_effort:
| Value | Effect |
|---|---|
off | No thinking. Fastest; best for extraction, classification, and short answers. |
low · medium · high | An increasing thinking budget. xhigh is accepted and treated as high. |
Tools and JSON output #
Tool calling follows the OpenAI shape: tools and tool_choice in the request, tool_calls in the reply. When streaming, tool calls arrive as delta.tool_calls with arguments built up piece by piece. A reply that only calls tools has content: null and finish_reason: "tool_calls".
response_format accepts {"type": "json_schema", ...} and {"type": "json_object"}. The schema is enforced by grammar as the answer is generated, after the thinking ends, so you get reasoning and valid JSON in the same reply.
reply = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Extract the city: I live in Austin."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "place",
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
},
)
# {"city": "Austin"}
print(reply.choices[0].message.content)
Images and video #
Send images the OpenAI way: a content list that mixes text parts with image parts. The image can be a data URL or a public URL.
{"role": "user", "content": [
{"type": "text", "text": "What does this label say?"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]}
- Images are processed at up to 2 megapixels, about 2K visual tokens.
- Video is sampled at 2 frames per second, up to 64 frames.
Responses API #
POST /v1/responses accepts the Responses request shape:
input, as a string or a list of itemsinstructionstools, in the flat formtext.formatreasoning.effortmax_output_tokens
Streams are typed event: lines ending with response.completed, or response.incomplete, carrying the whole response and its usage.
previous_response_id is refused. Send the full input every turn.Tokenize #
Use these to size a prompt before you send it. Both use the model's own tokenizer.
| Endpoint | Send | Get back |
|---|---|---|
POST /v1/tokenize | model, prompt (a string or a list), and optionally add_special_tokens | model, tokens, count, max_model_len |
POST /v1/detokenize | model, tokens, and optionally skip_special_tokens | model, text |
Concurrency and queueing #
Capacity is a pool of request slots, divided equally among the keys that have requests running or waiting right now. One busy client can't starve another, and a key with its own ceiling gets at most that.
When your share is full, a new request waits in line, oldest first, for up to 120 seconds, and starts as soon as a slot frees. A request is refused straight away only when your key's line is already long.
| Status | Code | Meaning |
|---|---|---|
| 429 | queue_timeout | Waited two minutes without a slot. Retry after a pause. |
| 429 | queue_full | Too many requests already waiting for this key. Reduce parallelism. |
| 503 | no_node · draining | No healthy node serves the model right now, usually maintenance. Retry with backoff. |
Every 429 and 503 carries Retry-After: 2. Follow-up turns of a conversation go to the node that already holds the start of the prompt in cache, so long conversations stay fast.
Errors #
Errors use the OpenAI envelope:
{"error": {"message": "...", "type": "invalid_request_error", "code": "unknown_key", "param": "..."}}
| Status | Type | When |
|---|---|---|
| 400 | invalid_request_error | Malformed JSON, an unknown body key, a bad value, or a missing model. |
| 401 403 | authentication_error · permission_error | A key problem; see Authentication. |
| 404 | invalid_request_error | An unknown model or route. |
| 413 | invalid_request_error | A body above 32 MB. |
| 429 | rate_limit_error | Queue timeout or queue full. |
| 500 | server_error | The API failed on this request. Retry shortly. |
| 502 503 | upstream_error | The model server failed or is unavailable. A 503 carries Retry-After; retry after it. |
Usage and billing #
Every request is recorded against its key, refused ones included: the model, the endpoint, the status, the token counts, and the duration. Never the text.
| Tokens | Billed at |
|---|---|
Cached prompt tokens, prompt_tokens_details.cached_tokens | The cache-read rate |
| The rest of the prompt | The input rate |
| Completion tokens, reasoning included | The output rate |
Limits #
| Limit | Value |
|---|---|
| Context window | 65,536 tokens, prompt and output together |
| Request body | 32 MB |
| Queue wait | 120 seconds, then 429 queue_timeout |
| Time to first token | 180 seconds before the request is failed |
| Stream idle | 60 seconds between frames |