docs(models): output budget passed through as sent, no reasoning floor

src/content/docs-es/examples.md

@@ -434,7 +434,7 @@ curl https://api.nan.builders/v1/chat/completions \
   }'
 ```
 
-Con el razonamiento activado se recomienda `max_tokens ≥ 300`, para dejarle sitio.
+Los tokens de razonamiento cuentan dentro de `max_tokens`, que se usa tal cual lo envías. Con el razonamiento activado, un presupuesto pequeño puede gastarse entero en razonar y llegar con `content` vacío y `finish_reason: "length"`. Si solo necesitas la respuesta, pon `"reasoning_effort": "none"`; si no, da un `max_tokens` generoso (los prompts densos pueden razonar miles de tokens) y usa `stream: true`. Mira [Controlar el razonamiento](/es/docs/models#controlar-el-razonamiento).
 
 ### visión (curl)
 

src/content/docs-es/models.mdx

@@ -50,7 +50,7 @@ OpenAI y la misma `base URL`.
   tag="305B MoE"
   leftLabel="generación de texto, chat y visión"
   rightLabel="capacidades"
-  description={'Modelo MoE de 305B parámetros, servido en su variante Vision-Exp: acepta imágenes de entrada. Contexto de 1M tokens. Tool calling y razonamiento. Cuota de 3B tokens al mes por miembro. Salida estructurada: response_format json_object es compatible (en api.nan.builders el prompt debe contener la palabra JSON; si no, se rechaza con un 400). json_schema se acepta en peticiones a /chat/completions sin streaming y sin tools: la respuesta se comprueba contra tu esquema y, si no lo cumple, normalmente la vuelve a servir un proveedor que lo impone; una respuesta que no se pudo comprobar, o un fallo que no se pudo reemplazar a tiempo, se devuelve tal cual (valídala si tu código depende de ella). En api.nan.builders el resto de peticiones json_schema se rechazan con un 400: con streaming, con tools, a /responses, con n mayor que 1, con un esquema de más de 16 KB, que no sea un JSON Schema válido o que el gateway no valida (un $ref fuera del esquema, $dynamicRef o $anchor, un $id anidado o demasiado grande al resolver sus $ref); en api.helmcode.com se aceptan. json_object solo garantiza JSON sintácticamente válido, no su forma: describe el esquema en el prompt. Para salida restringida a un esquema en esas otras peticiones, usa qwen3.6 o gemma4, donde json_schema con strict restringe campos, tipos y claves obligatorias; o, en este modelo, fuerza una única herramienta de tipo función cuyo parameters sea tu esquema (ver Ejemplos). Tu presupuesto de salida se usa exactamente como lo mandás en las dos rutas (max_tokens y max_completion_tokens en /chat/completions, max_output_tokens en /responses): nunca lo subimos. El razonamiento se factura contra ese mismo presupuesto, así que un presupuesto chico con un prompt que exige deliberar puede gastarse entero pensando, y la respuesta llega como HTTP 200 con finish_reason "length" y contenido vacío. Detectalo con finish_reason "length" Y contenido vacío Y usage.completion_tokens_details.reasoning_tokens igual a usage.completion_tokens; las llamadas sin streaming además traen el header x-nan-truncated-in-reasoning: true. Subí el presupuesto, o usá streaming.'}
+  description={'Modelo MoE de 305B parámetros, servido en su variante Vision-Exp: acepta imágenes de entrada. Contexto de 1M tokens. Tool calling y razonamiento. Cuota de 3B tokens al mes por miembro. Salida estructurada: response_format json_object es compatible (en api.nan.builders el prompt debe contener la palabra JSON; si no, se rechaza con un 400). json_schema se acepta en peticiones a /chat/completions sin streaming y sin tools: la respuesta se comprueba contra tu esquema y, si no lo cumple, normalmente la vuelve a servir un proveedor que lo impone; una respuesta que no se pudo comprobar, o un fallo que no se pudo reemplazar a tiempo, se devuelve tal cual (valídala si tu código depende de ella). En api.nan.builders el resto de peticiones json_schema se rechazan con un 400: con streaming, con tools, a /responses, con n mayor que 1, con un esquema de más de 16 KB, que no sea un JSON Schema válido o que el gateway no valida (un $ref fuera del esquema, $dynamicRef o $anchor, un $id anidado o demasiado grande al resolver sus $ref); en api.helmcode.com se aceptan. json_object solo garantiza JSON sintácticamente válido, no su forma: describe el esquema en el prompt. Para salida restringida a un esquema en esas otras peticiones, usa qwen3.6 o gemma4, donde json_schema con strict restringe campos, tipos y claves obligatorias; o, en este modelo, fuerza una única herramienta de tipo función cuyo parameters sea tu esquema (ver Ejemplos). Tu presupuesto de salida se usa tal cual lo envías (por encima de 393216, su máximo, se baja a 393216), con el razonamiento activado o apagado (max_tokens y max_completion_tokens en /chat/completions, max_output_tokens en /responses). Los tokens de razonamiento cuentan dentro de ese presupuesto: con el razonamiento activado, un presupuesto pequeño puede gastarse entero en razonar. En /chat/completions la respuesta llega entonces con content vacío y finish_reason "length" (el razonamiento está en reasoning_content, y usage.completion_tokens_details.reasoning_tokens es igual a completion_tokens; las llamadas sin streaming además traen el header de respuesta x-nan-truncated-in-reasoning: true); en /responses el status es incomplete, con solo un elemento de salida reasoning. Los prompts densos pueden razonar más de 16k tokens. La solución fiable es apagar el razonamiento (reasoning_effort "none" en /chat/completions, reasoning.effort "none" en /responses); un esfuerzo menor es una pista en este modelo, no un tope. O da un presupuesto generoso y usa streaming.'}
   specs={[
     { label: 'Tipo', value: 'MoE (305B total)' },
     { label: 'Cuantización', value: 'FP8' },
@@ -134,7 +134,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (function calling)',
-    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> lo apaga · de <code>low</code> a <code>max</code>; se recomienda <code>max_tokens &ge; 300</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
+    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> lo apaga · de <code>low</code> a <code>max</code>; el razonamiento cuenta dentro de <code>max_tokens</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
     'Audio (entrada de audio)',
     'Contexto de 1M tokens',
@@ -364,11 +364,29 @@ el valor.
 | `glm5.3` · `glm5.3-flash` | No es posible: GLM siempre razona. `none` se aplica como `minimal`, su razonamiento más corto (unos pocos tokens). | De `minimal` a `max`; los valores más altos razonan más antes de responder. |
 
 Sin parámetro, todos los modelos razonan (`qwen3.6` y `gemma4` con un
-presupuesto de 16.384 tokens). El razonamiento cuesta latencia y sus tokens
-cuentan dentro de `max_tokens`. Usa solo los valores de esta página.
+presupuesto de 16.384 tokens). El razonamiento cuesta latencia. Usa solo los valores de esta página.
 Cualquier otro valor se envía tal cual y queda fuera de este contrato: según el modelo,
 se rechaza con un `400` o se ignora.
 
+Tu presupuesto de salida (`max_tokens` o `max_completion_tokens` en Chat
+Completions, `max_output_tokens` en Responses) se usa tal cual lo envías en todos los modelos,
+salvo por encima del máximo del modelo en dos modelos, donde se baja a ese máximo: 131072 en `glm5.3-flash`, 393216 en `deepseek-v4-flash`.
+Los tokens de razonamiento salen de ese mismo presupuesto.
+
+**¿Respuesta vacía con `finish_reason: "length"`?** Con el razonamiento activado,
+un presupuesto pequeño puede agotarse antes de que
+empiece la respuesta. En Chat Completions recibes un `content` vacío con
+`finish_reason: "length"`, el razonamiento en `message.reasoning_content` y
+`usage.completion_tokens_details.reasoning_tokens` igual a `completion_tokens`;
+solo las tres juntas significan que el presupuesto se agotó razonando, y una llamada sin streaming además trae el header de respuesta `x-nan-truncated-in-reasoning: true`.
+En Responses la respuesta tiene `status: "incomplete"` con `incomplete_details.reason: "max_output_tokens"`, solo un elemento de salida `reasoning` y ningún texto de mensaje, y `usage.output_tokens_details.reasoning_tokens` es igual a `output_tokens`.
+En `deepseek-v4-flash` un prompt denso puede razonar más de 16k tokens. Si solo
+necesitas la respuesta, la solución fiable es apagar el razonamiento: `reasoning_effort: "none"` en Chat Completions, `reasoning: {"effort": "none"}` en Responses (GLM no puede apagarlo; `minimal` es lo más corto).
+Con el razonamiento apagado la respuesta también puede cortarse en el presupuesto, con texto, así que el presupuesto tiene que caberle a la respuesta.
+Un esfuerzo menor suele razonar menos, pero en `deepseek-v4-flash` y `qwen3.8-flash` es una pista, no un tope; solo `qwen3.6` y `gemma4` lo acotan, en Chat Completions. Para un tope estricto en `qwen3.6`, `gemma4` y `qwen3.8-flash`, mira [Limitar el razonamiento con un presupuesto de tokens](#limitar-el-razonamiento-con-un-presupuesto-de-tokens).
+Si quieres el razonamiento, da un presupuesto generoso y
+[usa streaming](#respuestas-largas-usa-streaming).
+
 ```bash
 curl https://api.nan.builders/v1/chat/completions \
   -H "Authorization: Bearer $NAN_API_KEY" \

