Official Function Calling API Documentation

This endpoint is used to create a Chat Completion. By providing a list of messages and an optional list of tools (Functions), the model can generate text responses or generate arguments conforming to specific JSON schemas to invoke external functions.

1. Interface Information

• Endpoint: https://api.codingplanx.ai/v1/chat/completions
• Method: POST
• Content-Type: application/json
• Authentication: Authorization: Bearer {{YOUR_API_KEY}}

2. Request Parameters

2.1 Headers

2.2 Request Body

---

3. Request Example

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like in Beijing today?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather for a specific location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city name, e.g., Beijing"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

---

4. Response Parameters

4.1 Response Body Structure

4.2 Response Example (Normal Text)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "It is sunny in Beijing today with a temperature of 25 degrees Celsius."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

5. FAQs

Q1: What is Function Calling (Tool Calling)? A: It is a way to provide models with external capabilities. The model does not execute code directly; instead, based on your description, it generates a JSON object containing a function name and required arguments. You need to extract this JSON, execute the function locally or on your server, and then pass the result back to the model.

Q2: Why did the model not return tool_calls despite me setting tools? A: This could happen for several reasons:

1. The model determines the user's query does not require calling that function.
2. Your function description is not clear enough for the model to match the user's intent.
3. tool_choice is explicitly set to none.
4. Model capability limitations (it is recommended to use models like gpt-4o or gpt-3.5-turbo which officially support tool calling).

Q3: How can I force the model to call a specific function? A: You can set tool_choice to a specific object, for example: "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}. This forces the model to generate parameters for that specific function even if it deems it unnecessary.

Q4: What should I do if the finish_reason is length? A: This means the generated response exceeded the max_tokens limit or the model's context window. You can try increasing the max_tokens parameter or shortening the messages history.

Q5: What are the precautions for using JSON Mode? A: When setting response_format: { "type": "json_object" }, you must also instruct the model via a System or User message to output JSON (e.g., "respond in JSON format"). Otherwise, the model might output an endless stream of whitespace.

Q6: How do I handle multiple tool calls? A: In a single request, the model may generate multiple tool calls (e.g., checking the weather for Beijing and Shanghai simultaneously). You should iterate through the choices[0].message.tool_calls array and execute the local logic for each call.