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

# Model Catalog

> A single pane to view and manage every AI provider and model in your organization. It provides centralized governance, discovery, and usage controls for all your AI resources.

The Model Catalog is a centralized hub for viewing and managing all AI providers and models within your organization. It abstracts raw API keys and scattered environment variables into governed Provider Integrations and Models, giving you complete control over how your teams access and use AI.

> [!NOTE]
>
> #### [Upgrading from Virtual Keys](https://docs.portkey.ai/docs/support/upgrade-to-model-catalog.md)
>
> The Model Catalog upgrades the Virtual Key experience by introducing a centralized, organization-level management layer, offering advantages like:
>
> * Centralized provider and model management - no more duplicate configs across workspaces.
> * Fine-grained control: budgets, rate limits, and model allow-lists at both org and workspace level.
> * Inline usage: just pass `model="@provider/model_slug"`
>
> **Need help?** See our [Migration Guide ➜](https://docs.portkey.ai/docs/support/upgrade-to-model-catalog.md)

![Model Catalog - Provider and Models](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/providersandmodels.gif?s=2ece1b684a96eb04c944888664fdbfde)

> [card] AI Providers
>
> AI Providers are what you use in your code. Each provider has:
>
> * ✅ A unique slug (e.g., `@openai-prod`)
> * ✅ Securely stored credentials
> * ✅ Budget and rate limits
> * ✅ Access to specific models
>
> **To use:** Add a provider, then use `@provider-slug/model-name` in your code.

> [card] Models
>
> The Models section is a gallery of all AI models available in your workspace. Each Model entry includes:
>
> * ✅ Model slug (`@openai-prod/gpt-4o`)
> * ✅ Ready-to-use code snippets
> * ✅ Input/output token limits
> * ✅ Pricing information (where available)
>
> [View all available models →](https://app.portkey.ai/model-catalog/models)

## Adding an AI Provider

Add providers via **UI** (follow the steps below) or [**API**](https://docs.portkey.ai/docs/api-reference/admin-api/introduction.md).

**1. Go to AI Providers → Add Provider**

Navigate to the [Model Catalog](https://app.portkey.ai/model-catalog) in your Portkey dashboard.

![Portkey Model Catalog - AI Providers list](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-ai-providers-list-new.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=93ab2a44815bb8c7f3ea9bc5b0c4f32f)

**2. Select the AI Service**

Choose from list (OpenAI, Anthropic, etc.) or *Self-hosted / Custom*.

![Portkey Model Catalog - Add Provider - Choose Service](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-add-provider-choose-service-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=2dd25c33792ad79ea0b61bc5cabb3656)

**3. Choose or Create Credentials**

**If credentials already exist:**

* Select from the dropdown (if your org admin set them up)
* Skip to step 4 - no API keys needed!

**If creating new credentials:**

* Choose "Create new credentials"
* Enter your API keys here

> [!NOTE]
>
> Creating new credentials here automatically creates a workspace-linked integration. To share credentials across multiple workspaces, create them in the [Integrations](https://docs.portkey.ai/docs/product/model-catalog/integrations.md) page (org admin only).

![Model Catalog - Add credentials](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-add-provider-credentials-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=b362ac55d0d07a836e43e725f01d35df)

**4. Name your provider & save**

Choose a name and slug for this provider. The slug (e.g., `openai-prod`) will be used in your code like `@openai-prod/gpt-4o`.

![Model Catalog - Add Provider Details](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-add-provider-details-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=ce888ea0ef956cb34619928290a78b96)

## Using Provider Models

Once you have AI Providers set up, use their models in your applications. There are three methods - we recommend the model prefix format for clarity.

In Portkey, model strings follow this format:

`@provider_slug/model_name`

![Model String Format](https://mintcdn.com/portkey-docs/Hf1XgyjG_b79ym4Q/Screenshot2025-07-21at5.39.59PM.png?fit=max\&auto=format\&n=Hf1XgyjG_b79ym4Q\&q=85\&s=884eb4c9a28e26166467d1caa461eabc)

For example, `@openai-prod/gpt-4o`, `@anthropic/claude-3-sonnet`, `@bedrock-us/claude-3-sonnet-v1`

```javascript Javascript SDK theme={"system"}
import { Portkey } from 'portkey-ai';
const client = new Portkey({ apiKey: "PORTKEY_API_KEY" });

const resp = await client.chat.completions.create({
  model: '@openai-prod/gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

```python Python SDK theme={"system"}
from portkey_ai import Portkey

portkey = Portkey(api_key="PORTKEY_API_KEY")

resp = portkey.chat.completions.create(
  model="@openai-prod/gpt-4o",
  messages=[{"role":"user","content":"Hello"}]
)
```

```python OpenAI Python SDK theme={"system"}
from openai import OpenAI

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

client.chat.completions.create(
	model="@openai-prod/gpt-4o",
	messages=[{"role": "user", "content": "Hello!"}]
)
```

```javascript OpenAI JS SDK theme={"system"}
import OpenAI from 'openai';

const openai = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://api.portkey.ai/v1"
});

const completion = await openai.chat.completions.create({
    model: "@openai-prod/gpt-4o",
    messages: [{ role: 'user', content: 'Hello!' }]
});
```

```bash cURL theme={"system"}
curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@openai-prod/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### 2. Using the `provider` header

Specify the provider separately using the `provider` parameter. Remember to add the `@` before your provider slug.

```javascript Javascript SDK theme={"system"}
import { Portkey } from 'portkey-ai';
const client = new Portkey({
	apiKey: "PORTKEY_API_KEY",
	provider: "@openai-prod"
});

const resp = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

```python Python SDK theme={"system"}
from portkey_ai import Portkey

portkey = Portkey(
	api_key="PORTKEY_API_KEY",
	provider="@openai-prod"
)

resp = portkey.chat.completions.create(
  model="gpt-4o",
  messages=[{"role":"user","content":"Hello"}]
)
```

```python OpenAI Python SDK theme={"system"}
from openai import OpenAI
from portkey_ai import createHeaders

client = OpenAI(
	api_key="PORTKEY_API_KEY",
	base_url="https://api.portkey.ai/v1",
	default_headers=createHeaders(
		provider="@openai-prod"
	)
)

client.chat.completions.create(
	model="gpt-4o",
	messages=[{"role": "user", "content": "Hello!"}]
)
```

```javascript OpenAI JS SDK theme={"system"}
import OpenAI from 'openai';
import { createHeaders } from 'portkey-ai'

const openai = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://api.portkey.ai/v1",
	defaultHeaders: createHeaders({
		provider: "@openai-prod"
	})
});

const completion = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: 'user', content: 'Hello!' }]
});
```

```bash cURL theme={"system"}
curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @openai-prod" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### 3. Specify `provider` in the config

