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

# Text & chat

> Generate text and hold conversations with the OpenAI-compatible chat completions API, including highly uncensored models.

The chat completions endpoint is the main way to generate text with the Deepshi API. It's fully OpenAI-compatible, so your existing prompts, SDKs, and tooling work unchanged.

| Endpoint                    | What it does                         |
| --------------------------- | ------------------------------------ |
| `POST /v1/chat/completions` | Generate text or hold a conversation |

## Basic request

Send a list of `messages`. Each message has a `role` (`system`, `user`, or `assistant`) and `content`.

<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": "system", "content": "You are a concise assistant." },
        { "role": "user", "content": "Explain backpropagation in two sentences." }
      ]
    }'
  ```

  ```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": "system", "content": "You are a concise assistant."},
          {"role": "user", "content": "Explain backpropagation in two sentences."},
      ],
  )
  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: "system", content: "You are a concise assistant." },
      { role: "user", content: "Explain backpropagation in two sentences." },
    ],
  });
  console.log(resp.choices[0].message.content);
  ```
</CodeGroup>

## Common parameters

| Parameter          | Type            | Description                                                                                                           |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `model`            | string          | The model id to use. See [Models](/models/text-models).                                                               |
| `messages`         | array           | The conversation so far. Required.                                                                                    |
| `temperature`      | number          | Sampling randomness, typically `0` to `2`. Lower is more deterministic.                                               |
| `top_p`            | number          | Nucleus sampling cutoff. Use instead of `temperature`, not both.                                                      |
| `max_tokens`       | integer         | Maximum tokens to generate in the response.                                                                           |
| `reasoning_effort` | string          | On reasoning models, how much to think: `none`, `low`, `medium`, or `high`. See [Reasoning](/capabilities/reasoning). |
| `stop`             | string or array | Sequences that stop generation.                                                                                       |
| `stream`           | boolean         | Stream tokens as Server-Sent Events. See [Streaming](#streaming).                                                     |
| `seed`             | integer         | Best-effort deterministic sampling for repeatable output.                                                             |
| `tools`            | array           | Function/tool definitions the model may call. See [Tool calling](/capabilities/tool-calling).                         |
| `response_format`  | object          | Set to `{ "type": "json_object" }` to force valid JSON output (model-dependent).                                      |

<Note>
  Supported parameters vary by model. Unsupported fields are safely ignored
  rather than rejected.
</Note>

## Multi-turn conversations

The API is stateless, so it doesn't remember previous calls. To continue a conversation, send the full message history each time and append the model's previous reply as an `assistant` message:

```python theme={null}
messages = [{"role": "user", "content": "What's the capital of France?"}]
resp = client.chat.completions.create(model="deepshi-3.0", messages=messages)

messages.append(resp.choices[0].message)              # the assistant's reply
messages.append({"role": "user", "content": "And its population?"})

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

## Image input

Vision-capable models accept images alongside text. Send the message `content` as an array of parts: a `text` part and an `image_url` part, where the image is a URL or a base64 `data:` URI.

```python theme={null}
resp = client.chat.completions.create(
    model="deepshi-3.0",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
        ],
    }],
)
print(resp.choices[0].message.content)
```

## Streaming

Set `"stream": true` to receive the response incrementally as Server-Sent Events (SSE) instead of waiting for the full completion. This is ideal for chat UIs that render tokens as they arrive. Image requests can stream too; see [Image generation](/capabilities/image-generation).

<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": "Write a haiku about the sea." }],
      "stream": true
    }'
  ```

  ```python Python theme={null}
  stream = client.chat.completions.create(
      model="deepshi-3.0",
      messages=[{"role": "user", "content": "Write a haiku about the sea."}],
      stream=True,
  )
  for chunk in stream:
      delta = chunk.choices[0].delta.content
      if delta:
          print(delta, end="", flush=True)
  ```

  ```javascript JavaScript theme={null}
  const stream = await client.chat.completions.create({
    model: "deepshi-3.0",
    messages: [{ role: "user", content: "Write a haiku about the sea." }],
    stream: true,
  });
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
  ```
</CodeGroup>

Each event is a `data:` line with a partial chunk; tokens arrive in `choices[0].delta.content`. The final chunk carries a `usage` object with `cost`, and the stream ends with a `data: [DONE]` sentinel:

```
data: {"choices":[{"delta":{"content":"Wide"}}]}

data: {"choices":[{"delta":{"content":" blue"}}]}

data: [DONE]
```

<Tip>
  Streaming works the same way for tool calls: the arguments arrive incrementally
  in `delta.tool_calls`. Accumulate them until `finish_reason` is `tool_calls`.
</Tip>

## Next steps

<CardGroup cols={3}>
  <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>

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