API reference

Tool calling & JSON.

Let a model call your functions, or force it to answer in JSON you can parse.

How tool calling works

You describe your functions in tools, each with a JSON Schema for its arguments.
The model either answers normally or returns tool_calls with the function name and arguments.
You run the function yourself and send the result back as a tool message.
The model uses that result to write its final answer.

Synaps never runs your functions. It only passes the definitions and calls between you and the model.

Full example

python

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_token_price",
        "description": "Get the current USD price of a token by its ticker.",
        "parameters": {
            "type": "object",
            "properties": {"ticker": {"type": "string", "description": "e.g. ETH"}},
            "required": ["ticker"],
        },
    },
}]

messages = [{"role": "user", "content": "What's ETH trading at?"}]
first = client.chat.completions.create(
    model="deepseek/deepseek-chat", messages=messages, tools=tools,
)

call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
price = {"ticker": args["ticker"], "usd": 3120.55}  # your own lookup

messages.append(first.choices[0].message)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(price)})

final = client.chat.completions.create(
    model="deepseek/deepseek-chat", messages=messages, tools=tools,
)
print(final.choices[0].message.content)

Controlling tool use

"tool_choice": "auto" (default): the model decides.
"tool_choice": "none": never call a tool.
"tool_choice": "required": must call at least one tool.
{"type": "function", "function": {"name": "get_token_price"}}: must call that function.

JSON output

JSON mode

Ask for any valid JSON object. Say in the prompt what fields you want:

python

reply = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    response_format={"type": "json_object"},
    messages=[{"role": "user", "content": "Give me {\"name\": str, \"chain\": str} for Uniswap."}],
)
data = json.loads(reply.choices[0].message.content)

JSON schema

On models that support structured outputs, pass a schema and the reply will match it:

json

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "token",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "chain": { "type": "string" },
        "launched": { "type": "boolean" }
      },
      "required": ["name", "chain", "launched"],
      "additionalProperties": false
    }
  }
}