Crear Completado de Chat (En Streaming)

Referencia de la documentación oficial: OpenAI Chat Create

Descripción de la API

Dado un prompt (indicación), el modelo devolverá uno o más completados de chat predichos. Esta API soporta tanto respuestas estándar como en streaming (SSE), y puede devolver las probabilidades de los tokens alternativos en cada posición.

Especificaciones de la Solicitud

Método HTTP: POST
Endpoint: https://api.codingplanx.ai/v1/chat/completions

Encabezados (Headers)

Parámetro	Obligatorio	Tipo	Ejemplo	Descripción
`Content-Type`	Sí	string	`application/json`	Formato de datos
`Accept`	Sí	string	`application/json`	Formato de datos de recepción
`Authorization`	No*	string	`Bearer {{YOUR_API_KEY}}`	Token de autenticación (generalmente obligatorio en llamadas reales)
`X-Forwarded-Host`	No	string	`localhost:5173`	Nombre de host del proxy (normalmente no es necesario pasarlo manualmente)

Cuerpo de la Solicitud (Request Body)

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	Sí	ID del modelo a utilizar. Consulta la tabla de compatibilidad de endpoints de modelos para ver la lista de modelos compatibles.
`messages`	array	Sí	Lista de mensajes que conforman la conversación hasta el momento. Contiene los campos `role` y `content`.
`tools`	array	Sí	Lista de herramientas que el modelo puede llamar. Actualmente solo se admiten funciones como herramientas.
`tool_choice`	object	Sí	Controla qué función llama el modelo (si la hay). `none` significa no llamar a ninguna, `auto` significa selección automática, o forzar la llamada a una función específica.
`extra_body`	object	Sí	Parámetros adicionales. Contiene `enable_thinking` (boolean), que establece si se activa el modo de pensamiento (requiere soporte del modelo).
`temperature`	integer/float	No	Temperatura de muestreo, entre 0 y 2. Valores altos (como 0.8) hacen que la salida sea más aleatoria, mientras que valores bajos (como 0.2) la hacen más enfocada y determinista. Se recomienda modificar este valor o `top_p`, pero no ambos a la vez.
`top_p`	integer/float	No	Parámetro de 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 este valor o `temperature`, pero no ambos a la vez.
`n`	integer	No	Cuántas opciones de completado de chat generar para cada mensaje de entrada. El valor predeterminado es 1.
`stream`	boolean	No	Si se activa la salida en streaming. Si se establece en `true`, se enviarán fragmentos de mensajes parciales en forma de Server-Sent Events (SSE), y el flujo terminará con el mensaje `data: [DONE]`.
`stop`	string/array	No	Secuencia (hasta 4) donde la API detendrá la generación de tokens adicionales. El valor predeterminado es null.
`max_tokens`	integer	No	Número máximo de tokens que se generarán en el completado. La longitud total de los tokens de entrada y generados está limitada por la longitud del contexto del modelo.
`presence_penalty`	number	No	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 de nuevos temas.
`frequency_penalty`	number	No	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, reduciendo la probabilidad de que el modelo repita el mismo contenido.
`logit_bias`	object	No	Modifica la probabilidad de que tokens específicos aparezcan en el completado. Acepta un objeto JSON que mapea los IDs de los tokens a un valor de sesgo (entre -100 y 100).
`user`	string	No	Identificador único que representa a tu usuario final, lo que ayuda a monitorear y detectar abusos.
`response_format`	object	No	Especifica el formato de salida del modelo. Configurar como `{ "type": "json_object" }` habilita el modo JSON. Nota: Cuando se utiliza, debe indicar al modelo que genere JSON dentro de los mensajes, de lo contrario podría resultar en un flujo de espacios en blanco infinito.
`seed`	integer	No	Establece la semilla (Seed) para realizar un muestreo determinista (Función Beta).

Ejemplo de Solicitud

