Skip to main content
Function calling lets a Lume model request actions or data from your application. Describe a function, receive its name and arguments, run your code, and send the result back so the model can answer. All four Lume models support function calling, strict function tools, and parallel tool calls on both APIs. Your application executes function tools. OverControl executes the separate web search and web fetch tools during a request.

Before you start

Create an API key in the dashboard with chat:completions for Chat Completions or messages:create for Messages. If your key has a model allowlist, include lume-3.5. Keep the key on your server and set it in the shell where you run the examples:
Send one authentication header per request: Authorization: Bearer or x-api-key. Supplying both with values returns HTTP 401. For SDK examples, install the client you use. cURL examples do not need an SDK.
Run Python examples from a .py file. Messages accepts an optional anthropic-version header. If supplied, it must be one valid calendar date in YYYY-MM-DD form. It is a compatibility hint and does not change the supported features. The SDK supplies its version header automatically.

Chat Completions

Call POST /v1/chat/completions with chat:completions. Declare each function as a tools entry with type: "function". Its parameters are a JSON Schema object. strict: true requests strict argument handling. The example below completes a two-request round trip. get_temperature uses fixed demonstration data so you can run the example without another API key. Replace that function with your application’s data source.
function.arguments is a JSON string. Parse it before calling your function. Keep the assistant’s tool calls in the conversation, then add a role: "tool" message for each result using the matching tool_call_id. The second request above disables further calls to make the demonstration finite. Set parallel_tool_calls: false when your application should receive one call at a time. If parallel calls are allowed, handle every returned call and pair each with its own result. Assistant text can accompany tool calls; use finish_reason and tool_calls to determine what work is needed. Older clients can send functions and function_call. Those responses use message.function_call and finish_reason: "function_call". Use tools for new integrations.

Messages

Call POST /v1/messages with messages:create. A function tool has name, description, and input_schema; omit type or use "custom". strict: true is supported. This complete example uses the same fixed demonstration lookup and returns the result in the next user message.
Messages returns tool_use blocks with an input object and stop_reason: "tool_use". Put each tool_result in a user message, preserving the matching tool_use_id. A result must refer to a preceding assistant call. For a function failure, return a tool result with is_error: true and a useful error description. Use disable_parallel_tool_use: true inside an auto, any, or named tool choice to disable parallel calls. That option is not valid with a none choice.

Compatible tool history

On a Messages tool_use, caller can be absent or exactly {"type":"direct"}. This describes the normal function-calling flow; your application still executes the function. Other caller types, including programmatic code-execution callers, are unsupported. On tool_use and tool_result, toolset_name can be absent or null. A named toolset is unsupported. An empty string or malformed value is invalid. Accepting null does not enable named toolsets. A tool result can contain a string or supported text/image blocks. Images need Lume Omni and must fit its media limits. PDF documents and arbitrary nested block types are not supported inside a client tool_result.

Limits and execution

You can declare up to 64 tools. Function names must match ^[A-Za-z0-9_-]{1,64}$. Each function schema can be at most 16,384 bytes. Messages also limits combined schemas to 512 KiB, individual descriptions to 64 KiB, and combined descriptions to 512 KiB. Lume 2 allows up to 16,384 output tokens; the other models allow up to 32,768. Chat accepts one of max_tokens and max_completion_tokens, defaulting to the model maximum; Messages requires a positive max_tokens. Both APIs reduce the budget to the model maximum and remaining context space. Tool definitions and results consume context too. Strict tools shape the requested arguments. Validate names, arguments, and application permissions before execution. A function call does not grant access to another user’s data or permission to perform an action. For a general schema, use a JSON Schema validator rather than relying only on the small checks in these examples. For a longer workflow, repeat the call/result cycle until the model finishes, with an application limit on the number of rounds. Check for Chat length or Messages max_tokens before executing an incomplete call. When streaming, accumulate Chat delta.tool_calls or Messages input_json_delta fragments before parsing arguments.

Usage and common errors

Both requests in a function round trip consume model tokens, including the function definitions and results you send. Your function’s own data-source costs are separate. Customer-executed functions have no OverControl server-side web-tool operation charge. Pricing explains model usage and the separate web-tool charges. Requests reserve estimated usage before execution and release unused reserved usage afterward. HTTP 400 can indicate an undeclared function, malformed arguments or history, an unsupported caller, or a schema limit. HTTP 401 indicates invalid authentication; HTTP 403 can indicate missing scope; Messages uses HTTP 404 for unknown or disallowed models. HTTP 429 with Insufficient credits means available usage cannot cover the reservation. Keep X-Request-Id for support; Messages also returns request-id.

Next

Web search

Let OverControl find web sources during a request.

Structured outputs

Return JSON text instead of requesting a function call.