src/content/docs/examples.md

@@ -434,7 +434,7 @@ curl https://api.nan.builders/v1/chat/completions \
   }'
 ```
 
-With reasoning enabled, `max_tokens ≥ 300` is recommended to leave room for reasoning.
+Reasoning tokens count inside `max_tokens`, which is used exactly as sent. With reasoning on, a small budget can be spent entirely on reasoning and come back with an empty `content` and `finish_reason: "length"`. If you only need the answer, set `"reasoning_effort": "none"`; otherwise give a generous `max_tokens` (dense prompts can reason for thousands of tokens) and use `stream: true`. See [Controlling reasoning](/docs/models#controlling-reasoning).
 
 ### vision (curl)
 

src/content/docs/models.mdx

@@ -50,7 +50,7 @@ with the same `base URL`.
   tag="305B MoE"
   leftLabel="text generation, chat & vision"
   rightLabel="capabilities"
-  description={'305B parameter MoE model, served as the Vision-Exp variant: it takes images as input. 1M token context. Tool calling and reasoning. 3B token monthly quota per member. Structured output: response_format json_object is supported (on api.nan.builders the prompt must contain the word JSON, otherwise it is rejected with a 400). json_schema is accepted on non-streamed /chat/completions requests without tools: the answer is checked against your schema and, when it does not match, usually re-served by a provider that enforces it; an answer that could not be checked, or a miss the re-serve could not replace in time, is returned as is (validate it if your code depends on it). On api.nan.builders other json_schema requests are rejected with a 400: streamed, with tools, on /responses, with n above 1, with a schema over 16 KB, not a valid JSON Schema, or one the gateway will not validate (a $ref outside the schema, $dynamicRef or $anchor, a nested $id, or too large once its $refs are inlined); on api.helmcode.com they are accepted. json_object guarantees syntactically valid JSON only, not its shape: describe the schema in the prompt. For schema-constrained output in those other requests, use qwen3.6 or gemma4, where json_schema with strict constrains fields, types and required keys; or, on this model, force one function tool whose parameters is your schema (see Examples). Your output budget is used exactly as sent on every route (max_tokens and max_completion_tokens on /chat/completions, max_output_tokens on /responses): we never raise it. Reasoning is billed against that same budget, so a small budget on a prompt that needs deliberation can be spent entirely thinking, and the answer then arrives as HTTP 200 with finish_reason "length" and empty content. Detect it with finish_reason "length" AND empty content AND usage.completion_tokens_details.reasoning_tokens equal to usage.completion_tokens; non-streamed calls also carry the response header x-nan-truncated-in-reasoning: true. Raise the budget, or stream.'}
+  description={'305B parameter MoE model, served as the Vision-Exp variant: it takes images as input. 1M token context. Tool calling and reasoning. 3B token monthly quota per member. Structured output: response_format json_object is supported (on api.nan.builders the prompt must contain the word JSON, otherwise it is rejected with a 400). json_schema is accepted on non-streamed /chat/completions requests without tools: the answer is checked against your schema and, when it does not match, usually re-served by a provider that enforces it; an answer that could not be checked, or a miss the re-serve could not replace in time, is returned as is (validate it if your code depends on it). On api.nan.builders other json_schema requests are rejected with a 400: streamed, with tools, on /responses, with n above 1, with a schema over 16 KB, not a valid JSON Schema, or one the gateway will not validate (a $ref outside the schema, $dynamicRef or $anchor, a nested $id, or too large once its $refs are inlined); on api.helmcode.com they are accepted. json_object guarantees syntactically valid JSON only, not its shape: describe the schema in the prompt. For schema-constrained output in those other requests, use qwen3.6 or gemma4, where json_schema with strict constrains fields, types and required keys; or, on this model, force one function tool whose parameters is your schema (see Examples). Your output budget is used exactly as sent (above 393216, its maximum, it is lowered to 393216), with reasoning on or off (max_tokens and max_completion_tokens on /chat/completions, max_output_tokens on /responses). Reasoning tokens count inside that budget: with reasoning on, a small budget can be spent entirely on reasoning. On /chat/completions the answer then comes back with an empty content and finish_reason "length" (the reasoning is in reasoning_content, and usage.completion_tokens_details.reasoning_tokens equals completion_tokens; non-streamed calls also carry the response header x-nan-truncated-in-reasoning: true); on /responses the status is incomplete, with only a reasoning output item. Dense prompts can reason past 16k tokens. The reliable fix is reasoning off (reasoning_effort "none" on /chat/completions, reasoning.effort "none" on /responses); a lower effort is a hint on this model, not a cap. Or give a generous budget and stream the answer.'}
   specs={[
     { label: 'Type', value: 'MoE (305B total)' },
     { label: 'Quantization', value: 'FP8' },
@@ -134,7 +134,7 @@ with the same `base URL`.
   ]}
   items={[
     'Tool calling (function calling)',
-    'Reasoning control (<code>reasoning_effort</code>: <code>none</code> turns it off · <code>low</code> to <code>max</code>; recommended <code>max_tokens &ge; 300</code>) · <a href="#controlling-reasoning">details</a>',
+    'Reasoning control (<code>reasoning_effort</code>: <code>none</code> turns it off · <code>low</code> to <code>max</code>; reasoning counts inside <code>max_tokens</code>) · <a href="#controlling-reasoning">details</a>',
     'Vision (image input)',
     'Audio (audio input)',
     '1M token context',
@@ -361,11 +361,28 @@ at the top level of the body or inside `extra_body`. Each one means exactly
 | `glm5.3` · `glm5.3-flash` | Not possible: GLM always reasons. `none` is applied as `minimal`, its shortest reasoning (a few tokens). | `minimal` to `max`; higher values reason longer before answering. |
 
 With no parameter every model reasons (`qwen3.6` and `gemma4` with a
-16,384-token budget). Reasoning costs latency and its tokens count toward
-`max_tokens`. Use only the values listed here.
+16,384-token budget). Reasoning costs latency. Use only the values listed here.
 Any other value is passed through unchanged and is not part of this contract: depending
 on the model it is rejected with a `400` or ignored.
 
+Your output budget (`max_tokens` or `max_completion_tokens` on Chat Completions,
+`max_output_tokens` on Responses) is used exactly as you send it on every model,
+except above the model's maximum on two models, where it is lowered to that maximum: 131072 on `glm5.3-flash`, 393216 on `deepseek-v4-flash`.
+Reasoning tokens are spent from that same budget.
+
+**Empty answer with `finish_reason: "length"`?** With reasoning on, a small
+budget can run out before the answer starts. On Chat Completions you get an empty `content` with
+`finish_reason: "length"`, the reasoning in `message.reasoning_content`, and
+`usage.completion_tokens_details.reasoning_tokens` equal to `completion_tokens`;
+only the three together mean the budget ran out while reasoning, and a non-streamed call also carries the response header `x-nan-truncated-in-reasoning: true`.
+On Responses the response has `status: "incomplete"` with `incomplete_details.reason: "max_output_tokens"`, only a `reasoning` output item and no message text, and `usage.output_tokens_details.reasoning_tokens` equals `output_tokens`.
+On `deepseek-v4-flash` a dense prompt can reason past 16k tokens. If you only
+need the answer, the reliable fix is to turn reasoning off: `reasoning_effort: "none"` on Chat Completions, `reasoning: {"effort": "none"}` on Responses (GLM cannot turn it off; `minimal` is its shortest).
+With reasoning off the answer can still stop at the budget, with text, so the budget must fit the answer.
+A lower effort usually reasons less, but on `deepseek-v4-flash` and `qwen3.8-flash` it is a hint, not a cap; only `qwen3.6` and `gemma4` cap it, on Chat Completions. For a hard cap on `qwen3.6`, `gemma4` and `qwen3.8-flash`, see [Capping reasoning with a token budget](#capping-reasoning-with-a-token-budget).
+If you want the reasoning, give a generous budget and
+[stream the answer](#long-outputs-stream-them).
+
 ```bash
 curl https://api.nan.builders/v1/chat/completions \
   -H "Authorization: Bearer $NAN_API_KEY" \