Controlar el Nivel de Esfuerzo de Razonamiento del Modelo (Chat Completions)

Descripción de la Interfaz

Dado un prompt (indicación), el modelo devolverá una o más respuestas de autocompletado predichas (soporta el control del nivel de esfuerzo de pensamiento/razonamiento del modelo).

Referencia de la Documentación Oficial: OpenAI Reasoning Guides
Estado de la Interfaz: Publicado (released)

Especificaciones de la Solicitud

Método de Solicitud: POST
URL de Solicitud: https://api.codingplanx.ai/v1/chat/completions

Encabezados (Headers)

Nombre del Parámetro	Obligatorio	Tipo	Valor de Ejemplo	Descripción
`Content-Type`	Sí	`string`	`application/json`	Formato de los datos
`Accept`	Sí	`string`	`application/json`	Formato de recepción
`Authorization`	No	`string`	`Bearer {{YOUR_API_KEY}}`	Credenciales de autenticación

Parámetros del Cuerpo de la Solicitud (Body)

Formato de datos: application/json

Nombre del Parámetro	Obligatorio	Tipo	Descripción
`model`	Sí	`string`	El ID del modelo a utilizar (por ejemplo, `o4-mini`, etc.).
`messages`	Sí	`array`	Una lista de mensajes que componen la conversación hasta el momento. Contiene el `role` (ej. user/assistant) y el `content` (contenido del mensaje).
`tools`	Sí	`array`	Una lista de herramientas (funciones) que el modelo puede llamar. Se utiliza para proporcionar funciones para las cuales el modelo puede generar una entrada JSON.
`tool_choice`	Sí	`object`	Controla qué función llama el modelo. `none` significa que no llamará a ninguna, `auto` significa selección automática.
`reasoning_effort`	No	`string`	Parámetro principal: Controla el nivel de esfuerzo (profundidad de pensamiento) del modelo de razonamiento al generar una respuesta. Los valores opcionales comunes son `low` (bajo), `medium` (medio) y `high` (alto).
`temperature`	No	`number`	Temperatura de muestreo, entre 0 y 2. Valores más altos (como 0.8) hacen que la salida sea más aleatoria, mientras que valores más bajos (como 0.2) la hacen más enfocada y determinista. Se recomienda modificar solo este parámetro o `top_p`, pero no ambos.
`top_p`	No	`number`	Muestreo de núcleo (nucleus sampling). 0.1 significa que solo se consideran los tokens que componen el 10% superior de la masa de probabilidad. Se recomienda modificar solo este parámetro o `temperature`, pero no ambos.
`n`	No	`integer`	Por defecto es 1. Cuántas opciones de autocompletado de chat generar por cada mensaje de entrada.
`stream`	No	`boolean`	Por defecto es false. Si se establece en true, se enviarán fragmentos parciales del mensaje como Server-Sent Events (SSE) y el flujo terminará con `data: [DONE]`.
`stop`	No	`string`	Hasta 4 secuencias de cadenas donde la API detendrá la generación de más tokens.
`max_tokens`	No	`integer`	El número máximo de tokens a generar en el autocompletado. La longitud total de los tokens de entrada y generados está limitada por la longitud del contexto del modelo.
`presence_penalty`	No	`number`	Número entre -2.0 y 2.0. Los valores positivos penalizan los nuevos tokens en función de si ya han aparecido en el texto hasta el momento, aumentando la probabilidad de que el modelo hable sobre nuevos temas.
`frequency_penalty`	No	`number`	Número entre -2.0 y 2.0. Los valores positivos penalizan los nuevos tokens en función de su frecuencia existente en el texto hasta el momento, disminuyendo la probabilidad de que el modelo repita el mismo contenido.
`logit_bias`	No	`object`	Acepta un objeto JSON que mapea los IDs de los tokens a un valor de sesgo (-100 a 100), utilizado para modificar la probabilidad de que los tokens especificados aparezcan en el autocompletado.
`user`	No	`string`	Un identificador único que representa a su usuario final, ayudando a monitorear y detectar abusos.
`response_format`	No	`object`	Especifica el formato que el modelo debe emitir. Por ejemplo, `{"type": "json_object"}` habilita el modo JSON.
`seen`	No	`integer`	Función en fase de pruebas (similar a un seed o semilla). Si se especifica, el sistema hará su mejor esfuerzo para realizar el muestreo de manera determinista, de modo que los mismos parámetros devuelvan los mismos resultados.

