Crear Chat Completion - DeepSeek v3.1 Control de razonamiento (Streaming)

Este endpoint se utiliza para crear una conversación de chat con el modelo DeepSeek v3.1. Soporta salida en streaming (SSE) y un control preciso sobre la capacidad de razonamiento profundo (Thinking) del modelo.

Detalles del Endpoint

Estado: Publicado (Released)
Método de solicitud: POST
URL de solicitud: https://api.codingplanx.ai/v1/chat/completions

Encabezados de la solicitud (Headers)

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 (generalmente obligatorio al realizar la llamada real)

(Nota: el encabezado X-Forwarded-Host está actualmente deshabilitado)

Cuerpo de la solicitud (Request Body)

Content-Type: application/json

Parámetro	Obligatorio	Tipo	Descripción
`model`	Sí	String	ID del modelo a utilizar. Ejemplo: `deepseek-v3-1-250821`
`messages`	Sí	Array of Objects	Lista de mensajes de la conversación.
? `role`	Sí	String	Rol del remitente del mensaje (ej. `system`, `user`, `assistant`).
? `content`	Sí	String	Contenido específico del mensaje.
`max_tokens`	No	Integer	Límite máximo de tokens que el modelo puede generar en una solicitud. La longitud total de tokens de entrada y salida está sujeta al límite de contexto del modelo.
`temperature`	No	Number	Temperatura de muestreo, entre 0 y 2. Valores más altos (como 0.8) hacen la salida más aleatoria, mientras que valores más bajos (como 0.2) la hacen más enfocada y determinista.
`stream`	No	Boolean	Si se establece en `true`, se enviarán incrementos del mensaje en formato streaming mediante SSE (Server-Sent Events). El flujo de mensajes termina con `data: [DONE]`.
`stream_options`	No	Object	Opciones relacionadas con la salida en streaming. Solo se puede configurar si el parámetro `stream` es `true`.
? `include_usage`	No	Boolean	Si es `true`, se transmitirá un bloque adicional justo antes del `data: [DONE]` final en el flujo. El campo `usage` en este bloque muestra las estadísticas de uso de tokens de toda la solicitud.
`thinking`	No	Object	Algunos modelos con capacidad de razonamiento profundo permiten controlar esta función a través de este campo.
? `type`	No	String	`enabled`: Activa el razonamiento profundo de forma forzada.<br>`disabled`: Lo desactiva de forma forzada.<br>`auto`: El modelo decide automáticamente.

Ejemplo de solicitud

{
  "model": "deepseek-v3-1-250821",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hola"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "thinking": {
    "type": "enabled"
  }
}

Cuerpo de la respuesta (Response)

Código de estado HTTP: 200 OK Content-Type: application/json

(Nota: cuando stream: true, el formato devuelto es un flujo de datos SSE, donde cada fragmento (chunk) de datos es una cadena JSON con la siguiente estructura. A continuación se muestra la estructura JSON estándar para respuestas sin streaming o una vez ensamblado completamente el flujo)

Campo	Tipo	Descripción
`id`	String	Identificador único de la solicitud.
`object`	String	Tipo de objeto, generalmente `chat.completion` o `chat.completion.chunk`.
`created`	Integer	Marca de tiempo de creación (en segundos).
`choices`	Array of Objects	Lista de respuestas generadas por el modelo.
? `index`	Integer	Índice de esta respuesta en la lista choices.
? `message`	Object	Objeto del mensaje generado (en solicitudes streaming suele ser `delta`).
? `role`	String	Rol (generalmente `assistant`).
? `content`	String	Contenido específico de la respuesta.
? `finish_reason`	String	Motivo por el que se detuvo la generación (ej. `stop`, `length`).
`usage`	Object	Estadísticas de uso de Tokens.
? `prompt_tokens`	Integer	Cantidad de tokens consumidos por el prompt (indicación).
? `completion_tokens`	Integer	Cantidad de tokens consumidos por el contenido generado.
? `total_tokens`	Integer	Cantidad total de tokens consumidos.

Ejemplo de respuesta (JSON)

{
    "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
    }
}

Preguntas Frecuentes (FAQs)

Q1: ¿Cómo obtener el consumo de tokens (Usage) en una solicitud de streaming (SSE)? A1: Debe establecer stream en true en el cuerpo de la solicitud y configurar stream_options: {"include_usage": true}. De esta manera, antes de enviar el marcador de fin de flujo data: [DONE], el servidor enviará un bloque de datos (chunk) adicional. El array choices de este bloque estará vacío, pero el campo usage contendrá la información completa de las estadísticas de tokens.

Q2: ¿Cuál es la diferencia entre enabled y auto en el parámetro thinking? A2:

enabled: Obliga al modelo a realizar un "razonamiento profundo" (Chain of Thought) antes de devolver la respuesta final. Esto suele producir resultados de inferencia de mayor calidad, pero puede aumentar el tiempo de respuesta (latencia del primer token) y el consumo de tokens de salida.
auto: Delega la decisión al modelo, el cual evaluará automáticamente si es necesario realizar un razonamiento profundo basándose en la complejidad de las preguntas contenidas en su array messages.

Q3: ¿Por qué la solicitud devuelve un error 401 Unauthorized? A3: Esto ocurre generalmente porque la autenticación ha fallado. Verifique que el campo Authorization en los Headers de su solicitud tenga el formato correcto Bearer {{YOUR_API_KEY}} y asegúrese de que su API Key sea válida y no haya expirado.

Q4: Después de habilitar el razonamiento profundo thinking, ¿se devolverá el contenido del proceso de pensamiento? A4: Según la implementación estándar compatible con el formato de OpenAI, si se trata de una salida en streaming, el contenido del razonamiento profundo puede devolverse dentro de identificadores específicos (como las etiquetas <think>...</think>) o a través de campos específicos dentro del chunk. Al analizar los datos en streaming desde el frontend, preste atención al procesamiento del proceso de pensamiento dentro de content para poder mostrar a los usuarios una interfaz (UI) de "pensando...".

Q5: ¿Qué significa si obtengo finish_reason: "length"? A5: Esto indica que la salida del modelo alcanzó el límite de max_tokens que usted configuró, o superó el límite de la ventana de contexto máximo del modelo, lo que provocó que la respuesta se truncara. Si la respuesta está incompleta, puede intentar aumentar el valor de max_tokens.