Documentación de la API: Crear Finalizaciones de Chat con Llamada a Funciones (Function Calling)

Descripción de la Interfaz

Dado un prompt (indicación), el modelo devolverá uno o más resultados de finalización predichos y puede incluir la probabilidad de los tokens alternativos en cada posición. Esta interfaz es especialmente compatible con la funcionalidad de Llamada a Funciones (Function Calling), lo que permite al modelo elegir de forma inteligente entre generar un mensaje de texto tradicional o invocar una función específica previamente definida.

Referencia Oficial: Guía de Function Calling

Información Básica

Método de Solicitud: POST
URL de la Solicitud: https://api.codingplanx.ai/v1/chat/completions
Formato de Datos: application/json

Encabezados de la Solicitud (Headers)

Parámetro	Tipo	Obligatorio	Valor de Ejemplo	Descripción
`Content-Type`	string	Sí	`application/json`	Tipo de contenido de los datos
`Accept`	string	Sí	`application/json`	Tipo de datos que el cliente puede recibir
`Authorization`	string	No	`Bearer {{YOUR_API_KEY}}`	Credencial de autenticación

Cuerpo de la Solicitud (Body)

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	Sí	El ID del modelo a utilizar (por ejemplo, `gpt-4o`). Para obtener detalles sobre los modelos disponibles, consulte la tabla de compatibilidad de endpoints de modelos.
`messages`	array	Sí	Una lista de los mensajes que componen la conversación hasta el momento. Cada objeto debe incluir los campos `role` y `content`.
`tools`	array	Sí	Una lista de herramientas que el modelo puede invocar. Actualmente, solo se admiten funciones como herramientas. Se utiliza para proporcionar al modelo una lista de funciones para las cuales puede generar entradas en formato JSON.
`tool_choice`	object/string	Sí	Controla qué función invoca el modelo (si la hay). `none` significa que no se llamará a ninguna; `auto` significa que el modelo elige por sí mismo. También se puede forzar la llamada a una función específica mediante `{"type": "function", "function": {"name": "mi_funcion"}}`.
`temperature`	number	No	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 determinista. Se recomienda no modificar este parámetro y `top_p` al mismo tiempo.
`top_p`	number	No	Método de muestreo de núcleo (nucleus sampling). Un valor de 0.1 significa que solo se consideran los tokens que componen el 10% superior de la masa de probabilidad. Se recomienda no modificar este parámetro y `temperature` al mismo tiempo.
`n`	integer	No	Cuántas opciones de finalización de chat generar por cada mensaje de entrada. El valor predeterminado es 1.
`stream`	boolean	No	El valor predeterminado es false. Si se establece en true, se enviarán fragmentos parciales del mensaje a través de Server-Sent Events (SSE) y terminará con el mensaje `data: [DONE]`.
`stop`	string/array	No	Hasta 4 secuencias donde la API dejará de generar más tokens. El valor predeterminado es null.
`max_tokens`	integer	No	El número máximo de tokens a generar en la finalización del chat. La longitud total (entrada + generación) está limitada por el tamaño de 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, 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 actual en el texto, reduciendo la probabilidad de que el modelo repita el mismo contenido.
`logit_bias`	object	No	Modifica la probabilidad de que aparezcan tokens específicos en la finalización. Acepta un objeto JSON que mapea IDs de tokens a valores de sesgo (de -100 a 100).
`user`	string	No	Un identificador único que representa a su usuario final, lo que puede ayudar a monitorear y detectar abusos.
`response_format`	object	No	Objeto que especifica el formato que el modelo debe utilizar para la salida. Por ejemplo, use `{ "type": "json_object" }` para habilitar el modo JSON.
`seen`	integer	No	Funcionalidad en fase de pruebas (Beta). Si se especifica, el sistema intentará realizar un muestreo determinista, de modo que las solicitudes con la misma semilla y parámetros devuelvan el mismo resultado.

