> ## Documentation Index
> Fetch the complete documentation index at: https://kiosapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Function Calling via Chat Completions Tools — KiosAPI

> Pass a tools array to POST /v1/chat/completions to enable function calling. The model returns structured JSON arguments for your functions.

You can enable any compatible chat model to call your own functions by including a `tools` array in your request to `POST /v1/chat/completions`. Instead of returning a plain text reply, the model will return structured JSON arguments matching the schema you define — it is your responsibility to execute the function and, if needed, send the result back in a follow-up message.

<Info>
  For a deeper conceptual overview of how function calling works, see the [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling).
</Info>

## Request

**`POST https://kiosapi.com/v1/chat/completions`**

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Content-Type`  | Yes      | `application/json` |
| `Authorization` | Yes      | `Bearer sk-xxx`    |

### Request Body

<ParamField body="model" type="string" required>
  The model to use for the request (e.g. `gpt-4o`).
</ParamField>

<ParamField body="messages" type="array" required>
  An array of message objects representing the conversation history so far.
</ParamField>

<ParamField body="tools" type="array" required>
  An array of tool definitions that the model may call. Each element describes one callable function.

  <Expandable title="tools[] properties">
    <ParamField body="tools[].type" type="string" required>
      The type of tool. Must always be `"function"`.
    </ParamField>

    <ParamField body="tools[].function.name" type="string" required>
      The name of the function. Allowed characters: `a-z`, `A-Z`, `0-9`, underscores, and dashes. Maximum 64 characters.
    </ParamField>

    <ParamField body="tools[].function.description" type="string">
      A plain-language description of what the function does. Providing a clear description helps the model decide when to call it.
    </ParamField>

    <ParamField body="tools[].function.parameters" type="object" required>
      A [JSON Schema](https://json-schema.org/) object that describes the function's parameters. Typically uses `"type": "object"` with a `properties` map and a `required` array.
    </ParamField>

    <ParamField body="tools[].function.strict" type="boolean">
      When set to `true`, the model will strictly adhere to the parameter schema you provide, refusing to pass any fields not defined in `parameters`.
    </ParamField>
  </Expandable>
</ParamField>

### Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://kiosapi.com/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxx" \
      -d '{
        "model": "gpt-4o",
        "messages": [
          {
            "role": "user",
            "content": "What is the weather like in Paris today?"
          }
        ],
        "tools": [
          {
            "type": "function",
            "function": {
              "name": "get_weather",
              "description": "Get current temperature for a given location.",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "City and country e.g. Paris, France"
                  }
                },
                "required": ["location"],
                "additionalProperties": false
              },
              "strict": true
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import openai
    import json

    openai.api_key = "sk-xxx"
    openai.base_url = "https://kiosapi.com/v1/"

    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "user", "content": "What is the weather like in Paris today?"}
        ],
        tools=[
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get current temperature for a given location.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "City and country e.g. Paris, France"
                            }
                        },
                        "required": ["location"],
                        "additionalProperties": False
                    },
                    "strict": True
                }
            }
        ]
    )

    # The model returns a function call
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(args)  # {"location": "Paris, France"}
    ```
  </Tab>
</Tabs>

## Response

When the model decides to call a function, the response contains a `tool_calls` array in the message object rather than a text `content` value.

```json theme={null}
{
  "id": "chatcmpl-Ax2bU1RFE8P0Y9uqKcErQNLcx4dDe",
  "object": "chat.completion",
  "created": 1738634724,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_FezxjoWuDV1CL3dITVFOjUzK",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\":\"Paris, France\"}"
            }
          }
        ],
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 65,
    "completion_tokens": 16,
    "total_tokens": 81
  },
  "system_fingerprint": "fp_f3927aa00d"
}
```

### Response Fields

<ResponseField name="choices[].message.tool_calls" type="array">
  Present when the model wants to invoke one or more functions. Each element contains an `id`, a `type` of `"function"`, and a `function` object with `name` and `arguments` (a JSON-encoded string).
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  Set to `"tool_calls"` when the model is requesting a function invocation rather than producing a final text response.
</ResponseField>

<Tip>
  When `finish_reason` is `"tool_calls"`, you should parse the `arguments` string, execute the function on your end, and send the result back to the model in a new message with `role: "tool"`. The model will then produce its final response based on that result.
</Tip>