Python client library for the Portkey API
Project Links
Meta
Author: Portkey.ai
Requires Python: >=3.8
Classifiers
Programming Language
- Python :: 3
Operating System
- OS Independent
Control Panel for AI Apps
pip install portkey-ai
Features
The Portkey SDK is built on top of the OpenAI SDK, allowing you to seamlessly integrate Portkey's advanced features while retaining full compatibility with OpenAI methods. With Portkey, you can enhance your interactions with OpenAI or any other OpenAI-like provider by leveraging robust monitoring, reliability, prompt management, and more features - without modifying much of your existing code.
AI Gateway
| Unified API Signature If you've used OpenAI, you already know how to use Portkey with any other provider. |
Interoperability Write once, run with any provider. Switch between any model from_any provider seamlessly. |
| Automated Fallbacks & Retries Ensure your application remains functional even if a primary service fails. |
Load Balancing Efficiently distribute incoming requests among multiple models. |
| Semantic Caching Reduce costs and latency by intelligently caching results. |
Virtual Keys Secure your LLM API keys by storing them in Portkey vault and using disposable virtual keys. |
| Request Timeouts Manage unpredictable LLM latencies effectively by setting custom request timeouts on requests. |
Observability
| Logging Keep track of all requests for monitoring and debugging. |
Requests Tracing Understand the journey of each request for optimization. |
| Custom Metadata Segment and categorize requests for better insights. |
Feedbacks Collect and analyse weighted feedback on requests from users. |
| Analytics Track your app & LLM's performance with 40+ production-critical metrics in a single place. |
Usage
Prerequisites
- Sign up on Portkey and grab your Portkey API Key
- Add your OpenAI key to Portkey's Virtual Keys page and keep it handy
# Installing the SDK
$ pip install portkey-ai
$ export PORTKEY_API_KEY=PORTKEY_API_KEY
Making a Request to OpenAI
- Portkey fully adheres to the OpenAI SDK signature. You can instantly switch to Portkey and start using our production features right out of the box.
- Just replace
from openai import OpenAIwithfrom portkey_ai import Portkey:
from portkey_ai import Portkey
portkey = Portkey(
api_key="PORTKEY_API_KEY",
virtual_key="VIRTUAL_KEY"
)
chat_completion = portkey.chat.completions.create(
messages = [{ "role": 'user', "content": 'Say this is a test' }],
model = 'gpt-4'
)
print(chat_completion)
Async Usage
- Use
AsyncPortkeyinstead ofPortkeywithawait:
import asyncio
from portkey_ai import AsyncPortkey
portkey = AsyncPortkey(
api_key="PORTKEY_API_KEY",
virtual_key="VIRTUAL_KEY"
)
async def main():
chat_completion = await portkey.chat.completions.create(
messages=[{'role': 'user', 'content': 'Say this is a test'}],
model='gpt-4'
)
print(chat_completion)
asyncio.run(main())
Strands Agents Integration (optional)
Installation:
pip install 'portkey-ai[strands]'
Usage with Strands:
from strands.agent import Agent
from portkey_ai.integrations.strands import PortkeyStrands
model = PortkeyStrands(
api_key="PORTKEY_API_KEY",
model_id="@openai/gpt-4o-mini",
# base_url="https://api.portkey.ai/v1", ## Optional
)
agent = Agent(model=model)
import asyncio
async def main():
result = await agent.invoke_async("Tell me a short programming joke.")
print(getattr(result, "text", result))
asyncio.run(main())
Google ADK Integration (optional)
Installation:
pip install 'portkey-ai[adk]'
Usage with ADK:
import asyncio
from google.adk.models.llm_request import LlmRequest
from google.genai import types
from portkey_ai.integrations.adk import PortkeyAdk
llm = PortkeyAdk(
api_key="PORTKEY_API_KEY",
model="@openai/gpt-4o-mini",
# base_url="https://api.portkey.ai/v1", ## Optional
)
req = LlmRequest(
model="@openai/gpt-4o-mini",
contents=[
types.Content(
role="user",
parts=[types.Part.from_text(text="Tell me a short programming joke.")],
)
],
)
async def main():
# Print only partial chunks to avoid duplicate final output
async for resp in llm.generate_content_async(req, stream=True):
if getattr(resp, "partial", False) and resp.content and resp.content.parts:
for p in resp.content.parts:
if getattr(p, "text", None):
print(p.text, end="")
print()
asyncio.run(main())
Non-streaming example (single final response):
import asyncio
from google.adk.models.llm_request import LlmRequest
from google.genai import types
from portkey_ai.integrations.adk import PortkeyAdk
llm = PortkeyAdk(
api_key="PORTKEY_API_KEY",
model="@openai/gpt-4o-mini",
)
req = LlmRequest(
model="@openai/gpt-4o-mini",
contents=[
types.Content(
role="user",
parts=[types.Part.from_text(text="Give me a one-line programming joke (final only).")],
)
],
)
async def main():
final_text = []
async for resp in llm.generate_content_async(req, stream=False):
if resp.content and resp.content.parts:
for p in resp.content.parts:
if getattr(p, "text", None):
final_text.append(p.text)
print("".join(final_text))
asyncio.run(main())
Configuration notes:
-
system_role: By default, the adapter sends the system instruction as a
developerrole message to align with ADK. If your provider expects a strictsystemrole, passsystem_role="system"when constructingPortkeyAdk.llm = PortkeyAdk( model="@openai/gpt-4o-mini", api_key="PORTKEY_API_KEY", system_role="system", # switch from default "developer" )
-
Tools: When tools are present in the ADK request, the adapter sets
tool_choice="auto"to enable function calling by default (mirrors the Strands adapter behavior).
Compatibility with OpenAI SDK
Portkey currently supports all the OpenAI methods, including the legacy ones.
| Methods | OpenAI V1.26.0 |
Portkey V1.3.1 |
|---|---|---|
| Audio | ✅ | ✅ |
| Chat | ✅ | ✅ |
| Embeddings | ✅ | ✅ |
| Images | ✅ | ✅ |
| Fine-tuning | ✅ | ✅ |
| Batch | ✅ | ✅ |
| Files | ✅ | ✅ |
| Models | ✅ | ✅ |
| Moderations | ✅ | ✅ |
| Assistants | ✅ | ✅ |
| Threads | ✅ | ✅ |
| Thread - Messages | ✅ | ✅ |
| Thread - Runs | ✅ | ✅ |
| Thread - Run - Steps | ✅ | ✅ |
| Vector Store | ✅ | ✅ |
| Vector Store - Files | ✅ | ✅ |
| Vector Store - Files Batches | ✅ | ✅ |
| Generations | ❌ (Deprecated) | ✅ |
| Completions | ❌ (Deprecated) | ✅ |
Portkey-Specific Methods
| Methods | Portkey V1.3.1 |
|---|---|
| Feedback | ✅ |
| Prompts | ✅ |
Check out Portkey docs for the full list of supported providers
Contributing
Get started by checking out Github issues. Email us at support@portkey.ai or just ping on Discord to chat.
2.2.0
Feb 16, 2026
2.1.0
Nov 25, 2025
2.0.4
Nov 13, 2025
2.0.3
Nov 05, 2025
2.0.2
Oct 22, 2025
2.0.1
Oct 21, 2025
2.0.0
Oct 14, 2025
1.15.1
Sep 22, 2025
1.15.0
Sep 17, 2025
1.14.4
Aug 29, 2025
1.14.3
Jul 27, 2025
1.14.2
Jul 23, 2025
1.14.1
Jul 11, 2025
1.14.0
Jun 18, 2025
1.13.0
May 26, 2025
1.13.0rc1
May 20, 2025
1.12.4rc1
May 14, 2025
1.12.3
May 13, 2025
1.12.2
Apr 24, 2025
1.12.1
Apr 24, 2025
1.12.0
Apr 07, 2025
1.11.2
Mar 27, 2025
1.11.1
Mar 06, 2025
1.11.0
Feb 28, 2025
1.10.5
Feb 27, 2025
1.10.4
Feb 24, 2025
1.10.3
Feb 19, 2025
1.10.2
Jan 29, 2025
1.10.1
Jan 09, 2025
1.10.0
Jan 03, 2025
1.9.10
Dec 26, 2024
1.9.9
Dec 11, 2024
1.9.8
Dec 05, 2024
1.9.7
Nov 29, 2024
1.9.6
Nov 26, 2024
1.9.5
Nov 21, 2024
1.9.4
Nov 07, 2024
1.9.3
Oct 22, 2024
1.9.2
Oct 18, 2024
1.9.1
Oct 09, 2024
1.9.0
Oct 08, 2024
1.8.7
Sep 04, 2024
1.8.6
Aug 31, 2024
1.8.5
Aug 28, 2024
1.8.4
Aug 26, 2024
1.8.3
Aug 23, 2024
1.8.2
Aug 16, 2024
1.8.1
Aug 13, 2024
1.8.0
Aug 12, 2024
1.7.2
Jul 31, 2024
1.7.1
Jul 25, 2024
1.7.1rc1
Jul 25, 2024
1.7.0
Jul 03, 2024
1.7.0rc1
Jul 03, 2024
1.6.0
Jun 28, 2024
1.5.1
Jun 26, 2024
1.5.0
Jun 22, 2024
1.4.1
Jun 18, 2024
1.4.0
Jun 06, 2024
1.3.2
Jun 01, 2024
1.3.1
May 31, 2024
1.3.0
May 31, 2024
1.2.4
Apr 13, 2024
1.2.3
Apr 05, 2024
1.2.2
Mar 23, 2024
1.2.1
Mar 22, 2024
1.2.0
Mar 21, 2024
1.1.7
Feb 13, 2024
1.1.6
Feb 02, 2024
1.1.5
Jan 24, 2024
1.1.4
Jan 17, 2024
1.1.3
Jan 12, 2024
1.1.2
Jan 09, 2024
1.1.1
Jan 08, 2024
1.1.0
Jan 02, 2024
1.0.1
Jan 02, 2024
1.0.0
Dec 08, 2023
0.1.53
Oct 10, 2023
0.1.52
Sep 21, 2023
0.1.51
Sep 20, 2023
0.1.50
Sep 19, 2023
0.1.49
Sep 16, 2023
0.1.48
Sep 14, 2023
0.1.47
Sep 13, 2023
0.1.46
Sep 13, 2023
0.1.45
Sep 12, 2023
0.1.44
Sep 11, 2023
0.1.43
Sep 11, 2023
0.1.42
Sep 11, 2023
0.1.41
Sep 11, 2023
0.1.40
Sep 11, 2023
0.1.39
Sep 09, 2023
0.1.38
Sep 09, 2023
0.1.37
Sep 09, 2023
0.1.36
Sep 09, 2023
0.1.35
Sep 09, 2023
0.1.34
Sep 09, 2023
0.1.32
Sep 09, 2023
0.1.31
Sep 07, 2023
0.1.30
Sep 07, 2023
0.1.29
Sep 07, 2023
0.1.28
Sep 06, 2023
0.1.27
Sep 05, 2023
