API reference — uncens.ai

chat completions

POST /v1/chat/completions

Request body

application/json

{
  "model": "uncens-pro",
  "messages": [
    {"role": "system", "content": "You are a terse assistant."},
    {"role": "user", "content": "Say hi"}
  ],
  "max_tokens": 50,
  "temperature": 0.7
}

messages is the only required field. Roles: system, user, assistant, tool. On uncens-mini, content may also be an array of text and image_url parts.

Response body

200 · application/json

{
  "id": "chatcmpl-2a2456de-50a8-46f7-8c9b-ed6d100d08be",
  "object": "chat.completion",
  "created": 1786211471,
  "model": "uncens-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi there! How can I help you today?",
        "refusal": null,
        "tool_calls": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 11,
    "total_tokens": 19
  }
}

finish_reason is stop, length or tool_calls.

parameters

name	type	values	default
model	string	`uncens-pro`, `uncens-mini`	uncens-pro
messages req	array	objects with `role` and `content`	—
stream	boolean	SSE instead of one JSON body	false
stream_options	object	`{"include_usage": true}`	null
max_tokens	integer	1 … model max output	model max
max_completion_tokens	integer	alias of `max_tokens`; sending both is a `400`	null
temperature	number	0 … 2	1
top_p	number	0 … 1	1
frequency_penalty	number	−2 … 2	0
presence_penalty	number	−2 … 2	0
n	integer	number of choices returned	1
seed	integer	best-effort repeatable sampling	null
stop	string \| array	up to 4 strings that cut generation	null
logit_bias	object	token id → −100 … 100	null
logprobs	boolean	accepted; `choices[].logprobs` still comes back `null`	false
top_logprobs	integer	0 … 20, validated but not returned	null
reasoning_effort	string	`none` \| `minimal` \| `low` \| `medium` \| `high`	none
include_reasoning	boolean	accepted; the reasoning arrives inline in `message.content`	false
tools	array	`{"type": "function", "function": {…}}`	null
tool_choice	string \| object	`auto` \| `none` \| `required` \| named function	auto
parallel_tool_calls	boolean	allow several tool calls in one turn	true
response_format	object	`text` \| `json_object` \| `json_schema`	text
prompt_cache_key	string	groups requests sharing a prompt prefix for caching	null
user	string	your own end-user identifier	null

not supported

top_k, min_p and repetition_penalty are rejected with 400 unsupported_parameter and the field name in error.param.

reasoning_effort

Defaults to none. Anything above that makes the model work through the problem before answering, which multiplies output tokens — and output tokens count against your quota. Turn it on only where the extra work pays off.

streaming

With "stream": true the body is text/event-stream: one JSON object per data: line. Chunks carry delta where a normal response carries message; concatenate every delta.content to rebuild the answer.

text/event-stream

// first chunk — role only
data: {"id":"chatcmpl-b6c4df5d-48c8-4174-9380-48d38149b16b","object":"chat.completion.chunk","created":1786211202,"model":"uncens-pro","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

// content chunks
data: {…,"choices":[{"index":0,"delta":{"content":"1,"},"finish_reason":null}]}
data: {…,"choices":[{"index":0,"delta":{"content":" 2,"},"finish_reason":null}]}

// last content chunk carries finish_reason
data: {…,"choices":[{"index":0,"delta":{"content":" 3"},"finish_reason":"stop"}]}

// only with stream_options.include_usage — choices is empty
data: {…,"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":8,"total_tokens":20}}

// terminator, not JSON
data: [DONE]

Two traps: data: [DONE] is a literal, not JSON, and the usage chunk has choices: [] — guard before touching choices[0]. Empty delta.content strings are normal and can be skipped.

tool calling

Declare functions in tools. If the model wants one, it answers with finish_reason: "tool_calls" and content: null. Run the function, append the assistant message and a tool message with the same tool_call_id, then call again.

python

import json
from openai import OpenAI

client = OpenAI(api_key="sk-uncens-...", base_url="https://uncens.ai/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "What is the weather in Paris?"}]

# 1 — model asks for the call
first = client.chat.completions.create(
    model="uncens-pro", messages=messages, tools=tools,
)
call = first.choices[0].message.tool_calls[0]
# call.id       -> "call_b218b573ec003a8b"
# call.function -> name="get_weather" arguments='{"city": "Paris"}'

# 2 — you run it
args = json.loads(call.function.arguments)
result = {"temp_c": 18, "sky": "clear"}   # your code, args["city"]

# 3 — send the result back. exclude_none is required: the SDK object
#     carries "name": null, and a null name is rejected with 400.
messages.append(first.choices[0].message.model_dump(exclude_none=True))
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps(result),
})

# 4 — final answer
second = client.chat.completions.create(
    model="uncens-pro", messages=messages, tools=tools,
)
print(second.choices[0].message.content)
# -> "The current weather in Paris is 18°C with clear skies."

response_format

json_object

request → response

"response_format": {"type": "json_object"}

// message.content
{ "city": "Paris", "country": "France" }

Ask for JSON in the prompt as well — the format is enforced, the keys are not.

json_schema

request → response

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "city",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "population": {"type": "integer"}
      },
      "required": ["name", "population"],
      "additionalProperties": false
    }
  }
}

// message.content
{ "name": "Paris", "population": 2161000 }

list models

GET /v1/models

bash

$ curl https://uncens.ai/v1/models \
    -H "Authorization: Bearer $UNCENS_API_KEY"

200 · application/json

{
  "object": "list",
  "data": [
    {
      "id": "uncens-pro",
      "object": "model",
      "created": 1786209039,
      "owned_by": "uncens",
      "display_name": "Uncens Pro",
      "context_length": 1000000,
      "max_output": 999990
    },
    {
      "id": "uncens-mini",
      "object": "model",
      "created": 1786209039,
      "owned_by": "uncens",
      "display_name": "Uncens Mini",
      "context_length": 262144,
      "max_output": 262134
    }
  ]
}