Skip to main content
The Portkey AI Gateway exposes an OpenAI-compatible REST API. You can point any OpenAI SDK or HTTP client at the gateway and route requests to any supported provider by adding a few extra headers.

​
Base URL

http://localhost:8787/v1
When running locally with npx @portkey-ai/gateway, the gateway listens on http://localhost:8787/v1. The console UI is available at http://localhost:8787/public/.

​
Request requirements

Every request must include either:
  • x-portkey-provider — to route directly to a single provider, or
  • x-portkey-config — to use a routing config (fallback, load balancing, guardrails, etc.)
See Authentication and Headers for details.

​
Endpoints

MethodPathDescription
POST/v1/chat/completionsChat completions (OpenAI-compatible). Supports streaming.
POST/v1/completionsLegacy text completions.
POST/v1/embeddingsGenerate text embeddings.
POST/v1/messagesAnthropic Messages API format.
POST/v1/messages/count_tokensCount tokens for an Anthropic request without generating a response.
POST/v1/images/generationsGenerate images from a text prompt.
POST/v1/images/editsEdit an existing image with a text prompt.
POST/v1/audio/speechText-to-speech synthesis.
POST/v1/audio/transcriptionsSpeech-to-text transcription (multipart/form-data).
POST/v1/audio/translationsTranslate audio to English text (multipart/form-data).
GET/v1/modelsList available models for a provider.
GET/v1/filesList uploaded files.
POST/v1/filesUpload a file.
GET/v1/files/:idRetrieve file metadata.
GET/v1/files/:id/contentDownload file content.
DELETE/v1/files/:idDelete a file.
POST/v1/batchesCreate a batch job.
GET/v1/batchesList batch jobs.
GET/v1/batches/:idRetrieve a batch job.
GET/v1/batches/*/outputGet batch job output.
POST/v1/batches/:id/cancelCancel a batch job.
POST/v1/responsesCreate a model response (Responses API).
GET/v1/responses/:idRetrieve a model response.
DELETE/v1/responses/:idDelete a model response.
GET/v1/responses/:id/input_itemsList input items for a response.
GET, POST/v1/fine_tuning/jobsList or create fine-tuning jobs.
GET, POST/v1/fine_tuning/jobs/:jobIdRetrieve or manage a fine-tuning job.
GET/v1/realtimeWebSocket endpoint for real-time streaming (Cloudflare Workers runtime only).

​
OpenAI compatibility

The gateway is a drop-in replacement for the OpenAI API base URL. To migrate an existing OpenAI integration:
  1. Change the base URL to http://localhost:8787/v1 (local) or your deployed gateway URL.
  2. Add the x-portkey-provider header to specify which provider to route to.
  3. Add an Authorization header with the provider API key.
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8787/v1",
    api_key="ignore",  # not used by the gateway directly
    default_headers={
        "x-portkey-provider": "openai",
        "Authorization": "Bearer sk-...",
    },
)

​
Provider passthrough

For endpoints not explicitly handled by the gateway, requests to /v1/* are forwarded directly to the configured provider. This enables access to provider-specific endpoints beyond the standard OpenAI surface.

Build docs developers (and LLMs) love

Get started for freeTalk to us