{"id":6034,"library":"portkey-ai","title":"Portkey.ai Python Client","description":"The Portkey.ai Python client library provides an interface to the Portkey API, a unified AI gateway for managing, monitoring, and routing large language model (LLM) requests. It offers features like observability, caching, load balancing, and prompt management across various LLM providers. The library is actively maintained, with frequent updates.","status":"active","version":"2.2.0","language":"python","source_language":"en","source_url":"https://github.com/Portkey-AI/portkey-python-sdk","tags":["AI","LLM","API Gateway","Observability","Prompt Management"],"install":[{"cmd":"pip install portkey-ai","lang":"bash","label":"Install core library"}],"dependencies":[],"imports":[{"note":"The primary synchronous client class is `Portkey`, imported directly from the `portkey_ai` package.","wrong":"import portkey_ai","symbol":"Portkey","correct":"from portkey_ai import Portkey"},{"note":"For asynchronous operations, `AsyncPortkey` is available.","symbol":"AsyncPortkey","correct":"from portkey_ai import AsyncPortkey"}],"quickstart":{"code":"import os\nfrom portkey_ai import Portkey\n\n# Set your Portkey API key as an environment variable: export PORTKEY_API_KEY=\"pk-sk-...\"\n# If using a direct provider (e.g., OpenAI) without Portkey Virtual Keys,\n# you might also need its API key, e.g.: export OPENAI_API_KEY=\"sk-...\"\n\nportkey_client = Portkey(\n    api_key=os.environ.get('PORTKEY_API_KEY', ''),\n    # Use a provider slug from your Portkey Model Catalog\n    # e.g., \"@openai-prod\" if configured in Portkey\n    provider=\"@openai-prod\"\n)\n\ntry:\n    response = portkey_client.chat.completions.create(\n        messages=[\n            {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n        ],\n        # Model name configured under the \"@openai-prod\" provider in Portkey\n        model=\"gpt-4o\"\n    )\n    print(response.choices[0].message.content)\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"Initializes the Portkey client using the `PORTKEY_API_KEY` environment variable and directs requests through a configured provider slug (e.g., `@openai-prod`). It then makes a chat completion request using a model available via that provider."},"warnings":[{"fix":"Review the Portkey and OpenAI SDK changelogs for relevant updates. Test existing integrations thoroughly after upgrading to v2.0.0 or later. Consult Portkey documentation for updated usage patterns, especially for advanced configurations or when directly interacting with vendored client internals.","message":"Major version 2.0.0 introduced significant internal changes, including vendoring a specific version of the OpenAI SDK. While Portkey aims for compatibility, direct dependencies or specific behaviors of the underlying OpenAI client might have changed. This could require adjustments for complex integrations that rely on specific OpenAI client versions or internal workings.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `PORTKEY_API_KEY` is set for the `Portkey` client. Manage LLM provider keys via Portkey's dashboard (recommended) and use provider slugs (e.g., `@openai-prod`) or `config` objects. Alternatively, provide provider-specific `Authorization` headers to the `Portkey` client for direct pass-through of provider keys.","message":"Portkey utilizes its own `PORTKEY_API_KEY` for authenticating with the Portkey gateway. Separately, your actual LLM provider API keys (e.g., OpenAI, Anthropic) must be configured within Portkey's 'Virtual Keys' or 'Model Catalog' dashboard, or provided via the `Authorization` parameter in the `Portkey` client constructor. Simply passing a provider's API key to `Portkey(api_key=\"...\")` is incorrect for LLM provider authentication.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the full `@provider-slug/model-name` format for the `model` parameter when using the `provider` argument in the client constructor. Alternatively, define a `config` object for the `Portkey` client that specifies the desired routing strategy and provider details. Refer to the Portkey Model Catalog documentation for valid provider slugs and model names.","message":"When using the `provider` parameter, Portkey often expects models to be specified in a `@provider-slug/model-name` format (e.g., `@openai-prod/gpt-4o`). Simply providing `model=\"gpt-4o\"` without the appropriate provider slug prefix, or without a `config` object defining the routing, may lead to errors or incorrect routing.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'across':41 'activ':48 'ai':18,53 'api':15,55 'balanc':37 'cach':35 'client':3,7 'featur':32 'frequent':51 'gateway':19,56 'interfac':11 'languag':26 'larg':25 'librari':8,46 'like':33 'llm':28,43,54 'load':36 'maintain':49 'manag':21,40,59 'model':27 'monitor':22 'observ':34,57 'offer':31 'portkey':14 'portkey.ai':1,5 'prompt':39,58 'provid':9,44 'python':2,6 'request':29 'rout':24 'unifi':17 'updat':52 'various':42","created_at":"2026-04-14T18:39:05.390303+00:00","updated_at":"2026-04-16T18:07:09.832798+00:00","problems":[{"fix":"Ensure the PORTKEY_API_KEY environment variable is set correctly with an active API key from your Portkey dashboard, or pass it directly to the Portkey client constructor.","cause":"Your Portkey API key is either missing, invalid, or expired, preventing authentication with the Portkey gateway.","error":"Error: Unauthorized (401) / Incorrect API key provided"},{"fix":"Set the appropriate provider API key (e.g., OPENAI_API_KEY) in your environment variables, configure it as a virtual key in the Portkey dashboard, or pass it via `Authorization` header in the Portkey client.","cause":"The API key for the underlying Large Language Model (LLM) provider (e.g., OpenAI, Anthropic) is not configured in Portkey or passed in the request.","error":"Error: Missing API key for provider"},{"fix":"Include either the `x-portkey-config` header with your configuration slug or the `x-portkey-provider` header with the target provider slug in your API request.","cause":"When using Portkey as a gateway, the request is missing mandatory headers that specify which Portkey configuration or provider to route the request through.","error":"Either x-portkey-config or x-portkey-provider header is required"},{"fix":"Verify the model name against the Portkey model catalog or the provider's documentation, and ensure your Portkey configuration or provider settings allow access to that model.","cause":"The model name provided in the request is incorrect, not available for your account through Portkey, or the underlying provider does not support it.","error":"Error: Model not supported / The specified model does not exist or access is restricted."},{"fix":"Implement retry logic with exponential backoff, use Portkey's built-in rate limit management features, or check your usage and limits on the Portkey dashboard and the LLM provider's platform.","cause":"You have exceeded the allowed number of requests to the LLM provider or the Portkey gateway within a given time frame.","error":"Error: Rate limit exceeded."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.3.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://portkey.ai","github":"https://github.com/Portkey-AI/portkey-python-sdk","docs":null,"changelog":null,"pypi":"https://pypi.org/project/portkey-ai/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}