Chat Completions (Gateway)

Create chat completions via the AI Gateway

1 min read

post/v1/chat/completions

Request example

curl --request POST \
  --url https://ai-gateway.helicone.ai/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "top_logprobs": 0,
  "temperature": 1,
  "top_p": 1,
  "top_k": 1,
  "user": "<string>",
  "safety_identifier": "<string>",
  "prompt_cache_key": "<string>",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "<string>"
  },
  "service_tier": "auto",
  "messages": [
    {
      "content": "<string>",
      "role": "developer",
      "name": "<string>"
    }
  ],
  "model": "<string>",
  "modalities": [
    "text"
  ],
  "verbosity": "low",
  "reasoning_effort": "minimal",
  "reasoning_options": {
    "budget_tokens": -9007199254740991
  },
  "max_completion_tokens": -9007199254740991,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "response_format": {
    "type": "text"
  },
  "store": false,
  "stream": false,
  "stop": "<string>",
  "logit_bias": null,
  "logprobs": false,
  "max_tokens": -9007199254740991,
  "n": 1,
  "prediction": {
    "type": "content",
    "content": "<string>",
    "reasoning": "<string>"
  },
  "seed": -9007199254740991,
  "stream_options": {
    "include_usage": true,
    "include_obfuscation": true
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "description": "<string>",
        "name": "<string>",
        "parameters": {},
        "strict": true
      }
    }
  ],
  "tool_choice": "none",
  "parallel_tool_calls": true,
  "function_call": "none",
  "functions": [
    {
      "description": "<string>",
      "name": "<string>",
      "parameters": {}
    }
  ],
  "context_editing": {
    "enabled": true,
    "clear_tool_uses": {
      "trigger": -9007199254740991,
      "keep": -9007199254740991,
      "clear_at_least": -9007199254740991,
      "exclude_tools": [
        "<string>"
      ],
      "clear_tool_inputs": true
    },
    "clear_thinking": {
      "keep": -9007199254740991
    }
  },
  "image_generation": {
    "aspect_ratio": "<string>",
    "image_size": "<string>"
  }
}'

post/v1/chat/completions

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 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

metadataobject · enum<string>#

Show child attributes

Any of

{key}any#

top_logprobsinteger#

Range: 0–20

temperaturenumber · enum<string>#

Show child attributes

Any of

top_pnumber · enum<string>#

Show child attributes

Any of

top_knumber · enum<string>#

Show child attributes

Any of

userstring#

safety_identifierstring#

prompt_cache_keystring#

cache_controlobject#

Show child attributes

typeenum<string>#

Options:ephemeral

ttlstring#

service_tierenum<string>#

Show child attributes

Any of

messagesobject[]required#

Items: min 1

Show child attributes

Any of

contentstring · object[]required#

Show child attributes

roleenum<string>required#

Options:developer

namestring#

contentstring · object[]required#

Show child attributes

roleenum<string>required#

Options:system

namestring#

contentstring · object[]required#

Show child attributes

roleenum<string>required#

Options:user

namestring#

contentstring · object[] · enum<string>#

Show child attributes

refusalstring · enum<string>#

Show child attributes

roleenum<string>required#

Options:assistant

namestring#

audioobject · enum<string>#

Show child attributes

tool_callsobject[]#

Show child attributes

function_callobject · enum<string>#

Show child attributes

roleenum<string>required#

Options:tool

contentstring · object[]required#

Show child attributes

tool_call_idstringrequired#

roleenum<string>required#

Options:function

contentstring · enum<string>required#

Show child attributes

namestringrequired#

modelstringrequired#

modalitiesenum<string>[] · enum<string>#

Show child attributes

Any of

verbosityenum<string>#

Show child attributes

Any of

reasoning_effortenum<string>#

Show child attributes

Any of

reasoning_optionsobject#

Show child attributes

budget_tokensintegerrequired#

Range: -9007199254740991–9007199254740991

max_completion_tokensinteger#

Range: -9007199254740991–9007199254740991

frequency_penaltynumber#

Default: 0

Range: -2–2

presence_penaltynumber#

Default: 0

Range: -2–2

response_formatobject#

Show child attributes

Any of

typeenum<string>required#

Options:text

typeenum<string>required#

Options:json_schema

json_schemaobjectrequired#

Show child attributes

descriptionstring#

namestringrequired#

schemaobject#

strictboolean · enum<string>#

Show child attributes

Any of

typeenum<string>required#

Options:json_object

storeboolean#

Default: false

streamboolean#

Default: false

stopstring · string[]#

Show child attributes

Any of

logit_biasobject#

Default: null

Show child attributes

{key}integer#

Range: -9007199254740991–9007199254740991

logprobsboolean#

Default: false

max_tokensinteger#

Range: -9007199254740991–9007199254740991

ninteger#

Default: 1

Range: 1–128

predictionobject#

Show child attributes

typeenum<string>required#

Options:content

contentstring · object[]required#

Show child attributes

Any of

typeenum<string>required#

Options:text

textstringrequired#

reasoningstring#

seedinteger#

Range: -9007199254740991–9007199254740991

stream_optionsobject · enum<string>#

Show child attributes

Any of

include_usageboolean#

include_obfuscationboolean#

toolsobject[]#

Show child attributes

Any of

typeenum<string>required#

Options:function

functionobjectrequired#

Show child attributes

descriptionstring#

namestringrequired#

parametersobject#

strictboolean · enum<string>#

Show child attributes

typeenum<string>required#

Options:custom

customobjectrequired#

Show child attributes

namestringrequired#

descriptionstring#

formatobject#

Show child attributes

tool_choiceenum<string> · object#

Show child attributes

Any of

typeenum<string>required#

Options:allowed_tools

allowed_toolsobjectrequired#

Show child attributes

modeenum<string>required#

Options:autorequired

toolsobject[]required#

typeenum<string>required#

Options:function

functionobjectrequired#

Show child attributes

namestringrequired#

typeenum<string>required#

Options:custom

customobjectrequired#

Show child attributes

namestringrequired#

parallel_tool_callsboolean#

Default: true

function_callenum<string> · object#

Show child attributes

Any of

functionsobject[]#

Items: 1–128

Show child attributes

descriptionstring#

namestringrequired#

parametersobject#

context_editingobject#

Show child attributes

enabledbooleanrequired#

clear_tool_usesobject#

Show child attributes

triggerinteger#

Range: -9007199254740991–9007199254740991

keepinteger#

Range: -9007199254740991–9007199254740991

clear_at_leastinteger#

Range: -9007199254740991–9007199254740991

exclude_toolsstring[]#

clear_tool_inputsboolean#

clear_thinkingobject#

Show child attributes

keepinteger · enum<string>#

Show child attributes

Any of

image_generationobject#

Show child attributes

aspect_ratiostringrequired#

image_sizestringrequired#

Responses

200

Request accepted

Responses