--- title: "Creates a model response for the given input." method: POST path: "/openai/v1/responses" tags: ["Responses"] --- # Creates a model response for the given input. `POST /openai/v1/responses` ## Request body - CreateResponseRequest - `model` union, required — ID of the model to use. For details on which models are compatible with the Responses API, see available [models](https://console.groq.com/docs/models) - string - 'gemma2-9b-it' | 'llama-3.3-70b-versatile' | 'llama-3.1-8b-instant' | 'llama-guard-3-8b' | 'llama3-70b-8192' | 'llama3-8b-8192' - `input` union, required — Text input to the model, used to generate a response. - string — A text input to the model, equivalent to a text input with the `user` role. - ResponseInputItem[] — A list of one or many input items to the model, containing different content types. - union - ResponseEasyInputMessage — A message input to the model with a role indicating instruction following hierarchy. - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `content` union, required — Text input to the model. - string — A text input to the model. - ResponseInputContent[] — An array of content parts. - … - ResponseInputMessage — A message input to the model with explicit type field. - `type` 'message', required — The type of the message input. Always set to `message`. - `role` 'user' | 'system' | 'developer', required — The role of the message input. One of `user`, `system`, or `developer`. Note: assistant role is not supported with explicit type. - `content` ResponseInputContent[], required — A list of one or many input content items. - `type` 'input_text', required — The type of the input item. Always `input_text`. - `text` string, required — The text input to the model. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of item. Populated when items are returned via API. - ResponseItemReference — An internal identifier for an item to reference. - `type` 'item_reference', required — The type of item to reference. Always `item_reference`. - `id` string, required — The ID of the item to reference. - ResponseFunctionCall — A function call generated by the model. - `type` 'function_call', required — The type of the function call. Always `function_call`. - `id` string — The unique ID of the function tool call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `name` string, required — The name of the function to call. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - ResponseFunctionCallOutput — The output of a function tool call. - `type` 'function_call_output', required — The type of the function tool call output. Always `function_call_output`. - `id` string — The unique ID of the function tool call output. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` string, required — A JSON string of the output of the function tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - `instructions` string, nullable — Inserts a system (or developer) message as the first item in the model's context. - `max_output_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. - `temperature` number, nullable — Controls randomness in the response generation. Range: 0 to 2. Lower values produce more deterministic outputs, higher values increase variety and creativity. - `top_p` number, nullable — Nucleus sampling parameter that controls the cumulative probability cutoff. Range: 0 to 1. A value of 0.1 restricts sampling to tokens within the top 10% probability mass. - `tools` ResponseTool[], nullable — List of tools available to the model. Currently supports function definitions only. Maximum of 128 functions. - `type` 'function', required — The type of the tool. Currently, only `function` is supported. - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `description` string — Describes the function's purpose. The model uses this to determine when to invoke the function. - `parameters` FunctionParameters — Function parameters defined as a JSON Schema object. Refer to https://json-schema.org/understanding-json-schema/ for schema documentation. - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the function call. - `tool_choice` union — Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present. - 'none' | 'auto' | 'required' — `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. - ResponseNamedToolChoice — Specifies a tool the model should use. Use to force the model to call a specific function. - `type` 'function', required — The type of the tool. Currently, only `function` is supported. - `function` object, required - `name` string, required — The name of the function to call. - `text` object — Response format configuration. Supports plain text or structured JSON output. - `format` union — An object specifying the format that the model must output. - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - TextResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `schema` object, required — The schema for the response format, described as a JSON Schema object. - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. - `reasoning` object, nullable — Configuration for reasoning capabilities when using [models that support reasoning](https://console.groq.com/docs/reasoning). - `effort` 'low' | 'medium' | 'high', nullable — Level of reasoning effort. Supported values: `low`, `medium`, `high`. Lower values provide faster responses with less reasoning depth. - `metadata` object, nullable — Custom key-value pairs for storing additional information. Maximum of 16 pairs. - `parallel_tool_calls` boolean, nullable — Enable parallel execution of multiple tool calls. - `store` boolean, nullable — Response storage flag. Note: Currently only supports false or null values. - `stream` boolean, nullable — Enable streaming mode to receive response data as server-sent events. - `user` string — Optional identifier for tracking end-user requests. Useful for usage monitoring and compliance. - `service_tier` 'auto' | 'default' | 'flex', nullable — Specifies the latency tier to use for processing the request. - `truncation` 'auto' | 'disabled', nullable — Context truncation strategy. Supported values: `auto` or `disabled`. ## Response `200` OK - CreateResponseResponse — Represents a response returned by model, based on the provided input. - `id` string, required — A unique identifier for the response. - `object` 'response', required — The object type, which is always `response`. - `status` 'completed' | 'failed' | 'in_progress' | 'incomplete', required — The status of the response generation. One of `completed`, `failed`, `in_progress`, or `incomplete`. - `created_at` integer, required — The Unix timestamp (in seconds) of when the response was created. - `output` ResponseOutputItem[], required — An array of content items generated by the model. - union - ResponseOutputMessage — An output message from the model. - `type` 'message', required — The type of the output message. Always `message`. - `id` string, required — The unique ID of the output message. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the message. - `role` 'assistant', required — The role of the output message. Always `assistant`. - `content` ResponseOutputContent[], required — The content of the output message. - `type` 'output_text', required — The type of the output text. Always `output_text`. - `text` string, required — The text output from the model. - `annotations` ResponseAnnotation[], required — The annotations of the text output. - union - … - `logprobs` string[], nullable — Log probability information for the output. - ResponseOutputFunctionCall — A function call generated by the model. - `type` 'function_call', required — The type of the function call. Always `function_call`. - `id` string, required — The unique ID of the function tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the function call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `name` string, required — The name of the function to call. - `arguments` string, required — A JSON string of the arguments to pass to the function. - ResponseOutputReasoning — A reasoning output from the model. Available for [models that support reasoning](https://console.groq.com/docs/reasoning). - `type` 'reasoning', required — The type of the reasoning output. Always `reasoning`. - `id` string, required — The unique ID of the reasoning output. - `summary` object[], required — Summary items (currently empty). - `previous_response_id` string, nullable — Not supported. Always null. - `model` string, required — The model used for the response. - `reasoning` object, nullable — Configuration options for [models that support reasoning](https://console.groq.com/docs/reasoning). - `effort` 'low' | 'medium' | 'high', nullable — The reasoning effort level used. - `summary` string, nullable — Not supported. Always null. - `max_output_tokens` integer, nullable — The maximum number of tokens configured for the response. - `instructions` string, nullable — The system instructions used for the response. - `text` object — Text format configuration used for the response. - `format` union — An object specifying the format that the model must output. - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - TextResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `schema` object, required — The schema for the response format, described as a JSON Schema object. - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. - `tools` ResponseTool[], required — The tools that were available to the model. - `type` 'function', required — The type of the tool. Currently, only `function` is supported. - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `description` string — Describes the function's purpose. The model uses this to determine when to invoke the function. - `parameters` FunctionParameters — Function parameters defined as a JSON Schema object. Refer to https://json-schema.org/understanding-json-schema/ for schema documentation. - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the function call. - `tool_choice` union, required — Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present. - 'none' | 'auto' | 'required' — `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. - ResponseNamedToolChoice — Specifies a tool the model should use. Use to force the model to call a specific function. - `type` 'function', required — The type of the tool. Currently, only `function` is supported. - `function` object, required - `name` string, required — The name of the function to call. - `truncation` 'auto' | 'disabled', required — The truncation strategy used. - `metadata` object, nullable, required — Metadata attached to the response. - `temperature` number, required — The sampling temperature used. - `top_p` number, required — The nucleus sampling parameter used. - `user` string, nullable — The user identifier. - `service_tier` 'auto' | 'default' | 'flex', required — The service tier used for processing. - `error` object, nullable, required — An error object if the response failed. - `code` string, required — The error code. - `message` string, required — A human-readable error message. - `incomplete_details` object, nullable, required — Details about why the response is incomplete. - `reason` string — The reason why the response is incomplete. - `usage` ResponseUsage — Usage statistics for the response request. - `input_tokens` integer, required — Number of tokens in the input. - `input_tokens_details` object, required — Breakdown of input tokens. - `cached_tokens` integer, required — Number of cached tokens. - `reasoning_tokens` integer — Number of reasoning tokens. - `output_tokens` integer, required — Number of tokens in the generated output. - `output_tokens_details` object, required — Breakdown of output tokens. - `cached_tokens` integer, required — Number of cached tokens. - `reasoning_tokens` integer, required — Number of reasoning tokens. - `total_tokens` integer, required — Total number of tokens used in the request (input + output). - `parallel_tool_calls` boolean, required — Whether the model can run tool calls in parallel. - `store` boolean, required — Whether the response was stored. - `background` boolean — Whether the response was generated in the background. - `top_logprobs` integer — The number of top log probabilities returned. - `max_tool_calls` integer, nullable — The maximum number of tool calls allowed. ## Changes - **2025-08-05** `4543b558a0a5` — 1 info - endpoint added [Change history](https://skmtc.dev/groq/apis/groqcloud-api/changes/openai/v1/responses/post.md) --- [API](https://skmtc.dev/groq/apis/groqcloud-api.md) · [All operations](https://skmtc.dev/groq/apis/groqcloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/groq/groqcloud-api/revisions/ea91f46f212a/schema)