Create Chat Completion

POST /v1/chat/completions - Generate chat completions

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"}
  }'