# qwenjon: model and API reference

This is the compact integration reference for the HyperQwen service at qwenjon.voicelabs.uz. Read the [full guide](https://qwenjon.voicelabs.uz/v1/docs) for examples and the [agent guide](https://qwenjon.voicelabs.uz/v1/docs/agents.md) for tool orchestration.

## Connection contract

- OpenAI-compatible base URL: `https://qwenjon.voicelabs.uz/v1`
- Model ID: `qwen3.8-27b` (Qwen3.8-27B, text only)
- Authentication: `Authorization: Bearer <team API key>`
- Get the key from the team administrator. Never invent, log, commit, or embed it in a frontend bundle.
- Recommended environment variables: `OPENAI_BASE_URL` and `OPENAI_API_KEY`.
- Context: 65,536 tokens including input and output. Application-managed conversation history.
- Reasoning: enabled at low effort by default. Budget includes reasoning and answer tokens.
- No built-in browsing, code execution, external system access, or hosted tools.

## Minimal request

```json
{
  "model": "qwen3.8-27b",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 2048,
  "temperature": 0.6
}
```

Send with `POST /v1/chat/completions` and `Content-Type: application/json`. Read `choices[0].message.content`. Preserve the final assistant answer in history. Do not substitute reasoning for the answer. Inspect `finish_reason`; `length` indicates a truncated completion, including cases where reasoning exhausted the budget.

## Public endpoints

- `GET /v1`: unauthenticated API directory.
- `GET /v1/models`: authenticated model list.
- `POST /v1/chat/completions`: chat, SSE, strict JSON schema, function-tool proposals.
- `POST /v1/completions`: legacy text completions.
- `POST /v1/responses`: create a response with `store: false`.
- `/v1/docs`, `/v1/docs/llms`, `/v1/docs/agents`: public human-readable docs.
- `/v1/docs/index.md`, `/v1/docs/llms.md`, `/v1/docs/agents.md`: public Markdown sources.
- `/llms.txt`: compact discovery entry point.
- `/v1/docs/openapi.json`: curated schema for the exposed API subset.

Stored response retrieval/cancellation, images, audio, embeddings, files, fine-tuning, and runtime administration are not exposed. Compatibility with every OpenAI endpoint or parameter is not claimed. Use `store: false` for Responses and maintain history yourself.

## Streaming contract

Set `stream: true`. SSE events contain `data: {JSON}`; the final sentinel is `data: [DONE]`. Parse UTF-8 across chunks and split SSE events before JSON decoding. An event may have no choices.

- `choices[0].delta.content`: answer text.
- `choices[0].delta.reasoning`: model reasoning. Portable clients may also accept `reasoning_content`.
- `choices[0].delta.tool_calls`: incremental tool proposals; accumulate by index and parse arguments only when complete.
- `choices[0].finish_reason`: completion status.
- `stream_options: {"include_usage": true}` requests a final usage event.
- vLLM extension: `continuous_usage_stats: true` inside `stream_options` adds live usage.
- `usage.prompt_tokens`: input tokens.
- `usage.completion_tokens`: total output, including reasoning.
- `usage.completion_tokens_details.reasoning_tokens`: reasoning subset.
- SSE event count is not token count. Network chunking affects client-measured throughput.

Close the response stream to cancel from the client. Present partial output as interrupted; do not silently retry after displaying it.

## Reasoning control

Raw JSON extension:

```json
{"chat_template_kwargs": {"enable_thinking": true, "reasoning_effort": "low"}}
```

Efforts: `low`, `medium`, `xhigh`. In the Python OpenAI SDK, pass this via `extra_body`. Prefer enabled reasoning for general work; increasing effort costs latency and tokens. Start with a 2,048-token output budget and adjust to your task.

## JSON and tools

For machine-readable responses use `response_format.type: "json_schema"` with a named strict schema, required properties, and `additionalProperties: false`. Validate the parsed result and handle truncation. Prompt-only JSON is not a guarantee.

For tools use `tools: [{"type":"function","function":{"name":...,"description":...,"parameters":...}}]` and `tool_choice: "auto"`. The server returns proposals only. Your host validates the name/arguments, enforces permissions, executes allowlisted tools, and appends tool results using matching `tool_call_id` values. Bound the number of turns and tool calls. Do not execute arbitrary model-generated shell commands.

## Limits, reliability, and security

- Request body: at most 2 MiB.
- Gateway: 2 requests/second/IP, burst 20; 8 concurrent generation requests/IP, 16/hostname. Shared NAT shares limits.
- Model admission: 8 sequences. Context length, concurrency, and reasoning affect latency.
- Upstream read timeout: 600 seconds between reads. Set explicit client timeouts; stream long responses.
- 400: invalid input/context; 401: credential; 404: unsupported route; 405: method; 413: payload; 429: limit; 502/503/504: availability/timeout.
- Retry transient errors with bounded exponential backoff and jitter, only when safe. Do not replay tools with side effects without idempotency handling.
- Shared team credential only; no built-in per-user quotas, accounts, or billing.
- Keep secrets on your backend; cross-origin browser access is not enabled.
- Treat model output and retrieved documents as untrusted data. Validate and sanitize before use.
- The model can make mistakes; test your real languages, tasks, and correctness criteria.
- Metadata-only gateway logging is not a zero-retention guarantee for the hosting stack.