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

# Provider Routing

> Control how your requests are routed across multiple AI providers. Optimize for cost, performance, or reliability with intelligent provider selection.

BLACKBOX AI routes requests to the best available providers for your model. By default, requests are load balanced across top providers to maximize uptime. You can customize routing behavior in two ways:

1. **Provider Prefix Shorthand** — Prepend a provider slug to the model name: `{provider}/{model}` example: `azure/gpt-5.2`
2. **Provider Object** — Pass a `provider` object in the request body for fine-grained control

***

## Provider Prefix Shorthand

The simplest way to route a request to a specific provider is to prefix the model name with the provider slug:

```
{provider}/{model-name}
```

For example, instead of sending a request to `claude-sonnet-4.5` (which is load-balanced across all available providers), you can send it to `bedrock/claude-sonnet-4.5` to force the request through **Amazon Bedrock**.

<Info>
  Provider prefix routing is currently supported on **enterprise.blackbox.ai**. Use `https://enterprise.blackbox.ai/chat/completions` as the base URL.
</Info>

### Supported Provider Prefixes

| Prefix           | Routes to          |
| ---------------- | ------------------ |
| `anthropic/`     | Anthropic          |
| `openai/`        | OpenAI             |
| `azure/`         | Azure              |
| `google/`        | Google             |
| `google-vertex/` | Google (Vertex AI) |
| `vertex/`        | Google (Vertex AI) |
| `together/`      | Together AI        |
| `deepinfra/`     | DeepInfra          |
| `fireworks/`     | Fireworks AI       |
| `groq/`          | Groq               |
| `bedrock/`       | Amazon Bedrock     |
| `aws-bedrock/`   | Amazon Bedrock     |
| `mistral/`       | Mistral            |

### Examples

#### Route Claude to Amazon Bedrock

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "bedrock/claude-sonnet-4.5",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "bedrock/claude-sonnet-4.5",
          "messages": [{"role": "user", "content": "Hello"}]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "bedrock/claude-sonnet-4.5",
          messages: [{ role: "user", content: "Hello" }]
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

#### Route Llama to Together AI

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "together/llama-3.1-8b-instruct",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "together/llama-3.1-8b-instruct",
          "messages": [{"role": "user", "content": "Hello"}]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "together/llama-3.1-8b-instruct",
          messages: [{ role: "user", content: "Hello" }]
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

#### Route GPT-4o Mini to Azure

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "azure/gpt-4o-mini",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "azure/gpt-4o-mini",
          "messages": [{"role": "user", "content": "Hello"}]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "azure/gpt-4o-mini",
          messages: [{ role: "user", content: "Hello" }]
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

#### Route Gemini to Google Vertex

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google-vertex/gemini-2.5-flash-lite",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "google-vertex/gemini-2.5-flash-lite",
          "messages": [{"role": "user", "content": "Hello"}]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "google-vertex/gemini-2.5-flash-lite",
          messages: [{ role: "user", content: "Hello" }]
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

#### Route Mistral Large to Mistral

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "mistral/mistral-large-2512",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "mistral/mistral-large-2512",
          "messages": [{"role": "user", "content": "Hello"}]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "mistral/mistral-large-2512",
          messages: [{ role: "user", content: "Hello" }]
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### How It Works

When you use the provider prefix shorthand:

1. The provider prefix is stripped from the model name (e.g., `bedrock/claude-sonnet-4.5` → `claude-sonnet-4.5`)
2. The stripped model name is matched against available model configurations
3. A provider preference is automatically added to route the request to the specified provider

This is equivalent to using the `provider` object with `order`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// These two requests are equivalent:

// Shorthand
{ "model": "together/llama-3.1-8b-instruct" }

// Explicit provider object
{
  "model": "llama-3.1-8b-instruct",
  "provider": { "order": ["Together"], "allow_fallbacks": true }
}
```

### Using with Full Model Paths

You can also use the provider prefix with full `blackboxai/` model paths:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{ "model": "bedrock/blackboxai/anthropic/claude-sonnet-4.5" }
```

This routes `blackboxai/anthropic/claude-sonnet-4.5` through Amazon Bedrock.

<Note>
  Provider availability varies by model. Not all providers host all models. If the specified provider doesn't host your model, the request may fall back to another provider or return an error.
