openapi: 3.0.1
info:
title: GroqCloud Audio Chat 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: Chat
paths:
/openai/v1/chat/completions:
post:
operationId: createChatCompletion
tags:
- Chat
summary: Creates a model response for the given chat conversation.
requestBody:
required: true
description: The chat prompt and parameters
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChatCompletionRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChatCompletionResponse'
x-groq-metadata:
returns: Returns a [chat completion](/docs/api-reference#chat-create) object, or a streamed sequence of [chat completion chunk](/docs/api-reference#chat-create) objects if the request is streamed.
examples:
- title: Default
request:
py: "import os\n\nfrom groq import Groq\n\nclient = Groq(\n # This is the default and can be omitted\n api_key=os.environ.get(\"GROQ_API_KEY\"),\n)\n\nchat_completion = client.chat.completions.create(\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Explain the importance of fast language models\",\n }\n ],\n model=\"llama-3.3-70b-versatile\",\n)\n\nprint(chat_completion.choices[0].message.content)\n"
js: "import Groq from \"groq-sdk\";\n\nconst groq = new Groq({ apiKey: process.env.GROQ_API_KEY });\n\nasync function main() {\n const completion = await groq.chat.completions\n .create({\n messages: [\n {\n role: \"user\",\n content: \"Explain the importance of fast language models\",\n },\n ],\n model: \"llama-3.3-70b-versatile\",\n })\n console.log(completion.choices[0].message.content);\n}\n\nmain();\n"
curl: "curl https://api.groq.com/openai/v1/chat/completions -s \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $GROQ_API_KEY\" \\\n-d '{\n \"model\": \"llama-3.3-70b-versatile\",\n \"messages\": [{\n \"role\": \"user\",\n \"content\": \"Explain the importance of fast language models\"\n }]\n}'\n"
response: "{\n \"id\": \"chatcmpl-f51b2cd2-bef7-417e-964e-a08f0b513c22\",\n \"object\": \"chat.completion\",\n \"created\": 1730241104,\n \"model\": \"openai/gpt-oss-20b\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Fast language models have gained significant attention in recent years due to their ability to process and generate human-like text quickly and efficiently. The importance of fast language models can be understood from their potential applications and benefits:\\n\\n1. **Real-time Chatbots and Conversational Interfaces**: Fast language models enable the development of chatbots and conversational interfaces that can respond promptly to user queries, making them more engaging and useful.\\n2. **Sentiment Analysis and Opinion Mining**: Fast language models can quickly analyze text data to identify sentiments, opinions, and emotions, allowing for improved customer service, market research, and opinion mining.\\n3. **Language Translation and Localization**: Fast language models can quickly translate text between languages, facilitating global communication and enabling businesses to reach a broader audience.\\n4. **Text Summarization and Generation**: Fast language models can summarize long documents or even generate new text on a given topic, improving information retrieval and processing efficiency.\\n5. **Named Entity Recognition and Information Extraction**: Fast language models can rapidly recognize and extract specific entities, such as names, locations, and organizations, from unstructured text data.\\n6. **Recommendation Systems**: Fast language models can analyze large amounts of text data to personalize product recommendations, improve customer experience, and increase sales.\\n7. **Content Generation for Social Media**: Fast language models can quickly generate engaging content for social media platforms, helping businesses maintain a consistent online presence and increasing their online visibility.\\n8. **Sentiment Analysis for Stock Market Analysis**: Fast language models can quickly analyze social media posts, news articles, and other text data to identify sentiment trends, enabling financial analysts to make more informed investment decisions.\\n9. **Language Learning and Education**: Fast language models can provide instant feedback and adaptive language learning, making language education more effective and engaging.\\n10. **Domain-Specific Knowledge Extraction**: Fast language models can quickly extract relevant information from vast amounts of text data, enabling domain experts to focus on high-level decision-making rather than manual information gathering.\\n\\nThe benefits of fast language models include:\\n\\n* **Increased Efficiency**: Fast language models can process large amounts of text data quickly, reducing the time and effort required for tasks such as sentiment analysis, entity recognition, and text summarization.\\n* **Improved Accuracy**: Fast language models can analyze and learn from large datasets, leading to more accurate results and more informed decision-making.\\n* **Enhanced User Experience**: Fast language models can enable real-time interactions, personalized recommendations, and timely responses, improving the overall user experience.\\n* **Cost Savings**: Fast language models can automate many tasks, reducing the need for manual labor and minimizing costs associated with data processing and analysis.\\n\\nIn summary, fast language models have the potential to transform various industries and applications by providing fast, accurate, and efficient language processing capabilities.\"\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"queue_time\": 0.037493756,\n \"prompt_tokens\": 18,\n \"prompt_time\": 0.000680594,\n \"completion_tokens\": 556,\n \"completion_time\": 0.463333333,\n \"total_tokens\": 574,\n \"total_time\": 0.464013927\n },\n \"system_fingerprint\": \"fp_179b0f92c9\",\n \"x_groq\": { \"id\": \"req_01jbd6g2qdfw2adyrt2az8hz4w\" }\n}\n"
components:
schemas:
ChatCompletionRequestMessageContentPartImage:
type: object
title: Image content part
properties:
type:
type: string
enum:
- image_url
description: The type of the content part.
image_url:
type: object
properties:
url:
type: string
description: Either a URL of the image or the base64 encoded image data.
format: uri
detail:
type: string
description: Specifies the detail level of the image.
enum:
- auto
- low
- high
default: auto
required:
- url
required:
- type
- image_url
ChartElement:
type: object
properties:
label:
type: string
description: The label for this chart element
group:
type: string
description: The group this element belongs to
value:
type: number
description: The value for this element
points:
type: array
items:
type: array
items:
type: number
description: The points for this element
angle:
type: number
description: The angle for this element
radius:
type: number
description: The radius for this element
min:
type: number
description: The minimum value for this element
first_quartile:
type: number
description: The first quartile value for this element
median:
type: number
description: The median value for this element
third_quartile:
type: number
description: The third quartile value for this element
max:
type: number
outliers:
type: array
items:
type: number
description: The outliers for this element
required:
- label
ChatCompletionRequestMessageContentPartText:
type: object
title: Text content part
properties:
type:
type: string
enum:
- text
description: The type of the content part.
text:
type: string
description: The text content.
required:
- type
- text
BrowserResult:
type: object
properties:
url:
type: string
description: The URL of the browser window
title:
type: string
description: The title of the browser window
live_view_url:
type: string
description: The live view URL for the browser window
content:
type: string
description: The content of the browser result
required:
- url
- title
additionalProperties: false
ChatCompletionUsageBreakdown:
type: object
description: Usage statistics for compound AI completion requests.
properties:
models:
type: array
description: List of models used in the request and their individual usage statistics
items:
type: object
properties:
model:
type: string
description: The name/identifier of the model used
usage:
$ref: '#/components/schemas/CompletionUsage'
required:
- model
- usage
required:
- models
FunctionCitation:
type: object
description: A citation referencing the result of a function or tool call.
properties:
start_index:
type: integer
description: The character index in the message content where this citation begins.
end_index:
type: integer
description: The character index in the message content where this citation ends.
tool_call_id:
type: string
description: The ID of the tool call being cited, corresponding to a tool call made during the conversation.
required:
- start_index
- end_index
- tool_call_id
additionalProperties: false
ChatCompletionDocument:
type: object
title: Document
description: A document that can be referenced by the model while generating responses.
additionalProperties: false
properties:
id:
type: string
nullable: true
description: Optional unique identifier that can be used for citations in responses.
source:
$ref: '#/components/schemas/ChatCompletionDocumentSource'
required:
- source
ChatCompletionTokenLogprob:
type: object
properties:
token: &id001
description: The token.
type: string
logprob: &id002
description: The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
type: number
bytes: &id003
description: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
type: array
items:
type: integer
nullable: true
top_logprobs:
description: List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.
type: array
items:
type: object
properties:
token: *id001
logprob: *id002
bytes: *id003
required:
- token
- logprob
- bytes
required:
- token
- logprob
- bytes
- top_logprobs
XGroqNonStreaming:
type: object
description: Groq-specific metadata for non-streaming chat completion responses.
properties:
id:
type: string
description: A groq request ID which can be used to refer to a specific request to groq support.
seed:
type: integer
nullable: true
description: The seed used for the request. See the seed property on CreateChatCompletionRequest for more details.
usage:
type: object
nullable: true
description: Additional Groq-specific usage metrics (hardware cache statistics).
properties:
sram_cached_tokens:
type: integer
description: Number of tokens served from SRAM cache.
dram_cached_tokens:
type: integer
description: Number of tokens served from DRAM cache.
debug:
allOf:
- $ref: '#/components/schemas/DebugData'
nullable: true
required:
- 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
FunctionObject:
type: object
properties:
description:
type: string
description: A description of what the function does, used by the model to choose when and how to call the function.
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.
parameters:
$ref: '#/components/schemas/FunctionParameters'
strict:
type: boolean
default: false
description: 'Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`.
'
required:
- name
ChatCompletionMessageToolCalls:
type: array
description: The tool calls generated by the model, such as function calls.
items:
$ref: '#/components/schemas/ChatCompletionMessageToolCall'
ChatCompletionDocumentSourceJSON:
type: object
title: JSON document source
description: A document whose contents are provided inline as JSON data.
additionalProperties: false
properties:
type:
type: string
enum:
- json
description: Identifies this document source as JSON data.
data:
type: object
description: The JSON payload associated with the document.
additionalProperties: true
required:
- type
- data
Chart:
type: object
properties:
type:
type: string
description: The type of chart
enum:
- bar
- box_and_whisker
- line
- pie
- scatter
- superchart
- unknown
title:
type: string
description: The title of the chart
x_label:
type: string
description: The label for the x-axis
y_label:
type: string
description: The label for the y-axis
x_unit:
type: string
description: The unit for the x-axis
y_unit:
type: string
description: The unit for the y-axis
x_ticks:
type: array
items:
type: number
description: The tick values for the x-axis
y_ticks:
type: array
items:
type: number
description: The tick values for the y-axis
x_tick_labels:
type: array
items:
type: string
description: The labels for the x-axis ticks
y_tick_labels:
type: array
items:
type: string
description: The labels for the y-axis ticks
x_scale:
type: string
description: The scale type for the x-axis
y_scale:
type: string
description: The scale type for the y-axis
elements:
type: array
items:
$ref: '#/components/schemas/ChartElement'
description: The chart elements (data series, points, etc.)
required:
- type
- elements
ChatCompletionTool:
type: object
properties:
type:
anyOf:
- type: string
enum:
- function
- browser_search
- code_interpreter
description: The type of the tool. `function`, `browser_search`, and `code_interpreter` are supported.
- type: string
function:
$ref: '#/components/schemas/FunctionObject'
required:
- type
ChatCompletionRequestSystemMessage:
type: object
title: System message
additionalProperties: false
properties:
content:
title: System message content
description: The contents of the system message.
oneOf:
- type: string
title: Text content
description: The text contents of the message.
- type: array
title: Array of content parts
description: An array of content parts with a defined type, only `text` is supported for this message type.
items:
$ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
minItems: 1
role:
type: string
enum:
- system
- developer
description: The role of the messages author, in this case `system`.
name:
type: string
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
required:
- content
- role
ChatCompletionDocumentSource:
title: Document source
description: The source of the document. Only text and JSON sources are currently supported.
oneOf:
- $ref: '#/components/schemas/ChatCompletionDocumentSourceText'
- $ref: '#/components/schemas/ChatCompletionDocumentSourceJSON'
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/ChatCompletionDocumentSourceText'
json: '#/components/schemas/ChatCompletionDocumentSourceJSON'
ChatCompletionDocumentSourceText:
type: object
title: Text document source
description: A document whose contents are provided inline as text.
additionalProperties: false
properties:
type:
type: string
enum:
- text
description: Identifies this document source as inline text.
text:
type: string
description: The document contents.
required:
- type
- text
CompletionUsage:
type: object
description: Usage statistics for the completion request.
properties:
queue_time:
type: number
description: Time the requests was spent queued
completion_time:
type: number
description: Time spent generating tokens
completion_tokens:
type: integer
description: Number of tokens in the generated completion.
prompt_time:
type: number
description: Time spent processing input tokens
prompt_tokens:
type: integer
description: Number of tokens in the prompt.
total_time:
type: number
description: completion time and prompt time combined
total_tokens:
type: integer
description: Total number of tokens used in the request (prompt + completion).
prompt_tokens_details:
type: object
nullable: true
description: Breakdown of tokens in the prompt.
properties:
cached_tokens:
type: integer
description: Number of tokens that were cached and reused.
required:
- cached_tokens
completion_tokens_details:
type: object
nullable: true
description: Breakdown of tokens in the completion.
properties:
reasoning_tokens:
type: integer
description: Number of tokens used for reasoning (for reasoning models).
required:
- reasoning_tokens
required:
- prompt_tokens
- completion_tokens
- total_tokens
ChatCompletionRequestAssistantMessage:
type: object
title: Assistant message
additionalProperties: false
properties:
content:
title: Assistant message content
nullable: true
description: 'The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified.
'
oneOf:
- type: string
title: Text content
description: The text contents of the message.
- type: array
description: An array of content parts with a defined type, only `text` is supported for this message type.
title: Array of content parts
items:
$ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
reasoning:
description: 'The reasoning output by the assistant if reasoning_format was set to ''parsed''.
This field is supported on [models that support reasoning](https://console.groq.com/docs/reasoning).
'
nullable: true
type: string
role:
type: string
enum:
- assistant
description: The role of the messages author, in this case `assistant`.
name:
type: string
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
tool_calls:
$ref: '#/components/schemas/ChatCompletionMessageToolCalls'
function_call:
type: object
deprecated: true
description: Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
properties:
arguments:
type: string
description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
name:
type: string
description: The name of the function to call.
required:
- role
ChatCompletionNamedToolChoice:
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
ChatCompletionFunctionCallOption:
type: object
description: 'Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
'
properties:
name:
type: string
description: The name of the function to call.
required:
- name
DocumentCitation:
type: object
description: A citation referencing a specific document that was provided in the request.
properties:
start_index:
type: integer
description: The character index in the message content where this citation begins.
end_index:
type: integer
description: The character index in the message content where this citation ends.
document_id:
type: string
description: The ID of the document being cited, corresponding to a document provided in the request.
required:
- start_index
- end_index
- document_id
additionalProperties: false
ChatCompletionMessageExecutedTools:
type: array
description: A list of tools that were executed during the chat completion for compound AI systems.
items:
type: object
properties:
index:
type: integer
description: The index of the executed tool.
type:
type: string
description: The type of tool that was executed.
arguments:
type: string
description: The arguments passed to the tool in JSON format.
output:
type: string
nullable: true
description: The output returned by the tool.
search_results:
type: object
nullable: true
description: The search results returned by the tool, if applicable.
properties:
results:
type: array
description: List of search results
items:
type: object
properties:
title:
type: string
description: The title of the search result
url:
type: string
description: The URL of the search result
content:
type: string
description: The content of the search result
score:
type: number
format: float
description: The relevance score of the search result
images:
type: array
description: List of image URLs returned by the search
items:
type: string
code_results:
type: array
items:
$ref: '#/components/schemas/CodeExecutionResult'
description: Array of code execution results
browser_results:
type: array
items:
$ref: '#/components/schemas/BrowserResult'
description: Array of browser results
required:
- index
- type
- arguments
CreateChatCompletionResponse:
type: object
description: Represents a chat completion response returned by model, based on the provided input.
properties:
id:
type: string
description: A unique identifier for the chat completion.
choices:
type: array
description: A list of chat completion choices. Can be more than one if `n` is greater than 1.
items:
type: object
required:
- finish_reason
- index
- message
- logprobs
properties:
finish_reason:
type: string
description: 'The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
`length` if the maximum number of tokens specified in the request was reached,
`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
'
enum:
- stop
- length
- tool_calls
- function_call
index:
type: integer
description: The index of the choice in the list of choices.
message:
$ref: '#/components/schemas/ChatCompletionResponseMessage'
logprobs:
description: Log probability information for the choice.
type: object
nullable: true
properties:
content:
description: A list of message content tokens with log probability information.
type: array
items:
$ref: '#/components/schemas/ChatCompletionTokenLogprob'
nullable: true
required:
- content
created:
type: integer
description: The Unix timestamp (in seconds) of when the chat completion was created.
model:
type: string
description: The model used for the chat completion.
system_fingerprint:
type: string
description: 'This fingerprint represents the backend configuration that the model runs with.
Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
'
object:
type: string
description: The object type, which is always `chat.completion`.
enum:
- chat.completion
usage:
$ref: '#/components/schemas/CompletionUsage'
usage_breakdown:
$ref: '#/components/schemas/ChatCompletionUsageBreakdown'
description: Detailed usage breakdown by model when multiple models are used in the request for compound AI systems.
service_tier:
type: string
nullable: true
description: The service tier used for the request.
enum:
- auto
- on_demand
- flex
- performance
- null
mcp_list_tools:
type: array
nullable: true
description: List of discovered MCP tools from connected servers.
items:
type: object
properties:
id:
type: string
description: Unique identifier for this tool list response.
type:
type: string
description: The type identifier.
server_label:
type: string
description: Human-readable label for the MCP server.
tools:
type: array
description: Array of discovered tools from the server.
items:
type: object
properties:
annotations:
description: Additional metadata for the tool.
description:
type: string
description: Description of what the tool does.
input_schema:
type: object
additionalProperties: true
description: JSON Schema describing the tool's input parameters.
name:
type: string
description: The name of the tool.
x_groq:
$ref: '#/components/schemas/XGroqNonStreaming'
required:
- choices
- created
- id
- model
- object
DebugData:
type: object
description:
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/groq/refs/heads/main/openapi/groq-chat-api-openapi.yml