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

# Structured outputs

> Force the model to return JSON that matches a schema you define.

Structured outputs let you request responses that match a JSON shape you define. When you supply a schema, the model is far less likely to invent keys or return malformed JSON than when you ask for a format in the system prompt.

Deepshi uses the OpenAI `response_format` field, so the schema format matches the [OpenAI structured outputs guide](https://platform.openai.com/docs/guides/structured-outputs).

## JSON mode

For simple "just give me valid JSON" cases, set `response_format` to `json_object`:

```python theme={null}
resp = client.chat.completions.create(
    model="deepshi-3.0",
    messages=[
        {"role": "system", "content": "Reply with JSON only."},
        {"role": "user", "content": "Give me a user with name and age."},
    ],
    response_format={"type": "json_object"},
)
```

## JSON schema

To enforce an exact shape, pass a `json_schema`. This example asks the model to show its steps solving an equation:

```bash 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": "system", "content": "You are a helpful math tutor." },
      { "role": "user", "content": "solve 8x + 31 = 2" }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "math_response",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "steps": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "explanation": { "type": "string" },
                  "output": { "type": "string" }
                },
                "required": ["explanation", "output"],
                "additionalProperties": false
              }
            },
            "final_answer": { "type": "string" }
          },
          "required": ["steps", "final_answer"],
          "additionalProperties": false
        }
      }
    }
  }'
```

The model returns content matching the schema exactly:

```json theme={null}
{
  "steps": [
    { "explanation": "Subtract 31 from both sides.", "output": "8x = -29" },
    { "explanation": "Divide both sides by 8.", "output": "x = -29 / 8" }
  ],
  "final_answer": "x = -29 / 8"
}
```

Beyond math, use this for data extraction, classification, UI generation, and any case where you parse the model's output downstream.

## Gotchas

* Every property must be listed in `required`. To make a field optional, allow `null` in its type: `"type": ["string", "null"]`.
* `additionalProperties` must be set to `false` for strict schemas.
* `strict` must be `true` for the schema to be enforced.
* A schema constrains the **shape**, not the **correctness**. The values still depend on the prompt and the model.
* Very large schemas can hit `max_tokens` or time out before completing. Keep schemas focused.

## Next steps

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

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