</Note>

<Tip>
  Use the provider prefix shorthand for quick, one-off routing. Use the `provider` object (documented below) when you need more advanced control like sorting, fallback policies, or performance thresholds.
</Tip>

***

## Provider Object (Advanced)

For more fine-grained control over routing, use the `provider` object in your request body. This gives you access to sorting, fallback policies, performance thresholds, and more.

***

## Available Providers

Common provider slugs you can use with `order`, `only`, and `ignore`:

| Provider     | Slug            |
| ------------ | --------------- |
| Anthropic    | `anthropic`     |
| OpenAI       | `openai`        |
| Azure        | `azure`         |
| Google       | `google-vertex` |
| Together AI  | `together`      |
| DeepInfra    | `deepinfra`     |
| Fireworks AI | `fireworks`     |
| Groq         | `groq`          |
| AWS Bedrock  | `bedrock`       |
| Mistral      | `mistral`       |

<Note>
  Provider availability varies by model. Not all providers host all models. If you specify a provider that doesn't host your requested model, it will be skipped.
</Note>

***

## Provider Object

The `provider` object can contain the following fields:

| Field                      | Type              | Default | Description                                                              |
| -------------------------- | ----------------- | ------- | ------------------------------------------------------------------------ |
| `sort`                     | string \| object  | -       | Sort providers by `"price"`, `"throughput"`, or `"latency"`              |
| `order`                    | string\[]         | -       | List of provider slugs to try in order (e.g., `["anthropic", "openai"]`) |
| `only`                     | string\[]         | -       | List of provider slugs to allow for this request                         |
| `ignore`                   | string\[]         | -       | List of provider slugs to skip for this request                          |
| `allow_fallbacks`          | boolean           | `true`  | Whether to allow backup providers when the primary is unavailable        |
| `require_parameters`       | boolean           | `false` | Only use providers that support all parameters in your request           |
| `data_collection`          | "allow" \| "deny" | "allow" | Control whether to use providers that may store data                     |
| `quantizations`            | string\[]         | -       | List of quantization levels to filter by (e.g., `["int4", "int8"]`)      |
| `preferred_min_throughput` | number \| object  | -       | Preferred minimum throughput (tokens/sec)                                |
| `preferred_max_latency`    | number \| object  | -       | Preferred maximum latency (seconds)                                      |

***

## Provider Sorting

Control how providers are prioritized for your request. By default, BLACKBOX AI load balances based on price while accounting for uptime.

### Sort by Price

Route to the lowest-cost provider:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "sort": "price"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "sort": "price"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              sort: "price"
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Sort by Throughput

Route to the highest-throughput provider for faster token generation:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "sort": "throughput"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "sort": "throughput"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              sort: "throughput"
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Sort by Latency

Route to the lowest-latency provider for faster time-to-first-token:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "sort": "latency"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "sort": "latency"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              sort: "latency"
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

***

## Ordering Specific Providers

Use the `order` field to specify which providers to try first, in order of preference:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "order": ["together", "deepinfra", "fireworks"]
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "order": ["together", "deepinfra", "fireworks"]
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              order: ["together", "deepinfra", "fireworks"]
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

The router will try providers in the specified order. If none are available, it will fall back to other providers unless fallbacks are disabled.

***

## Allowing Only Specific Providers

Use the `only` field to restrict requests to specific providers:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "only": ["anthropic"]
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "claude-sonnet-4",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "only": ["anthropic"]
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "claude-sonnet-4",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              only: ["anthropic"]
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Warning>
  Restricting to specific providers may reduce fallback options and limit request recovery if the specified provider is unavailable.
</Warning>

***

## Ignoring Providers

Use the `ignore` field to exclude specific providers from routing:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "ignore": ["azure", "aws"]
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "ignore": ["azure", "aws"]
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              ignore: ["azure", "aws"]
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

***

## Disabling Fallbacks

By default, if your preferred provider fails, BLACKBOX AI will try other available providers. To disable this behavior:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "order": ["together"],
        "allow_fallbacks": false
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "order": ["together"],
              "allow_fallbacks": False
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              order: ["together"],
              allow_fallbacks: false
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

With `allow_fallbacks: false`, if the specified provider fails, the request will return an error instead of trying other providers.

