From 0f7299dd4dc87c5a256916e36631d9c219f3a1fa Mon Sep 17 00:00:00 2001 From: barckcode Date: Fri, 16 Oct 2026 10:26:12 +0200 Subject: [PATCH 1/2] docs(models): long outputs need stream=true (120s non-stream limit) Non-streaming requests return nothing until the whole answer is ready and must be ready within 120 seconds; agents asking for 32k-131k output tokens without streaming hit a 524. Document the limit and that a stream has no total time limit while it keeps producing. EN and ES. Co-Authored-By: Claude Opus 5.5 --- src/content/docs-es/models.mdx | 16 ++++++++++++++++ src/content/docs/models.mdx | 6 ++++++ 2 files changed, 22 insertions(+) diff --git a/src/content/docs-es/models.mdx b/src/content/docs-es/models.mdx index 3b036f8a..e8c4e592 100644 --- a/src/content/docs-es/models.mdx +++ b/src/content/docs-es/models.mdx @@ -455,6 +455,22 @@ const chat = await client.chat.completions.create({ }); ``` +## Respuestas largas: usá streaming. + +Una petición sin `stream: true` no devuelve nada hasta que la respuesta +completa está lista, y tiene que estar lista en **120 segundos**. Pasado +ese tiempo la conexión se cierra con un `524` (o con un error unos segundos +antes), sea cual sea el modelo. A las velocidades de generación habituales +eso son unos 10.000 a 15.000 tokens de salida, menos en los modelos con +razonamiento, que piensan antes de responder. + +Si pedís respuestas largas (un `max_tokens` grande, ficheros de código +largos, agentes que escriben documentos enteros), usá `stream: true`. Un +stream no tiene límite de tiempo total: los tokens te llegan a medida que se +generan, y la respuesta puede durar lo que necesite mientras siga +produciendo. Todos los modelos y los dos endpoints (`/v1/chat/completions` +y `/v1/responses`) lo soportan. + ## Límite de stream solo-razonamiento. Los prompts que exigen mucho razonamiento pueden dejar al modelo pensando diff --git a/src/content/docs/models.mdx b/src/content/docs/models.mdx index 2b0c2474..e2ad621e 100644 --- a/src/content/docs/models.mdx +++ b/src/content/docs/models.mdx @@ -452,6 +452,12 @@ const chat = await client.chat.completions.create({ }); ``` +## Long outputs: stream them. + +A request without `stream: true` returns nothing until the whole answer is ready, and it has to be ready within **120 seconds**. Past that, the connection is closed with a `524` (or an error a few seconds earlier), whatever the model. At the usual generation speeds that is roughly 10,000 to 15,000 output tokens, less for reasoning models that think before they answer. + +If you ask for long outputs (a large `max_tokens`, long code files, agents that write whole documents), use `stream: true`. A stream has no total time limit: tokens reach you as they are generated, and the answer can run for as long as it needs while it keeps producing. Every model and both endpoints (`/v1/chat/completions` and `/v1/responses`) support it. + ## Reasoning-only stream limit. Reasoning-heavy prompts can keep a model thinking for a long time before it writes anything. When a streaming turn has produced only reasoning — no `content`, no tool calls — for **420 seconds**, the platform closes the turn instead of letting it run into a dead end. A turn that is demonstrably thinking — it has already produced more than 45,000 reasoning characters — gets until **600 seconds**. The reasoning-character budget also scales with the size of your prompt: roughly 150,000 characters of headroom plus half the prompt's size in characters, capped at 300,000. When the platform closes the turn you receive `finish_reason: "length"` on an empty delta, followed by a usage chunk. From 8424403428a052e34c10797d1c7cdfa5ad227b0d Mon Sep 17 00:00:00 2001 From: barckcode Date: Fri, 16 Oct 2026 11:35:01 +0200 Subject: [PATCH 2/2] docs(models): link the reasoning-only cap, scope the token estimate, tu register The "no total time limit" line now points at the reasoning-only stream limit right below it, the 10-15k token estimate is stated for deepseek-v4-flash speed, streaming is claimed for chat models only, and the Spanish copy uses tu like the rest of the page (two older voseo lines too). Co-Authored-By: Claude Opus 5.5 --- src/content/docs-es/models.mdx | 30 ++++++++++++++++-------------- src/content/docs/models.mdx | 4 ++-- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/src/content/docs-es/models.mdx b/src/content/docs-es/models.mdx index e8c4e592..4d87024a 100644 --- a/src/content/docs-es/models.mdx +++ b/src/content/docs-es/models.mdx @@ -455,21 +455,23 @@ const chat = await client.chat.completions.create({ }); ``` -## Respuestas largas: usá streaming. +## Respuestas largas: usa streaming. Una petición sin `stream: true` no devuelve nada hasta que la respuesta completa está lista, y tiene que estar lista en **120 segundos**. Pasado ese tiempo la conexión se cierra con un `524` (o con un error unos segundos -antes), sea cual sea el modelo. A las velocidades de generación habituales -eso son unos 10.000 a 15.000 tokens de salida, menos en los modelos con -razonamiento, que piensan antes de responder. - -Si pedís respuestas largas (un `max_tokens` grande, ficheros de código -largos, agentes que escriben documentos enteros), usá `stream: true`. Un -stream no tiene límite de tiempo total: los tokens te llegan a medida que se -generan, y la respuesta puede durar lo que necesite mientras siga -produciendo. Todos los modelos y los dos endpoints (`/v1/chat/completions` -y `/v1/responses`) lo soportan. +antes), sea cual sea el modelo. A la velocidad de `deepseek-v4-flash` eso +son unos 10.000 a 15.000 tokens de salida; los modelos más lentos, y los +modelos con razonamiento, que piensan antes de responder, caben en menos. + +Si pides respuestas largas (un `max_tokens` grande, ficheros de código +largos, agentes que escriben documentos enteros), usa `stream: true`. Un +stream no tiene límite de tiempo total mientras siga produciendo: los tokens +te llegan a medida que se generan, dure lo que dure la respuesta. La única +excepción es un turno que solo produce razonamiento durante mucho tiempo, +mira el [límite de stream solo-razonamiento](#límite-de-stream-solo-razonamiento) +más abajo. Todos los modelos de chat soportan streaming en los dos endpoints +(`/v1/chat/completions` y `/v1/responses`). ## Límite de stream solo-razonamiento. @@ -482,7 +484,7 @@ sin salida. Un turno que demuestra que está pensando — ya produjo más de presupuesto de caracteres de razonamiento también escala con el tamaño de tu prompt: unos 150.000 caracteres de margen más la mitad del tamaño del prompt en caracteres, con un tope de 300.000. Cuando la plataforma cierra -el turno recibís `finish_reason: "length"` sobre un delta vacío, seguido de +el turno recibes `finish_reason: "length"` sobre un delta vacío, seguido de un chunk de usage. Ese chunk de usage es una estimación de lo que consumió el intento hasta el @@ -490,7 +492,7 @@ corte (tokens de prompt y de razonamiento), marcada con `"estimated": true, "billed": false` — los turnos cerrados así no se cobran de tu cuota — y lleva un marcador `nan_truncation` para que los clientes puedan distinguir este cierre de un corte real por longitud de contexto. -Pedilo con `stream_options: {"include_usage": true}`. +Pídelo con `stream_options: {"include_usage": true}`. Dos cosas que conviene saber: @@ -499,7 +501,7 @@ Dos cosas que conviene saber: escriben sobre la marcha nunca se cortan, por largas que sean. - Si un turno se cierra así, el modelo seguía planificando cuando tocó el techo. Baja `reasoning_effort` donde el modelo lo soporte (tabla de - arriba), o reestructurá el prompt para que empiece a escribir temprano. + arriba), o reestructura el prompt para que empiece a escribir temprano. El límite existe para acotar un modo de fallo conocido de los modelos con thinking: a veces planifican sin converger durante 10–25 minutos y queman diff --git a/src/content/docs/models.mdx b/src/content/docs/models.mdx index e2ad621e..10603a60 100644 --- a/src/content/docs/models.mdx +++ b/src/content/docs/models.mdx @@ -454,9 +454,9 @@ const chat = await client.chat.completions.create({ ## Long outputs: stream them. -A request without `stream: true` returns nothing until the whole answer is ready, and it has to be ready within **120 seconds**. Past that, the connection is closed with a `524` (or an error a few seconds earlier), whatever the model. At the usual generation speeds that is roughly 10,000 to 15,000 output tokens, less for reasoning models that think before they answer. +A request without `stream: true` returns nothing until the whole answer is ready, and it has to be ready within **120 seconds**. Past that, the connection is closed with a `524` (or an error a few seconds earlier), whatever the model. At `deepseek-v4-flash` speeds that is roughly 10,000 to 15,000 output tokens; slower models, and reasoning models that think before they answer, fit less. -If you ask for long outputs (a large `max_tokens`, long code files, agents that write whole documents), use `stream: true`. A stream has no total time limit: tokens reach you as they are generated, and the answer can run for as long as it needs while it keeps producing. Every model and both endpoints (`/v1/chat/completions` and `/v1/responses`) support it. +If you ask for long outputs (a large `max_tokens`, long code files, agents that write whole documents), use `stream: true`. A stream has no total time limit while it keeps producing: tokens reach you as they are generated, however long the answer runs. The one exception is a turn that produces only reasoning for a long time, see the [reasoning-only stream limit](#reasoning-only-stream-limit) below. Every chat model supports streaming on both endpoints (`/v1/chat/completions` and `/v1/responses`). ## Reasoning-only stream limit.