Universal API - Portkey Docs

Available on all Portkey plans.

Portkey’s AI Gateway provides a single, unified API for 200+ models from every major provider. Write once in any format, switch providers by changing one parameter.

Three API Formats, Any Provider

Portkey supports three API formats. Each works with all providers — Portkey handles translation automatically.

Chat Completions

OpenAI spec · POST /v1/chat/completionsWidest ecosystem compatibility

Responses API

OpenAI spec · POST /v1/responsesAgentic AI with built-in tool use

Messages API

Anthropic spec · POST /v1/messagesNative Anthropic format across providers

Chat Completions — `POST /v1/chat/completions`

OpenAI-compatible format with the widest ecosystem support. Full guide →

from portkey_ai import Portkey

portkey = Portkey(api_key="PORTKEY_API_KEY")

response = portkey.chat.completions.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

import Portkey from 'portkey-ai';

const portkey = new Portkey({ apiKey: "PORTKEY_API_KEY" });

const response = await portkey.chat.completions.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    messages: [{ role: "user", content: "Hello!" }]
});

console.log(response.choices[0].message.content);

from openai import OpenAI

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

response = client.chat.completions.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

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

const response = await client.chat.completions.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    messages: [{ role: "user", content: "Hello!" }]
});

console.log(response.choices[0].message.content);

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Responses API — `POST /v1/responses`

OpenAI’s next-gen format for agentic AI with built-in tool use and reasoning. Full guide →

from portkey_ai import Portkey

portkey = Portkey(api_key="PORTKEY_API_KEY")

response = portkey.responses.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    input="Hello!"
)

print(response.output_text)

import Portkey from 'portkey-ai';

const portkey = new Portkey({ apiKey: "PORTKEY_API_KEY" });

const response = await portkey.responses.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    input: "Hello!"
});

console.log(response.output_text);

from openai import OpenAI

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

response = client.responses.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    input="Hello!"
)

print(response.output_text)

import OpenAI from 'openai';

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

const response = await client.responses.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    input: "Hello!"
});

console.log(response.output_text);

curl https://api.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "Hello!"
  }'

Messages API — `POST /v1/messages`

Anthropic-native format using the Anthropic SDK pointed at Portkey’s base URL. Full guide →

import anthropic

client = anthropic.Anthropic(
    api_key="dummy", # we will use portkey's provider slug
    default_headers={"x-portkey-api-key": "YOUR_PORTKEY_API_KEY"},
    base_url="https://api.portkey.ai"
)

message = client.messages.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

print(message.content[0].text)

import Anthropic from '@anthropic-ai/sdk';

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

const message = await client.messages.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }]
});

console.log(message.content[0].text);

curl https://api.portkey.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The Portkey SDK is a superset of the OpenAI SDK. The OpenAI SDK also works directly — point base_url at https://api.portkey.ai/v1. For the Messages API, use the Anthropic SDK. See Model Catalog for provider setup.

Switching Providers

Change the @provider/model string to switch between any provider. The API format stays the same.

from portkey_ai import Portkey

portkey = Portkey(api_key="PORTKEY_API_KEY")

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

# Switch to Anthropic -- same client, different model string
response = portkey.chat.completions.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    messages=[{"role": "user", "content": "Hello"}]
)

# Switch to Gemini
response = portkey.chat.completions.create(
    model="@google-provider/gemini-2.0-flash",
    messages=[{"role": "user", "content": "Hello"}]
)

import Portkey from 'portkey-ai';

const portkey = new Portkey({ apiKey: "PORTKEY_API_KEY" });

// OpenAI
const response = await portkey.chat.completions.create({
    model: "@openai-provider/gpt-4o",
    messages: [{ role: "user", content: "Hello" }]
});

// Switch to Anthropic -- same client, different model string
const response2 = await portkey.chat.completions.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    messages: [{ role: "user", content: "Hello" }]
});

from openai import OpenAI

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

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

# Switch to Anthropic -- same client, different model string
response = client.chat.completions.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    messages=[{"role": "user", "content": "Hello"}]
)

# Switch to Gemini
response = client.chat.completions.create(
    model="@google-provider/gemini-2.0-flash",
    messages=[{"role": "user", "content": "Hello"}]
)

import OpenAI from 'openai';

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

// OpenAI
const response = await client.chat.completions.create({
    model: "@openai-provider/gpt-4o",
    messages: [{ role: "user", content: "Hello" }]
});

// Switch to Anthropic -- same client, different model string
const response2 = await client.chat.completions.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    messages: [{ role: "user", content: "Hello" }]
});

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

# Switch to Anthropic -- same endpoint, different model string
curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{"model": "@anthropic-provider/claude-sonnet-4-5-20250514", "messages": [{"role": "user", "content": "Hello"}]}'

Set up providers and credentials in the Model Catalog. The @provider-slug in the model string routes requests to the correct provider automatically.

Routing, Fallbacks, and Load Balancing

Configs enable routing strategies, fallbacks, and load balancing across providers.

from portkey_ai import Portkey

config = {
    "strategy": {"mode": "fallback"},
    "targets": [
        {"override_params": {"model": "@openai-provider/gpt-4o"}},
        {"override_params": {"model": "@anthropic-provider/claude-sonnet-4-5-20250514"}}
    ]
}

