> ## Documentation Index > Fetch the complete documentation index at: https://docs.helicone.ai/llms.txt > Use this file to discover all available pages before exploring further. # Responses (Gateway) > Create responses via the AI Gateway 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](/gateway/provider-routing). ```bash cURL theme={null} 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." }' ``` ```typescript TypeScript theme={null} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://ai-gateway.helicone.ai/v1", apiKey: process.env.HELICONE_API_KEY, }); const response = await client.responses.create({ model: "gpt-4o-mini", input: "Say hello in one sentence.", }); ``` ```python Python theme={null} import os from openai import OpenAI client = OpenAI( base_url="https://ai-gateway.helicone.ai/v1", api_key=os.environ.get("HELICONE_API_KEY"), ) response = client.responses.create( model="gpt-4o-mini", input="Say hello in one sentence.", ) ``` ## OpenAPI ````yaml post /v1/responses openapi: 3.0.0 info: title: Helicone AI Gateway API version: 1.0.0 description: OpenAPI spec derived from Zod schemas for AI Gateway. servers: - url: https://ai-gateway.helicone.ai security: [] paths: /v1/responses: post: summary: Create Response requestBody: required: true content: application/json: schema: type: object properties: top_logprobs: type: integer minimum: 0 maximum: 20 top_k: anyOf: - type: number - type: string nullable: true enum: - null temperature: anyOf: - type: number - type: string nullable: true enum: - null top_p: anyOf: - type: number - type: string nullable: true enum: - null user: type: string safety_identifier: type: string prompt_cache_key: type: string service_tier: anyOf: - type: string enum: - auto - default - flex - scale - priority - type: string nullable: true enum: - null model: anyOf: - anyOf: - type: string - type: string - type: string reasoning: anyOf: - type: object properties: effort: anyOf: - type: string enum: - minimal - low - medium - high - type: string nullable: true enum: - null summary: anyOf: - type: string enum: - auto - concise - detailed - type: string nullable: true enum: - null generate_summary: anyOf: - type: string enum: - auto - concise - detailed - type: string nullable: true enum: - null - type: string nullable: true enum: - null reasoning_options: type: object properties: budget_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 max_output_tokens: anyOf: - type: number - type: string nullable: true enum: - null max_tool_calls: anyOf: - type: number - type: string nullable: true enum: - null text: type: object properties: format: anyOf: - type: object properties: type: type: string enum: - text required: - type - type: object properties: type: type: string enum: - json_schema description: type: string name: type: string schema: type: object properties: {} strict: anyOf: - type: boolean - type: string nullable: true enum: - null required: - type - name - schema - type: object properties: type: type: string enum: - json_object required: - type verbosity: anyOf: - type: string enum: - low - medium - high - type: string nullable: true enum: - null tools: type: array items: anyOf: - type: object properties: type: default: function type: string enum: - function name: type: string description: anyOf: - type: string - type: string nullable: true enum: - null parameters: anyOf: - type: object properties: {} - type: string nullable: true enum: - null strict: anyOf: - type: boolean - type: string nullable: true enum: - null required: - name - parameters - type: object properties: type: type: string enum: - mcp server_label: type: string server_url: type: string connector_id: type: string enum: - connector_dropbox - connector_gmail - connector_googlecalendar - connector_googledrive - connector_microsoftteams - connector_outlookcalendar - connector_outlookemail - connector_sharepoint authorization: type: string server_description: type: string headers: anyOf: - type: object additionalProperties: type: string - type: string nullable: true enum: - null allowed_tools: anyOf: - anyOf: - type: array items: type: string - type: object properties: tool_names: type: array items: type: string read_only: type: boolean - type: string nullable: true enum: - null require_approval: anyOf: - anyOf: - type: object properties: always: type: object properties: tool_names: type: array items: type: string read_only: type: boolean never: type: object properties: tool_names: type: array items: type: string read_only: type: boolean - type: string enum: - always - never - type: string nullable: true enum: - null required: - type - server_label - type: object properties: type: type: string enum: - code_interpreter container: anyOf: - type: string - type: object properties: type: default: auto type: string enum: - auto file_ids: maxItems: 50 type: array items: type: string required: - type - container - type: object properties: type: type: string enum: - image_generation model: default: gpt-image-1 type: string enum: - gpt-image-1 - gpt-image-1-mini quality: default: auto type: string enum: - low - medium - high - auto size: default: auto type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto output_format: default: png type: string enum: - png - webp - jpeg output_compression: default: 100 type: integer minimum: 0 maximum: 100 moderation: default: auto type: string enum: - auto - low background: default: auto type: string enum: - transparent - opaque - auto input_fidelity: anyOf: - type: string enum: - high - low - type: string nullable: true enum: - null input_image_mask: type: object properties: image_url: type: string file_id: type: string partial_images: default: 0 type: integer minimum: 0 maximum: 3 required: - type - type: object properties: type: type: string enum: - web_search - web_search_2025_08_26 filters: type: object properties: allowed_domains: default: [] type: array items: type: string search_context_size: default: medium type: string enum: - low - medium - high user_location: type: object properties: city: type: string country: type: string region: type: string timezone: type: string type: default: approximate type: string enum: - approximate required: - type - type: object properties: type: default: custom type: string enum: - custom name: type: string description: type: string format: anyOf: - type: object properties: type: default: text type: string enum: - text - type: object properties: type: default: grammar type: string enum: - grammar syntax: type: string enum: - lark - regex definition: type: string required: - syntax - definition required: - name tool_choice: anyOf: - type: string enum: - none - auto - required - type: object properties: type: type: string enum: - allowed_tools mode: type: string enum: - auto - required tools: type: array items: type: object properties: {} required: - type - mode - tools - type: object properties: type: type: string enum: - image_generation - web_search - code_interpreter required: - type - type: object properties: type: type: string enum: - function name: type: string required: - type - name - type: object properties: type: type: string enum: - mcp server_label: type: string name: anyOf: - type: string - type: string nullable: true enum: - null required: - type - server_label - type: object properties: type: type: string enum: - custom name: type: string required: - type - name truncation: anyOf: - type: string enum: - auto - disabled - type: string nullable: true enum: - null input: anyOf: - type: string - type: array items: anyOf: - type: object properties: role: type: string enum: - user - assistant - system - developer content: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: default: input_text type: string enum: - input_text text: type: string required: - text - type: object properties: type: default: input_image type: string enum: - input_image image_url: anyOf: - type: string - type: string nullable: true enum: - null file_id: anyOf: - type: string - type: string nullable: true enum: - null detail: type: string enum: - low - high - auto required: - detail - type: object properties: type: default: input_file type: string enum: - input_file file_id: anyOf: - type: string - type: string nullable: true enum: - null filename: type: string file_url: type: string file_data: type: string type: type: string enum: - message required: - role - content - anyOf: - type: object properties: type: type: string enum: - message role: type: string enum: - user - system - developer status: type: string enum: - in_progress - completed - incomplete content: type: array items: anyOf: - type: object properties: type: default: input_text type: string enum: - input_text text: type: string required: - text - type: object properties: type: default: input_image type: string enum: - input_image image_url: anyOf: - type: string - type: string nullable: true enum: - null file_id: anyOf: - type: string - type: string nullable: true enum: - null detail: type: string enum: - low - high - auto required: - detail - type: object properties: type: default: input_file type: string enum: - input_file file_id: anyOf: - type: string - type: string nullable: true enum: - null filename: type: string file_url: type: string file_data: type: string required: - role - content - type: object properties: id: type: string type: type: string enum: - message role: type: string enum: - assistant content: type: array items: anyOf: - type: object properties: type: default: output_text type: string enum: - output_text text: type: string annotations: type: array items: anyOf: - type: object properties: type: default: file_citation type: string enum: - file_citation file_id: type: string index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 filename: type: string required: - file_id - index - filename - type: object properties: type: default: url_citation type: string enum: - url_citation url: type: string start_index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 end_index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 title: type: string required: - url - start_index - end_index - title - type: object properties: type: default: container_file_citation type: string enum: - container_file_citation container_id: type: string file_id: type: string start_index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 end_index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 filename: type: string required: - container_id - file_id - start_index - end_index - filename - type: object properties: type: type: string enum: - file_path file_id: type: string index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - type - file_id - index logprobs: type: array items: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer minimum: -9007199254740991 maximum: 9007199254740991 top_logprobs: type: array items: type: object properties: token: type: string logprob: type: number bytes: type: array items: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - token - logprob - bytes required: - token - logprob - bytes - top_logprobs required: - text - annotations - type: object properties: type: default: refusal type: string enum: - refusal refusal: type: string required: - refusal - type: object properties: type: default: output_image type: string enum: - output_image image_url: type: string detail: type: string enum: - low - high - auto required: - image_url status: type: string enum: - in_progress - completed - incomplete required: - id - type - role - content - status - type: object properties: id: type: string type: type: string enum: - function_call call_id: type: string name: type: string arguments: type: string status: type: string enum: - in_progress - completed - incomplete required: - type - call_id - name - arguments - type: object properties: id: anyOf: - type: string - type: string nullable: true enum: - null call_id: type: string minLength: 1 maxLength: 64 type: default: function_call_output type: string enum: - function_call_output output: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: default: input_text type: string enum: - input_text text: type: string maxLength: 10485760 required: - text - type: object properties: type: default: input_image type: string enum: - input_image image_url: anyOf: - type: string - type: string nullable: true enum: - null file_id: anyOf: - type: string - type: string nullable: true enum: - null detail: anyOf: - type: string enum: - low - high - auto - type: string nullable: true enum: - null - type: object properties: type: default: input_file type: string enum: - input_file file_id: anyOf: - type: string - type: string nullable: true enum: - null filename: anyOf: - type: string - type: string nullable: true enum: - null file_data: anyOf: - type: string - type: string nullable: true enum: - null file_url: anyOf: - type: string - type: string nullable: true enum: - null status: anyOf: - type: string enum: - in_progress - completed - incomplete - type: string nullable: true enum: - null required: - call_id - output - type: object properties: type: type: string enum: - reasoning id: type: string encrypted_content: anyOf: - type: string - type: string nullable: true enum: - null summary: type: array items: type: object properties: type: default: summary_text type: string enum: - summary_text text: type: string required: - text content: type: array items: type: object properties: type: default: reasoning_text type: string enum: - reasoning_text text: type: string required: - text status: type: string enum: - in_progress - completed - incomplete required: - type - id - summary - type: object properties: type: type: string enum: - image_generation_call id: type: string status: type: string enum: - in_progress - completed - generating - failed result: anyOf: - type: string - type: string nullable: true enum: - null required: - type - id - status - result - type: object properties: type: default: code_interpreter_call type: string enum: - code_interpreter_call id: type: string status: type: string enum: - in_progress - completed - incomplete - interpreting - failed container_id: type: string code: anyOf: - type: string - type: string nullable: true enum: - null outputs: anyOf: - type: array items: anyOf: - type: object properties: type: default: logs type: string enum: - logs logs: type: string required: - logs - type: object properties: type: default: image type: string enum: - image url: type: string required: - url - type: string nullable: true enum: - null required: - id - status - container_id - code - outputs - type: object properties: type: type: string enum: - mcp_list_tools id: type: string server_label: type: string tools: type: array items: type: object properties: name: type: string description: anyOf: - type: string - type: string nullable: true enum: - null input_schema: type: object properties: {} annotations: anyOf: - type: object properties: {} - type: string nullable: true enum: - null required: - name - input_schema error: anyOf: - type: string - type: string nullable: true enum: - null required: - type - id - server_label - tools - type: object properties: type: type: string enum: - mcp_approval_request id: type: string server_label: type: string name: type: string arguments: type: string required: - type - id - server_label - name - arguments - type: object properties: type: type: string enum: - mcp_approval_response id: anyOf: - type: string - type: string nullable: true enum: - null approval_request_id: type: string approve: type: boolean reason: anyOf: - type: string - type: string nullable: true enum: - null required: - type - approval_request_id - approve - type: object properties: type: type: string enum: - mcp_call id: type: string server_label: type: string name: type: string arguments: type: string output: anyOf: - type: string - type: string nullable: true enum: - null error: anyOf: - type: string - type: string nullable: true enum: - null status: type: string enum: - in_progress - completed - incomplete - calling - failed approval_request_id: anyOf: - type: string - type: string nullable: true enum: - null required: - type - id - server_label - name - arguments - type: object properties: type: type: string enum: - custom_tool_call_output id: type: string call_id: type: string output: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: default: input_text type: string enum: - input_text text: type: string required: - text - type: object properties: type: default: input_image type: string enum: - input_image image_url: anyOf: - type: string - type: string nullable: true enum: - null file_id: anyOf: - type: string - type: string nullable: true enum: - null detail: type: string enum: - low - high - auto required: - detail - type: object properties: type: default: input_file type: string enum: - input_file file_id: anyOf: - type: string - type: string nullable: true enum: - null filename: type: string file_url: type: string file_data: type: string required: - type - call_id - output - type: object properties: type: type: string enum: - custom_tool_call id: type: string call_id: type: string name: type: string input: type: string required: - type - call_id - name - input - type: object properties: type: anyOf: - type: string enum: - item_reference - type: string nullable: true enum: - null id: type: string required: - id include: anyOf: - type: array items: type: string enum: - message.input_image.image_url - code_interpreter_call.outputs - reasoning.encrypted_content - message.output_text.logprobs - type: string nullable: true enum: - null parallel_tool_calls: anyOf: - type: boolean - type: string nullable: true enum: - null instructions: anyOf: - type: string - type: string nullable: true enum: - null stream: anyOf: - type: boolean - type: string nullable: true enum: - null stream_options: anyOf: - type: object properties: include_obfuscation: type: boolean - type: string nullable: true enum: - null context_editing: type: object properties: enabled: type: boolean clear_tool_uses: type: object properties: trigger: type: integer minimum: -9007199254740991 maximum: 9007199254740991 keep: type: integer minimum: -9007199254740991 maximum: 9007199254740991 clear_at_least: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclude_tools: type: array items: type: string clear_tool_inputs: type: boolean additionalProperties: {} clear_thinking: type: object properties: keep: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: string enum: - all additionalProperties: {} required: - enabled additionalProperties: {} image_generation: type: object properties: aspect_ratio: type: string image_size: type: string required: - aspect_ratio - image_size additionalProperties: false responses: '200': description: Request accepted ````