Ejemplo del Cuerpo de la Solicitud

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful customer support assistant. Use the supplied tools to assist the user."
        },
        {
            "role": "user",
            "content": "Hi, can you tell me the delivery date for my order?"
        },
        {"role": "assistant", "content": "Hi there! I can help with that. Can you please provide your order ID?"},
        {"role": "user", "content": "i think it is order_12345"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_delivery_date",
                "description": "Get the delivery date for a customer's order. Call this whenever you need to know the delivery date, for example when a customer asks 'Where is my package'",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "order_id": {
                            "type": "string",
                            "description": "The customer's order ID."
                        }
                    },
                    "required": [
                        "order_id"
                    ],
                    "additionalProperties": false
                }
            }
        }
    ]
}

Parámetros de Respuesta (Response)

Parámetro	Tipo	Descripción
`id`	string	Identificador único de la finalización de chat.
`object`	string	Tipo de objeto, generalmente `chat.completion`.
`created`	integer	Marca de tiempo Unix de cuando se creó la finalización.
`choices`	array	Lista de las opciones de finalización del chat generadas.
? `index`	integer	El índice de esta opción dentro de la lista de opciones.
? `message`	object	El objeto del mensaje de respuesta generado por el modelo, contiene `role` y `content`.
? `finish_reason`	string	El motivo por el cual el modelo dejó de generar tokens (por ejemplo, `stop`, `length` o porque se activó una llamada a función).
`usage`	object	Estadísticas de consumo de tokens para esta solicitud.
? `prompt_tokens`	integer	Número de tokens consumidos por el prompt (entrada).
? `completion_tokens`	integer	Número de tokens consumidos por la respuesta generada por el modelo.
? `total_tokens`	integer	Número total de tokens consumidos en esta solicitud.

Ejemplo de Respuesta (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
    }
}

Preguntas Frecuentes (FAQs)

Q1: ¿Cómo forzar al modelo a llamar a una función específica que yo indique? R: Puede lograr esto configurando el parámetro tool_choice. Por ejemplo, si su función se llama get_weather, puede establecer tool_choice como: {"type": "function", "function": {"name": "get_weather"}}. De esta manera, el modelo ignorará las respuestas de texto normales y se verá obligado a generar los parámetros para esa función específica.

Q2: ¿Por qué el contenido de mi respuesta está cortado o truncado? R: Verifique el valor de choices[0].finish_reason en la respuesta. Si es "length", significa que el texto generado superó el límite establecido en el parámetro max_tokens, o que ha alcanzado la longitud máxima del contexto del modelo. Puede intentar aumentar el valor de max_tokens.

Q3: Tanto temperature como top_p pueden controlar la aleatoriedad, ¿cómo debo usarlos? R: Efectivamente, ambos parámetros ajustan la diversidad de la salida del modelo. Valores más altos hacen que la salida sea más creativa, mientras que valores más bajos la hacen más rigurosa y determinista. La recomendación oficial es ajustar solo uno de estos parámetros y mantener el otro en su valor predeterminado. Evite modificar ambos al mismo tiempo para no generar resultados impredecibles.

Q4: Después de activar stream: true, ¿cuál es el formato de los datos devueltos por la interfaz? R: Al habilitar la transmisión en flujo (streaming), la interfaz deja de devolver un único objeto JSON y, en su lugar, devuelve un flujo de datos mediante Server-Sent Events (SSE). Los datos se enviarán en fragmentos con el siguiente formato: data: {"id": "...", "choices": [{"delta": {"content": "..."}}]} . Cuando finalice la transmisión, el último mensaje será data: [DONE].

Q5: ¿Qué precauciones debo tomar al habilitar response_format en modo JSON? R: Cuando configure response_format como { "type": "json_object" }, es obligatorio que también instruya explícitamente al modelo a generar datos en formato JSON dentro de messages (ya sea en el system prompt o en el user prompt). Si no lo hace, el modelo podría entrar en un bucle infinito generando espacios en blanco, lo que provocaría que la solicitud agote el tiempo de espera (timeout) o alcance el límite máximo de tokens.