GUIDES

Connect models to your tools.

Let a model request a function, then execute it in your application.

Define a function

Choose a model with function calling support. Describe the function with a JSON schema and send it in tools. This Chat Completions example lets the model request a local weather lookup.

{
  "model": "gpt-5.4-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Helsinki?"
    }
  ],
  "max_tokens": 256,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    }
  ]
}

Execute and return the result

When message.tool_calls is present, validate the function name and arguments before executing code. Append the assistant message to history, then a tool message with the matching tool_call_id and your result as text. Send the updated messages for the final answer.

Your application executes the function. Allow intended operations and enforce your permissions. Up to 32 function tools are accepted per request.

A complete function call

This runnable Python example asks the model to call add_numbers. Your Python code validates the arguments, calculates the result and returns it to the model. It makes two generation requests when a function is called.

Install the SDK and set TOKELY_API_KEY as shown in Quickstart. Save this example as tools.py and run python3 tools.py. The model should explain that 12 plus 7 is 19; its wording may vary.

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKELY_API_KEY"],
    base_url="https://api.tokely.me/v1",
)
messages = [{"role": "user", "content": "What is 12 plus 7?"}]
tools = [{
    "type": "function",
    "function": {
        "name": "add_numbers",
        "description": "Add two numbers.",
        "parameters": {
            "type": "object",
            "properties": {
                "a": {"type": "number"},
                "b": {"type": "number"},
            },
            "required": ["a", "b"],
            "additionalProperties": False,
        },
    },
}]
response = client.chat.completions.create(
    model="gpt-5.4-mini", messages=messages, tools=tools,
    tool_choice={"type": "function", "function": {"name": "add_numbers"}},
    max_tokens=1024,
)
message = response.choices[0].message
if message.tool_calls:
    messages.append({
        "role": "assistant",
        "content": message.content,
        "tool_calls": [call.model_dump() for call in message.tool_calls],
    })
    for call in message.tool_calls:
        if call.function.name != "add_numbers":
            raise ValueError("Unexpected function")
        arguments = json.loads(call.function.arguments)
        if set(arguments) != {"a", "b"} or any(
            type(value) not in (int, float) for value in arguments.values()
        ):
            raise ValueError("Invalid function arguments")
        result = arguments["a"] + arguments["b"]
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps({"result": result}),
        })
    final = client.chat.completions.create(
        model="gpt-5.4-mini", messages=messages, max_tokens=1024,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)

Functions with Responses

Responses uses function definitions with name, description and parameters directly on the tool object. Continue with function_call and function_call_output items, matching their call_id. Provider-hosted web search, code execution and other built-in tools are not enabled.

EXPLORE DOCUMENTATION

IntroductionConnect your app to AI models through one familiar API. This is your guide to building with Tokely.QuickstartMake your first Tokely request in three steps.API keysConnect securely with a key from your Tokely dashboard.ModelsChoose an available model and use its exact ID in your request.PlaygroundUse the Tokely Playground to test prompts before writing code.Use your existing appConnect an existing OpenAI-compatible application to Tokely.Chat CompletionsGenerate responses from text messages and supported inline images or PDFs.ResponsesUse stateless text and supported multimodal input with the Responses API.EmbeddingsTurn text into vectors for search, RAG, clustering and classification with the OpenAI-compatible /v1/embeddings endpoint.Claude Code and the Messages APIPoint Claude Code or the Anthropic SDK at Tokely. Use the native /v1/messages endpoint with streaming, tools and prompt caching.Images and PDFsSend inline images and PDFs to compatible models through Chat Completions or Responses.Images, video & audioGenerate media with your Tokely API key and account balance.Errors & limitsDiagnose failed requests and keep your integration within service limits.StreamingDisplay generated text as it arrives with server-sent events.Function callingLet a model request a function, then execute it in your application.Structured outputRequest JSON output or a defined schema from a compatible model.Usage & billingModel prices, account balance and output reservations.WebhooksTokely webhook events, HMAC signature verification, delivery retries and replay behavior.
Use Tab to browse results ESC to close