portkey = Portkey(api_key="PORTKEY_API_KEY", config=config)

# Automatically falls back to Anthropic if OpenAI fails
response = portkey.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}]
)

import Portkey from 'portkey-ai';

const config = {
    strategy: { mode: "fallback" },
    targets: [
        { override_params: { model: "@openai-provider/gpt-4o" } },
        { override_params: { model: "@anthropic-provider/claude-sonnet-4-5-20250514" } }
    ]
};

const portkey = new Portkey({ apiKey: "PORTKEY_API_KEY", config });

// Automatically falls back to Anthropic if OpenAI fails
const response = await portkey.chat.completions.create({
    messages: [{ role: "user", content: "Hello" }]
});

from openai import OpenAI

# Use a saved config ID from Portkey dashboard
client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://api.portkey.ai/v1",
    default_headers={"x-portkey-config": "pp-config-xxx"}
)

# Automatically falls back to Anthropic if OpenAI fails
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

import OpenAI from 'openai';

// Use a saved config ID from Portkey dashboard
const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://api.portkey.ai/v1",
    defaultHeaders: { "x-portkey-config": "pp-config-xxx" }
});

// Automatically falls back to Anthropic if OpenAI fails
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }]
});

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-config: pp-config-xxx" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Configs work with all three API formats — Chat Completions, Responses, and Messages. For more details, see Configs and Conditional Routing.

Local and Private Models

Route to local or private models with custom_host. The model must be compatible with a supported provider format.

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="mistral-ai",
    custom_host="http://MODEL_URL/v1/"
)

response = portkey.chat.completions.create(
    model="mixtral-8x22b",
    messages=[{"role": "user", "content": "Hello"}]
)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "mistral-ai",
    customHost: "http://MODEL_URL/v1/"
});

const response = await portkey.chat.completions.create({
    model: "mixtral-8x22b",
    messages: [{ role: "user", content: "Hello" }]
});

from openai import OpenAI

client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://api.portkey.ai/v1",
    default_headers={
        "x-portkey-provider": "mistral-ai",
        "x-portkey-custom-host": "http://MODEL_URL/v1/"
    }
)

response = client.chat.completions.create(
    model="mixtral-8x22b",
    messages=[{"role": "user", "content": "Hello"}]
)

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://api.portkey.ai/v1",
    defaultHeaders: {
        "x-portkey-provider": "mistral-ai",
        "x-portkey-custom-host": "http://MODEL_URL/v1/"
    }
});

const response = await client.chat.completions.create({
    model: "mixtral-8x22b",
    messages: [{ role: "user", content: "Hello" }]
});

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: mistral-ai" \
  -H "x-portkey-custom-host: http://MODEL_URL/v1/" \
  -d '{"model": "mixtral-8x22b", "messages": [{"role": "user", "content": "Hello"}]}'

Include the version identifier (e.g., /v1) in the custom_host URL. Portkey appends the endpoint path (/chat/completions, /responses, etc.) automatically. For Ollama, see the Ollama integration.

Portkey blocks requests to private and reserved IP ranges by default to prevent SSRF attacks. If you need to route to a private network IP, see Custom hosts for the full list of blocked patterns and how to allowlist specific hosts.

Supported Endpoints

Core Endpoints

Chat Completions — OpenAI-compatible text generation with streaming, function calling, and multimodal inputs
Responses API — Next-gen format with built-in tool use and reasoning
Messages API — Anthropic-compatible endpoint across all providers
Images — Generate, edit, and create image variations (DALL-E, gpt-image-1, Stable Diffusion)
Audio — Speech-to-text and text-to-speech

Advanced Capabilities

Fine-tuning — Customize models on specific datasets
Batch Processing — Process large request volumes efficiently
Files — Upload and manage files for fine-tuning and batch operations
Moderations — Content safety and compliance checks

Additional Endpoints

Gateway to Other APIs — Proxy requests to any provider endpoint
Assistants API — OpenAI Assistants with persistent threads
Completions — Legacy text completion endpoint

Multimodal Capabilities

Multimodal inputs work across all three API formats:

Vision — Image understanding across providers
Function Calling — Tool use and function calling
Image Generation — Text-to-image generation
Speech-to-Text — Audio transcription
Text-to-Speech — Audio generation
Thinking / Reasoning — Extended reasoning modes

Not all providers support every endpoint or modality. See the provider compatibility matrix for details.

​Three API Formats, Any Provider

Chat Completions

Responses API

Messages API

​Chat Completions — POST /v1/chat/completions

​Responses API — POST /v1/responses

​Messages API — POST /v1/messages

​Switching Providers

​Routing, Fallbacks, and Load Balancing

​Local and Private Models

​Supported Endpoints

​Core Endpoints

​Advanced Capabilities

​Additional Endpoints

​Multimodal Capabilities

Three API Formats, Any Provider

Chat Completions — `POST /v1/chat/completions`

Responses API — `POST /v1/responses`

Messages API — `POST /v1/messages`

Switching Providers

Routing, Fallbacks, and Load Balancing

Local and Private Models

Supported Endpoints

Core Endpoints

Advanced Capabilities

Additional Endpoints

Multimodal Capabilities