Ejemplo de Solicitud

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Hola, por favor explica en detalle los principios de la computación cuántica."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

Especificaciones de la Respuesta

Parámetros del Cuerpo de la Respuesta

Formato de datos: application/json

Nombre del Parámetro	Tipo	Descripción
`id`	`string`	El identificador único para esta solicitud.
`object`	`string`	El tipo de objeto, generalmente es `chat.completion`.
`created`	`integer`	La marca de tiempo (timestamp) de creación.
`choices`	`array`	Lista de resultados de autocompletado.
└ `index`	`integer`	El índice de la opción actual dentro de la lista.
└ `message`	`object`	El cuerpo del mensaje de respuesta generado por el modelo. Contiene el `role` y el `content`.
└ `finish_reason`	`string`	El motivo por el cual se detuvo la generación (por ejemplo, `stop`, `length`).
`usage`	`object`	Estadísticas de consumo de tokens.
└ `prompt_tokens`	`integer`	Número de tokens consumidos por el prompt (indicación de entrada).
└ `completion_tokens`	`integer`	Número de tokens consumidos en la generación del modelo.
└ `total_tokens`	`integer`	Número total de tokens consumidos.

Ejemplo de Respuesta (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (Preguntas Frecuentes)

1. ¿Cuál es la función del parámetro `reasoning_effort`?

El parámetro reasoning_effort se utiliza para controlar cuántos recursos computacionales y tiempo invierte en "pensamiento interno" un modelo con capacidades de razonamiento avanzado (como la serie de modelos o1/o4 de OpenAI) antes de dar una respuesta final. Generalmente soporta tres niveles: low (bajo), medium (medio) y high (alto). Cuando se establece en high, el modelo realizará deducciones lógicas más profundas, lo cual es ideal para resolver problemas matemáticos o de programación complejos; sin embargo, el tiempo de respuesta también aumentará en consecuencia.

2. ¿Por qué no recibo una respuesta JSON estándar después de habilitar `stream: true`?

Cuando se habilita la transmisión de datos por streaming (stream: true), la API utiliza el protocolo Server-Sent Events (SSE) para devolver continuamente bloques de datos (Chunks). Cada bloque de datos se envía en el formato data: {...}, y cuando todo el contenido ha terminado de transmitirse, se envía un mensaje data: [DONE]. Los desarrolladores necesitan leer línea por línea y parsear la cadena JSON que sigue a data: para ensamblar la respuesta completa.

3. La documentación sugiere modificar solo `temperature` o `top_p`, ¿por qué?

Ambos parámetros se utilizan para controlar la aleatoriedad y diversidad del contenido de salida del modelo. El parámetro temperature cambia la distribución de probabilidad escalando los logits, mientras que top_p (muestreo de núcleo) limita el grupo de candidatos truncando el vocabulario con una probabilidad acumulada más baja. Ajustar ambos parámetros al mismo tiempo hará que el comportamiento del modelo sea difícil de predecir y controlar. Por lo tanto, la mejor práctica es fijar uno de ellos (generalmente manteniendo su valor por defecto) y ajustar solo el otro para satisfacer las necesidades de control de la "aleatoriedad".

4. ¿Qué significa si `finish_reason` devuelve `"length"`?

Esto significa que la respuesta del modelo fue truncada de forma forzosa. Generalmente hay dos razones para esto: la primera es que el número de tokens generados alcanzó el límite máximo establecido en el parámetro max_tokens de su solicitud; la segunda es que la suma total de tokens de su prompt de entrada más la respuesta generada por el modelo superó el límite de la ventana de contexto máxima permitida para ese modelo. En este caso, se recomienda acortar el historial de la conversación o aumentar el valor del parámetro max_tokens.

5. ¿Cómo forzar al modelo a devolver datos en formato JSON?

Puede activar el modo JSON pasando "response_format": {"type": "json_object"} en el cuerpo de la solicitud. Muy importante: Al habilitar este modo, es imprescindible indicar explícitamente al modelo usando lenguaje natural (generalmente en el prompt del sistema o del usuario) que la salida debe ser en JSON. De lo contrario, el modelo podría entrar en un bucle infinito generando espacios en blanco hasta alcanzar el límite de tokens.