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

> ## Agent Instructions
> The Deepshi API is an OpenAI-compatible gateway. Base URL: https://api.deepshi.ai/v1. API keys start with sk-bf- and go in the Authorization: Bearer header. Prefer the official OpenAI SDKs pointed at the Deepshi base URL. Model ids are clean with no provider prefix (e.g. deepshi-3.0, claude-opus-4.8, gpt-5.5). Chat and image requests are synchronous; video and music requests are asynchronous job APIs (create, then poll). Every synchronous response carries usage.cost.total_cost in USD. Do not reference the internal /api/* admin plane or virtual keys.

# Tool calling

> Let models call your functions and external tools.

Tool calling (also called function calling) lets a model decide to invoke functions you define, with arguments it generates. You run the function and feed the result back, so the model can use live data and take actions.

Deepshi uses the OpenAI tool-calling format, so it works with the OpenAI SDKs and agent frameworks unchanged.

## How it works

<Steps>
  <Step title="Define tools">
    Describe your functions with a JSON Schema for their parameters and pass them in `tools`.
  </Step>

  <Step title="Model requests a call">
    If the model decides a tool is needed, the response contains `tool_calls` with the function name and JSON arguments, and `finish_reason` is `tool_calls`.
  </Step>

  <Step title="You run the function">
    Execute the function in your own code with the supplied arguments.
  </Step>

  <Step title="Return the result">
    Append a `tool` message with the output and call the API again. The model uses it to produce a final answer.
  </Step>
</Steps>

## Example

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI
  import json

  client = OpenAI(base_url="https://api.deepshi.ai/v1", api_key="YOUR_DEEPSHI_API_KEY")

  tools = [{
      "type": "function",
      "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
              "type": "object",
              "properties": {"city": {"type": "string"}},
              "required": ["city"],
          },
      },
  }]

  messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

  resp = client.chat.completions.create(
      model="deepshi-3.0", messages=messages, tools=tools,
  )

  call = resp.choices[0].message.tool_calls[0]
  args = json.loads(call.function.arguments)

  # Run your real function here.
  result = {"city": args["city"], "temp_c": 22, "conditions": "clear"}

  messages.append(resp.choices[0].message)             # the assistant's tool call
  messages.append({
      "role": "tool",
      "tool_call_id": call.id,
      "content": json.dumps(result),
  })

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

  ```bash curl theme={null}
  curl https://api.deepshi.ai/v1/chat/completions \
    -H "Authorization: Bearer $DEEPSHI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepshi-3.0",
      "messages": [{ "role": "user", "content": "What is the weather in Tokyo?" }],
      "tools": [{
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }]
    }'
  ```
</CodeGroup>

## Controlling tool use

Use `tool_choice` to steer the model:

| Value                                                   | Behavior                                                                    |
| ------------------------------------------------------- | --------------------------------------------------------------------------- |
| `"auto"`                                                | The model decides whether to call a tool. Default when `tools` are present. |
| `"none"`                                                | The model never calls a tool and replies with text.                         |
| `"required"`                                            | The model must call at least one tool.                                      |
| `{ "type": "function", "function": { "name": "..." } }` | Force a specific tool.                                                      |

Set `parallel_tool_calls` to `false` if you want at most one tool call per turn.

## Next steps

<CardGroup cols={2}>
  <Card title="Structured outputs" icon="code" href="/capabilities/structured-outputs">
    Force responses that match a JSON schema.
  </Card>

  <Card title="Reasoning" icon="brain" href="/capabilities/reasoning">
    Use models that think before they answer.
  </Card>
</CardGroup>