openapi: 3.0.1
info:
title: GroqCloud Audio Responses API
description: Specification of the Groq cloud API
termsOfService: https://groq.com/terms-of-use/
contact:
name: Groq Support
email: support@groq.com
version: '2.1'
servers:
- url: https://api.groq.com
security:
- api_key: []
tags:
- name: Responses
paths:
/openai/v1/responses:
post:
operationId: createResponse
tags:
- Responses
summary: Creates a model response for the given input.
requestBody:
required: true
description: The input prompt and parameters
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResponseRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResponseResponse'
x-groq-metadata:
returns: Returns a [response](/docs/api-reference#responses-create) object, or a streamed sequence of [response events](/docs/api-reference#responses-streaming) if the request is streamed.
examples:
- title: Default
request:
curl: "curl https://api.groq.com/openai/v1/responses -s \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $GROQ_API_KEY\" \\\n-d '{\n \"model\": \"openai/gpt-oss-120b\",\n \"input\": \"Tell me a three sentence bedtime story about a unicorn.\"\n}'\n"
response: "{\n \"id\": \"resp_01k1x6w9ane6d8rfxm05cb45yk\",\n \"object\": \"response\",\n \"status\": \"completed\",\n \"created_at\": 1754400695,\n \"output\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_01k1x6w9ane6eb0650crhawwyy\",\n \"status\": \"completed\",\n \"role\": \"assistant\",\n \"content\": [\n {\n \"type\": \"output_text\",\n \"text\": \"When the stars blinked awake, Luna the unicorn curled her mane and whispered wishes to the sleeping pine trees. She galloped through a field of moonlit daisies, gathering dew like tiny silver pearls. With a gentle sigh, she tucked her hooves beneath a silver cloud so the world slept softly, dreaming of her gentle hooves until the morning.\",\n \"annotations\": []\n }\n ]\n }\n ],\n \"previous_response_id\": null,\n \"model\": \"llama-3.3-70b-versatile\",\n \"reasoning\": {\n \"effort\": null,\n \"summary\": null\n },\n \"max_output_tokens\": null,\n \"instructions\": null,\n \"text\": {\n \"format\": {\n \"type\": \"text\"\n }\n },\n \"tools\": [],\n \"tool_choice\": \"auto\",\n \"truncation\": \"disabled\",\n \"metadata\": {},\n \"temperature\": 1,\n \"top_p\": 1,\n \"user\": null,\n \"service_tier\": \"default\",\n \"error\": null,\n \"incomplete_details\": null,\n \"usage\": {\n \"input_tokens\": 82,\n \"input_tokens_details\": {\n \"cached_tokens\": 0\n },\n \"output_tokens\": 266,\n \"output_tokens_details\": {\n \"reasoning_tokens\": 0\n },\n \"total_tokens\": 348\n },\n \"parallel_tool_calls\": true,\n \"store\": false\n}\n"
components:
schemas:
ResponseOutputContent:
oneOf:
- $ref: '#/components/schemas/ResponseOutputTextContent'
discriminator:
propertyName: type
mapping:
output_text: '#/components/schemas/ResponseOutputTextContent'
ResponseInputContent:
oneOf:
- $ref: '#/components/schemas/ResponseInputTextContent'
discriminator:
propertyName: type
mapping:
input_text: '#/components/schemas/ResponseInputTextContent'
ResponseUsage:
type: object
description: Usage statistics for the response request.
properties:
input_tokens:
type: integer
description: Number of tokens in the input.
input_tokens_details:
type: object
description: Breakdown of input tokens.
properties:
cached_tokens:
type: integer
description: Number of cached tokens.
reasoning_tokens:
type: integer
description: Number of reasoning tokens.
required:
- cached_tokens
output_tokens:
type: integer
description: Number of tokens in the generated output.
output_tokens_details:
type: object
description: Breakdown of output tokens.
properties:
cached_tokens:
type: integer
description: Number of cached tokens.
reasoning_tokens:
type: integer
description: Number of reasoning tokens.
required:
- cached_tokens
- reasoning_tokens
total_tokens:
type: integer
description: Total number of tokens used in the request (input + output).
required:
- input_tokens
- input_tokens_details
- output_tokens
- output_tokens_details
- total_tokens
ResponseFunctionCall:
type: object
title: Function call
description: A function call generated by the model.
properties:
type:
type: string
enum:
- function_call
description: The type of the function call. Always `function_call`.
x-stainless-const: true
id:
type: string
description: The unique ID of the function tool call.
call_id:
type: string
description: The unique ID of the function tool call generated by the model.
name:
type: string
description: The name of the function to call.
arguments:
type: string
description: A JSON string of the arguments to pass to the function.
status:
type: string
description: The status of the item.
enum:
- in_progress
- completed
- incomplete
required:
- type
- call_id
- name
- arguments
ResponseInputMessage:
type: object
title: Input message
description: 'A message input to the model with explicit type field.
'
properties:
type:
type: string
description: The type of the message input. Always set to `message`.
enum:
- message
x-stainless-const: true
role:
type: string
description: 'The role of the message input. One of `user`, `system`, or `developer`. Note: assistant role is not supported with explicit type.
'
enum:
- user
- system
- developer
content:
type: array
description: A list of one or many input content items.
items:
$ref: '#/components/schemas/ResponseInputContent'
status:
type: string
description: The status of item. Populated when items are returned via API.
enum:
- in_progress
- completed
- incomplete
required:
- type
- role
- content
FunctionParameters:
type: object
description: Function parameters defined as a JSON Schema object. Refer to https://json-schema.org/understanding-json-schema/ for schema documentation.
additionalProperties: true
ResponseNamedToolChoice:
type: object
description: Specifies a tool the model should use. Use to force the model to call a specific function.
properties:
type:
type: string
enum:
- function
description: The type of the tool. Currently, only `function` is supported.
function:
type: object
properties:
name:
type: string
description: The name of the function to call.
required:
- name
required:
- type
- function
ResponseItemReference:
type: object
title: Item reference
description: An internal identifier for an item to reference.
properties:
type:
type: string
enum:
- item_reference
description: The type of item to reference. Always `item_reference`.
x-stainless-const: true
id:
type: string
description: The ID of the item to reference.
required:
- type
- id
ResponseFormatText:
type: object
title: Text
description: 'Default response format. Used to generate text responses.
'
properties:
type:
type: string
description: The type of response format being defined. Always `text`.
enum:
- text
x-stainless-const: true
required:
- type
ResponseFunctionCallOutput:
type: object
title: Function call output
description: The output of a function tool call.
properties:
type:
type: string
enum:
- function_call_output
description: The type of the function tool call output. Always `function_call_output`.
x-stainless-const: true
id:
type: string
description: The unique ID of the function tool call output.
call_id:
type: string
description: The unique ID of the function tool call generated by the model.
output:
type: string
description: A JSON string of the output of the function tool call.
status:
type: string
description: The status of the item.
enum:
- in_progress
- completed
- incomplete
required:
- type
- call_id
- output
TextResponseFormatJsonSchema:
type: object
title: JSON schema
description: 'JSON Schema response format. Used to generate structured JSON responses.
'
properties:
type:
type: string
description: The type of response format being defined. Always `json_schema`.
enum:
- json_schema
x-stainless-const: true
name:
type: string
description: '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:
type: string
description: 'A description of what the response format is for, used by the model to determine how to respond in the format.
'
schema:
type: object
description: 'The schema for the response format, described as a JSON Schema object.
'
additionalProperties: true
strict:
type: boolean
nullable: true
default: false
description: 'Whether to enable strict schema adherence when generating the output.
'
required:
- type
- name
- schema
ResponseEasyInputMessage:
type: object
title: Easy input message
description: 'A message input to the model with a role indicating instruction following hierarchy.
'
properties:
role:
type: string
description: 'The role of the message input. One of `user`, `assistant`, `system`, or `developer`.
'
enum:
- user
- assistant
- system
- developer
content:
description: 'Text input to the model.
'
oneOf:
- type: string
title: Text input
description: A text input to the model.
- type: array
title: Content array
description: An array of content parts.
items:
$ref: '#/components/schemas/ResponseInputContent'
required:
- role
- content
CreateResponseResponse:
type: object
description: Represents a response returned by model, based on the provided input.
properties:
id:
type: string
description: A unique identifier for the response.
object:
type: string
description: The object type, which is always `response`.
enum:
- response
status:
type: string
description: 'The status of the response generation. One of `completed`, `failed`, `in_progress`, or `incomplete`.
'
enum:
- completed
- failed
- in_progress
- incomplete
created_at:
type: integer
description: The Unix timestamp (in seconds) of when the response was created.
output:
type: array
description: An array of content items generated by the model.
items:
$ref: '#/components/schemas/ResponseOutputItem'
previous_response_id:
type: string
description: Not supported. Always null.
nullable: true
model:
type: string
description: The model used for the response.
reasoning:
type: object
nullable: true
description: Configuration options for [models that support reasoning](https://console.groq.com/docs/reasoning).
properties:
effort:
type: string
enum:
- low
- medium
- high
nullable: true
description: The reasoning effort level used.
summary:
type: string
nullable: true
description: Not supported. Always null.
max_output_tokens:
type: integer
nullable: true
description: The maximum number of tokens configured for the response.
instructions:
type: string
nullable: true
description: The system instructions used for the response.
text:
type: object
description: Text format configuration used for the response.
properties:
format:
$ref: '#/components/schemas/ResponseFormatConfiguration'
tools:
type: array
description: The tools that were available to the model.
items:
$ref: '#/components/schemas/ResponseTool'
tool_choice:
$ref: '#/components/schemas/ResponseToolChoiceOption'
truncation:
type: string
description: The truncation strategy used.
enum:
- auto
- disabled
metadata:
type: object
nullable: true
additionalProperties:
type: string
description: Metadata attached to the response.
temperature:
type: number
description: The sampling temperature used.
top_p:
type: number
description: The nucleus sampling parameter used.
user:
type: string
nullable: true
description: The user identifier.
service_tier:
type: string
description: The service tier used for processing.
enum:
- auto
- default
- flex
error:
type: object
nullable: true
description: An error object if the response failed.
properties:
code:
type: string
description: The error code.
message:
type: string
description: A human-readable error message.
required:
- code
- message
incomplete_details:
type: object
nullable: true
description: Details about why the response is incomplete.
properties:
reason:
type: string
description: The reason why the response is incomplete.
usage:
$ref: '#/components/schemas/ResponseUsage'
parallel_tool_calls:
type: boolean
description: Whether the model can run tool calls in parallel.
store:
type: boolean
description: Whether the response was stored.
background:
type: boolean
description: Whether the response was generated in the background.
default: false
top_logprobs:
type: integer
description: The number of top log probabilities returned.
default: 0
max_tool_calls:
type: integer
nullable: true
description: The maximum number of tool calls allowed.
required:
- id
- object
- status
- created_at
- output
- model
- tools
- tool_choice
- truncation
- metadata
- temperature
- top_p
- service_tier
- error
- incomplete_details
- parallel_tool_calls
- store
ResponseOutputTextContent:
type: object
title: Output text
description: A text output from the model.
properties:
type:
type: string
enum:
- output_text
description: The type of the output text. Always `output_text`.
x-stainless-const: true
text:
type: string
description: The text output from the model.
annotations:
type: array
description: The annotations of the text output.
items:
$ref: '#/components/schemas/ResponseAnnotation'
logprobs:
type: array
nullable: true
description: Log probability information for the output.
items:
type: string
required:
- type
- text
- annotations
ResponseTool:
type: object
properties:
type:
type: string
enum:
- function
description: The type of the tool. Currently, only `function` is supported.
name:
type: string
description: 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:
type: string
description: Describes the function's purpose. The model uses this to determine when to invoke the function.
parameters:
$ref: '#/components/schemas/FunctionParameters'
strict:
type: boolean
nullable: true
description: Whether to enable strict schema adherence when generating the function call.
required:
- type
- name
ResponseUrlCitation:
type: object
title: URL citation
description: A citation for a web resource.
properties:
type:
type: string
enum:
- url_citation
description: The type of the annotation. Always `url_citation`.
x-stainless-const: true
url:
type: string
description: The URL of the web resource.
start_index:
type: integer
description: The index of the first character of the URL citation in the message.
end_index:
type: integer
description: The index of the last character of the URL citation in the message.
title:
type: string
description: The title of the web resource.
required:
- type
- url
ResponseAnnotation:
oneOf:
- $ref: '#/components/schemas/ResponseFileCitation'
- $ref: '#/components/schemas/ResponseUrlCitation'
discriminator:
propertyName: type
mapping:
file_citation: '#/components/schemas/ResponseFileCitation'
url_citation: '#/components/schemas/ResponseUrlCitation'
ResponseOutputFunctionCall:
type: object
title: Function call
description: A function call generated by the model.
properties:
type:
type: string
enum:
- function_call
description: The type of the function call. Always `function_call`.
x-stainless-const: true
id:
type: string
description: The unique ID of the function tool call.
status:
type: string
description: The status of the function call.
enum:
- in_progress
- completed
- incomplete
call_id:
type: string
description: The unique ID of the function tool call generated by the model.
name:
type: string
description: The name of the function to call.
arguments:
type: string
description: A JSON string of the arguments to pass to the function.
required:
- type
- id
- call_id
- name
- arguments
ResponseInputItem:
oneOf:
- $ref: '#/components/schemas/ResponseEasyInputMessage'
- $ref: '#/components/schemas/ResponseInputMessage'
- $ref: '#/components/schemas/ResponseItemReference'
- $ref: '#/components/schemas/ResponseFunctionCall'
- $ref: '#/components/schemas/ResponseFunctionCallOutput'
discriminator:
propertyName: type
mapping:
message: '#/components/schemas/ResponseInputMessage'
item_reference: '#/components/schemas/ResponseItemReference'
function_call: '#/components/schemas/ResponseFunctionCall'
function_call_output: '#/components/schemas/ResponseFunctionCallOutput'
ResponseOutputItem:
oneOf:
- $ref: '#/components/schemas/ResponseOutputMessage'
- $ref: '#/components/schemas/ResponseOutputFunctionCall'
- $ref: '#/components/schemas/ResponseOutputReasoning'
discriminator:
propertyName: type
mapping:
message: '#/components/schemas/ResponseOutputMessage'
function_call: '#/components/schemas/ResponseOutputFunctionCall'
reasoning: '#/components/schemas/ResponseOutputReasoning'
CreateResponseRequest:
type: object
additionalProperties: false
properties:
model:
description: 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)
example: llama-3.3-70b-versatile
anyOf:
- type: string
- type: string
enum:
- gemma2-9b-it
- llama-3.3-70b-versatile
- llama-3.1-8b-instant
- llama-guard-3-8b
- llama3-70b-8192
- llama3-8b-8192
input:
description: 'Text input to the model, used to generate a response.
'
oneOf:
- type: string
title: Text input
description: A text input to the model, equivalent to a text input with the `user` role.
- type: array
title: Input item list
description: A list of one or many input items to the model, containing different content types.
items:
$ref: '#/components/schemas/ResponseInputItem'
instructions:
type: string
description: 'Inserts a system (or developer) message as the first item in the model''s context.
'
nullable: true
max_output_tokens:
description: 'An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
'
type: integer
nullable: true
temperature:
type: number
minimum: 0
maximum: 2
default: 1
example: 1
nullable: true
description: 'Controls randomness in the response generation. Range: 0 to 2. Lower values produce more deterministic outputs, higher values increase variety and creativity.
'
top_p:
type: number
minimum: 0
maximum: 1
default: 1
example: 1
nullable: true
description: '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:
type: array
nullable: true
maxItems: 128
description: 'List of tools available to the model. Currently supports function definitions only. Maximum of 128 functions.
'
items:
$ref: '#/components/schemas/ResponseTool'
tool_choice:
$ref: '#/components/schemas/ResponseToolChoiceOption'
text:
type: object
description: 'Response format configuration. Supports plain text or structured JSON output.
'
properties:
format:
$ref: '#/components/schemas/ResponseFormatConfiguration'
reasoning:
type: object
nullable: true
description: 'Configuration for reasoning capabilities when using [models that support reasoning](https://console.groq.com/docs/reasoning).
'
properties:
effort:
type: string
enum:
- low
- medium
- high
default: medium
nullable: true
description: 'Level of reasoning effort. Supported values: `low`, `medium`, `high`. Lower values provide faster responses with less reasoning depth.
'
metadata:
type: object
nullable: true
additionalProperties:
type: string
description: 'Custom key-value pairs for storing additional information. Maximum of 16 pairs.
'
parallel_tool_calls:
type: boolean
description: 'Enable parallel execution of multiple tool calls.
'
default: true
nullable: true
store:
type: boolean
description: 'Response storage flag. Note: Currently only supports false or null values.
'
default: false
nullable: true
stream:
description: 'Enable streaming mode to receive response data as server-sent events.
'
type: boolean
nullable: true
default: false
user:
type: string
example: user-1234
description: 'Optional identifier for tracking end-user requests. Useful for usage monitoring and compliance.
'
service_tier:
type: string
description: 'Specifies the latency tier to use for processing the request.
'
enum:
- auto
- default
- flex
nullable: true
default: auto
truncation:
type: string
description: 'Context truncation strategy. Supported values: `auto` or `disabled`.
'
enum:
- auto
- disabled
nullable: true
default: disabled
required:
- model
- input
ResponseOutputMessage:
type: object
title: Output message
description: An output message from the model.
properties:
type:
type: string
description: The type of the output message. Always `message`.
enum:
- message
x-stainless-const: true
id:
type: string
description: The unique ID of the output message.
status:
type: string
description: The status of the message.
enum:
- in_progress
- completed
- incomplete
role:
type: string
description: The role of the output message. Always `assistant`.
enum:
- assistant
x-stainless-const: true
content:
type: array
description: The content of the output message.
items:
$ref: '#/components/schemas/ResponseOutputContent'
required:
- type
- id
- role
- content
ResponseFormatConfiguration:
description: 'An object specifying the format that the model must output.
'
oneOf:
- $ref: '#/components/schemas/ResponseFormatText'
- $ref: '#/components/schemas/ResponseFormatJsonObject'
- $ref: '#/components/schemas/TextResponseFormatJsonSchema'
ResponseOutputReasoning:
type: object
title: Reasoning
description: A reasoning output from the model. Available for [models that support reasoning](https://console.groq.com/docs/reasoning).
properties:
type:
type: string
enum:
- reasoning
description: The type of the reasoning output. Always `reasoning`.
x-stainless-const: true
id:
type: string
description: The unique ID of the reasoning output.
summary:
type: array
description: Summary items (currently empty).
items:
type: object
required:
- type
- id
- summary
ResponseFileCitation:
type: object
title: File citation
description: A citation to a file.
properties:
type:
type: string
enum:
- file_citation
description: The type of the annotation. Always `file_citation`.
x-stainless-const: true
file_id:
type: string
description: The ID of the file.
index:
type: integer
description: The index of the citation in the text.
required:
- type
- file_id
ResponseFormatJsonObject:
type: object
title: JSON object
description: '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.
'
properties:
type:
type: string
description: The type of response format being defined. Always `json_object`.
enum:
- json_object
x-stainless-const: true
required:
- type
ResponseInputTextContent:
type: object
title: Input text
description: A text input to the model.
properties:
type:
type: string
enum:
- input_text
description: The type of the input item. Always `input_text`.
x-stainless-const: true
text:
type: string
description: The text input to the model.
required:
- type
- text
ResponseToolChoiceOption:
nullable: true
description: '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.
'
oneOf:
- type: string
description: '`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.
'
enum:
- none
- auto
- required
- $ref: '#/components/schemas/ResponseNamedToolChoice'
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: apiKey
x-groq-metadata:
groups:
- id: chat
type: endpoints
title: Chat
description: ''
sections:
- type: endpoint
key: createChatCompletion
path: create
- id: responses
type: endpoints
title: Responses (beta)
description: ''
sections:
- type: endpoint
key: createResponse
path: create
- id: audio
type: endpoints
title: Audio
description: ''
sections:
- type: endpoint
key: createTranscription
path: transcription
- type: endpoint
key: createTranslation
path: translation
- type: endpoint
key: createSpeech
path: speech
- id: models
type:
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/groq/refs/heads/main/openapi/groq-responses-api-openapi.yml