{
  "model": "gpt-5-mini",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

Especificaciones de la Respuesta

Content-Type: application/json (No streaming) o text/event-stream (Cuando se usa streaming stream: true)

Parámetros de Respuesta (Estructura no streaming)

Parámetro	Tipo	Descripción
`id`	string	Identificador único del completado de chat.
`object`	string	Tipo de objeto, generalmente `chat.completion` o `chat.completion.chunk`.
`created`	integer	Marca de tiempo de creación (Tiempo Unix).
`choices`	array	Lista de opciones de completado.
`choices[].index`	integer	Índice en la lista de opciones.
`choices[].message`	object	Objeto del mensaje generado por el modelo, contiene `role` y `content`. En streaming se denomina `delta`.
`choices[].finish_reason`	string	Motivo por el que se detuvo la generación (ej. `stop`, `length`, etc.).
`usage`	object	Estadísticas de uso de tokens de la API.
`usage.prompt_tokens`	integer	Número de tokens consumidos por el prompt (indicación).
`usage.completion_tokens`	integer	Número de tokens generados por el modelo.
`usage.total_tokens`	integer	Número total de tokens consumidos en esta solicitud.

Ejemplo de Respuesta (No streaming / Resultado agregado de streaming)

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

(Nota: Si se especifica stream: true en la solicitud, el cuerpo de la respuesta será un flujo de eventos SSE separados por saltos de línea, cada línea comenzando con data: {...}, y terminando finalmente con data: [DONE].)

FAQs (Preguntas Frecuentes)

P1: ¿Cómo analizo (parse) una respuesta en streaming cuando stream: true está activado? R: Cuando se activa stream: true, la API devuelve los datos a través del protocolo Server-Sent Events (SSE). El cliente debe leer el flujo de respuesta línea por línea, buscar las cadenas que comienzan con el prefijo data: y analizarlas como JSON. Tenga en cuenta que el último mensaje del flujo de datos es siempre data: [DONE], marcando el final del flujo. Este indicador de finalización debe filtrarse durante el análisis.

P2: ¿Por qué mi solicitud se bloquea o devuelve un flujo infinito de espacios en blanco después de configurar response_format a JSON? R: Cuando habilita el modo JSON utilizando { "type": "json_object" }, debe indicar explícitamente al modelo "por favor, genere en formato JSON" dentro de los messages pasados (generalmente en el system prompt). Si no hay un texto de indicación relevante, el modelo puede atascarse y generar caracteres en blanco sin fin hasta que se active el límite de max_tokens.

P3: ¿Se pueden ajustar los parámetros temperature y top_p al mismo tiempo? R: Oficialmente se recomienda encarecidamente NO ajustar ambos parámetros al mismo tiempo. Ambos son mecanismos utilizados para controlar la aleatoriedad de la salida del modelo. Si desea que la salida sea más estable y predecible, reduzca temperature O disminuya top_p; si desea respuestas más creativas, aumente uno de ellos. Modificar ambos simultáneamente hará que los resultados sean impredecibles.

P4: ¿Cuál es el propósito del parámetro extra_body.enable_thinking? R: Este es un parámetro de extensión especial para esta API. Al pasar {"enable_thinking": true}, si el modelo actual utilizado por el backend admite el "Modo de Pensamiento (Thinking Mode/CoT)" (como ciertos modelos grandes mejorados para el razonamiento), el modelo iniciará un proceso de pensamiento profundo. Si el modelo no lo admite, este parámetro generalmente será ignorado.

P5: ¿Por qué el finish_reason en la respuesta es length en lugar de stop? R: Cuando finish_reason devuelve length, indica que el modelo no ha generado una respuesta completa y fue truncado por la fuerza. Esto se debe generalmente a que su parámetro max_tokens es demasiado pequeño, o a que el número total de tokens de entrada y generados excedió el límite máximo de la ventana de contexto permitido por el modelo actual. Por favor, intente aumentar el valor de max_tokens.