Responses (Gateway)

Create responses via the AI Gateway

1 min read

post/v1/responses

Request example

curl --request POST \
  --url https://ai-gateway.helicone.ai/v1/responses \
  --header 'Content-Type: application/json' \
  --data '{
  "top_logprobs": 0,
  "top_k": 1,
  "temperature": 1,
  "top_p": 1,
  "user": "<string>",
  "safety_identifier": "<string>",
  "prompt_cache_key": "<string>",
  "service_tier": "auto",
  "model": "<string>",
  "reasoning": {
    "effort": "minimal",
    "summary": "auto",
    "generate_summary": "auto"
  },
  "reasoning_options": {
    "budget_tokens": -9007199254740991
  },
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tools": [
    {
      "type": "function",
      "name": "<string>",
      "description": "<string>",
      "parameters": {},
      "strict": true
    }
  ],
  "tool_choice": "none",
  "truncation": "auto",
  "input": "<string>",
  "include": [
    "message.input_image.image_url"
  ],
  "parallel_tool_calls": true,
  "instructions": "<string>",
  "stream": true,
  "stream_options": {
    "include_obfuscation": true
  },
  "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/responses

This request schema applies when using the Helicone AI Gateway with pass‑through billing (credits). In BYOK mode, the standard OpenAI Responses API 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/responses \  -H "Authorization: Bearer $HELICONE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-4o-mini",    "input": "Say hello in one sentence."  }'

Body

application/json

top_logprobsinteger#

Range: 0–20

top_knumber · enum<string>#

Show child attributes

Any of

temperaturenumber · enum<string>#

Show child attributes

Any of

top_pnumber · enum<string>#

Show child attributes

Any of

userstring#

safety_identifierstring#

prompt_cache_keystring#

service_tierenum<string>#

Show child attributes

Any of

modelstring#

Show child attributes

Any of

reasoningobject · enum<string>#

Show child attributes

Any of

effortenum<string>#

Show child attributes

Any of

summaryenum<string>#

Show child attributes

Any of

generate_summaryenum<string>#

Show child attributes

Any of

reasoning_optionsobject#

Show child attributes

budget_tokensinteger#

Range: -9007199254740991–9007199254740991

max_output_tokensnumber · enum<string>#

Show child attributes

Any of

max_tool_callsnumber · enum<string>#

Show child attributes

Any of

textobject#

Show child attributes

formatobject#

Show child attributes

Any of

typeenum<string>required#

Options:text

typeenum<string>required#

Options:json_schema

descriptionstring#

namestringrequired#

schemaobjectrequired#

strictboolean · enum<string>#

Show child attributes

Any of

typeenum<string>required#

Options:json_object

verbosityenum<string>#

Show child attributes

Any of

toolsobject[]#

Show child attributes

Any of

typeenum<string>#

Default: "function"

Options:function

namestringrequired#

descriptionstring · enum<string>#

Show child attributes

parametersobject · enum<string>required#

Show child attributes

strictboolean · enum<string>#

Show child attributes

typeenum<string>required#

Options:mcp

server_labelstringrequired#

server_urlstring#

connector_idenum<string>#

Options:connector_dropboxconnector_gmailconnector_googlecalendarconnector_googledriveconnector_microsoftteamsconnector_outlookcalendarconnector_outlookemailconnector_sharepoint

authorizationstring#

server_descriptionstring#

headersobject · enum<string>#

Show child attributes

allowed_toolsstring[] · object · enum<string>#

Show child attributes

require_approvalobject · enum<string> · enum<string>#

Show child attributes

typeenum<string>required#

Options:code_interpreter

containerstring · objectrequired#

Show child attributes

typeenum<string>required#

Options:image_generation

modelenum<string>#

Default: "gpt-image-1"

Options:gpt-image-1gpt-image-1-mini

qualityenum<string>#

Default: "auto"

Options:lowmediumhighauto

sizeenum<string>#

Default: "auto"

Options:1024x10241024x15361536x1024auto

output_formatenum<string>#

Default: "png"

Options:pngwebpjpeg

output_compressioninteger#

Default: 100

Range: 0–100

moderationenum<string>#

Default: "auto"

Options:autolow

backgroundenum<string>#

Default: "auto"

Options:transparentopaqueauto

input_fidelityenum<string>#

Show child attributes

input_image_maskobject#

Show child attributes

image_urlstring#

file_idstring#

partial_imagesinteger#

Default: 0

Range: 0–3

typeenum<string>required#

Options:web_searchweb_search_2025_08_26

filtersobject#

Show child attributes

allowed_domainsstring[]#

Default: []

search_context_sizeenum<string>#

Default: "medium"

Options:lowmediumhigh

user_locationobject#

Show child attributes

citystring#

countrystring#

regionstring#

timezonestring#

typeenum<string>#

Default: "approximate"

Options:approximate

typeenum<string>#

Default: "custom"

Options:custom

namestringrequired#

descriptionstring#

formatobject#

Show child attributes

tool_choiceenum<string> · object#

Show child attributes

Any of

typeenum<string>required#

Options:allowed_tools

modeenum<string>required#

Options:autorequired

toolsobject[]required#

typeenum<string>required#

Options:image_generationweb_searchcode_interpreter

typeenum<string>required#

Options:function

namestringrequired#

typeenum<string>required#

Options:mcp

server_labelstringrequired#

namestring · enum<string>#

Show child attributes

typeenum<string>required#

Options:custom

namestringrequired#

truncationenum<string>#

Show child attributes

Any of

inputstring · object[]#

Show child attributes

Any of

roleenum<string>required#

Options:userassistantsystemdeveloper

contentstring · object[]required#

Show child attributes

Any of

typeenum<string>#

Options:message

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

Show child attributes

Any of

parallel_tool_callsboolean · enum<string>#

Show child attributes

Any of

instructionsstring · enum<string>#

Show child attributes

Any of

streamboolean · enum<string>#

Show child attributes

Any of

stream_optionsobject · enum<string>#

Show child attributes

Any of

include_obfuscationboolean#

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#

{key}any#

clear_thinkingobject#

Show child attributes

keepinteger · enum<string>#

Show child attributes

Any of

{key}any#

image_generationobject#

Show child attributes

aspect_ratiostringrequired#

image_sizestringrequired#

Responses

200

Request accepted

Chat Completions Get Models (OpenAI Compatible)