Portkey's configs are simple JSON structures that help you define routing logic for LLM requests. Learn more [here](https://docs.portkey.ai/docs/product/ai-gateway/configs.md).

There are three ways to specify providers in configs:

**Method 1: Model in override\_params (Recommended)**

Specify provider and model together in `override_params`. Works great with multi-provider strategies:

```json theme={"system"}
{
	"strategy": { "mode": "fallback" },
	"targets": [{
		"override_params": { "model": "@openai-prod/gpt-4o" }
	}, {
		"override_params": { "model": "@anthropic/claude-3-sonnet" }
	}]
}
```

**Method 2: Provider in target**

Specify provider directly in the target (remember the `@` symbol):

```json theme={"system"}
{
	"strategy": { "mode": "single" },
	"targets": [{
		"provider": "@openai-prod",
		"override_params": {
			"model": "gpt-4o"
		}
	}]
}
```

**Method 3: Legacy virtual\_key (Backwards Compatible)**

The `virtual_key` field still works:

```json theme={"system"}
{
	"strategy": { "mode": "single" },
	"targets": [{
		"virtual_key": "openai-prod"
	}]
}
```

> **Ordering:** `config` (if provided) defines base; `override_params` merges on top (last write wins for scalars, deep merge for objects like `metadata`).

## Integrations

At the heart of Model Catalog is a simple concept: your AI provider credentials need to be stored securely, governed carefully and managed centrally. In Portkey, these stored credentials are called **Integrations**. Think of an Integration as a secure vault for your API keys - whether it's your OpenAI API key, AWS Bedrock credentials, or Azure OpenAI configuration.

![Integrations Overview Page](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-integrations-overview-v3.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=8839394362344ee3fc19b45dec152c46)

Once you create an Integration (by storing your credentials), you can use it to create multiple AI Providers. For example, you might have one OpenAI Integration, but create three different AI Providers from it:

* `@openai-dev` for development with strict rate limits
* `@openai-staging` for testing with moderate budgets
* `@openai-prod` for production with higher limits

This separation gives you granular control over how different teams and environments use the same underlying credentials.

