API 接口文档：创建聊天函数调用

接口说明

给定一个提示，该模型将返回一个或多个预测的补全结果，并且可以返回每个位置替代标记的概率。此接口特别支持**函数调用（Function Calling）**功能，允许模型在生成消息和调用指定函数之间进行智能选择。

官方参考：Function Calling Guide

基础信息

请求方法：POST
请求地址：https://api.codingplanx.ai/v1/chat/completions
数据格式：application/json

请求头 (Headers)

参数名	类型	必填	示例值	描述
`Content-Type`	string	是	`application/json`	数据内容类型
`Accept`	string	是	`application/json`	客户端接收的数据类型
`Authorization`	string	否	`Bearer {{YOUR_API_KEY}}`	身份验证凭证

请求体 (Body)

参数名	类型	必填	描述
`model`	string	是	要使用的模型的 ID（例如 `gpt-4o`）。有关可用模型的详细信息，请参阅模型端点兼容性表。
`messages`	array	是	至今为止对话所包含的消息列表。每个对象需包含 `role` 和 `content` 字段。
`tools`	array	是	模型可以调用的一组工具列表。目前仅支持函数作为工具。用于提供模型可以为其生成 JSON 输入的函数列表。
`tool_choice`	object/string	是	控制模型调用哪个函数（如果有的话）。`none` 表示不调用；`auto` 表示模型自行选择。也可以通过 `{"type": "function", "function": {"name": "my_function"}}` 强制调用特定函数。
`temperature`	number	否	采样温度，介于 0 和 2 之间。较高的值（如 0.8）使输出更随机，较低的值（如 0.2）使输出更确定。建议不要同时修改此项和 `top_p`。
`top_p`	number	否	核采样方法。0.1 意味着只考虑构成前 10% 概率质量的标记。建议不要同时修改此项和 `temperature`。
`n`	integer	否	为每个输入消息生成多少个聊天补全选择。默认为 1。
`stream`	boolean	否	默认为 false。如果设置为 true，将以 Server-Sent Events (SSE) 的形式发送部分消息增量，并在 `data: [DONE]` 时终止。
`stop`	string/array	否	最多 4 个序列，API 将在遇到这些序列时停止进一步生成标记。默认为 null。
`max_tokens`	integer	否	在聊天补全中生成的最大标记数。输入和生成的总长度受模型的上下文长度限制。
`presence_penalty`	number	否	-2.0 到 2.0 之间的数字。正值会根据标记是否已出现在文本中来惩罚新标记，增加模型谈论新主题的可能性。
`frequency_penalty`	number	否	-2.0 到 2.0 之间的数字。正值根据文本目前的存在频率惩罚新标记，降低模型重复相同内容的可能性。
`logit_bias`	object	否	修改指定标记出现在补全中的可能性。接受将标记 ID 映射到偏差值（-100 到 100）的 JSON 对象。
`user`	string	否	代表您的最终用户的唯一标识符，可以帮助监控和检测滥用行为。
`response_format`	object	否	指定模型必须输出的格式的对象。例如使用 `{ "type": "json_object" }` 启用 JSON 模式。
`seen`	integer	否	测试阶段功能。如果指定，系统将尝试确定性地进行采样，使相同种子和参数的请求返回相同结果。

请求体示例

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

响应参数 (Response)

参数名	类型	描述
`id`	string	聊天补全的唯一标识符。
`object`	string	对象类型，通常为 `chat.completion`。
`created`	integer	创建聊天补全时的 Unix 时间戳。
`choices`	array	聊天补全选择列表。
? `index`	integer	该选择在选项列表中的索引。
? `message`	object	模型生成的回复消息对象，包含 `role` 和 `content`。
? `finish_reason`	string	模型停止生成标记的原因（如 `stop`、`length` 或触发了函数调用）。
`usage`	object	本次请求的标记消耗统计信息。
? `prompt_tokens`	integer	提示词（输入）消耗的标记数。
? `completion_tokens`	integer	模型生成的回复消耗的标记数。
? `total_tokens`	integer	本次请求总共消耗的标记数。

响应示例 (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)

Q1: 如何强制模型调用我指定的某个具体函数？ A: 您可以通过设置 tool_choice 参数来实现。例如，如果您的函数名为 get_weather，您可以将 tool_choice 设置为：{"type": "function", "function": {"name": "get_weather"}}。这样模型将忽略普通回复，强制输出该函数的参数。

Q2: 为什么我的回复内容被截断了？ A: 请检查响应中 choices[0].finish_reason 的值。如果是 "length"，则说明生成的文本超过了您设置的 max_tokens 参数限制，或者是达到了模型上下文的最大长度。您可以尝试调大 max_tokens 的值。

Q3: temperature 和 top_p 都可以控制随机性，我应该怎么用？ A: 这两个参数确实都能调节模型输出的多样性。较高的值会让输出更具创造性，较低的值则让输出更严谨确定。官方建议只调整其中一个参数，而保持另一个为默认值，不要同时修改两者，以免产生不可预期的结果。

Q4: 开启 stream: true 后，接口返回的数据格式是什么样的？ A: 开启流式传输后，接口不再返回单个 JSON 对象，而是返回 Server-Sent Events (SSE) 数据流。数据会以 data: {"id": "...", "choices": [{"delta": {"content": "..."}}]} 的形式逐块发送。当传输完成时，最后一条消息将是 data: [DONE]。

Q5: 启用 response_format 为 JSON 模式时有什么注意事项？ A: 当您将 response_format 设置为 { "type": "json_object" } 时，必须同时在 messages（系统提示或用户提示）中明确告诉模型生成 JSON 格式的数据。如果不这样做，模型可能会陷入死循环生成空白字符，导致请求超时或触发 token 上限。