***

## Data Collection Policy

Control whether to use providers that may store or train on your data:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "data_collection": "deny"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "data_collection": "deny"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              data_collection: "deny"
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

* `"allow"` (default): Allow providers that may store data non-transiently
* `"deny"`: Only use providers that do not collect user data

***

## Requiring Parameter Support

Ensure your request only goes to providers that support all specified parameters:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "response_format": {"type": "json_object"},
      "provider": {
        "require_parameters": true
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "response_format": {"type": "json_object"},
          "provider": {
              "require_parameters": True
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          response_format: { type: "json_object" },
          provider: {
              require_parameters: true
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

This is useful when using features like JSON mode or specific sampling parameters that not all providers support.

***

## Performance Thresholds

Set minimum throughput or maximum latency preferences to filter providers based on performance:

### Minimum Throughput

Prefer providers with at least a certain throughput (tokens per second):

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "preferred_min_throughput": {
          "p90": 50
        }
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "preferred_min_throughput": {
                  "p90": 50
              }
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              preferred_min_throughput: {
                  p90: 50
              }
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Maximum Latency

Prefer providers with latency below a certain threshold (in seconds):

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "preferred_max_latency": {
          "p90": 3
        }
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "preferred_max_latency": {
                  "p90": 3
              }
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              preferred_max_latency: {
                  p90: 3
              }
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Percentile Options

Performance thresholds support the following percentile cutoffs:

* `p50` - Median performance (50% of requests perform better)
* `p75` - 75th percentile
* `p90` - 90th percentile (recommended for most use cases)
* `p99` - 99th percentile (strictest)

<Note>
  Performance thresholds are preferences, not hard requirements. Providers that don't meet the threshold are deprioritized but not excluded entirely.
</Note>

***

## Quantization Filtering

Filter providers by model quantization level:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.1-8b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "quantizations": ["fp8", "fp16"]
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.1-8b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "quantizations": ["fp8", "fp16"]
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.1-8b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              quantizations: ["fp8", "fp16"]
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Available Quantization Levels

* `int4` - Integer 4-bit
* `int8` - Integer 8-bit
* `fp4` - Floating point 4-bit
* `fp6` - Floating point 6-bit
* `fp8` - Floating point 8-bit
* `fp16` - Floating point 16-bit
* `bf16` - Brain floating point 16-bit
* `fp32` - Floating point 32-bit

<Warning>
  Quantized models may exhibit degraded performance for certain prompts. Lower quantization levels reduce memory requirements but may affect output quality.
</Warning>

***

## Combining Options

You can combine multiple provider options for fine-grained control:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/chat/completions
  curl -X POST https://enterprise.blackbox.ai/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "Hello"}],
      "provider": {
        "sort": "price",
        "ignore": ["azure"],
        "data_collection": "deny",
        "preferred_min_throughput": {"p90": 30}
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  response = requests.post(
      # Public api users: use https://api.blackbox.ai/chat/completions
      "https://enterprise.blackbox.ai/chat/completions",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "llama-3.3-70b-instruct",
          "messages": [{"role": "user", "content": "Hello"}],
          "provider": {
              "sort": "price",
              "ignore": ["azure"],
              "data_collection": "deny",
              "preferred_min_throughput": {"p90": 30}
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // Public api users: use https://api.blackbox.ai/chat/completions
  const response = await fetch("https://enterprise.blackbox.ai/chat/completions", {
      method: "POST",
      headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      body: JSON.stringify({
          model: "llama-3.3-70b-instruct",
          messages: [{ role: "user", content: "Hello" }],
          provider: {
              sort: "price",
              ignore: ["azure"],
              data_collection: "deny",
              preferred_min_throughput: { p90: 30 }
          }
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

This example:

1. Sorts providers by price (lowest first)
2. Excludes Azure from consideration
3. Only uses providers that don't collect data
4. Prefers providers with at least 30 tokens/sec throughput at p90

***

## Response Provider Field

The response includes a `provider` field indicating which provider served the request:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "gen-...",
  "model": "llama-3.3-70b-instruct",
  "choices": [...],
  "usage": {...},
  "provider": "Together"
}
```

This helps you track which provider was used, especially useful when using load balancing or fallbacks.