> [card] [Integrations](https://docs.portkey.ai/docs/product/model-catalog/integrations.md)
>
> Learn how to create and manage AI service credentials across your organization

## Managing Access and Controls

Each Integration in Portkey acts as a control point where you can configure:

### Budget Limits

Set spending controls at the Integration level to prevent unexpected costs. You can configure:

* **Cost-based limits**: Maximum spend in USD (e.g., \$1000/month)
* **Token-based limits**: Maximum tokens consumed (e.g., 10M tokens/week)
* **Periodic resets**: Weekly or monthly budget refreshes

![Budget Limits Configuration](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-budget-limits-configuration-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=b0a468fcbb4a9d6bec5af3651784ed65)

These limits cascade down to all AI Providers created from that Integration.

> [card] [Budget Management](https://docs.portkey.ai/docs/product/model-catalog/integrations.md#3-budget-%26-rate-limits)
>
> Set up cost controls and spending limits for your AI usage

### Rate Limits

Control request rates to manage load and prevent abuse:

* **Requests per minute/hour/day**: Set appropriate throughput limits
* **Concurrent request limits**: Control parallel processing
* **Burst protection**: Prevent sudden spikes in usage

Rate limits help you maintain service quality and prevent any single user or team from monopolizing resources.

> [card] [Rate Limiting](https://docs.portkey.ai/docs/product/model-catalog/integrations.md#3-budget-%26-rate-limits)
>
> Configure request rate controls to ensure fair usage and prevent abuse

### Workspace Provisioning

Control which workspaces in your organization can access specific AI Providers:

* **Selective access**: Choose which teams can use production vs development providers
* **Environment isolation**: Keep staging and production resources separate
* **Department-level control**: Give finance different access than engineering

![Workspace Provisioning Interface](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-workspace-provisioning-interface-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=8b3beb7be9c2c91de451f5e1fa116782)

This hierarchical approach ensures teams only have access to the resources they need.

> [card] [Workspace Provisioning](https://docs.portkey.ai/docs/product/model-catalog/integrations.md#1-workspace-provisioning)
>
> Manage workspace access to AI providers and models

### Model Provisioning

Fine-tune which models are available through each Integration:

* **Model allowlists**: Only expose specific models (e.g., only GPT-4 for production)
* **Model denylists**: Block access to expensive or experimental models
* **Custom model addition**: Add your fine-tuned or self-hosted models

![Model Provisioning Settings](https://mintcdn.com/portkey-docs/Az_PJRPMq602xEZC/images/product/model-catalog/model-catalog-model-provisioning-settings-v2.png?fit=max\&auto=format\&n=Az_PJRPMq602xEZC\&q=85\&s=9db56aa9eed577214b59d267801d22c6)

Model provisioning helps you maintain consistency and control costs across your organization.

> [card] [Model Provisioning](https://docs.portkey.ai/docs/product/model-catalog/integrations.md#2-model-provisioning)
>
> Configure which models are available through each integration

## Advanced Model Management

### Custom Models

The Model Catalog isn't limited to standard provider models. You can add:

* **Fine-tuned models**: Your custom OpenAI or Anthropic fine-tunes
* **Self-hosted models**: Models running on your infrastructure
* **Private models**: Internal models not publicly available

Each custom model gets the same governance controls as standard models.

> [card] [Custom Models](https://docs.portkey.ai/docs/product/model-catalog/custom-models.md)
>
> Add and manage your fine-tuned, self-hosted, or private models

### Overriding Model Details (Custom Pricing)

Override default model pricing for:

* **Negotiated rates**: If you have enterprise agreements with providers
* **Internal chargebacks**: Set custom rates for internal cost allocation
* **Free tier models**: Mark certain models as free for specific teams

Custom pricing ensures your cost tracking accurately reflects your actual spend.

> [card] [Custom Pricing](https://docs.portkey.ai/docs/product/model-catalog/model-overrides.md)
>
> Configure custom pricing for models with special rates

## Self-hosted AI Providers

> [card] Coming Soon

***

> [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact)
>
> Contact Us


## Related topics

- [Autogen](https://docs.portkey.ai/docs/integrations/agents/autogen.md)
- [Models](https://docs.portkey.ai/docs/api-reference/inference-api/models/models.md)
- [Upgrade to Model Catalog](https://docs.portkey.ai/docs/support/upgrade-to-model-catalog.md)
- [Overriding Model Details](https://docs.portkey.ai/docs/product/model-catalog/model-overrides.md)
- [Adding Custom Models](https://docs.portkey.ai/docs/product/model-catalog/custom-models.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.