¡Invita a amigos y gana tokens gratuitos!Saber más

Aquí tienes la traducción al español, optimizada con terminología técnica estándar que los desarrolladores hispanohablantes y los motores de búsqueda (SEO) reconocen fácilmente. He conservado intacto el formato Markdown.

# Crear Chat Completion (No streaming)

Este *endpoint* de la API se utiliza para proporcionar un *prompt* (indicación) y hacer que el modelo devuelva uno o más resultados de *completion* (finalización) predichos. La interfaz sin *streaming* devuelve el resultado completo de una sola vez tras generar la respuesta en su totalidad.

- **URL del Endpoint**: `https://api.codingplanx.ai/v1/chat/completions`
- **Método HTTP**: `POST`
- **Content-Type**: `application/json`

---

## Parámetros de Solicitud

### Encabezados (Headers)

| Parámetro | Tipo | Requerido | Valor de Ejemplo | Descripción |
| :--- | :--- | :--- | :--- | :--- |
| Content-Type | string | Sí | `application/json` | Formato del cuerpo de la solicitud |
| Accept | string | Sí | `application/json` | Formato del cuerpo de la respuesta |
| Authorization | string | No | `Bearer {{YOUR_API_KEY}}` | Token de autenticación |

### Cuerpo de la Solicitud (Body)

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción |
| :--- | :--- | :--- | :--- | :--- |
| **model** | string | Sí | - | ID del modelo a utilizar (ej. `gpt-4o`, `gpt-3.5-turbo`). |
| **messages** | array | Sí | - | Lista de mensajes de la conversación. Cada objeto incluye el `role` (system/user/assistant) y el `content`. |
| temperature | number | No | 1 | Temperatura de muestreo (0-2). Valores más altos hacen que el resultado sea más aleatorio, valores más bajos lo hacen más determinista. |
| top_p | number | No | 1 | Muestreo de núcleo (*nucleus sampling*). Considera solo los tokens que conforman el top_p de la masa de probabilidad. Se recomienda modificar este valor o `temperature`, pero no ambos. |
| n | integer | No | 1 | Número de opciones de *completion* a generar por cada mensaje de entrada. |
| stream | boolean | No | false | Si se debe usar *streaming* (flujo de datos en tiempo real). Aquí debe establecerse en `false`. |
| stop | string/array| No | null | Secuencia de hasta 4 cadenas donde la API detendrá la generación de tokens. |
| max_tokens | integer | No | inf | Número máximo de tokens a generar, limitado por la longitud máxima de contexto del modelo. |
| presence_penalty | number | No | 0 | Número entre -2.0 y 2.0. Los valores positivos penalizan tokens nuevos, aumentando la probabilidad de que el modelo hable de nuevos temas. |
| frequency_penalty| number | No | 0 | Número entre -2.0 y 2.0. Los valores positivos penalizan tokens según su frecuencia en el texto, disminuyendo la probabilidad de que el modelo repita las mismas palabras. |
| logit_bias | object | No | null | Modifica la probabilidad de que aparezcan tokens específicos en el *completion*. |
| user | string | No | - | Identificador único del usuario final, utilizado para la detección de abusos. |
| response_format | object | No | - | Especifica el formato de salida. Ej. `{ "type": "json_object" }` para activar el modo JSON. |
| tools | array | No | - | Lista de herramientas que el modelo puede llamar (actualmente solo admite `function`). |
| tool_choice | string/obj | No | auto | Controla qué función llama el modelo (`none` / `auto` / o una función específica). |

---

## Parámetros de Respuesta

### Cuerpo de la Respuesta (Response Body)

| Parámetro | Tipo | Descripción |
| :--- | :--- | :--- |
| id | string | Identificador único para esta solicitud. |
| object | string | Tipo de objeto, siempre será `chat.completion`. |
| created | integer | Marca de tiempo Unix (en segundos) de cuando se creó el *completion*. |
| choices | array | Lista de resultados generados (*completions*). |
| ├─ index | integer | Índice del resultado dentro de la lista. |
| ├─ message | object | Contenido del mensaje generado por el modelo. |
| │  ├─ role | string | Rol del emisor, generalmente `assistant`. |
| │  └─ content | string | El texto específico generado. |
| └─ finish_reason| string | Razón por la que el modelo dejó de generar (ej. `stop`, `length`, `tool_calls`). |
| usage | object | Estadísticas de uso de tokens. |
| ├─ prompt_tokens | integer | Número de tokens consumidos por el *prompt* de entrada. |
| ├─ completion_tokens | integer | Número de tokens generados en la respuesta. |
| └─ total_tokens | integer | Total de tokens consumidos en la solicitud. |

---

## Ejemplos

### Ejemplo de Solicitud (cURL)
```bash
curl --location --request POST 'https://api.codingplanx.ai/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Hola, por favor preséntate."
    }
  ],
  "max_tokens": 1000
}'

Ejemplo de Respuesta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "¡Hola! Soy un asistente de IA proporcionado por CodingPlanX, encantado de ayudarte."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 25,
        "total_tokens": 40
    }
}

Preguntas Frecuentes (FAQs)

P1: ¿Cómo habilito el modo JSON? R1: Configura "response_format": { "type": "json_object" } en el cuerpo de la solicitud. Nota importante: Cuando uses el modo JSON, debes indicarle explícitamente al modelo (en el mensaje system o user) que genere una salida en formato JSON; de lo contrario, el modelo podría entrar en un bucle infinito generando contenido en blanco.

P2: ¿Cómo debo elegir entre temperature y top_p? R2: Por lo general, recomendamos modificar solo uno de los dos. Si necesitas que el modelo sea más creativo, aumenta la temperature (ej. a 0.8); si prefieres respuestas más rigurosas y deterministas, redúcela (ej. a 0.2).

P3: ¿Por qué el finish_reason muestra length? R3: Esto indica que la respuesta generada fue truncada porque alcanzó el límite de max_tokens que configuraste, o bien superó la longitud máxima de contexto del modelo.

P4: ¿Qué es un Token? R4: Un token es la unidad básica que el modelo utiliza para procesar texto. Para el idioma chino, un carácter equivale aproximadamente a 1~2 tokens (para idiomas occidentales como el español, un token suele equivaler a ~4 caracteres o 3/4 de una palabra). La facturación de la API y los límites de contexto se basan estrictamente en el número de tokens.

P5: ¿Cuál es la diferencia entre presence_penalty y frequency_penalty? R5: presence_penalty se centra en "hablar de temas nuevos", es decir, penaliza los tokens con el simple hecho de haber aparecido al menos una vez; frequency_penalty se centra en "la cantidad de veces que se repite una palabra", por lo que la penalización aumenta cuantas más veces aparezca una palabra en el texto.

P6: ¿Qué debo hacer si quiero obtener un efecto de generación de texto en tiempo real (efecto máquina de escribir)? R6: Establece el parámetro stream en true. Ten en cuenta que el formato de respuesta mediante streaming es diferente al de este documento (no streaming), ya que se basa en Server-Sent Events (SSE).