Skip to main content

​
Endpoint

POST /v1/chat/completions
Creates a completion for the chat conversation using the specified model.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json
​
x-portkey-provider
string
required
The AI provider to use (e.g., openai, anthropic, google)
​
x-portkey-api-key
string
required
Your API key for the specified provider
​
x-portkey-config
string
Optional JSON config for routing, fallbacks, and guardrails

​
Body Parameters

​
model
string
required
The model to use for completion (e.g., gpt-4o-mini, claude-3-5-sonnet-20241022)
​
messages
array
required
Array of message objects with role and content
[
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Hello!"}
]
​
temperature
number
default:1
Sampling temperature between 0 and 2. Higher values make output more random.
​
max_tokens
integer
Maximum number of tokens to generate
​
top_p
number
default:1
Nucleus sampling parameter. Alternative to temperature.
​
stream
boolean
default:false
Whether to stream the response
​
stop
string | array
Up to 4 sequences where the API will stop generating
​
presence_penalty
number
default:0
Penalty for token presence (-2.0 to 2.0)
​
frequency_penalty
number
default:0
Penalty for token frequency (-2.0 to 2.0)
​
n
integer
default:1
Number of completions to generate
​
user
string
Unique identifier for the end-user
​
tools
array
List of tools the model can call
​
tool_choice
string | object
Controls which tool the model should use
​
response_format
object
Format of the response (e.g., {"type": "json_object"})
​
seed
integer
Seed for deterministic sampling

​
Response

​
id
string
Unique identifier for the completion
​
object
string
Object type, always chat.completion
​
created
integer
Unix timestamp of creation
​
model
string
The model used for completion
​
choices
array
Array of completion choices
​
index
integer
Choice index
​
message
object
The generated message
​
role
string
Role of the message author (always assistant)
​
content
string
The message content
​
tool_calls
array
Tool calls made by the model
​
finish_reason
string
Reason for completion: stop, length, tool_calls, or content_filter
​
usage
object
Token usage information
​
prompt_tokens
integer
Number of tokens in the prompt
​
completion_tokens
integer
Number of tokens in the completion
​
total_tokens
integer
Total tokens used

​
Examples

​
Basic Request

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-api-key: sk-..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

​
Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

​
Using Python SDK

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-..."
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

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

​
Using JavaScript SDK

import Portkey from 'portkey-ai';

const client = new Portkey({
  provider: 'openai',
  Authorization: 'sk-...'
});

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    {role: 'system', content: 'You are a helpful assistant.'},
    {role: 'user', content: 'What is the capital of France?'}
  ]
});

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

​
With Function Calling

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-api-key: sk-..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is the weather in Boston?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather in a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
          },
          "required": ["location"]
        }
      }
    }]
  }'

​
With JSON Mode

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-api-key: sk-..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{
      "role": "user",
      "content": "Extract the name and age: John is 30 years old"
    }],
    "response_format": {"type": "json_object"}
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us