> ## 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.

# Reasoning models

> Use models that think before they answer, and read their reasoning trace.

Some models think through a problem before giving a final answer. This makes them stronger at math, code, and logic-heavy tasks. Models with the **`reasoning`** capability (Deepshi's own models and most frontier models) can return their thinking alongside the answer.

See [Chat models](/models/text-models) for which models support reasoning.

## Control reasoning

Set `reasoning_effort` to control how much a reasoning model thinks: `none`, `low`, `medium`, or `high`. Use `none` to skip reasoning and answer directly, or a higher level for more thorough reasoning. Omit it to use the model's default.

<CodeGroup>
  ```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 23 times 47?" }],
      "reasoning_effort": "high"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

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

  resp = client.chat.completions.create(
      model="deepshi-3.0",
      messages=[{"role": "user", "content": "What is 23 times 47?"}],
      reasoning_effort="high",   # use "none" to turn reasoning off
  )
  print(resp.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.deepshi.ai/v1",
    apiKey: process.env.DEEPSHI_API_KEY,
  });

  const resp = await client.chat.completions.create({
    model: "deepshi-3.0",
    messages: [{ role: "user", content: "What is 23 times 47?" }],
    reasoning_effort: "high", // use "none" to turn reasoning off
  });
  console.log(resp.choices[0].message.content);
  ```
</CodeGroup>

## Reading the reasoning trace

On a reasoning model, the assistant message can carry extra fields next to `content`:

* `message.reasoning`: the reasoning text.
* `message.reasoning_details`: a structured array of reasoning segments.

```python theme={null}
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="deepshi-3.0",
    messages=[{"role": "user", "content": "What is 15% of 240?"}],
    max_tokens=2048,
)

msg = resp.choices[0].message
print(getattr(msg, "reasoning", None))   # the thinking trace (may be None)
print(msg.content)                        # the final answer
```

<Tip>
  If you only want the final answer, read `message.content` and ignore the
  reasoning fields.
</Tip>

## Give reasoning models enough tokens

Reasoning and the visible answer **share the same generation budget**. If you set `max_tokens` too low, a reasoning model can spend its whole budget thinking and return **empty `content` with `finish_reason: "length"`**. That is a normal `200`, not an error.

```json theme={null}
{
  "choices": [{ "index": 0, "finish_reason": "length", "message": { "role": "assistant", "content": "" } }]
}
```

To avoid it, give reasoning models a generous `max_tokens` so there's room for both the thinking and the answer.

## Streaming

Reasoning works with streaming too. Set `"stream": true` and read `choices[].delta`. See [Streaming](/capabilities/text-and-chat#streaming).

## Best practices

* Allow ample `max_tokens` on reasoning models (room for thinking **and** the answer).
* Use a reasoning model for math, code, and multi-step problems; a non-reasoning model is faster and cheaper for simple tasks.
* Both reasoning and answer tokens count toward `usage.completion_tokens` and your cost.

## Next steps

<CardGroup cols={3}>
  <Card title="Tool calling" icon="wrench" href="/capabilities/tool-calling">
    Let the model call your functions.
  </Card>

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

  <Card title="Chat models" icon="message" href="/models/text-models">
    See which models support reasoning.
  </Card>
</CardGroup>