Chat Completions (Gateway)

Create chat completions via the AI Gateway

POST /v1/chat/completions

Try it

cURL

curl https://ai-gateway.helicone.ai/v1/chat/completions \
  -H "Authorization: Bearer $HELICONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Say hello in one sentence." }
    ]
  }'

This request schema applies when using the Helicone AI Gateway with pass‑through billing (credits). In BYOK mode, the standard OpenAI Chat Completions schema is allowed. The schema is defined based on fields that are stable across all provider-model mappings.

Learn more about pass‑through billing vs BYOK.

cURL

curl https://ai-gateway.helicone.ai/v1/chat/completions \
  -H "Authorization: Bearer $HELICONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Say hello in one sentence." }
    ]
  }'

Body

application/json

messages · object[] · required

Minimum array length: 1

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

messages. content · required

messages. role · enum<string> · required

Available options: developer

messages. name · string

model · string · required

metadata

Show child attributes

metadata. {key} · any

top_logprobs · integer | null

Required range: 0 <= x <= 20

temperature

top_p

user · string

safety_identifier · string

prompt_cache_key · string

cache_control · object

Show child attributes

cache_control. type · enum<string>

Available options: ephemeral

cache_control. ttl · string

service_tier

Available options: auto, default, flex, scale, priority

modalities

Available options: text

verbosity

Available options: low, medium, high

reasoning_effort

Available options: minimal, low, medium, high

max_completion_tokens · integer | null

Required range: -9007199254740991 <= x <= 9007199254740991

frequency_penalty · number | null · default: 0

Required range: -2 <= x <= 2

presence_penalty · number | null · default: 0

Required range: -2 <= x <= 2

response_format · object

Option 1

Option 2

Option 3

Show child attributes

response_format. type · enum<string> · required

Available options: text

store · boolean | null · default: false

stream · boolean | null · default: false

stop

logit_bias · object

Show child attributes

logit_bias. {key} · integer

Required range: -9007199254740991 <= x <= 9007199254740991

logprobs · boolean | null · default: false

max_tokens · integer | null

Required range: -9007199254740991 <= x <= 9007199254740991

n · integer | null · default: 1

Required range: 1 <= x <= 128

prediction · object

Show child attributes

prediction. type · enum<string> · required

Available options: content

prediction. content · required

seed · integer | null

Required range: -9007199254740991 <= x <= 9007199254740991

stream_options

Show child attributes

stream_options. include_usage · boolean

stream_options. include_obfuscation · boolean

tools · object[]

Option 1

Option 2

Show child attributes

tools. type · enum<string> · required

Available options: function

tools. function · object · required

Show child attributes

tools.function. name · string · required

tools.function. description · string

tools.function. parameters · object

tools.function. strict

tool_choice

Available options: none, auto, required

parallel_tool_calls · boolean · default: true

function_call

Available options: none, auto

functions · object[]

Required array length: 1 - 128 elements

Show child attributes

functions. name · string · required

functions. description · string

functions. parameters · object

Response

200

Request accepted