API Reference

Chat

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Completions

Given a list of messages comprising a conversation, the model will return a response.

Create chat completion

$ openai chat:completions create

POST/chat/completions

Delete chat completion

$ openai chat:completions delete

DELETE/chat/completions/{completion_id}

List Chat Completions

$ openai chat:completions list

GET/chat/completions

Get chat completion

$ openai chat:completions retrieve

GET/chat/completions/{completion_id}

Update chat completion

$ openai chat:completions update

POST/chat/completions/{completion_id}

ModelsExpand Collapse

ChatCompletionAllowedTools: object { mode, tools }

Constrains the tools available to the model to a pre-defined set.

chat_completion: object { id, choices, created, 7 more }

Represents a chat completion response returned by model, based on the provided input.

chat_completion_allowed_tool_choice: object { allowed_tools, type }

Constrains the tools available to the model to a pre-defined set.

chat_completion_assistant_message_param: object { role, audio, content, 4 more }

Messages sent by the model in response to user messages.

chat_completion_audio: object { id, data, expires_at, transcript }

If the audio output modality is requested, this object contains data about the audio response from the model. Learn more.

chat_completion_audio_param: object { format, voice }

Parameters for audio output. Required when audio output is requested with modalities: ["audio"]. Learn more.

chat_completion_chunk: object { id, choices, created, 7 more }

Represents a streamed chunk of a chat completion response returned by the model, based on the provided input. Learn more.

chat_completion_content_part: ChatCompletionContentPartText { text, type, prompt_cache_breakpoint } or ChatCompletionContentPartImage { image_url, type, prompt_cache_breakpoint } or ChatCompletionContentPartInputAudio { input_audio, type, prompt_cache_breakpoint } or object { file, type, prompt_cache_breakpoint }

Learn about text inputs.

chat_completion_content_part_image: object { image_url, type, prompt_cache_breakpoint }

Learn about image inputs.

chat_completion_content_part_input_audio: object { input_audio, type, prompt_cache_breakpoint }

Learn about audio inputs.

chat_completion_content_part_refusal: object { refusal, type }

chat_completion_content_part_text: object { text, type, prompt_cache_breakpoint }

Learn about text inputs.

chat_completion_custom_tool: object { custom, type }

A custom tool that processes input using a specified format.

chat_completion_deleted: object { id, deleted, object }

chat_completion_developer_message_param: object { content, role, name }

Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, developer messages replace the previous system messages.

chat_completion_function_call_option: object { name }

Specifying a particular function via {"name": "my_function"} forces the model to call that function.

chat_completion_function_message_param: object { content, name, role }

chat_completion_function_tool: object { function, type }

A function tool that can be used to generate a response.

chat_completion_message: object { content, refusal, role, 4 more }

A chat completion message generated by the model.

chat_completion_message_custom_tool_call: object { id, custom, type }

A call to a custom tool created by the model.

chat_completion_message_function_tool_call: object { id, function, type }

A call to a function tool created by the model.

chat_completion_message_param: ChatCompletionDeveloperMessageParam { content, role, name } or ChatCompletionSystemMessageParam { content, role, name } or ChatCompletionUserMessageParam { content, role, name } or 3 more

Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, developer messages replace the previous system messages.

chat_completion_message_tool_call: ChatCompletionMessageFunctionToolCall { id, function, type } or ChatCompletionMessageCustomToolCall { id, custom, type }

A call to a function tool created by the model.

chat_completion_modality: "text" or "audio"

chat_completion_named_tool_choice: object { function, type }

Specifies a tool the model should use. Use to force the model to call a specific function.

chat_completion_named_tool_choice_custom: object { custom, type }

Specifies a tool the model should use. Use to force the model to call a specific custom tool.

chat_completion_prediction_content: object { content, type }

Static predicted output content, such as the content of a text file that is being regenerated.

chat_completion_role: "developer" or "system" or "user" or 3 more

The role of the author of a message

chat_completion_store_message: ChatCompletionMessage { content, refusal, role, 4 more }

A chat completion message generated by the model.

chat_completion_stream_options: object { include_obfuscation, include_usage }

Options for streaming response. Only set this when you set stream: true.

chat_completion_system_message_param: object { content, role, name }

Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, use developer messages for this purpose instead.

chat_completion_token_logprob: object { token, bytes, logprob, top_logprobs }

chat_completion_tool: ChatCompletionFunctionTool { function, type } or ChatCompletionCustomTool { custom, type }

A function tool that can be used to generate a response.

chat_completion_tool_choice_option: "none" or "auto" or "required" or ChatCompletionAllowedToolChoice { allowed_tools, type } or ChatCompletionNamedToolChoice { function, type } or ChatCompletionNamedToolChoiceCustom { custom, type }

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.

chat_completion_tool_message_param: object { content, role, tool_call_id }

chat_completion_user_message_param: object { content, role, name }

Messages sent by an end user, containing prompts or additional context information.

CompletionsMessages

Given a list of messages comprising a conversation, the model will return a response.

Get chat messages

$ openai chat:completions:messages list

GET/chat/completions/{completion_id}/messages