API REFERENCE

Chat requests and parameters

Build conversations, set generation limits, and handle model-specific options.

Request body

Send an uncompressed JSON object to POST /v1/chat/completions. Put request options in the JSON body, not the query string.

{
  "model": "<MODEL_ID_FROM_YOUR_CATALOG>",
  "messages": [
    { "role": "system", "content": "Explain unfamiliar terms in plain language." },
    { "role": "user", "content": "What is a trace?" }
  ],
  "max_tokens": 256,
  "stream": false
}

Field	Meaning	Usage guidance
`model`	Required model ID	Match the authenticated catalog exactly.
`messages`	Required conversation, oldest first	Include the context needed for this call. A prior request does not automatically become conversation memory.
`max_tokens`	Maximum generated tokens	Use a positive value appropriate to the task and model. Larger caps can increase the credit reserved for a request.
`stream`	Whether to return incremental events	Defaults to `false`; use `true` for streaming.
`temperature`	Sampling randomness	Model dependent; the API schema describes a range of 0–2. Lower values generally vary less.
`top_p`	Alternative sampling control	Usually adjust this or temperature first, rather than tuning both at once.
`stop`	A stop string or up to four strings	Only use if the model supports it.
`presence_penalty`, `frequency_penalty`	Repetition controls	Provider and model support vary.
`seed`	Best-effort reproducibility	Does not guarantee identical responses.
`n`	Number of completions	Keep at 1 unless the selected model supports more.
`reasoning`	Canonical reasoning controls	Use `enabled`, `effort`, `exclude`, or a `max_tokens` reasoning budget. Effort and budget are mutually exclusive.
`reasoning_effort`	Legacy reasoning control	DeepSeek V4 Flash 0731 supports `none` (thinking off), `low`, `medium`, `high`, and `max`. `medium` is an alias for `high`; other models may differ.
`thinking`	DeepSeek V4 compatibility control	Send `{"type":"enabled"}` or `{"type":"disabled"}`. Enabled selects `high` unless an explicit effort or reasoning budget is supplied. Prefer `reasoning` for new integrations.
`chat_template_kwargs`	Model template controls	For compatible thinking models, send `{"thinking": true}` (or the model's documented native key). Unsupported controls are rejected; check model support.
`tools`, `tool_choice`, `response_format`	Tool calling and structured output	Check the model first; these are not guaranteed by OpenAI compatibility.

Unreserved fields can be forwarded to the selected model. Forwarding is not validation or a guarantee that a parameter takes effect. Provider errors may be returned for unsupported fields.

For tool-capable models, the model proposes a tool call; your application validates the arguments, executes the permitted action, and sends the tool result in the next conversation turn. Netra does not run your application's tools for you. Keep tool outputs paired with their tool-call IDs.

Automatic tool choice (tool_choice: "auto"), forced tool calls, tool-result continuation, and strict JSON schema output are supported for DeepSeek V4 Flash 0731. A forced function uses tool_choice: {"type":"function","function":{"name":"YOUR_TOOL_NAME"}}; include the matching definition in tools. Strict JSON uses response_format with type: "json_schema" and a JSON schema marked strict: true.

Custom agent labels are retained when organization recording is enabled. Use X-Netra-Agent: support-agent to label inference usage, and avoid sensitive data in labels. Use a stable name for a deployed agent, rather than a new label per request. Labels are trimmed, stripped of control characters, and limited to 128 characters. Propagate W3C traceparent from your tracing library to associate the call with a trace.

Thinking and reasoning

For Chat Completions, send reasoning: {"enabled": false} to disable thinking or an explicit effort to enable it; do not rely on an omitted control selecting the same behaviour in every request. Both models support non-thinking plus low, high, and max thinking efforts; medium maps to high. Playground enables thinking at low by default, and restores saved conversation settings. V4.1 also supports thinking with image input.

Use the canonical object for new clients:

{
  "reasoning": { "enabled": true, "effort": "high", "exclude": false }
}

The Python OpenAI SDK accepts it through extra_body={"reasoning": {"effort": "high"}}; JavaScript accepts the extra JSON body field reasoning: { effort: "high" }. enabled: false turns thinking off. exclude: true hides returned reasoning without disabling the model's reasoning or changing its token charges. Some providers do not expose reasoning text.

Use either effort or max_tokens, never both. A budget request also needs a larger positive overall generation cap (max_tokens or max_completion_tokens at the request's top level). For example:

{
  "max_tokens": 4096,
  "reasoning": { "max_tokens": 2048 }
}

Reasoning budgets are approximate for models that support effort levels rather than exact budgets. The model determines actual reasoning length. DeepSeek V4 accepts none, low, high, and max effort levels. For OpenAI-compatible clients, medium is an alias for high, for both reasoning.effort and legacy reasoning_effort. enabled: true alone also uses high. Unsupported or contradictory combinations return a validation error.

Legacy reasoning_effort, include_reasoning, and supported chat_template_kwargs remain available. include_reasoning: false hides reasoning; it does not disable thinking. Send one control style when possible. Clients must consume reasoning separately from the answer; see Streaming.

DeepSeek clients and LiteLLM

For DeepSeek V4, you can also send the top-level DeepSeek API object "thinking": {"type":"enabled"}. This enables thinking at high effort unless the request includes an explicit reasoning.effort, reasoning_effort, or reasoning budget. "thinking": {"type":"disabled"} disables thinking.

Malformed or contradictory controls return 400 before credit is reserved. For example, thinking.type: enabled conflicts with reasoning_effort: none or a false template thinking toggle. The thinking object accepts only type, with value enabled or disabled; use reasoning.max_tokens for a budget. reasoning.exclude: true still hides returned reasoning without turning thinking off.

For LiteLLM, select its OpenAI-compatible provider and set the Netra base URL and complete catalog model ID:

model_list:
  - model_name: netra-deepseek
    litellm_params:
      model: openai/deepseek/deepseek-v4-flash-0731
      api_base: https://api.netraruntime.com/v1
      api_key: os.environ/NETRA_API_KEY
      extra_body:
        reasoning:
          effort: high
          exclude: false

LiteLLM consumes the openai/ prefix; the model ID sent to Netra is deepseek/deepseek-v4-flash-0731. The SDK expands extra_body, so the outgoing HTTP JSON contains top-level reasoning. Change effort to max when needed.

Some LiteLLM DeepSeek adapter versions replace the requested effort with only thinking: {"type":"enabled"}. Netra accepts that object, but cannot recover a max level that the adapter discarded. Use the OpenAI-compatible configuration above to preserve the effort. Check your installed LiteLLM version and sanitized outgoing body if results differ. See LiteLLM's OpenAI-compatible endpoint guide.

The default uncompressed inference request-body limit is 64 MiB (67,108,864 bytes), including JSON and message overhead. Model-specific limits can be lower. A request must fit both the configured byte limit and the model's context-token limit.