NAME
OpenAPI::Client::OpenAI::Schema - OpenAI API client Schema
DESCRIPTION
This module contains the schema for the OpenAI API client. To aid in comprehension, the schema has all references resolved. This makes this schema much larger than the original OpenAPI schema.
SCHEMA
---
components:
schemas:
AddUploadPartRequest:
additionalProperties: false
properties: &1
data:
description: |
The chunk of bytes for this Part.
format: binary
type: string
required: &2
- data
type: object
AssistantObject:
description: Represents an `assistant` that can call the model and use tools.
properties: &3
created_at:
description: The Unix timestamp (in seconds) for when the assistant was
created.
type: integer
description:
description: |
The description of the assistant. The maximum length is 512 characters.
maxLength: 512
nullable: true
type: string
id:
description: The identifier, which can be referenced in API endpoints.
type: string
instructions:
description: |
The system instructions that the assistant uses. The maximum length is 256,000 characters.
maxLength: 256000
nullable: true
type: string
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
description: |
ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
type: string
name:
description: |
The name of the assistant. The maximum length is 256 characters.
maxLength: 256
nullable: true
type: string
object:
description: The object type, which is always `assistant`.
enum:
- assistant
type: string
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: &4
- description: "`auto` is the default value\n"
enum:
- auto
type: string
- properties: &5
type:
description: 'The type of response format being defined: `text`'
enum:
- text
type: string
required: &6
- type
type: object
- properties: &7
type:
description: 'The type of response format being defined: `json_object`'
enum:
- json_object
type: string
required: &8
- type
type: object
- properties: &9
json_schema:
properties:
description:
description: A description of what the response format is for,
used by the model to determine how to respond in the format.
type: string
name:
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.
type: string
schema:
additionalProperties: true
description: The schema for the response format, described as
a JSON Schema object.
type: object
strict:
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`. To learn more,
read the [Structured Outputs guide](/docs/guides/structured-outputs).
nullable: true
type: boolean
required:
- type
- name
type: object
type:
description: 'The type of response format being defined: `json_schema`'
enum:
- json_schema
type: string
required: &10
- type
- json_schema
type: object
x-oaiExpandable: true
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
tool_resources:
description: |
A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
properties:
vector_store_ids:
description: |
The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.
items:
type: string
maxItems: 1
type: array
type: object
type: object
tools:
default: []
description: |
A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`.
items:
oneOf:
- properties: &11
type:
description: 'The type of tool being defined: `code_interpreter`'
enum:
- code_interpreter
type: string
required: &12
- type
title: Code interpreter tool
type: object
- properties: &13
file_search:
description: Overrides for the file search tool.
properties:
max_num_results:
description: |
The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive.
Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) for more information.
maximum: 50
minimum: 1
type: integer
ranking_options:
description: |
The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0.
See the [file search tool documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) for more information.
properties: &14
ranker:
description: The ranker to use for the file search. If not
specified will use the `auto` ranker.
enum:
- auto
- default_2024_08_21
type: string
score_threshold:
description: The score threshold for the file search. All
values must be a floating point number between 0 and 1.
maximum: 1
minimum: 0
type: number
required: &15
- score_threshold
title: File search tool call ranking options
type: object
type: object
type:
description: 'The type of tool being defined: `file_search`'
enum:
- file_search
type: string
required: &16
- type
title: FileSearch tool
type: object
- properties: &17
function:
properties: &18
description:
description: A description of what the function does, used by
the model to choose when and how to call the function.
type: string
name:
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.
type: string
parameters:
additionalProperties: true
description: "The parameters the functions accepts, described
as a JSON Schema object. See the [guide](/docs/guides/function-calling)
for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/)
for documentation about the format. \n\nOmitting `parameters`
defines a function with an empty parameter list."
type: object
strict:
default: false
description: Whether to enable strict schema adherence when
generating the function call. If set to true, the model will
follow the exact schema defined in the `parameters` field.
Only a subset of JSON Schema is supported when `strict` is
`true`. Learn more about Structured Outputs in the [function
calling guide](docs/guides/function-calling).
nullable: true
type: boolean
required: &19
- name
type: object
type:
description: 'The type of tool being defined: `function`'
enum:
- function
type: string
required: &20
- type
- function
title: Function tool
type: object
x-oaiExpandable: true
maxItems: 128
type: array
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
required: &21
- id
- object
- created_at
- name
- description
- model
- instructions
- tools
- metadata
title: Assistant
type: object
AssistantStreamEvent:
description: |
Represents an event emitted when streaming a Run.
Each event in a server-sent events stream has an `event` and `data` property:
```
event: thread.created
data: {"id": "thread_123", "object": "thread", ...}
```
We emit events whenever a new object is created, transitions to a new state, or is being
streamed in parts (deltas). For example, we emit `thread.run.created` when a new run
is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses
to create a message during a run, we emit a `thread.message.created event`, a
`thread.message.in_progress` event, many `thread.message.delta` events, and finally a
`thread.message.completed` event.
We may add additional events over time, so we recommend handling unknown events gracefully
in your code. See the [Assistants API quickstart](/docs/assistants/overview) to learn how to
integrate the Assistants API with streaming.
oneOf:
- oneOf: &22
- description: Occurs when a new [thread](/docs/api-reference/threads/object)
is created.
properties:
data:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: &23
created_at:
description: The Unix timestamp (in seconds) for when the thread
was created.
type: integer
id:
description: The identifier, which can be referenced in API endpoints.
type: string
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread`.
enum:
- thread
type: string
tool_resources:
description: |
A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
properties:
vector_store_ids:
description: |
The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread.
items:
type: string
maxItems: 1
type: array
type: object
type: object
required: &24
- id
- object
- created_at
- tool_resources
- metadata
title: Thread
type: object
event:
enum:
- thread.created
type: string
required:
- event
- data
type: object
- oneOf: &25
- description: Occurs when a new [run](/docs/api-reference/runs/object) is
created.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: &26
assistant_id:
description: The ID of the [assistant](/docs/api-reference/assistants)
used for execution of this run.
type: string
cancelled_at:
description: The Unix timestamp (in seconds) for when the run was
cancelled.
nullable: true
type: integer
completed_at:
description: The Unix timestamp (in seconds) for when the run was
completed.
nullable: true
type: integer
created_at:
description: The Unix timestamp (in seconds) for when the run was
created.
type: integer
expires_at:
description: The Unix timestamp (in seconds) for when the run will
expire.
nullable: true
type: integer
failed_at:
description: The Unix timestamp (in seconds) for when the run failed.
nullable: true
type: integer
id:
description: The identifier, which can be referenced in API endpoints.
type: string
incomplete_details:
description: Details on why the run is incomplete. Will be `null`
if the run is not incomplete.
nullable: true
properties:
reason:
description: The reason why the run is incomplete. This will
point to which specific token limit was reached over the course
of the run.
enum:
- max_completion_tokens
- max_prompt_tokens
type: string
type: object
instructions:
description: The instructions that the [assistant](/docs/api-reference/assistants)
used for this run.
type: string
last_error:
description: The last error associated with this run. Will be `null`
if there are no errors.
nullable: true
properties:
code:
description: One of `server_error`, `rate_limit_exceeded`, or
`invalid_prompt`.
enum:
- server_error
- rate_limit_exceeded
- invalid_prompt
type: string
message:
description: A human-readable description of the error.
type: string
required:
- code
- message
type: object
max_completion_tokens:
description: |
The maximum number of completion tokens specified to have been used over the course of the run.
minimum: 256
nullable: true
type: integer
max_prompt_tokens:
description: |
The maximum number of prompt tokens specified to have been used over the course of the run.
minimum: 256
nullable: true
type: integer
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
description: The model that the [assistant](/docs/api-reference/assistants)
used for this run.
type: string
object:
description: The object type, which is always `thread.run`.
enum:
- thread.run
type: string
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
required_action:
description: Details on the action required to continue the run.
Will be `null` if no action is required.
nullable: true
properties:
submit_tool_outputs:
description: Details on the tool outputs needed for this run
to continue.
properties:
tool_calls:
description: A list of the relevant tool calls.
items:
description: Tool call objects
properties: &27
function:
description: The function definition.
properties:
arguments:
description: The arguments that the model expects
you to pass to the function.
type: string
name:
description: The name of the function.
type: string
required:
- name
- arguments
type: object
id:
description: The ID of the tool call. This ID must
be referenced when you submit the tool outputs in
using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs)
endpoint.
type: string
type:
description: The type of tool call the output is required
for. For now, this is always `function`.
enum:
- function
type: string
required: &28
- id
- type
- function
type: object
type: array
required:
- tool_calls
type: object
type:
description: For now, this is always `submit_tool_outputs`.
enum:
- submit_tool_outputs
type: string
required:
- type
- submit_tool_outputs
type: object
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: *4
x-oaiExpandable: true
started_at:
description: The Unix timestamp (in seconds) for when the run was
started.
nullable: true
type: integer
status:
description: The status of the run, which can be either `queued`,
`in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`,
`completed`, `incomplete`, or `expired`.
enum:
- queued
- in_progress
- requires_action
- cancelling
- cancelled
- failed
- completed
- incomplete
- expired
type: string
temperature:
description: The sampling temperature used for this run. If not
set, defaults to 1.
nullable: true
type: number
thread_id:
description: The ID of the [thread](/docs/api-reference/threads)
that was executed on as a part of this run.
type: string
tool_choice:
description: |
Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and 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 before responding to the user.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
nullable: true
oneOf: &29
- description: |
`none` means the model will not call any tools 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 before responding to the user.
enum:
- none
- auto
- required
type: string
- description: Specifies a tool the model should use. Use to force
the model to call a specific tool.
properties: &30
function:
properties:
name:
description: The name of the function to call.
type: string
required:
- name
type: object
type:
description: The type of the tool. If type is `function`,
the function name must be set
enum:
- function
- code_interpreter
- file_search
type: string
required: &31
- type
type: object
x-oaiExpandable: true
tools:
default: []
description: The list of tools that the [assistant](/docs/api-reference/assistants)
used for this run.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *13
required: *16
title: FileSearch tool
type: object
- properties: *17
required: *20
title: Function tool
type: object
x-oaiExpandable: true
maxItems: 20
type: array
top_p:
description: The nucleus sampling value used for this run. If not
set, defaults to 1.
nullable: true
type: number
truncation_strategy:
description: Controls for how a thread will be truncated prior to
the run. Use this to control the intial context window of the
run.
nullable: true
properties: &32
last_messages:
description: The number of most recent messages from the thread
when constructing the context for the run.
minimum: 1
nullable: true
type: integer
type:
description: The truncation strategy to use for the thread.
The default is `auto`. If set to `last_messages`, the thread
will be truncated to the n most recent messages in the thread.
When set to `auto`, messages in the middle of the thread will
be dropped to fit the context length of the model, `max_prompt_tokens`.
enum:
- auto
- last_messages
type: string
required: &33
- type
title: Thread Truncation Controls
type: object
usage:
description: Usage statistics related to the run. This value will
be `null` if the run is not in a terminal state (i.e. `in_progress`,
`queued`, etc.).
nullable: true
properties: &34
completion_tokens:
description: Number of completion tokens used over the course
of the run.
type: integer
prompt_tokens:
description: Number of prompt tokens used over the course of
the run.
type: integer
total_tokens:
description: Total number of tokens used (prompt + completion).
type: integer
required: &35
- prompt_tokens
- completion_tokens
- total_tokens
type: object
required: &36
- id
- object
- created_at
- thread_id
- assistant_id
- status
- required_action
- last_error
- expires_at
- started_at
- cancelled_at
- failed_at
- completed_at
- model
- instructions
- tools
- metadata
- usage
- incomplete_details
- max_prompt_tokens
- max_completion_tokens
- truncation_strategy
- tool_choice
- parallel_tool_calls
- response_format
title: A run on a thread
type: object
event:
enum:
- thread.run.created
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) moves
to a `queued` status.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.queued
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) moves
to an `in_progress` status.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.in_progress
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) moves
to a `requires_action` status.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.requires_action
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) is completed.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.completed
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) ends with
status `incomplete`.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.incomplete
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) fails.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.failed
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) moves
to a `cancelling` status.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.cancelling
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) is cancelled.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.cancelled
type: string
required:
- event
- data
type: object
- description: Occurs when a [run](/docs/api-reference/runs/object) expires.
properties:
data:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
event:
enum:
- thread.run.expired
type: string
required:
- event
- data
type: object
- oneOf: &37
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
is created.
properties:
data:
description: |
Represents a step in execution of a run.
properties: &38
assistant_id:
description: The ID of the [assistant](/docs/api-reference/assistants)
associated with the run step.
type: string
cancelled_at:
description: The Unix timestamp (in seconds) for when the run step
was cancelled.
nullable: true
type: integer
completed_at:
description: The Unix timestamp (in seconds) for when the run step
completed.
nullable: true
type: integer
created_at:
description: The Unix timestamp (in seconds) for when the run step
was created.
type: integer
expired_at:
description: The Unix timestamp (in seconds) for when the run step
expired. A step is considered expired if the parent run is expired.
nullable: true
type: integer
failed_at:
description: The Unix timestamp (in seconds) for when the run step
failed.
nullable: true
type: integer
id:
description: The identifier of the run step, which can be referenced
in API endpoints.
type: string
last_error:
description: The last error associated with this run step. Will
be `null` if there are no errors.
nullable: true
properties:
code:
description: One of `server_error` or `rate_limit_exceeded`.
enum:
- server_error
- rate_limit_exceeded
type: string
message:
description: A human-readable description of the error.
type: string
required:
- code
- message
type: object
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread.run.step`.
enum:
- thread.run.step
type: string
run_id:
description: The ID of the [run](/docs/api-reference/runs) that
this run step is a part of.
type: string
status:
description: The status of the run step, which can be either `in_progress`,
`cancelled`, `failed`, `completed`, or `expired`.
enum:
- in_progress
- cancelled
- failed
- completed
- expired
type: string
step_details:
description: The details of the run step.
oneOf:
- description: Details of the message creation by the run step.
properties: &39
message_creation:
properties:
message_id:
description: The ID of the message that was created by
this run step.
type: string
required:
- message_id
type: object
type:
description: Always `message_creation`.
enum:
- message_creation
type: string
required: &40
- type
- message_creation
title: Message creation
type: object
- description: Details of the tool call.
properties: &41
tool_calls:
description: |
An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`.
items:
oneOf:
- description: Details of the Code Interpreter tool call
the run step was involved in.
properties: &42
code_interpreter:
description: The Code Interpreter tool call definition.
properties:
input:
description: The input to the Code Interpreter
tool call.
type: string
outputs:
description: The outputs from the Code Interpreter
tool call. Code Interpreter can output one or
more items, including text (`logs`) or images
(`image`). Each of these are represented by
a different object type.
items:
oneOf:
- description: Text output from the Code Interpreter
tool call as part of a run step.
properties: &43
logs:
description: The text output from the
Code Interpreter tool call.
type: string
type:
description: Always `logs`.
enum:
- logs
type: string
required: &44
- type
- logs
title: Code Interpreter log output
type: object
- properties: &45
image:
properties:
file_id:
description: The [file](/docs/api-reference/files)
ID of the image.
type: string
required:
- file_id
type: object
type:
description: Always `image`.
enum:
- image
type: string
required: &46
- type
- image
title: Code Interpreter image output
type: object
type: object
x-oaiExpandable: true
type: array
required:
- input
- outputs
type: object
id:
description: The ID of the tool call.
type: string
type:
description: The type of tool call. This is always
going to be `code_interpreter` for this type of
tool call.
enum:
- code_interpreter
type: string
required: &47
- id
- type
- code_interpreter
title: Code Interpreter tool call
type: object
- properties: &48
file_search:
description: For now, this is always going to be an
empty object.
properties:
ranking_options:
description: The ranking options for the file
search.
properties: &49
ranker:
description: The ranker used for the file
search.
enum:
- default_2024_08_21
type: string
score_threshold:
description: The score threshold for the file
search. All values must be a floating point
number between 0 and 1.
maximum: 1
minimum: 0
type: number
required: &50
- ranker
- score_threshold
title: File search tool call ranking options
type: object
results:
description: The results of the file search.
items:
description: A result instance of the file search.
properties: &51
content:
description: The content of the result that
was found. The content is only included
if requested via the include query parameter.
items:
properties:
text:
description: The text content of the
file.
type: string
type:
description: The type of the content.
enum:
- text
type: string
type: object
type: array
file_id:
description: The ID of the file that result
was found in.
type: string
file_name:
description: The name of the file that result
was found in.
type: string
score:
description: The score of the result. All
values must be a floating point number
between 0 and 1.
maximum: 1
minimum: 0
type: number
required: &52
- file_id
- file_name
- score
title: File search tool call result
type: object
x-oaiTypeLabel: map
type: array
type: object
x-oaiTypeLabel: map
id:
description: The ID of the tool call object.
type: string
type:
description: The type of tool call. This is always
going to be `file_search` for this type of tool
call.
enum:
- file_search
type: string
required: &53
- id
- type
- file_search
title: File search tool call
type: object
- properties: &54
function:
description: The definition of the function that was
called.
properties:
arguments:
description: The arguments passed to the function.
type: string
name:
description: The name of the function.
type: string
output:
description: The output of the function. This
will be `null` if the outputs have not been
[submitted](/docs/api-reference/runs/submitToolOutputs)
yet.
nullable: true
type: string
required:
- name
- arguments
- output
type: object
id:
description: The ID of the tool call object.
type: string
type:
description: The type of tool call. This is always
going to be `function` for this type of tool call.
enum:
- function
type: string
required: &55
- id
- type
- function
title: Function tool call
type: object
x-oaiExpandable: true
type: array
type:
description: Always `tool_calls`.
enum:
- tool_calls
type: string
required: &56
- type
- tool_calls
title: Tool calls
type: object
type: object
x-oaiExpandable: true
thread_id:
description: The ID of the [thread](/docs/api-reference/threads)
that was run.
type: string
type:
description: The type of run step, which can be either `message_creation`
or `tool_calls`.
enum:
- message_creation
- tool_calls
type: string
usage:
description: Usage statistics related to the run step. This value
will be `null` while the run step's status is `in_progress`.
nullable: true
properties: &57
completion_tokens:
description: Number of completion tokens used over the course
of the run step.
type: integer
prompt_tokens:
description: Number of prompt tokens used over the course of
the run step.
type: integer
total_tokens:
description: Total number of tokens used (prompt + completion).
type: integer
required: &58
- prompt_tokens
- completion_tokens
- total_tokens
type: object
required: &59
- id
- object
- created_at
- assistant_id
- thread_id
- run_id
- type
- status
- step_details
- last_error
- expired_at
- cancelled_at
- failed_at
- completed_at
- metadata
- usage
title: Run steps
type: object
event:
enum:
- thread.run.step.created
type: string
required:
- event
- data
type: object
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
moves to an `in_progress` state.
properties:
data:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
event:
enum:
- thread.run.step.in_progress
type: string
required:
- event
- data
type: object
- description: Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object)
are being streamed.
properties:
data:
description: |
Represents a run step delta i.e. any changed fields on a run step during streaming.
properties: &60
delta:
description: The delta containing the fields that have changed on
the run step.
properties:
step_details:
description: The details of the run step.
oneOf:
- description: Details of the message creation by the run step.
properties: &61
message_creation:
properties:
message_id:
description: The ID of the message that was created
by this run step.
type: string
type: object
type:
description: Always `message_creation`.
enum:
- message_creation
type: string
required: &62
- type
title: Message creation
type: object
- description: Details of the tool call.
properties: &63
tool_calls:
description: |
An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`.
items:
oneOf:
- description: Details of the Code Interpreter tool
call the run step was involved in.
properties: &64
code_interpreter:
description: The Code Interpreter tool call definition.
properties:
input:
description: The input to the Code Interpreter
tool call.
type: string
outputs:
description: The outputs from the Code Interpreter
tool call. Code Interpreter can output one
or more items, including text (`logs`) or
images (`image`). Each of these are represented
by a different object type.
items:
oneOf:
- description: Text output from the Code
Interpreter tool call as part of a run
step.
properties: &65
index:
description: The index of the output
in the outputs array.
type: integer
logs:
description: The text output from
the Code Interpreter tool call.
type: string
type:
description: Always `logs`.
enum:
- logs
type: string
required: &66
- index
- type
title: Code interpreter log output
type: object
- properties: &67
image:
properties:
file_id:
description: The [file](/docs/api-reference/files)
ID of the image.
type: string
type: object
index:
description: The index of the output
in the outputs array.
type: integer
type:
description: Always `image`.
enum:
- image
type: string
required: &68
- index
- type
title: Code interpreter image output
type: object
type: object
x-oaiExpandable: true
type: array
type: object
id:
description: The ID of the tool call.
type: string
index:
description: The index of the tool call in the
tool calls array.
type: integer
type:
description: The type of tool call. This is always
going to be `code_interpreter` for this type
of tool call.
enum:
- code_interpreter
type: string
required: &69
- index
- type
title: Code interpreter tool call
type: object
- properties: &70
file_search:
description: For now, this is always going to
be an empty object.
type: object
x-oaiTypeLabel: map
id:
description: The ID of the tool call object.
type: string
index:
description: The index of the tool call in the
tool calls array.
type: integer
type:
description: The type of tool call. This is always
going to be `file_search` for this type of tool
call.
enum:
- file_search
type: string
required: &71
- index
- type
- file_search
title: File search tool call
type: object
- properties: &72
function:
description: The definition of the function that
was called.
properties:
arguments:
description: The arguments passed to the function.
type: string
name:
description: The name of the function.
type: string
output:
description: The output of the function. This
will be `null` if the outputs have not been
[submitted](/docs/api-reference/runs/submitToolOutputs)
yet.
nullable: true
type: string
type: object
id:
description: The ID of the tool call object.
type: string
index:
description: The index of the tool call in the
tool calls array.
type: integer
type:
description: The type of tool call. This is always
going to be `function` for this type of tool
call.
enum:
- function
type: string
required: &73
- index
- type
title: Function tool call
type: object
x-oaiExpandable: true
type: array
type:
description: Always `tool_calls`.
enum:
- tool_calls
type: string
required: &74
- type
title: Tool calls
type: object
type: object
x-oaiExpandable: true
type: object
id:
description: The identifier of the run step, which can be referenced
in API endpoints.
type: string
object:
description: The object type, which is always `thread.run.step.delta`.
enum:
- thread.run.step.delta
type: string
required: &75
- id
- object
- delta
title: Run step delta object
type: object
event:
enum:
- thread.run.step.delta
type: string
required:
- event
- data
type: object
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
is completed.
properties:
data:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
event:
enum:
- thread.run.step.completed
type: string
required:
- event
- data
type: object
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
fails.
properties:
data:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
event:
enum:
- thread.run.step.failed
type: string
required:
- event
- data
type: object
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
is cancelled.
properties:
data:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
event:
enum:
- thread.run.step.cancelled
type: string
required:
- event
- data
type: object
- description: Occurs when a [run step](/docs/api-reference/run-steps/step-object)
expires.
properties:
data:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
event:
enum:
- thread.run.step.expired
type: string
required:
- event
- data
type: object
- oneOf: &76
- description: Occurs when a [message](/docs/api-reference/messages/object)
is created.
properties:
data:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: &77
assistant_id:
description: If applicable, the ID of the [assistant](/docs/api-reference/assistants)
that authored this message.
nullable: true
type: string
attachments:
description: A list of files attached to the message, and the tools
they were added to.
items:
properties:
file_id:
description: The ID of the file to attach to the message.
type: string
tools:
description: The tools to add this file to.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: &78
type:
description: 'The type of tool being defined: `file_search`'
enum:
- file_search
type: string
required: &79
- type
title: FileSearch tool
type: object
x-oaiExpandable: true
type: array
type: object
nullable: true
type: array
completed_at:
description: The Unix timestamp (in seconds) for when the message
was completed.
nullable: true
type: integer
content:
description: The content of the message in array of text and/or
images.
items:
oneOf:
- description: References an image [File](/docs/api-reference/files)
in the content of a message.
properties: &80
image_file:
properties:
detail:
default: auto
description: Specifies the detail level of the image
if specified by the user. `low` uses fewer tokens,
you can opt in to high resolution using `high`.
enum:
- auto
- low
- high
type: string
file_id:
description: The [File](/docs/api-reference/files) ID
of the image in the message content. Set `purpose="vision"`
when uploading the File if you need to later display
the file content.
type: string
required:
- file_id
type: object
type:
description: Always `image_file`.
enum:
- image_file
type: string
required: &81
- type
- image_file
title: Image file
type: object
- description: References an image URL in the content of a message.
properties: &82
image_url:
properties:
detail:
default: auto
description: Specifies the detail level of the image.
`low` uses fewer tokens, you can opt in to high resolution
using `high`. Default value is `auto`
enum:
- auto
- low
- high
type: string
url:
description: 'The external URL of the image, must be
a supported image types: jpeg, jpg, png, gif, webp.'
format: uri
type: string
required:
- url
type: object
type:
description: The type of the content part.
enum:
- image_url
type: string
required: &83
- type
- image_url
title: Image URL
type: object
- description: The text content that is part of a message.
properties: &84
text:
properties:
annotations:
items:
oneOf:
- description: A citation within the message that
points to a specific quote from a specific File
associated with the assistant or the message.
Generated when the assistant uses the "file_search"
tool to search files.
properties: &85
end_index:
minimum: 0
type: integer
file_citation:
properties:
file_id:
description: The ID of the specific File
the citation is from.
type: string
required:
- file_id
type: object
start_index:
minimum: 0
type: integer
text:
description: The text in the message content
that needs to be replaced.
type: string
type:
description: Always `file_citation`.
enum:
- file_citation
type: string
required: &86
- type
- text
- file_citation
- start_index
- end_index
title: File citation
type: object
- description: A URL for the file that's generated
when the assistant used the `code_interpreter`
tool to generate a file.
properties: &87
end_index:
minimum: 0
type: integer
file_path:
properties:
file_id:
description: The ID of the file that was
generated.
type: string
required:
- file_id
type: object
start_index:
minimum: 0
type: integer
text:
description: The text in the message content
that needs to be replaced.
type: string
type:
description: Always `file_path`.
enum:
- file_path
type: string
required: &88
- type
- text
- file_path
- start_index
- end_index
title: File path
type: object
x-oaiExpandable: true
type: array
value:
description: The data that makes up the text.
type: string
required:
- value
- annotations
type: object
type:
description: Always `text`.
enum:
- text
type: string
required: &89
- type
- text
title: Text
type: object
- description: The refusal content generated by the assistant.
properties: &90
refusal:
nullable: false
type: string
type:
description: Always `refusal`.
enum:
- refusal
type: string
required: &91
- type
- refusal
title: Refusal
type: object
x-oaiExpandable: true
type: array
created_at:
description: The Unix timestamp (in seconds) for when the message
was created.
type: integer
id:
description: The identifier, which can be referenced in API endpoints.
type: string
incomplete_at:
description: The Unix timestamp (in seconds) for when the message
was marked as incomplete.
nullable: true
type: integer
incomplete_details:
description: On an incomplete message, details about why the message
is incomplete.
nullable: true
properties:
reason:
description: The reason the message is incomplete.
enum:
- content_filter
- max_tokens
- run_cancelled
- run_expired
- run_failed
type: string
required:
- reason
type: object
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread.message`.
enum:
- thread.message
type: string
role:
description: The entity that produced the message. One of `user`
or `assistant`.
enum:
- user
- assistant
type: string
run_id:
description: The ID of the [run](/docs/api-reference/runs) associated
with the creation of this message. Value is `null` when messages
are created manually using the create message or create thread
endpoints.
nullable: true
type: string
status:
description: The status of the message, which can be either `in_progress`,
`incomplete`, or `completed`.
enum:
- in_progress
- incomplete
- completed
type: string
thread_id:
description: The [thread](/docs/api-reference/threads) ID that this
message belongs to.
type: string
required: &92
- id
- object
- created_at
- thread_id
- status
- incomplete_details
- completed_at
- incomplete_at
- role
- content
- assistant_id
- run_id
- attachments
- metadata
title: The message object
type: object
event:
enum:
- thread.message.created
type: string
required:
- event
- data
type: object
- description: Occurs when a [message](/docs/api-reference/messages/object)
moves to an `in_progress` state.
properties:
data:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
event:
enum:
- thread.message.in_progress
type: string
required:
- event
- data
type: object
- description: Occurs when parts of a [Message](/docs/api-reference/messages/object)
are being streamed.
properties:
data:
description: |
Represents a message delta i.e. any changed fields on a message during streaming.
properties: &93
delta:
description: The delta containing the fields that have changed on
the Message.
properties:
content:
description: The content of the message in array of text and/or
images.
items:
oneOf:
- description: References an image [File](/docs/api-reference/files)
in the content of a message.
properties: &94
image_file:
properties:
detail:
default: auto
description: Specifies the detail level of the image
if specified by the user. `low` uses fewer tokens,
you can opt in to high resolution using `high`.
enum:
- auto
- low
- high
type: string
file_id:
description: The [File](/docs/api-reference/files)
ID of the image in the message content. Set `purpose="vision"`
when uploading the File if you need to later display
the file content.
type: string
type: object
index:
description: The index of the content part in the message.
type: integer
type:
description: Always `image_file`.
enum:
- image_file
type: string
required: &95
- index
- type
title: Image file
type: object
- description: The text content that is part of a message.
properties: &96
index:
description: The index of the content part in the message.
type: integer
text:
properties:
annotations:
items:
oneOf:
- description: A citation within the message that
points to a specific quote from a specific
File associated with the assistant or the
message. Generated when the assistant uses
the "file_search" tool to search files.
properties: &97
end_index:
minimum: 0
type: integer
file_citation:
properties:
file_id:
description: The ID of the specific
File the citation is from.
type: string
quote:
description: The specific quote in the
file.
type: string
type: object
index:
description: The index of the annotation
in the text content part.
type: integer
start_index:
minimum: 0
type: integer
text:
description: The text in the message content
that needs to be replaced.
type: string
type:
description: Always `file_citation`.
enum:
- file_citation
type: string
required: &98
- index
- type
title: File citation
type: object
- description: A URL for the file that's generated
when the assistant used the `code_interpreter`
tool to generate a file.
properties: &99
end_index:
minimum: 0
type: integer
file_path:
properties:
file_id:
description: The ID of the file that
was generated.
type: string
type: object
index:
description: The index of the annotation
in the text content part.
type: integer
start_index:
minimum: 0
type: integer
text:
description: The text in the message content
that needs to be replaced.
type: string
type:
description: Always `file_path`.
enum:
- file_path
type: string
required: &100
- index
- type
title: File path
type: object
x-oaiExpandable: true
type: array
value:
description: The data that makes up the text.
type: string
type: object
type:
description: Always `text`.
enum:
- text
type: string
required: &101
- index
- type
title: Text
type: object
- description: The refusal content that is part of a message.
properties: &102
index:
description: The index of the refusal part in the message.
type: integer
refusal:
type: string
type:
description: Always `refusal`.
enum:
- refusal
type: string
required: &103
- index
- type
title: Refusal
type: object
- description: References an image URL in the content of a
message.
properties: &104
image_url:
properties:
detail:
default: auto
description: Specifies the detail level of the image.
`low` uses fewer tokens, you can opt in to high
resolution using `high`.
enum:
- auto
- low
- high
type: string
url:
description: 'The URL of the image, must be a supported
image types: jpeg, jpg, png, gif, webp.'
type: string
type: object
index:
description: The index of the content part in the message.
type: integer
type:
description: Always `image_url`.
enum:
- image_url
type: string
required: &105
- index
- type
title: Image URL
type: object
x-oaiExpandable: true
type: array
role:
description: The entity that produced the message. One of `user`
or `assistant`.
enum:
- user
- assistant
type: string
type: object
id:
description: The identifier of the message, which can be referenced
in API endpoints.
type: string
object:
description: The object type, which is always `thread.message.delta`.
enum:
- thread.message.delta
type: string
required: &106
- id
- object
- delta
title: Message delta object
type: object
event:
enum:
- thread.message.delta
type: string
required:
- event
- data
type: object
- description: Occurs when a [message](/docs/api-reference/messages/object)
is completed.
properties:
data:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
event:
enum:
- thread.message.completed
type: string
required:
- event
- data
type: object
- description: Occurs when a [message](/docs/api-reference/messages/object)
ends before it is completed.
properties:
data:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
event:
enum:
- thread.message.incomplete
type: string
required:
- event
- data
type: object
- description: Occurs when an [error](/docs/guides/error-codes/api-errors) occurs.
This can happen due to an internal server error or a timeout.
properties: &107
data:
properties: &108
code:
nullable: true
type: string
message:
nullable: false
type: string
param:
nullable: true
type: string
type:
nullable: false
type: string
required: &109
- type
- message
- param
- code
type: object
event:
enum:
- error
type: string
required: &110
- event
- data
type: object
- description: Occurs when a stream ends.
properties: &111
data:
enum:
- '[DONE]'
type: string
event:
enum:
- done
type: string
required: &112
- event
- data
type: object
AssistantToolsCode:
properties: *11
required: *12
title: Code interpreter tool
type: object
AssistantToolsFileSearch:
properties: *13
required: *16
title: FileSearch tool
type: object
AssistantToolsFileSearchTypeOnly:
properties: *78
required: *79
title: FileSearch tool
type: object
AssistantToolsFunction:
properties: *17
required: *20
title: Function tool
type: object
AssistantsApiResponseFormatOption:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
oneOf: *4
x-oaiExpandable: true
AssistantsApiToolChoiceOption:
description: |
Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and 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 before responding to the user.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
oneOf: *29
x-oaiExpandable: true
AssistantsNamedToolChoice:
description: Specifies a tool the model should use. Use to force the model to
call a specific tool.
properties: *30
required: *31
type: object
AuditLog:
description: A log of a user action or configuration change within this organization.
properties: &113
actor:
description: The actor who performed the audit logged action.
properties: &114
api_key:
description: The API Key used to perform the audit logged action.
properties: &115
id:
description: The tracking id of the API key.
type: string
service_account:
description: The service account that performed the audit logged
action.
properties: &116
id:
description: The service account id.
type: string
type: object
type:
description: The type of API key. Can be either `user` or `service_account`.
enum:
- user
- service_account
type: string
user:
description: The user who performed the audit logged action.
properties: &117
email:
description: The user email.
type: string
id:
description: The user id.
type: string
type: object
type: object
session:
description: The session in which the audit logged action was performed.
properties: &118
ip_address:
description: The IP address from which the action was performed.
type: string
user:
description: The user who performed the audit logged action.
properties: *117
type: object
type: object
type:
description: The type of actor. Is either `session` or `api_key`.
enum:
- session
- api_key
type: string
type: object
api_key.created:
description: The details for events with this `type`.
properties:
data:
description: The payload used to create the API key.
properties:
scopes:
description: A list of scopes allowed for the API key, e.g. `["api.model.request"]`
items:
type: string
type: array
type: object
id:
description: The tracking ID of the API key.
type: string
type: object
api_key.deleted:
description: The details for events with this `type`.
properties:
id:
description: The tracking ID of the API key.
type: string
type: object
api_key.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to update the API key.
properties:
scopes:
description: A list of scopes allowed for the API key, e.g. `["api.model.request"]`
items:
type: string
type: array
type: object
id:
description: The tracking ID of the API key.
type: string
type: object
effective_at:
description: The Unix timestamp (in seconds) of the event.
type: integer
id:
description: The ID of this log.
type: string
invite.accepted:
description: The details for events with this `type`.
properties:
id:
description: The ID of the invite.
type: string
type: object
invite.deleted:
description: The details for events with this `type`.
properties:
id:
description: The ID of the invite.
type: string
type: object
invite.sent:
description: The details for events with this `type`.
properties:
data:
description: The payload used to create the invite.
properties:
email:
description: The email invited to the organization.
type: string
role:
description: The role the email was invited to be. Is either `owner`
or `member`.
type: string
type: object
id:
description: The ID of the invite.
type: string
type: object
login.failed:
description: The details for events with this `type`.
properties:
error_code:
description: The error code of the failure.
type: string
error_message:
description: The error message of the failure.
type: string
type: object
logout.failed:
description: The details for events with this `type`.
properties:
error_code:
description: The error code of the failure.
type: string
error_message:
description: The error message of the failure.
type: string
type: object
organization.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to update the organization settings.
properties:
description:
description: The organization description.
type: string
name:
description: The organization name.
type: string
settings:
properties:
threads_ui_visibility:
description: Visibility of the threads page which shows messages
created with the Assistants API and Playground. One of `ANY_ROLE`,
`OWNERS`, or `NONE`.
type: string
usage_dashboard_visibility:
description: Visibility of the usage dashboard which shows activity
and costs for your organization. One of `ANY_ROLE` or `OWNERS`.
type: string
type: object
title:
description: The organization title.
type: string
type: object
id:
description: The organization ID.
type: string
type: object
project:
description: The project that the action was scoped to. Absent for actions
not scoped to projects.
properties:
id:
description: The project ID.
type: string
name:
description: The project title.
type: string
type: object
project.archived:
description: The details for events with this `type`.
properties:
id:
description: The project ID.
type: string
type: object
project.created:
description: The details for events with this `type`.
properties:
data:
description: The payload used to create the project.
properties:
name:
description: The project name.
type: string
title:
description: The title of the project as seen on the dashboard.
type: string
type: object
id:
description: The project ID.
type: string
type: object
project.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to update the project.
properties:
title:
description: The title of the project as seen on the dashboard.
type: string
type: object
id:
description: The project ID.
type: string
type: object
service_account.created:
description: The details for events with this `type`.
properties:
data:
description: The payload used to create the service account.
properties:
role:
description: The role of the service account. Is either `owner`
or `member`.
type: string
type: object
id:
description: The service account ID.
type: string
type: object
service_account.deleted:
description: The details for events with this `type`.
properties:
id:
description: The service account ID.
type: string
type: object
service_account.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to updated the service account.
properties:
role:
description: The role of the service account. Is either `owner`
or `member`.
type: string
type: object
id:
description: The service account ID.
type: string
type: object
type:
description: The event type.
enum: &119
- api_key.created
- api_key.updated
- api_key.deleted
- invite.sent
- invite.accepted
- invite.deleted
- login.succeeded
- login.failed
- logout.succeeded
- logout.failed
- organization.updated
- project.created
- project.updated
- project.archived
- service_account.created
- service_account.updated
- service_account.deleted
- user.added
- user.updated
- user.deleted
type: string
x-oaiExpandable: true
user.added:
description: The details for events with this `type`.
properties:
data:
description: The payload used to add the user to the project.
properties:
role:
description: The role of the user. Is either `owner` or `member`.
type: string
type: object
id:
description: The user ID.
type: string
type: object
user.deleted:
description: The details for events with this `type`.
properties:
id:
description: The user ID.
type: string
type: object
user.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to update the user.
properties:
role:
description: The role of the user. Is either `owner` or `member`.
type: string
type: object
id:
description: The project ID.
type: string
type: object
required: &120
- id
- type
- effective_at
- actor
type: object
AuditLogActor:
description: The actor who performed the audit logged action.
properties: *114
type: object
AuditLogActorApiKey:
description: The API Key used to perform the audit logged action.
properties: *115
type: object
AuditLogActorServiceAccount:
description: The service account that performed the audit logged action.
properties: *116
type: object
AuditLogActorSession:
description: The session in which the audit logged action was performed.
properties: *118
type: object
AuditLogActorUser:
description: The user who performed the audit logged action.
properties: *117
type: object
AuditLogEventType:
description: The event type.
enum: *119
type: string
x-oaiExpandable: true
AutoChunkingStrategyRequestParam:
additionalProperties: false
description: The default strategy. This strategy currently uses a `max_chunk_size_tokens`
of `800` and `chunk_overlap_tokens` of `400`.
properties: &121
type:
description: Always `auto`.
enum:
- auto
type: string
required: &122
- type
title: Auto Chunking Strategy
type: object
Batch:
properties: &123
cancelled_at:
description: The Unix timestamp (in seconds) for when the batch was cancelled.
type: integer
cancelling_at:
description: The Unix timestamp (in seconds) for when the batch started
cancelling.
type: integer
completed_at:
description: The Unix timestamp (in seconds) for when the batch was completed.
type: integer
completion_window:
description: The time frame within which the batch should be processed.
type: string
created_at:
description: The Unix timestamp (in seconds) for when the batch was created.
type: integer
endpoint:
description: The OpenAI API endpoint used by the batch.
type: string
error_file_id:
description: The ID of the file containing the outputs of requests with
errors.
type: string
errors:
properties:
data:
items:
properties:
code:
description: An error code identifying the error type.
type: string
line:
description: The line number of the input file where the error
occurred, if applicable.
nullable: true
type: integer
message:
description: A human-readable message providing more details about
the error.
type: string
param:
description: The name of the parameter that caused the error,
if applicable.
nullable: true
type: string
type: object
type: array
object:
description: The object type, which is always `list`.
type: string
type: object
expired_at:
description: The Unix timestamp (in seconds) for when the batch expired.
type: integer
expires_at:
description: The Unix timestamp (in seconds) for when the batch will expire.
type: integer
failed_at:
description: The Unix timestamp (in seconds) for when the batch failed.
type: integer
finalizing_at:
description: The Unix timestamp (in seconds) for when the batch started
finalizing.
type: integer
id:
type: string
in_progress_at:
description: The Unix timestamp (in seconds) for when the batch started
processing.
type: integer
input_file_id:
description: The ID of the input file for the batch.
type: string
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `batch`.
enum:
- batch
type: string
output_file_id:
description: The ID of the file containing the outputs of successfully executed
requests.
type: string
request_counts:
description: The request counts for different statuses within the batch.
properties:
completed:
description: Number of requests that have been completed successfully.
type: integer
failed:
description: Number of requests that have failed.
type: integer
total:
description: Total number of requests in the batch.
type: integer
required:
- total
- completed
- failed
type: object
status:
description: The current status of the batch.
enum:
- validating
- failed
- in_progress
- finalizing
- completed
- expired
- cancelling
- cancelled
type: string
required: &124
- id
- object
- endpoint
- input_file_id
- completion_window
- status
- created_at
type: object
BatchRequestInput:
description: The per-line object of the batch input file
properties:
custom_id:
description: A developer-provided per-request id that will be used to match
outputs to inputs. Must be unique for each request in a batch.
type: string
method:
description: The HTTP method to be used for the request. Currently only
`POST` is supported.
enum:
- POST
type: string
url:
description: The OpenAI API relative URL to be used for the request. Currently
`/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported.
type: string
type: object
BatchRequestOutput:
description: The per-line object of the batch output and error files
properties:
custom_id:
description: A developer-provided per-request id that will be used to match
outputs to inputs.
type: string
error:
description: For requests that failed with a non-HTTP error, this will contain
more information on the cause of the failure.
nullable: true
properties:
code:
description: A machine-readable error code.
type: string
message:
description: A human-readable error message.
type: string
type: object
id:
type: string
response:
nullable: true
properties:
body:
description: The JSON body of the response
type: object
x-oaiTypeLabel: map
request_id:
description: An unique identifier for the OpenAI API request. Please
include this request ID when contacting support.
type: string
status_code:
description: The HTTP status code of the response
type: integer
type: object
type: object
CancelUploadRequest:
additionalProperties: false
type: object
ChatCompletionFunctionCallOption:
description: |
Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
properties: &125
name:
description: The name of the function to call.
type: string
required: &126
- name
type: object
ChatCompletionFunctions:
deprecated: true
properties: &127
description:
description: A description of what the function does, used by the model
to choose when and how to call the function.
type: string
name:
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.
type: string
parameters:
additionalProperties: true
description: "The parameters the functions accepts, described as a JSON
Schema object. See the [guide](/docs/guides/function-calling) for examples,
and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/)
for documentation about the format. \n\nOmitting `parameters` defines
a function with an empty parameter list."
type: object
required: &128
- name
type: object
ChatCompletionMessageToolCall:
properties: &129
function:
description: The function that the model called.
properties:
arguments:
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.
type: string
name:
description: The name of the function to call.
type: string
required:
- name
- arguments
type: object
id:
description: The ID of the tool call.
type: string
type:
description: The type of the tool. Currently, only `function` is supported.
enum:
- function
type: string
required: &130
- id
- type
- function
type: object
ChatCompletionMessageToolCallChunk:
properties: &131
function:
properties:
arguments:
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.
type: string
name:
description: The name of the function to call.
type: string
type: object
id:
description: The ID of the tool call.
type: string
index:
type: integer
type:
description: The type of the tool. Currently, only `function` is supported.
enum:
- function
type: string
required: &132
- index
type: object
ChatCompletionMessageToolCalls:
description: The tool calls generated by the model, such as function calls.
items: &133
properties: *129
required: *130
type: object
type: array
ChatCompletionNamedToolChoice:
description: Specifies a tool the model should use. Use to force the model to
call a specific function.
properties: &134
function:
properties:
name:
description: The name of the function to call.
type: string
required:
- name
type: object
type:
description: The type of the tool. Currently, only `function` is supported.
enum:
- function
type: string
required: &135
- type
- function
type: object
ChatCompletionRequestAssistantMessage:
properties: &136
content:
description: |
The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified.
nullable: true
oneOf:
- description: The contents of the assistant message.
title: Text content
type: string
- description: An array of content parts with a defined type. Can be one
or more of type `text`, or exactly one of type `refusal`.
items:
oneOf: &137
- properties: &138
text:
description: The text content.
type: string
type:
description: The type of the content part.
enum:
- text
type: string
required: &139
- type
- text
title: Text content part
type: object
- properties: &140
refusal:
description: The refusal message generated by the model.
type: string
type:
description: The type of the content part.
enum:
- refusal
type: string
required: &141
- type
- refusal
title: Refusal content part
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
function_call:
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.
nullable: true
properties:
arguments:
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.
type: string
name:
description: The name of the function to call.
type: string
required:
- arguments
- name
type: object
name:
description: An optional name for the participant. Provides the model information
to differentiate between participants of the same role.
type: string
refusal:
description: The refusal message by the assistant.
nullable: true
type: string
role:
description: The role of the messages author, in this case `assistant`.
enum:
- assistant
type: string
tool_calls:
description: The tool calls generated by the model, such as function calls.
items: *133
type: array
required: &142
- role
title: Assistant message
type: object
ChatCompletionRequestAssistantMessageContentPart:
oneOf: *137
x-oaiExpandable: true
ChatCompletionRequestFunctionMessage:
deprecated: true
properties: &143
content:
description: The contents of the function message.
nullable: true
type: string
name:
description: The name of the function to call.
type: string
role:
description: The role of the messages author, in this case `function`.
enum:
- function
type: string
required: &144
- role
- content
- name
title: Function message
type: object
ChatCompletionRequestMessage:
oneOf: &145
- properties: &146
content:
description: The contents of the system message.
oneOf:
- description: The contents of the system message.
title: Text content
type: string
- description: An array of content parts with a defined type. For system
messages, only type `text` is supported.
items:
oneOf: &147
- properties: *138
required: *139
title: Text content part
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
name:
description: An optional name for the participant. Provides the model
information to differentiate between participants of the same role.
type: string
role:
description: The role of the messages author, in this case `system`.
enum:
- system
type: string
required: &148
- content
- role
title: System message
type: object
- properties: &149
content:
description: |
The contents of the user message.
oneOf:
- description: The text contents of the message.
title: Text content
type: string
- description: An array of content parts with a defined type, each can
be of type `text` or `image_url` when passing in images. You can pass
multiple images by adding multiple `image_url` content parts. Image
input is only supported when using the `gpt-4o` model.
items:
oneOf: &150
- properties: *138
required: *139
title: Text content part
type: object
- properties: &151
image_url:
properties:
detail:
default: auto
description: Specifies the detail level of the image. Learn
more in the [Vision guide](/docs/guides/vision/low-or-high-fidelity-image-understanding).
enum:
- auto
- low
- high
type: string
url:
description: Either a URL of the image or the base64 encoded
image data.
format: uri
type: string
required:
- url
type: object
type:
description: The type of the content part.
enum:
- image_url
type: string
required: &152
- type
- image_url
title: Image content part
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
x-oaiExpandable: true
name:
description: An optional name for the participant. Provides the model
information to differentiate between participants of the same role.
type: string
role:
description: The role of the messages author, in this case `user`.
enum:
- user
type: string
required: &153
- content
- role
title: User message
type: object
- properties: *136
required: *142
title: Assistant message
type: object
- properties: &154
content:
description: The contents of the tool message.
oneOf:
- description: The contents of the tool message.
title: Text content
type: string
- description: An array of content parts with a defined type. For tool
messages, only type `text` is supported.
items:
oneOf: &155
- properties: *138
required: *139
title: Text content part
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
role:
description: The role of the messages author, in this case `tool`.
enum:
- tool
type: string
tool_call_id:
description: Tool call that this message is responding to.
type: string
required: &156
- role
- content
- tool_call_id
title: Tool message
type: object
- deprecated: true
properties: *143
required: *144
title: Function message
type: object
x-oaiExpandable: true
ChatCompletionRequestMessageContentPartImage:
properties: *151
required: *152
title: Image content part
type: object
ChatCompletionRequestMessageContentPartRefusal:
properties: *140
required: *141
title: Refusal content part
type: object
ChatCompletionRequestMessageContentPartText:
properties: *138
required: *139
title: Text content part
type: object
ChatCompletionRequestSystemMessage:
properties: *146
required: *148
title: System message
type: object
ChatCompletionRequestSystemMessageContentPart:
oneOf: *147
x-oaiExpandable: true
ChatCompletionRequestToolMessage:
properties: *154
required: *156
title: Tool message
type: object
ChatCompletionRequestToolMessageContentPart:
oneOf: *155
x-oaiExpandable: true
ChatCompletionRequestUserMessage:
properties: *149
required: *153
title: User message
type: object
ChatCompletionRequestUserMessageContentPart:
oneOf: *150
x-oaiExpandable: true
ChatCompletionResponseMessage:
description: A chat completion message generated by the model.
properties: &157
content:
description: The contents of the message.
nullable: true
type: string
function_call:
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:
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.
type: string
name:
description: The name of the function to call.
type: string
required:
- name
- arguments
type: object
refusal:
description: The refusal message generated by the model.
nullable: true
type: string
role:
description: The role of the author of this message.
enum:
- assistant
type: string
tool_calls:
description: The tool calls generated by the model, such as function calls.
items: *133
type: array
required: &158
- role
- content
- refusal
type: object
ChatCompletionRole:
description: The role of the author of a message
enum:
- system
- user
- assistant
- tool
- function
type: string
ChatCompletionStreamOptions:
default: ~
description: |
Options for streaming response. Only set this when you set `stream: true`.
nullable: true
properties: &159
include_usage:
description: |
If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value.
type: boolean
type: object
ChatCompletionStreamResponseDelta:
description: A chat completion delta generated by streamed model responses.
properties: &160
content:
description: The contents of the chunk message.
nullable: true
type: string
function_call:
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:
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.
type: string
name:
description: The name of the function to call.
type: string
type: object
refusal:
description: The refusal message generated by the model.
nullable: true
type: string
role:
description: The role of the author of this message.
enum:
- system
- user
- assistant
- tool
type: string
tool_calls:
items:
properties: *131
required: *132
type: object
type: array
type: object
ChatCompletionTokenLogprob:
properties: &161
bytes: &162
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.
items:
type: integer
nullable: true
type: array
logprob: &163
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
token: &164
description: The token.
type: string
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.
items:
properties:
bytes: *162
logprob: *163
token: *164
required:
- token
- logprob
- bytes
type: object
type: array
required: &165
- token
- logprob
- bytes
- top_logprobs
type: object
ChatCompletionTool:
properties: &166
function:
properties: *18
required: *19
type: object
type:
description: The type of the tool. Currently, only `function` is supported.
enum:
- function
type: string
required: &167
- type
- function
type: object
ChatCompletionToolChoiceOption:
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: &168
- 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
type: string
- description: Specifies a tool the model should use. Use to force the model
to call a specific function.
properties: *134
required: *135
type: object
x-oaiExpandable: true
ChunkingStrategyRequestParam:
description: The chunking strategy used to chunk the file(s). If not set, will
use the `auto` strategy.
oneOf: &169
- additionalProperties: false
description: The default strategy. This strategy currently uses a `max_chunk_size_tokens`
of `800` and `chunk_overlap_tokens` of `400`.
properties: *121
required: *122
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties: &170
static:
additionalProperties: false
properties: &171
chunk_overlap_tokens:
description: |
The number of tokens that overlap between chunks. The default value is `400`.
Note that the overlap must not exceed half of `max_chunk_size_tokens`.
type: integer
max_chunk_size_tokens:
description: The maximum number of tokens in each chunk. The default
value is `800`. The minimum value is `100` and the maximum value
is `4096`.
maximum: 4096
minimum: 100
type: integer
required: &172
- max_chunk_size_tokens
- chunk_overlap_tokens
type: object
type:
description: Always `static`.
enum:
- static
type: string
required: &173
- type
- static
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
CompleteUploadRequest:
additionalProperties: false
properties: &174
md5:
description: |
The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.
type: string
part_ids:
description: "The ordered list of Part IDs.\n"
items:
type: string
type: array
required: &175
- part_ids
type: object
CompletionUsage:
description: Usage statistics for the completion request.
properties: &176
completion_tokens:
description: Number of tokens in the generated completion.
type: integer
completion_tokens_details:
description: Breakdown of tokens used in a completion.
properties:
reasoning_tokens:
description: Tokens generated by the model for reasoning.
type: integer
type: object
prompt_tokens:
description: Number of tokens in the prompt.
type: integer
total_tokens:
description: Total number of tokens used in the request (prompt + completion).
type: integer
required: &177
- prompt_tokens
- completion_tokens
- total_tokens
type: object
CreateAssistantRequest:
additionalProperties: false
properties: &178
description:
description: |
The description of the assistant. The maximum length is 512 characters.
maxLength: 512
nullable: true
type: string
instructions:
description: |
The system instructions that the assistant uses. The maximum length is 256,000 characters.
maxLength: 256000
nullable: true
type: string
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum:
- gpt-4o
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- gpt-4o-2024-08-06
- gpt-4o-mini
- gpt-4o-mini-2024-07-18
- gpt-4-turbo
- gpt-4-turbo-2024-04-09
- gpt-4-0125-preview
- gpt-4-turbo-preview
- gpt-4-1106-preview
- gpt-4-vision-preview
- gpt-4
- gpt-4-0314
- gpt-4-0613
- gpt-4-32k
- gpt-4-32k-0314
- gpt-4-32k-0613
- gpt-3.5-turbo
- gpt-3.5-turbo-16k
- gpt-3.5-turbo-0613
- gpt-3.5-turbo-1106
- gpt-3.5-turbo-0125
- gpt-3.5-turbo-16k-0613
type: string
description: |
ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
example: gpt-4o
x-oaiTypeLabel: string
name:
description: |
The name of the assistant. The maximum length is 256 characters.
maxLength: 256
nullable: true
type: string
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: *4
x-oaiExpandable: true
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
tool_resources:
description: |
A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
oneOf:
- required:
- vector_store_ids
- required:
- vector_stores
properties:
vector_store_ids:
description: |
The [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.
items:
type: string
maxItems: 1
type: array
vector_stores:
description: |
A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant.
items:
properties:
chunking_strategy:
description: The chunking strategy used to chunk the file(s).
If not set, will use the `auto` strategy.
oneOf:
- additionalProperties: false
description: The default strategy. This strategy currently
uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens`
of `400`.
properties:
type:
description: Always `auto`.
enum:
- auto
type: string
required:
- type
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties:
static:
additionalProperties: false
properties:
chunk_overlap_tokens:
description: |
The number of tokens that overlap between chunks. The default value is `400`.
Note that the overlap must not exceed half of `max_chunk_size_tokens`.
type: integer
max_chunk_size_tokens:
description: The maximum number of tokens in each
chunk. The default value is `800`. The minimum
value is `100` and the maximum value is `4096`.
maximum: 4096
minimum: 100
type: integer
required:
- max_chunk_size_tokens
- chunk_overlap_tokens
type: object
type:
description: Always `static`.
enum:
- static
type: string
required:
- type
- static
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
file_ids:
description: |
A list of [file](/docs/api-reference/files) IDs to add to the vector store. There can be a maximum of 10000 files in a vector store.
items:
type: string
maxItems: 10000
type: array
metadata:
description: |
Set of 16 key-value pairs that can be attached to a vector store. This can be useful for storing additional information about the vector store in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
type: object
x-oaiTypeLabel: map
type: object
maxItems: 1
type: array
type: object
type: object
tools:
default: []
description: |
A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *13
required: *16
title: FileSearch tool
type: object
- properties: *17
required: *20
title: Function tool
type: object
x-oaiExpandable: true
maxItems: 128
type: array
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
required: &179
- model
type: object
CreateChatCompletionFunctionResponse:
description: Represents a chat completion response returned by model, based
on the provided input.
properties:
choices:
description: A list of chat completion choices. Can be more than one if
`n` is greater than 1.
items:
properties:
finish_reason:
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, `content_filter` if content was omitted due to a flag from our content filters, or `function_call` if the model called a function.
enum:
- stop
- length
- function_call
- content_filter
type: string
index:
description: The index of the choice in the list of choices.
type: integer
message:
description: A chat completion message generated by the model.
properties: *157
required: *158
type: object
required:
- finish_reason
- index
- message
- logprobs
type: object
type: array
created:
description: The Unix timestamp (in seconds) of when the chat completion
was created.
type: integer
id:
description: A unique identifier for the chat completion.
type: string
model:
description: The model used for the chat completion.
type: string
object:
description: The object type, which is always `chat.completion`.
enum:
- chat.completion
type: string
system_fingerprint:
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.
type: string
usage:
description: Usage statistics for the completion request.
properties: *176
required: *177
type: object
required:
- choices
- created
- id
- model
- object
type: object
CreateChatCompletionImageResponse:
description: Represents a streamed chunk of a chat completion response returned
by model, based on the provided input.
type: object
CreateChatCompletionRequest:
properties: &180
frequency_penalty:
default: 0
description: |
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
[See more information about frequency and presence penalties.](/docs/guides/text-generation/parameter-details)
maximum: 2
minimum: -2
nullable: true
type: number
function_call:
deprecated: true
description: |
Deprecated in favor of `tool_choice`.
Controls which (if any) function is called by the model.
`none` means the model will not call a function and instead generates a message.
`auto` means the model can pick between generating a message or calling a function.
Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
`none` is the default when no functions are present. `auto` is the default if functions are present.
oneOf:
- description: |
`none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function.
enum:
- none
- auto
type: string
- description: |
Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
properties: *125
required: *126
type: object
x-oaiExpandable: true
functions:
deprecated: true
description: |
Deprecated in favor of `tools`.
A list of functions the model may generate JSON inputs for.
items:
deprecated: true
properties: *127
required: *128
type: object
maxItems: 128
minItems: 1
type: array
logit_bias:
additionalProperties:
type: integer
default: ~
description: |
Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
nullable: true
type: object
x-oaiTypeLabel: map
logprobs:
default: false
description: Whether to return log probabilities of the output tokens or
not. If true, returns the log probabilities of each output token returned
in the `content` of `message`.
nullable: true
type: boolean
max_completion_tokens:
description: |
An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](/docs/guides/reasoning).
nullable: true
type: integer
max_tokens:
deprecated: true
description: |
The maximum number of [tokens](/tokenizer) that can be generated in the chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API.
This value is now deprecated in favor of `max_completion_tokens`, and is not compatible with [o1 series models](/docs/guides/reasoning).
nullable: true
type: integer
messages:
description: A list of messages comprising the conversation so far. [Example
Python code](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models).
items:
oneOf: *145
x-oaiExpandable: true
minItems: 1
type: array
model:
anyOf:
- type: string
- enum:
- o1-preview
- o1-preview-2024-09-12
- o1-mini
- o1-mini-2024-09-12
- gpt-4o
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- gpt-4o-2024-08-06
- chatgpt-4o-latest
- gpt-4o-mini
- gpt-4o-mini-2024-07-18
- gpt-4-turbo
- gpt-4-turbo-2024-04-09
- gpt-4-0125-preview
- gpt-4-turbo-preview
- gpt-4-1106-preview
- gpt-4-vision-preview
- gpt-4
- gpt-4-0314
- gpt-4-0613
- gpt-4-32k
- gpt-4-32k-0314
- gpt-4-32k-0613
- gpt-3.5-turbo
- gpt-3.5-turbo-16k
- gpt-3.5-turbo-0301
- gpt-3.5-turbo-0613
- gpt-3.5-turbo-1106
- gpt-3.5-turbo-0125
- gpt-3.5-turbo-16k-0613
type: string
description: ID of the model to use. See the [model endpoint compatibility](/docs/models/model-endpoint-compatibility)
table for details on which models work with the Chat API.
example: gpt-4o
x-oaiTypeLabel: string
n:
default: 1
description: How many chat completion choices to generate for each input
message. Note that you will be charged based on the number of generated
tokens across all of the choices. Keep `n` as `1` to minimize costs.
example: 1
maximum: 128
minimum: 1
nullable: true
type: integer
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
presence_penalty:
default: 0
description: |
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
[See more information about frequency and presence penalties.](/docs/guides/text-generation/parameter-details)
maximum: 2
minimum: -2
nullable: true
type: number
response_format:
description: |
An object specifying the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4o mini](/docs/models/gpt-4o-mini), [GPT-4 Turbo](/docs/models/gpt-4-and-gpt-4-turbo) and all GPT-3.5 Turbo models newer than `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
oneOf:
- properties: *5
required: *6
type: object
- properties: *7
required: *8
type: object
- properties: *9
required: *10
type: object
x-oaiExpandable: true
seed:
description: |
This feature is in Beta.
If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.
Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
maximum: 9223372036854775807
minimum: -9223372036854775808
nullable: true
type: integer
service_tier:
default: ~
description: "Specifies the latency tier to use for processing the request.
This parameter is relevant for customers subscribed to the scale tier
service:\n - If set to 'auto', and the Project is Scale tier enabled,
the system will utilize scale tier credits until they are exhausted. \n
\ - If set to 'auto', and the Project is not Scale tier enabled, the request
will be processed using the default service tier with a lower uptime SLA
and no latency guarentee.\n - If set to 'default', the request will be
processed using the default service tier with a lower uptime SLA and no
latency guarentee.\n - When not set, the default behavior is 'auto'.\n\n
\ When this parameter is set, the response body will include the `service_tier`
utilized.\n"
enum:
- auto
- default
nullable: true
type: string
stop:
default: ~
description: |
Up to 4 sequences where the API will stop generating further tokens.
oneOf:
- nullable: true
type: string
- items:
type: string
maxItems: 4
minItems: 1
type: array
stream:
default: false
description: |
If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).
nullable: true
type: boolean
stream_options:
default: ~
description: |
Options for streaming response. Only set this when you set `stream: true`.
nullable: true
properties: *159
type: object
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
We generally recommend altering this or `top_p` but not both.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
tool_choice:
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: *168
x-oaiExpandable: true
tools:
description: |
A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
items:
properties: *166
required: *167
type: object
type: array
top_logprobs:
description: An integer between 0 and 20 specifying the number of most likely
tokens to return at each token position, each with an associated log probability.
`logprobs` must be set to `true` if this parameter is used.
maximum: 20
minimum: 0
nullable: true
type: integer
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or `temperature` but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
user: &181
description: |
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices/end-user-ids).
example: user-1234
type: string
required: &182
- model
- messages
type: object
CreateChatCompletionResponse:
description: Represents a chat completion response returned by model, based
on the provided input.
properties: &183
choices:
description: A list of chat completion choices. Can be more than one if
`n` is greater than 1.
items:
properties:
finish_reason:
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,
`content_filter` if content was omitted due to a flag from our content filters,
`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
enum:
- stop
- length
- tool_calls
- content_filter
- function_call
type: string
index:
description: The index of the choice in the list of choices.
type: integer
logprobs: &184
description: Log probability information for the choice.
nullable: true
properties:
content:
description: A list of message content tokens with log probability
information.
items:
properties: *161
required: *165
type: object
nullable: true
type: array
refusal:
description: A list of message refusal tokens with log probability
information.
items:
properties: *161
required: *165
type: object
nullable: true
type: array
required:
- content
- refusal
type: object
message:
description: A chat completion message generated by the model.
properties: *157
required: *158
type: object
required:
- finish_reason
- index
- message
- logprobs
type: object
type: array
created:
description: The Unix timestamp (in seconds) of when the chat completion
was created.
type: integer
id:
description: A unique identifier for the chat completion.
type: string
model:
description: The model used for the chat completion.
type: string
object:
description: The object type, which is always `chat.completion`.
enum:
- chat.completion
type: string
service_tier:
description: The service tier used for processing the request. This field
is only included if the `service_tier` parameter is specified in the request.
enum:
- scale
- default
example: scale
nullable: true
type: string
system_fingerprint:
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.
type: string
usage:
description: Usage statistics for the completion request.
properties: *176
required: *177
type: object
required: &185
- choices
- created
- id
- model
- object
type: object
CreateChatCompletionStreamResponse:
description: Represents a streamed chunk of a chat completion response returned
by model, based on the provided input.
properties:
choices:
description: |
A list of chat completion choices. Can contain more than one elements if `n` is greater than 1. Can also be empty for the
last chunk if you set `stream_options: {"include_usage": true}`.
items:
properties:
delta:
description: A chat completion delta generated by streamed model responses.
properties: *160
type: object
finish_reason:
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,
`content_filter` if content was omitted due to a flag from our content filters,
`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
enum:
- stop
- length
- tool_calls
- content_filter
- function_call
nullable: true
type: string
index:
description: The index of the choice in the list of choices.
type: integer
logprobs: *184
required:
- delta
- finish_reason
- index
type: object
type: array
created:
description: The Unix timestamp (in seconds) of when the chat completion
was created. Each chunk has the same timestamp.
type: integer
id:
description: A unique identifier for the chat completion. Each chunk has
the same ID.
type: string
model:
description: The model to generate the completion.
type: string
object:
description: The object type, which is always `chat.completion.chunk`.
enum:
- chat.completion.chunk
type: string
service_tier:
description: The service tier used for processing the request. This field
is only included if the `service_tier` parameter is specified in the request.
enum:
- scale
- default
example: scale
nullable: true
type: string
system_fingerprint:
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.
type: string
usage:
description: |
An optional field that will only be present when you set `stream_options: {"include_usage": true}` in your request.
When present, it contains a null value except for the last chunk which contains the token usage statistics for the entire request.
properties:
completion_tokens:
description: Number of tokens in the generated completion.
type: integer
prompt_tokens:
description: Number of tokens in the prompt.
type: integer
total_tokens:
description: Total number of tokens used in the request (prompt + completion).
type: integer
required:
- prompt_tokens
- completion_tokens
- total_tokens
type: object
required:
- choices
- created
- id
- model
- object
type: object
CreateCompletionRequest:
properties: &186
best_of:
default: 1
description: |
Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.
When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.
**Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
maximum: 20
minimum: 0
nullable: true
type: integer
echo:
default: false
description: |
Echo back the prompt in addition to the completion
nullable: true
type: boolean
frequency_penalty:
default: 0
description: |
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
[See more information about frequency and presence penalties.](/docs/guides/text-generation/parameter-details)
maximum: 2
minimum: -2
nullable: true
type: number
logit_bias:
additionalProperties:
type: integer
default: ~
description: |
Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated.
nullable: true
type: object
x-oaiTypeLabel: map
logprobs:
default: ~
description: |
Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.
The maximum value for `logprobs` is 5.
maximum: 5
minimum: 0
nullable: true
type: integer
max_tokens:
default: 16
description: |
The maximum number of [tokens](/tokenizer) that can be generated in the completion.
The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
example: 16
minimum: 0
nullable: true
type: integer
model:
anyOf:
- type: string
- enum:
- gpt-3.5-turbo-instruct
- davinci-002
- babbage-002
type: string
description: |
ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
x-oaiTypeLabel: string
n:
default: 1
description: |
How many completions to generate for each prompt.
**Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
example: 1
maximum: 128
minimum: 1
nullable: true
type: integer
presence_penalty:
default: 0
description: |
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
[See more information about frequency and presence penalties.](/docs/guides/text-generation/parameter-details)
maximum: 2
minimum: -2
nullable: true
type: number
prompt:
default: <|endoftext|>
description: |
The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
nullable: true
oneOf:
- default: ''
example: This is a test.
type: string
- items:
default: ''
example: This is a test.
type: string
type: array
- example: '[1212, 318, 257, 1332, 13]'
items:
type: integer
minItems: 1
type: array
- example: '[[1212, 318, 257, 1332, 13]]'
items:
items:
type: integer
minItems: 1
type: array
minItems: 1
type: array
seed:
description: |
If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.
Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
maximum: 9223372036854775807
minimum: -9223372036854775808
nullable: true
type: integer
stop:
default: ~
description: |
Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
nullable: true
oneOf:
- default: <|endoftext|>
example: "\n"
nullable: true
type: string
- items:
example: '["\n"]'
type: string
maxItems: 4
minItems: 1
type: array
stream:
default: false
description: |
Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).
nullable: true
type: boolean
stream_options:
default: ~
description: |
Options for streaming response. Only set this when you set `stream: true`.
nullable: true
properties: *159
type: object
suffix:
default: ~
description: |
The suffix that comes after a completion of inserted text.
This parameter is only supported for `gpt-3.5-turbo-instruct`.
example: test.
nullable: true
type: string
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
We generally recommend altering this or `top_p` but not both.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or `temperature` but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
user: *181
required: &187
- model
- prompt
type: object
CreateCompletionResponse:
description: |
Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
properties: &188
choices:
description: The list of completion choices the model generated for the
input prompt.
items:
properties:
finish_reason:
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,
or `content_filter` if content was omitted due to a flag from our content filters.
enum:
- stop
- length
- content_filter
type: string
index:
type: integer
logprobs:
nullable: true
properties:
text_offset:
items:
type: integer
type: array
token_logprobs:
items:
type: number
type: array
tokens:
items:
type: string
type: array
top_logprobs:
items:
additionalProperties:
type: number
type: object
type: array
type: object
text:
type: string
required:
- finish_reason
- index
- logprobs
- text
type: object
type: array
created:
description: The Unix timestamp (in seconds) of when the completion was
created.
type: integer
id:
description: A unique identifier for the completion.
type: string
model:
description: The model used for completion.
type: string
object:
description: The object type, which is always "text_completion"
enum:
- text_completion
type: string
system_fingerprint:
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.
type: string
usage:
description: Usage statistics for the completion request.
properties: *176
required: *177
type: object
required: &189
- id
- object
- created
- model
- choices
type: object
CreateEmbeddingRequest:
additionalProperties: false
properties: &190
dimensions:
description: |
The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models.
minimum: 1
type: integer
encoding_format:
default: float
description: The format to return the embeddings in. Can be either `float`
or [`base64`](https://pypi.org/project/pybase64/).
enum:
- float
- base64
example: float
type: string
input:
description: |
Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
example: The quick brown fox jumped over the lazy dog
oneOf:
- default: ''
description: The string that will be turned into an embedding.
example: This is a test.
title: string
type: string
- description: The array of strings that will be turned into an embedding.
items:
default: ''
example: '[''This is a test.'']'
type: string
maxItems: 2048
minItems: 1
title: array
type: array
- description: The array of integers that will be turned into an embedding.
example: '[1212, 318, 257, 1332, 13]'
items:
type: integer
maxItems: 2048
minItems: 1
title: array
type: array
- description: The array of arrays containing integers that will be turned
into an embedding.
example: '[[1212, 318, 257, 1332, 13]]'
items:
items:
type: integer
minItems: 1
type: array
maxItems: 2048
minItems: 1
title: array
type: array
x-oaiExpandable: true
model:
anyOf:
- type: string
- enum:
- text-embedding-ada-002
- text-embedding-3-small
- text-embedding-3-large
type: string
description: |
ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
example: text-embedding-3-small
x-oaiTypeLabel: string
user: *181
required: &191
- model
- input
type: object
CreateEmbeddingResponse:
properties: &192
data:
description: The list of embeddings generated by the model.
items:
description: |
Represents an embedding vector returned by embedding endpoint.
properties: &193
embedding:
description: |
The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the [embedding guide](/docs/guides/embeddings).
items:
type: number
type: array
index:
description: The index of the embedding in the list of embeddings.
type: integer
object:
description: The object type, which is always "embedding".
enum:
- embedding
type: string
required: &194
- index
- object
- embedding
type: object
type: array
model:
description: The name of the model used to generate the embedding.
type: string
object:
description: The object type, which is always "list".
enum:
- list
type: string
usage:
description: The usage information for the request.
properties:
prompt_tokens:
description: The number of tokens used by the prompt.
type: integer
total_tokens:
description: The total number of tokens used by the request.
type: integer
required:
- prompt_tokens
- total_tokens
type: object
required: &195
- object
- model
- data
- usage
type: object
CreateFileRequest:
additionalProperties: false
properties: &196
file:
description: |
The File object (not file name) to be uploaded.
format: binary
type: string
purpose:
description: |
The intended purpose of the uploaded file.
Use "assistants" for [Assistants](/docs/api-reference/assistants) and [Message](/docs/api-reference/messages) files, "vision" for Assistants image file inputs, "batch" for [Batch API](/docs/guides/batch), and "fine-tune" for [Fine-tuning](/docs/api-reference/fine-tuning).
enum:
- assistants
- batch
- fine-tune
- vision
type: string
required: &197
- file
- purpose
type: object
CreateFineTuningJobRequest:
properties: &198
hyperparameters:
description: The hyperparameters used for the fine-tuning job.
properties:
batch_size:
default: auto
description: |
Number of examples in each batch. A larger batch size means that model parameters
are updated less frequently, but with lower variance.
oneOf:
- enum:
- auto
type: string
- maximum: 256
minimum: 1
type: integer
learning_rate_multiplier:
default: auto
description: |
Scaling factor for the learning rate. A smaller learning rate may be useful to avoid
overfitting.
oneOf:
- enum:
- auto
type: string
- exclusiveMinimum: true
minimum: 0
type: number
n_epochs:
default: auto
description: |
The number of epochs to train the model for. An epoch refers to one full cycle
through the training dataset.
oneOf:
- enum:
- auto
type: string
- maximum: 50
minimum: 1
type: integer
type: object
integrations:
description: A list of integrations to enable for your fine-tuning job.
items:
properties:
type:
description: |
The type of integration to enable. Currently, only "wandb" (Weights and Biases) is supported.
oneOf:
- enum:
- wandb
type: string
wandb:
description: |
The settings for your integration with Weights and Biases. This payload specifies the project that
metrics will be sent to. Optionally, you can set an explicit display name for your run, add tags
to your run, and set a default entity (team, username, etc) to be associated with your run.
properties:
entity:
description: |
The entity to use for the run. This allows you to set the team or username of the WandB user that you would
like associated with the run. If not set, the default entity for the registered WandB API key is used.
nullable: true
type: string
name:
description: |
A display name to set for the run. If not set, we will use the Job ID as the name.
nullable: true
type: string
project:
description: |
The name of the project that the new run will be created under.
example: my-wandb-project
type: string
tags:
description: |
A list of tags to be attached to the newly created run. These tags are passed through directly to WandB. Some
default tags are generated by OpenAI: "openai/finetune", "openai/{base-model}", "openai/{ftjob-abcdef}".
items:
example: custom-tag
type: string
type: array
required:
- project
type: object
required:
- type
- wandb
type: object
nullable: true
type: array
model:
anyOf:
- type: string
- enum:
- babbage-002
- davinci-002
- gpt-3.5-turbo
- gpt-4o-mini
type: string
description: |
The name of the model to fine-tune. You can select one of the
[supported models](/docs/guides/fine-tuning/which-models-can-be-fine-tuned).
example: gpt-4o-mini
x-oaiTypeLabel: string
seed:
description: |
The seed controls the reproducibility of the job. Passing in the same seed and job parameters should produce the same results, but may differ in rare cases.
If a seed is not specified, one will be generated for you.
example: 42
maximum: 2147483647
minimum: 0
nullable: true
type: integer
suffix:
default: ~
description: |
A string of up to 64 characters that will be added to your fine-tuned model name.
For example, a `suffix` of "custom-model-name" would produce a model name like `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`.
maxLength: 64
minLength: 1
nullable: true
type: string
training_file:
description: |
The ID of an uploaded file that contains training data.
See [upload file](/docs/api-reference/files/create) for how to upload a file.
Your dataset must be formatted as a JSONL file. Additionally, you must upload your file with the purpose `fine-tune`.
The contents of the file should differ depending on if the model uses the [chat](/docs/api-reference/fine-tuning/chat-input) or [completions](/docs/api-reference/fine-tuning/completions-input) format.
See the [fine-tuning guide](/docs/guides/fine-tuning) for more details.
example: file-abc123
type: string
validation_file:
description: |
The ID of an uploaded file that contains validation data.
If you provide this file, the data is used to generate validation
metrics periodically during fine-tuning. These metrics can be viewed in
the fine-tuning results file.
The same data should not be present in both train and validation files.
Your dataset must be formatted as a JSONL file. You must upload your file with the purpose `fine-tune`.
See the [fine-tuning guide](/docs/guides/fine-tuning) for more details.
example: file-abc123
nullable: true
type: string
required: &199
- model
- training_file
type: object
CreateImageEditRequest:
properties: &200
image:
description: The image to edit. Must be a valid PNG file, less than 4MB,
and square. If mask is not provided, image must have transparency, which
will be used as the mask.
format: binary
type: string
mask:
description: An additional image whose fully transparent areas (e.g. where
alpha is zero) indicate where `image` should be edited. Must be a valid
PNG file, less than 4MB, and have the same dimensions as `image`.
format: binary
type: string
model:
anyOf:
- type: string
- enum:
- dall-e-2
type: string
default: dall-e-2
description: The model to use for image generation. Only `dall-e-2` is supported
at this time.
example: dall-e-2
nullable: true
x-oaiTypeLabel: string
n:
default: 1
description: The number of images to generate. Must be between 1 and 10.
example: 1
maximum: 10
minimum: 1
nullable: true
type: integer
prompt:
description: A text description of the desired image(s). The maximum length
is 1000 characters.
example: A cute baby sea otter wearing a beret
type: string
response_format: &201
default: url
description: The format in which the generated images are returned. Must
be one of `url` or `b64_json`. URLs are only valid for 60 minutes after
the image has been generated.
enum:
- url
- b64_json
example: url
nullable: true
type: string
size: &202
default: 1024x1024
description: The size of the generated images. Must be one of `256x256`,
`512x512`, or `1024x1024`.
enum:
- 256x256
- 512x512
- 1024x1024
example: 1024x1024
nullable: true
type: string
user: *181
required: &203
- prompt
- image
type: object
CreateImageRequest:
properties: &204
model:
anyOf:
- type: string
- enum:
- dall-e-2
- dall-e-3
type: string
default: dall-e-2
description: The model to use for image generation.
example: dall-e-3
nullable: true
x-oaiTypeLabel: string
n: &205
default: 1
description: The number of images to generate. Must be between 1 and 10.
For `dall-e-3`, only `n=1` is supported.
example: 1
maximum: 10
minimum: 1
nullable: true
type: integer
prompt:
description: A text description of the desired image(s). The maximum length
is 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`.
example: A cute baby sea otter
type: string
quality:
default: standard
description: The quality of the image that will be generated. `hd` creates
images with finer details and greater consistency across the image. This
param is only supported for `dall-e-3`.
enum:
- standard
- hd
example: standard
type: string
response_format: *201
size:
default: 1024x1024
description: The size of the generated images. Must be one of `256x256`,
`512x512`, or `1024x1024` for `dall-e-2`. Must be one of `1024x1024`,
`1792x1024`, or `1024x1792` for `dall-e-3` models.
enum:
- 256x256
- 512x512
- 1024x1024
- 1792x1024
- 1024x1792
example: 1024x1024
nullable: true
type: string
style:
default: vivid
description: The style of the generated images. Must be one of `vivid` or
`natural`. Vivid causes the model to lean towards generating hyper-real
and dramatic images. Natural causes the model to produce more natural,
less hyper-real looking images. This param is only supported for `dall-e-3`.
enum:
- vivid
- natural
example: vivid
nullable: true
type: string
user: *181
required: &206
- prompt
type: object
CreateImageVariationRequest:
properties: &207
image:
description: The image to use as the basis for the variation(s). Must be
a valid PNG file, less than 4MB, and square.
format: binary
type: string
model:
anyOf:
- type: string
- enum:
- dall-e-2
type: string
default: dall-e-2
description: The model to use for image generation. Only `dall-e-2` is supported
at this time.
example: dall-e-2
nullable: true
x-oaiTypeLabel: string
n: *205
response_format: *201
size: *202
user: *181
required: &208
- image
type: object
CreateMessageRequest:
additionalProperties: false
properties: &209
attachments:
description: A list of files attached to the message, and the tools they
should be added to.
items:
properties:
file_id:
description: The ID of the file to attach to the message.
type: string
tools:
description: The tools to add this file to.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *78
required: *79
title: FileSearch tool
type: object
x-oaiExpandable: true
type: array
type: object
nullable: true
required:
- file_id
- tools
type: array
content:
oneOf:
- description: The text contents of the message.
title: Text content
type: string
- description: An array of content parts with a defined type, each can be
of type `text` or images can be passed with `image_url` or `image_file`.
Image types are only supported on [Vision-compatible models](/docs/models/overview).
items:
oneOf:
- description: References an image [File](/docs/api-reference/files)
in the content of a message.
properties: *80
required: *81
title: Image file
type: object
- description: References an image URL in the content of a message.
properties: *82
required: *83
title: Image URL
type: object
- description: The text content that is part of a message.
properties: &210
text:
description: Text content to be sent to the model
type: string
type:
description: Always `text`.
enum:
- text
type: string
required: &211
- type
- text
title: Text
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
x-oaiExpandable: true
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
role:
description: |
The role of the entity that is creating the message. Allowed values include:
- `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
- `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.
enum:
- user
- assistant
type: string
required: &212
- role
- content
type: object
CreateModerationRequest:
properties: &213
input:
description: The input text to classify
oneOf:
- default: ''
example: I want to kill them.
type: string
- items:
default: ''
example: I want to kill them.
type: string
type: array
model:
anyOf:
- type: string
- enum:
- text-moderation-latest
- text-moderation-stable
type: string
default: text-moderation-latest
description: |
Two content moderations models are available: `text-moderation-stable` and `text-moderation-latest`.
The default is `text-moderation-latest` which will be automatically upgraded over time. This ensures you are always using our most accurate model. If you use `text-moderation-stable`, we will provide advanced notice before updating the model. Accuracy of `text-moderation-stable` may be slightly lower than for `text-moderation-latest`.
example: text-moderation-stable
nullable: false
x-oaiTypeLabel: string
required: &214
- input
type: object
CreateModerationResponse:
description: Represents if a given text input is potentially harmful.
properties: &215
id:
description: The unique identifier for the moderation request.
type: string
model:
description: The model used to generate the moderation results.
type: string
results:
description: A list of moderation objects.
items:
properties:
categories:
description: A list of the categories, and whether they are flagged
or not.
properties:
harassment:
description: Content that expresses, incites, or promotes harassing
language towards any target.
type: boolean
harassment/threatening:
description: Harassment content that also includes violence or
serious harm towards any target.
type: boolean
hate:
description: Content that expresses, incites, or promotes hate
based on race, gender, ethnicity, religion, nationality, sexual
orientation, disability status, or caste. Hateful content aimed
at non-protected groups (e.g., chess players) is harassment.
type: boolean
hate/threatening:
description: Hateful content that also includes violence or serious
harm towards the targeted group based on race, gender, ethnicity,
religion, nationality, sexual orientation, disability status,
or caste.
type: boolean
self-harm:
description: Content that promotes, encourages, or depicts acts
of self-harm, such as suicide, cutting, and eating disorders.
type: boolean
self-harm/instructions:
description: Content that encourages performing acts of self-harm,
such as suicide, cutting, and eating disorders, or that gives
instructions or advice on how to commit such acts.
type: boolean
self-harm/intent:
description: Content where the speaker expresses that they are
engaging or intend to engage in acts of self-harm, such as suicide,
cutting, and eating disorders.
type: boolean
sexual:
description: Content meant to arouse sexual excitement, such as
the description of sexual activity, or that promotes sexual
services (excluding sex education and wellness).
type: boolean
sexual/minors:
description: Sexual content that includes an individual who is
under 18 years old.
type: boolean
violence:
description: Content that depicts death, violence, or physical
injury.
type: boolean
violence/graphic:
description: Content that depicts death, violence, or physical
injury in graphic detail.
type: boolean
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
type: object
category_scores:
description: A list of the categories along with their scores as predicted
by model.
properties:
harassment:
description: The score for the category 'harassment'.
type: number
harassment/threatening:
description: The score for the category 'harassment/threatening'.
type: number
hate:
description: The score for the category 'hate'.
type: number
hate/threatening:
description: The score for the category 'hate/threatening'.
type: number
self-harm:
description: The score for the category 'self-harm'.
type: number
self-harm/instructions:
description: The score for the category 'self-harm/instructions'.
type: number
self-harm/intent:
description: The score for the category 'self-harm/intent'.
type: number
sexual:
description: The score for the category 'sexual'.
type: number
sexual/minors:
description: The score for the category 'sexual/minors'.
type: number
violence:
description: The score for the category 'violence'.
type: number
violence/graphic:
description: The score for the category 'violence/graphic'.
type: number
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
type: object
flagged:
description: Whether any of the below categories are flagged.
type: boolean
required:
- flagged
- categories
- category_scores
type: object
type: array
required: &216
- id
- model
- results
type: object
CreateRunRequest:
additionalProperties: false
properties: &217
additional_instructions:
description: Appends additional instructions at the end of the instructions
for the run. This is useful for modifying the behavior on a per-run basis
without overriding other instructions.
nullable: true
type: string
additional_messages:
description: Adds additional messages to the thread before creating the
run.
items:
additionalProperties: false
properties: *209
required: *212
type: object
nullable: true
type: array
assistant_id:
description: The ID of the [assistant](/docs/api-reference/assistants) to
use to execute this run.
type: string
instructions:
description: Overrides the [instructions](/docs/api-reference/assistants/createAssistant)
of the assistant. This is useful for modifying the behavior on a per-run
basis.
nullable: true
type: string
max_completion_tokens:
description: |
The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
minimum: 256
nullable: true
type: integer
max_prompt_tokens:
description: |
The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
minimum: 256
nullable: true
type: integer
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum:
- gpt-4o
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- gpt-4o-2024-08-06
- gpt-4o-mini
- gpt-4o-mini-2024-07-18
- gpt-4-turbo
- gpt-4-turbo-2024-04-09
- gpt-4-0125-preview
- gpt-4-turbo-preview
- gpt-4-1106-preview
- gpt-4-vision-preview
- gpt-4
- gpt-4-0314
- gpt-4-0613
- gpt-4-32k
- gpt-4-32k-0314
- gpt-4-32k-0613
- gpt-3.5-turbo
- gpt-3.5-turbo-16k
- gpt-3.5-turbo-0613
- gpt-3.5-turbo-1106
- gpt-3.5-turbo-0125
- gpt-3.5-turbo-16k-0613
type: string
description: The ID of the [Model](/docs/api-reference/models) to be used
to execute this run. If a value is provided here, it will override the
model associated with the assistant. If not, the model associated with
the assistant will be used.
example: gpt-4o
nullable: true
x-oaiTypeLabel: string
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: *4
x-oaiExpandable: true
stream:
description: |
If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message.
nullable: true
type: boolean
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
tool_choice:
description: |
Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and 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 before responding to the user.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
nullable: true
oneOf: *29
x-oaiExpandable: true
tools:
description: Override the tools the assistant can use for this run. This
is useful for modifying the behavior on a per-run basis.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *13
required: *16
title: FileSearch tool
type: object
- properties: *17
required: *20
title: Function tool
type: object
x-oaiExpandable: true
maxItems: 20
nullable: true
type: array
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
truncation_strategy:
description: Controls for how a thread will be truncated prior to the run.
Use this to control the intial context window of the run.
nullable: true
properties: *32
required: *33
title: Thread Truncation Controls
type: object
required: &218
- thread_id
- assistant_id
type: object
CreateSpeechRequest:
additionalProperties: false
properties: &219
input:
description: The text to generate audio for. The maximum length is 4096
characters.
maxLength: 4096
type: string
model:
anyOf:
- type: string
- enum:
- tts-1
- tts-1-hd
type: string
description: |
One of the available [TTS models](/docs/models/tts): `tts-1` or `tts-1-hd`
x-oaiTypeLabel: string
response_format:
default: mp3
description: The format to audio in. Supported formats are `mp3`, `opus`,
`aac`, `flac`, `wav`, and `pcm`.
enum:
- mp3
- opus
- aac
- flac
- wav
- pcm
type: string
speed:
default: 1.0
description: The speed of the generated audio. Select a value from `0.25`
to `4.0`. `1.0` is the default.
maximum: 4.0
minimum: 0.25
type: number
voice:
description: The voice to use when generating the audio. Supported voices
are `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`. Previews
of the voices are available in the [Text to speech guide](/docs/guides/text-to-speech/voice-options).
enum:
- alloy
- echo
- fable
- onyx
- nova
- shimmer
type: string
required: &220
- model
- input
- voice
type: object
CreateThreadAndRunRequest:
additionalProperties: false
properties: &221
assistant_id:
description: The ID of the [assistant](/docs/api-reference/assistants) to
use to execute this run.
type: string
instructions:
description: Override the default system message of the assistant. This
is useful for modifying the behavior on a per-run basis.
nullable: true
type: string
max_completion_tokens:
description: |
The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
minimum: 256
nullable: true
type: integer
max_prompt_tokens:
description: |
The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
minimum: 256
nullable: true
type: integer
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum:
- gpt-4o
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- gpt-4o-2024-08-06
- gpt-4o-mini
- gpt-4o-mini-2024-07-18
- gpt-4-turbo
- gpt-4-turbo-2024-04-09
- gpt-4-0125-preview
- gpt-4-turbo-preview
- gpt-4-1106-preview
- gpt-4-vision-preview
- gpt-4
- gpt-4-0314
- gpt-4-0613
- gpt-4-32k
- gpt-4-32k-0314
- gpt-4-32k-0613
- gpt-3.5-turbo
- gpt-3.5-turbo-16k
- gpt-3.5-turbo-0613
- gpt-3.5-turbo-1106
- gpt-3.5-turbo-0125
- gpt-3.5-turbo-16k-0613
type: string
description: The ID of the [Model](/docs/api-reference/models) to be used
to execute this run. If a value is provided here, it will override the
model associated with the assistant. If not, the model associated with
the assistant will be used.
example: gpt-4o
nullable: true
x-oaiTypeLabel: string
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: *4
x-oaiExpandable: true
stream:
description: |
If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message.
nullable: true
type: boolean
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
thread:
additionalProperties: false
description: If no thread is provided, an empty thread will be created.
properties: &222
messages:
description: A list of [messages](/docs/api-reference/messages) to start
the thread with.
items:
additionalProperties: false
properties: *209
required: *212
type: object
type: array
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
tool_resources:
description: |
A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
oneOf:
- required:
- vector_store_ids
- required:
- vector_stores
properties:
vector_store_ids:
description: |
The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread.
items:
type: string
maxItems: 1
type: array
vector_stores:
description: |
A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread.
items:
properties:
chunking_strategy:
description: The chunking strategy used to chunk the file(s).
If not set, will use the `auto` strategy.
oneOf:
- additionalProperties: false
description: The default strategy. This strategy currently
uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens`
of `400`.
properties:
type:
description: Always `auto`.
enum:
- auto
type: string
required:
- type
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties:
static:
additionalProperties: false
properties:
chunk_overlap_tokens:
description: |
The number of tokens that overlap between chunks. The default value is `400`.
Note that the overlap must not exceed half of `max_chunk_size_tokens`.
type: integer
max_chunk_size_tokens:
description: The maximum number of tokens in
each chunk. The default value is `800`. The
minimum value is `100` and the maximum value
is `4096`.
maximum: 4096
minimum: 100
type: integer
required:
- max_chunk_size_tokens
- chunk_overlap_tokens
type: object
type:
description: Always `static`.
enum:
- static
type: string
required:
- type
- static
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
file_ids:
description: |
A list of [file](/docs/api-reference/files) IDs to add to the vector store. There can be a maximum of 10000 files in a vector store.
items:
type: string
maxItems: 10000
type: array
metadata:
description: |
Set of 16 key-value pairs that can be attached to a vector store. This can be useful for storing additional information about the vector store in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
type: object
x-oaiTypeLabel: map
type: object
x-oaiExpandable: true
maxItems: 1
type: array
type: object
type: object
type: object
tool_choice:
description: |
Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and 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 before responding to the user.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
nullable: true
oneOf: *29
x-oaiExpandable: true
tool_resources:
description: |
A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
properties:
vector_store_ids:
description: |
The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.
items:
type: string
maxItems: 1
type: array
type: object
type: object
tools:
description: Override the tools the assistant can use for this run. This
is useful for modifying the behavior on a per-run basis.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *13
required: *16
title: FileSearch tool
type: object
- properties: *17
required: *20
title: Function tool
type: object
maxItems: 20
nullable: true
type: array
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
truncation_strategy:
description: Controls for how a thread will be truncated prior to the run.
Use this to control the intial context window of the run.
nullable: true
properties: *32
required: *33
title: Thread Truncation Controls
type: object
required: &223
- thread_id
- assistant_id
type: object
CreateThreadRequest:
additionalProperties: false
properties: *222
type: object
CreateTranscriptionRequest:
additionalProperties: false
properties: &224
file:
description: |
The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
format: binary
type: string
x-oaiTypeLabel: file
language:
description: |
The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format will improve accuracy and latency.
type: string
model:
anyOf:
- type: string
- enum:
- whisper-1
type: string
description: |
ID of the model to use. Only `whisper-1` (which is powered by our open source Whisper V2 model) is currently available.
example: whisper-1
x-oaiTypeLabel: string
prompt:
description: |
An optional text to guide the model's style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text/prompting) should match the audio language.
type: string
response_format:
default: json
description: |
The format of the transcript output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.
enum:
- json
- text
- srt
- verbose_json
- vtt
type: string
temperature:
default: 0
description: |
The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit.
type: number
timestamp_granularities[]:
default:
- segment
description: |
The timestamp granularities to populate for this transcription. `response_format` must be set `verbose_json` to use timestamp granularities. Either or both of these options are supported: `word`, or `segment`. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency.
items:
enum:
- word
- segment
type: string
type: array
required: &225
- file
- model
type: object
CreateTranscriptionResponseJson:
description: Represents a transcription response returned by model, based on
the provided input.
properties: &226
text:
description: The transcribed text.
type: string
required: &227
- text
type: object
CreateTranscriptionResponseVerboseJson:
description: Represents a verbose json transcription response returned by model,
based on the provided input.
properties: &228
duration:
description: The duration of the input audio.
type: string
language:
description: The language of the input audio.
type: string
segments:
description: Segments of the transcribed text and their corresponding details.
items:
properties: &229
avg_logprob:
description: Average logprob of the segment. If the value is lower
than -1, consider the logprobs failed.
format: float
type: number
compression_ratio:
description: Compression ratio of the segment. If the value is greater
than 2.4, consider the compression failed.
format: float
type: number
end:
description: End time of the segment in seconds.
format: float
type: number
id:
description: Unique identifier of the segment.
type: integer
no_speech_prob:
description: Probability of no speech in the segment. If the value
is higher than 1.0 and the `avg_logprob` is below -1, consider this
segment silent.
format: float
type: number
seek:
description: Seek offset of the segment.
type: integer
start:
description: Start time of the segment in seconds.
format: float
type: number
temperature:
description: Temperature parameter used for generating the segment.
format: float
type: number
text:
description: Text content of the segment.
type: string
tokens:
description: Array of token IDs for the text content.
items:
type: integer
type: array
required: &230
- id
- seek
- start
- end
- text
- tokens
- temperature
- avg_logprob
- compression_ratio
- no_speech_prob
type: object
type: array
text:
description: The transcribed text.
type: string
words:
description: Extracted words and their corresponding timestamps.
items:
properties: &231
end:
description: End time of the word in seconds.
format: float
type: number
start:
description: Start time of the word in seconds.
format: float
type: number
word:
description: The text content of the word.
type: string
required: &232
- word
- start
- end
type: object
type: array
required: &233
- language
- duration
- text
type: object
CreateTranslationRequest:
additionalProperties: false
properties: &234
file:
description: |
The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
format: binary
type: string
x-oaiTypeLabel: file
model:
anyOf:
- type: string
- enum:
- whisper-1
type: string
description: |
ID of the model to use. Only `whisper-1` (which is powered by our open source Whisper V2 model) is currently available.
example: whisper-1
x-oaiTypeLabel: string
prompt:
description: |
An optional text to guide the model's style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text/prompting) should be in English.
type: string
response_format:
default: json
description: |
The format of the transcript output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.
type: string
temperature:
default: 0
description: |
The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit.
type: number
required: &235
- file
- model
type: object
CreateTranslationResponseJson:
properties: &236
text:
type: string
required: &237
- text
type: object
CreateTranslationResponseVerboseJson:
properties: &238
duration:
description: The duration of the input audio.
type: string
language:
description: The language of the output translation (always `english`).
type: string
segments:
description: Segments of the translated text and their corresponding details.
items:
properties: *229
required: *230
type: object
type: array
text:
description: The translated text.
type: string
required: &239
- language
- duration
- text
type: object
CreateUploadRequest:
additionalProperties: false
properties: &240
bytes:
description: |
The number of bytes in the file you are uploading.
type: integer
filename:
description: |
The name of the file to upload.
type: string
mime_type:
description: |
The MIME type of the file.
This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.
type: string
purpose:
description: |
The intended purpose of the uploaded file.
See the [documentation on File purposes](/docs/api-reference/files/create#files-create-purpose).
enum:
- assistants
- batch
- fine-tune
- vision
type: string
required: &241
- filename
- purpose
- bytes
- mime_type
type: object
CreateVectorStoreFileBatchRequest:
additionalProperties: false
properties: &242
chunking_strategy:
description: The chunking strategy used to chunk the file(s). If not set,
will use the `auto` strategy.
oneOf: *169
type: object
x-oaiExpandable: true
file_ids:
description: A list of [File](/docs/api-reference/files) IDs that the vector
store should use. Useful for tools like `file_search` that can access
files.
items:
type: string
maxItems: 500
minItems: 1
type: array
required: &243
- file_ids
type: object
CreateVectorStoreFileRequest:
additionalProperties: false
properties: &244
chunking_strategy:
description: The chunking strategy used to chunk the file(s). If not set,
will use the `auto` strategy.
oneOf: *169
type: object
x-oaiExpandable: true
file_id:
description: A [File](/docs/api-reference/files) ID that the vector store
should use. Useful for tools like `file_search` that can access files.
type: string
required: &245
- file_id
type: object
CreateVectorStoreRequest:
additionalProperties: false
properties: &246
chunking_strategy:
description: The chunking strategy used to chunk the file(s). If not set,
will use the `auto` strategy. Only applicable if `file_ids` is non-empty.
oneOf:
- additionalProperties: false
description: The default strategy. This strategy currently uses a `max_chunk_size_tokens`
of `800` and `chunk_overlap_tokens` of `400`.
properties: *121
required: *122
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties: *170
required: *173
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
expires_after:
description: The expiration policy for a vector store.
properties: &247
anchor:
description: 'Anchor timestamp after which the expiration policy applies.
Supported anchors: `last_active_at`.'
enum:
- last_active_at
type: string
days:
description: The number of days after the anchor time that the vector
store will expire.
maximum: 365
minimum: 1
type: integer
required: &248
- anchor
- days
title: Vector store expiration policy
type: object
file_ids:
description: A list of [File](/docs/api-reference/files) IDs that the vector
store should use. Useful for tools like `file_search` that can access
files.
items:
type: string
maxItems: 500
type: array
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
name:
description: The name of the vector store.
type: string
type: object
DefaultProjectErrorResponse:
properties:
code:
type: integer
message:
type: string
required:
- code
- message
type: object
DeleteAssistantResponse:
properties: &249
deleted:
type: boolean
id:
type: string
object:
enum:
- assistant.deleted
type: string
required: &250
- id
- object
- deleted
type: object
DeleteFileResponse:
properties: &251
deleted:
type: boolean
id:
type: string
object:
enum:
- file
type: string
required: &252
- id
- object
- deleted
type: object
DeleteMessageResponse:
properties: &253
deleted:
type: boolean
id:
type: string
object:
enum:
- thread.message.deleted
type: string
required: &254
- id
- object
- deleted
type: object
DeleteModelResponse:
properties: &255
deleted:
type: boolean
id:
type: string
object:
type: string
required: &256
- id
- object
- deleted
type: object
DeleteThreadResponse:
properties: &257
deleted:
type: boolean
id:
type: string
object:
enum:
- thread.deleted
type: string
required: &258
- id
- object
- deleted
type: object
DeleteVectorStoreFileResponse:
properties: &259
deleted:
type: boolean
id:
type: string
object:
enum:
- vector_store.file.deleted
type: string
required: &260
- id
- object
- deleted
type: object
DeleteVectorStoreResponse:
properties: &261
deleted:
type: boolean
id:
type: string
object:
enum:
- vector_store.deleted
type: string
required: &262
- id
- object
- deleted
type: object
DoneEvent:
description: Occurs when a stream ends.
properties: *111
required: *112
type: object
Embedding:
description: |
Represents an embedding vector returned by embedding endpoint.
properties: *193
required: *194
type: object
Error:
properties: *108
required: *109
type: object
ErrorEvent:
description: Occurs when an [error](/docs/guides/error-codes/api-errors) occurs.
This can happen due to an internal server error or a timeout.
properties: *107
required: *110
type: object
ErrorResponse:
properties: &263
error:
properties: *108
required: *109
type: object
required: &264
- error
type: object
FileSearchRankingOptions:
description: |
The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0.
See the [file search tool documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) for more information.
properties: *14
required: *15
title: File search tool call ranking options
type: object
FineTuneChatCompletionRequestAssistantMessage:
allOf: &265
- deprecated: false
properties:
weight:
description: Controls whether the assistant message is trained against
(0 or 1)
enum:
- 0
- 1
type: integer
title: Assistant message
type: object
- properties: *136
required: *142
title: Assistant message
type: object
required: &266
- role
FineTuningIntegration:
properties: &267
type:
description: The type of the integration being enabled for the fine-tuning
job
enum:
- wandb
type: string
wandb:
description: |
The settings for your integration with Weights and Biases. This payload specifies the project that
metrics will be sent to. Optionally, you can set an explicit display name for your run, add tags
to your run, and set a default entity (team, username, etc) to be associated with your run.
properties:
entity:
description: |
The entity to use for the run. This allows you to set the team or username of the WandB user that you would
like associated with the run. If not set, the default entity for the registered WandB API key is used.
nullable: true
type: string
name:
description: |
A display name to set for the run. If not set, we will use the Job ID as the name.
nullable: true
type: string
project:
description: |
The name of the project that the new run will be created under.
example: my-wandb-project
type: string
tags:
description: |
A list of tags to be attached to the newly created run. These tags are passed through directly to WandB. Some
default tags are generated by OpenAI: "openai/finetune", "openai/{base-model}", "openai/{ftjob-abcdef}".
items:
example: custom-tag
type: string
type: array
required:
- project
type: object
required: &268
- type
- wandb
title: Fine-Tuning Job Integration
type: object
FineTuningJob:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: &269
created_at:
description: The Unix timestamp (in seconds) for when the fine-tuning job
was created.
type: integer
error:
description: For fine-tuning jobs that have `failed`, this will contain
more information on the cause of the failure.
nullable: true
properties:
code:
description: A machine-readable error code.
type: string
message:
description: A human-readable error message.
type: string
param:
description: The parameter that was invalid, usually `training_file`
or `validation_file`. This field will be null if the failure was not
parameter-specific.
nullable: true
type: string
required:
- code
- message
- param
type: object
estimated_finish:
description: The Unix timestamp (in seconds) for when the fine-tuning job
is estimated to finish. The value will be null if the fine-tuning job
is not running.
nullable: true
type: integer
fine_tuned_model:
description: The name of the fine-tuned model that is being created. The
value will be null if the fine-tuning job is still running.
nullable: true
type: string
finished_at:
description: The Unix timestamp (in seconds) for when the fine-tuning job
was finished. The value will be null if the fine-tuning job is still running.
nullable: true
type: integer
hyperparameters:
description: The hyperparameters used for the fine-tuning job. See the [fine-tuning
guide](/docs/guides/fine-tuning) for more details.
properties:
n_epochs:
default: auto
description: |-
The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
"auto" decides the optimal number of epochs based on the size of the dataset. If setting the number manually, we support any number between 1 and 50 epochs.
oneOf:
- enum:
- auto
type: string
- maximum: 50
minimum: 1
type: integer
required:
- n_epochs
type: object
id:
description: The object identifier, which can be referenced in the API endpoints.
type: string
integrations:
description: A list of integrations to enable for this fine-tuning job.
items:
oneOf:
- properties: *267
required: *268
title: Fine-Tuning Job Integration
type: object
x-oaiExpandable: true
maxItems: 5
nullable: true
type: array
model:
description: The base model that is being fine-tuned.
type: string
object:
description: The object type, which is always "fine_tuning.job".
enum:
- fine_tuning.job
type: string
organization_id:
description: The organization that owns the fine-tuning job.
type: string
result_files:
description: The compiled results file ID(s) for the fine-tuning job. You
can retrieve the results with the [Files API](/docs/api-reference/files/retrieve-contents).
items:
example: file-abc123
type: string
type: array
seed:
description: The seed used for the fine-tuning job.
type: integer
status:
description: The current status of the fine-tuning job, which can be either
`validating_files`, `queued`, `running`, `succeeded`, `failed`, or `cancelled`.
enum:
- validating_files
- queued
- running
- succeeded
- failed
- cancelled
type: string
trained_tokens:
description: The total number of billable tokens processed by this fine-tuning
job. The value will be null if the fine-tuning job is still running.
nullable: true
type: integer
training_file:
description: The file ID used for training. You can retrieve the training
data with the [Files API](/docs/api-reference/files/retrieve-contents).
type: string
validation_file:
description: The file ID used for validation. You can retrieve the validation
results with the [Files API](/docs/api-reference/files/retrieve-contents).
nullable: true
type: string
required: &270
- created_at
- error
- finished_at
- fine_tuned_model
- hyperparameters
- id
- model
- object
- organization_id
- result_files
- status
- trained_tokens
- training_file
- validation_file
- seed
title: FineTuningJob
type: object
FineTuningJobCheckpoint:
description: |
The `fine_tuning.job.checkpoint` object represents a model checkpoint for a fine-tuning job that is ready to use.
properties: &271
created_at:
description: The Unix timestamp (in seconds) for when the checkpoint was
created.
type: integer
fine_tuned_model_checkpoint:
description: The name of the fine-tuned checkpoint model that is created.
type: string
fine_tuning_job_id:
description: The name of the fine-tuning job that this checkpoint was created
from.
type: string
id:
description: The checkpoint identifier, which can be referenced in the API
endpoints.
type: string
metrics:
description: Metrics at the step number during the fine-tuning job.
properties:
full_valid_loss:
type: number
full_valid_mean_token_accuracy:
type: number
step:
type: number
train_loss:
type: number
train_mean_token_accuracy:
type: number
valid_loss:
type: number
valid_mean_token_accuracy:
type: number
type: object
object:
description: The object type, which is always "fine_tuning.job.checkpoint".
enum:
- fine_tuning.job.checkpoint
type: string
step_number:
description: The step number that the checkpoint was created at.
type: integer
required: &272
- created_at
- fine_tuning_job_id
- fine_tuned_model_checkpoint
- id
- metrics
- object
- step_number
title: FineTuningJobCheckpoint
type: object
FineTuningJobEvent:
description: Fine-tuning job event object
properties: &273
created_at:
type: integer
id:
type: string
level:
enum:
- info
- warn
- error
type: string
message:
type: string
object:
enum:
- fine_tuning.job.event
type: string
required: &274
- id
- object
- created_at
- level
- message
type: object
FinetuneChatRequestInput:
description: The per-line training example of a fine-tuning input file for chat
models
properties:
functions:
deprecated: true
description: A list of functions the model may generate JSON inputs for.
items:
deprecated: true
properties: *127
required: *128
type: object
maxItems: 128
minItems: 1
type: array
messages:
items:
oneOf:
- properties: *146
required: *148
title: System message
type: object
- properties: *149
required: *153
title: User message
type: object
- allOf: *265
required: *266
- properties: *154
required: *156
title: Tool message
type: object
- deprecated: true
properties: *143
required: *144
title: Function message
type: object
x-oaiExpandable: true
minItems: 1
type: array
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
tools:
description: A list of tools the model may generate JSON inputs for.
items:
properties: *166
required: *167
type: object
type: array
type: object
FinetuneCompletionRequestInput:
description: The per-line training example of a fine-tuning input file for completions
models
properties:
completion:
description: The desired completion for this training example.
type: string
prompt:
description: The input prompt for this training example.
type: string
type: object
FunctionObject:
properties: *18
required: *19
type: object
FunctionParameters:
additionalProperties: true
description: "The parameters the functions accepts, described as a JSON Schema
object. See the [guide](/docs/guides/function-calling) for examples, and the
[JSON Schema reference](https://json-schema.org/understanding-json-schema/)
for documentation about the format. \n\nOmitting `parameters` defines a function
with an empty parameter list."
type: object
Image:
description: Represents the url or the content of an image generated by the
OpenAI API.
properties: &275
b64_json:
description: The base64-encoded JSON of the generated image, if `response_format`
is `b64_json`.
type: string
revised_prompt:
description: The prompt that was used to generate the image, if there was
any revision to the prompt.
type: string
url:
description: The URL of the generated image, if `response_format` is `url`
(default).
type: string
type: object
ImagesResponse:
properties: &276
created:
type: integer
data:
items:
description: Represents the url or the content of an image generated by
the OpenAI API.
properties: *275
type: object
type: array
required: &277
- created
- data
Invite:
description: Represents an individual `invite` to the organization.
properties: &278
accepted_at:
description: The Unix timestamp (in seconds) of when the invite was accepted.
type: integer
email:
description: The email address of the individual to whom the invite was
sent
type: string
expires_at:
description: The Unix timestamp (in seconds) of when the invite expires.
type: integer
id:
description: The identifier, which can be referenced in API endpoints
type: string
invited_at:
description: The Unix timestamp (in seconds) of when the invite was sent.
type: integer
object:
description: The object type, which is always `organization.invite`
enum:
- organization.invite
type: string
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
status:
description: '`accepted`,`expired`, or `pending`'
enum:
- accepted
- expired
- pending
type: string
required: &279
- object
- id
- email
- role
- status
- invited_at
- expires_at
type: object
InviteDeleteResponse:
properties: &280
deleted:
type: boolean
id:
type: string
object:
description: The object type, which is always `organization.invite.deleted`
enum:
- organization.invite.deleted
type: string
required: &281
- object
- id
- deleted
type: object
InviteListResponse:
properties: &282
data:
items:
description: Represents an individual `invite` to the organization.
properties: *278
required: *279
type: object
type: array
first_id:
description: The first `invite_id` in the retrieved `list`
type: string
has_more:
description: The `has_more` property is used for pagination to indicate
there are additional results.
type: boolean
last_id:
description: The last `invite_id` in the retrieved `list`
type: string
object:
description: The object type, which is always `list`
enum:
- list
type: string
required: &283
- object
- data
type: object
InviteRequest:
properties: &284
email:
description: Send an email to this address
type: string
role:
description: '`owner` or `reader`'
enum:
- reader
- owner
type: string
required: &285
- email
- role
type: object
ListAssistantsResponse:
properties: &286
data:
items:
description: Represents an `assistant` that can call the model and use
tools.
properties: *3
required: *21
title: Assistant
type: object
type: array
first_id:
example: asst_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: asst_abc456
type: string
object:
example: list
type: string
required: &287
- object
- data
- first_id
- last_id
- has_more
type: object
ListAuditLogsResponse:
properties: &288
data:
items:
description: A log of a user action or configuration change within this
organization.
properties: *113
required: *120
type: object
type: array
first_id:
example: audit_log-defb456h8dks
type: string
has_more:
type: boolean
last_id:
example: audit_log-hnbkd8s93s
type: string
object:
enum:
- list
type: string
required: &289
- object
- data
- first_id
- last_id
- has_more
type: object
ListBatchesResponse:
properties: &290
data:
items:
properties: *123
required: *124
type: object
type: array
first_id:
example: batch_abc123
type: string
has_more:
type: boolean
last_id:
example: batch_abc456
type: string
object:
enum:
- list
type: string
required: &291
- object
- data
- has_more
type: object
ListFilesResponse:
properties: &292
data:
items:
description: The `File` object represents a document that has been uploaded
to OpenAI.
properties: &293
bytes:
description: The size of the file, in bytes.
type: integer
created_at:
description: The Unix timestamp (in seconds) for when the file was
created.
type: integer
filename:
description: The name of the file.
type: string
id:
description: The file identifier, which can be referenced in the API
endpoints.
type: string
object:
description: The object type, which is always `file`.
enum:
- file
type: string
purpose:
description: The intended purpose of the file. Supported values are
`assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`,
`fine-tune-results` and `vision`.
enum:
- assistants
- assistants_output
- batch
- batch_output
- fine-tune
- fine-tune-results
- vision
type: string
status:
deprecated: true
description: Deprecated. The current status of the file, which can
be either `uploaded`, `processed`, or `error`.
enum:
- uploaded
- processed
- error
type: string
status_details:
deprecated: true
description: Deprecated. For details on why a fine-tuning training
file failed validation, see the `error` field on `fine_tuning.job`.
type: string
required: &294
- id
- object
- bytes
- created_at
- filename
- purpose
- status
title: OpenAIFile
type: array
object:
enum:
- list
type: string
required: &295
- object
- data
type: object
ListFineTuningJobCheckpointsResponse:
properties: &296
data:
items:
description: |
The `fine_tuning.job.checkpoint` object represents a model checkpoint for a fine-tuning job that is ready to use.
properties: *271
required: *272
title: FineTuningJobCheckpoint
type: object
type: array
first_id:
nullable: true
type: string
has_more:
type: boolean
last_id:
nullable: true
type: string
object:
enum:
- list
type: string
required: &297
- object
- data
- has_more
type: object
ListFineTuningJobEventsResponse:
properties: &298
data:
items:
description: Fine-tuning job event object
properties: *273
required: *274
type: object
type: array
object:
enum:
- list
type: string
required: &299
- object
- data
type: object
ListMessagesResponse:
properties: &300
data:
items:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
type: array
first_id:
example: msg_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: msg_abc123
type: string
object:
example: list
type: string
required: &301
- object
- data
- first_id
- last_id
- has_more
ListModelsResponse:
properties: &302
data:
items:
description: Describes an OpenAI model offering that can be used with
the API.
properties: &303
created:
description: The Unix timestamp (in seconds) when the model was created.
type: integer
id:
description: The model identifier, which can be referenced in the
API endpoints.
type: string
object:
description: The object type, which is always "model".
enum:
- model
type: string
owned_by:
description: The organization that owns the model.
type: string
required: &304
- id
- object
- created
- owned_by
title: Model
type: array
object:
enum:
- list
type: string
required: &305
- object
- data
type: object
ListPaginatedFineTuningJobsResponse:
properties: &306
data:
items:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: *269
required: *270
title: FineTuningJob
type: object
type: array
has_more:
type: boolean
object:
enum:
- list
type: string
required: &307
- object
- data
- has_more
type: object
ListRunStepsResponse:
properties: &308
data:
items:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
type: array
first_id:
example: step_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: step_abc456
type: string
object:
example: list
type: string
required: &309
- object
- data
- first_id
- last_id
- has_more
ListRunsResponse:
properties: &310
data:
items:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
type: array
first_id:
example: run_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: run_abc456
type: string
object:
example: list
type: string
required: &311
- object
- data
- first_id
- last_id
- has_more
type: object
ListThreadsResponse:
properties:
data:
items:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *23
required: *24
title: Thread
type: object
type: array
first_id:
example: asst_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: asst_abc456
type: string
object:
example: list
type: string
required:
- object
- data
- first_id
- last_id
- has_more
ListVectorStoreFilesResponse:
properties: &312
data:
items:
description: A list of files attached to a vector store.
properties: &313
chunking_strategy:
description: The strategy used to chunk the file.
oneOf:
- additionalProperties: false
properties: &314
static:
additionalProperties: false
properties: *171
required: *172
type: object
type:
description: Always `static`.
enum:
- static
type: string
required: &315
- type
- static
title: Static Chunking Strategy
type: object
- additionalProperties: false
description: This is returned when the chunking strategy is unknown.
Typically, this is because the file was indexed before the `chunking_strategy`
concept was introduced in the API.
properties: &316
type:
description: Always `other`.
enum:
- other
type: string
required: &317
- type
title: Other Chunking Strategy
type: object
type: object
x-oaiExpandable: true
created_at:
description: The Unix timestamp (in seconds) for when the vector store
file was created.
type: integer
id:
description: The identifier, which can be referenced in API endpoints.
type: string
last_error:
description: The last error associated with this vector store file.
Will be `null` if there are no errors.
nullable: true
properties:
code:
description: One of `server_error` or `rate_limit_exceeded`.
enum:
- server_error
- unsupported_file
- invalid_file
type: string
message:
description: A human-readable description of the error.
type: string
required:
- code
- message
type: object
object:
description: The object type, which is always `vector_store.file`.
enum:
- vector_store.file
type: string
status:
description: The status of the vector store file, which can be either
`in_progress`, `completed`, `cancelled`, or `failed`. The status
`completed` indicates that the vector store file is ready for use.
enum:
- in_progress
- completed
- cancelled
- failed
type: string
usage_bytes:
description: The total vector store usage in bytes. Note that this
may be different from the original file size.
type: integer
vector_store_id:
description: The ID of the [vector store](/docs/api-reference/vector-stores/object)
that the [File](/docs/api-reference/files) is attached to.
type: string
required: &318
- id
- object
- usage_bytes
- created_at
- vector_store_id
- status
- last_error
title: Vector store files
type: object
type: array
first_id:
example: file-abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: file-abc456
type: string
object:
example: list
type: string
required: &319
- object
- data
- first_id
- last_id
- has_more
ListVectorStoresResponse:
properties: &320
data:
items:
description: A vector store is a collection of processed files can be
used by the `file_search` tool.
properties: &321
created_at:
description: The Unix timestamp (in seconds) for when the vector store
was created.
type: integer
expires_after:
description: The expiration policy for a vector store.
properties: *247
required: *248
title: Vector store expiration policy
type: object
expires_at:
description: The Unix timestamp (in seconds) for when the vector store
will expire.
nullable: true
type: integer
file_counts:
properties:
cancelled:
description: The number of files that were cancelled.
type: integer
completed:
description: The number of files that have been successfully processed.
type: integer
failed:
description: The number of files that have failed to process.
type: integer
in_progress:
description: The number of files that are currently being processed.
type: integer
total:
description: The total number of files.
type: integer
required:
- in_progress
- completed
- failed
- cancelled
- total
type: object
id:
description: The identifier, which can be referenced in API endpoints.
type: string
last_active_at:
description: The Unix timestamp (in seconds) for when the vector store
was last active.
nullable: true
type: integer
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
name:
description: The name of the vector store.
type: string
object:
description: The object type, which is always `vector_store`.
enum:
- vector_store
type: string
status:
description: The status of the vector store, which can be either `expired`,
`in_progress`, or `completed`. A status of `completed` indicates
that the vector store is ready for use.
enum:
- expired
- in_progress
- completed
type: string
usage_bytes:
description: The total number of bytes used by the files in the vector
store.
type: integer
required: &322
- id
- object
- usage_bytes
- created_at
- status
- last_active_at
- name
- file_counts
- metadata
title: Vector store
type: object
type: array
first_id:
example: vs_abc123
type: string
has_more:
example: false
type: boolean
last_id:
example: vs_abc456
type: string
object:
example: list
type: string
required: &323
- object
- data
- first_id
- last_id
- has_more
MessageContentImageFileObject:
description: References an image [File](/docs/api-reference/files) in the content
of a message.
properties: *80
required: *81
title: Image file
type: object
MessageContentImageUrlObject:
description: References an image URL in the content of a message.
properties: *82
required: *83
title: Image URL
type: object
MessageContentRefusalObject:
description: The refusal content generated by the assistant.
properties: *90
required: *91
title: Refusal
type: object
MessageContentTextAnnotationsFileCitationObject:
description: A citation within the message that points to a specific quote from
a specific File associated with the assistant or the message. Generated when
the assistant uses the "file_search" tool to search files.
properties: *85
required: *86
title: File citation
type: object
MessageContentTextAnnotationsFilePathObject:
description: A URL for the file that's generated when the assistant used the
`code_interpreter` tool to generate a file.
properties: *87
required: *88
title: File path
type: object
MessageContentTextObject:
description: The text content that is part of a message.
properties: *84
required: *89
title: Text
type: object
MessageDeltaContentImageFileObject:
description: References an image [File](/docs/api-reference/files) in the content
of a message.
properties: *94
required: *95
title: Image file
type: object
MessageDeltaContentImageUrlObject:
description: References an image URL in the content of a message.
properties: *104
required: *105
title: Image URL
type: object
MessageDeltaContentRefusalObject:
description: The refusal content that is part of a message.
properties: *102
required: *103
title: Refusal
type: object
MessageDeltaContentTextAnnotationsFileCitationObject:
description: A citation within the message that points to a specific quote from
a specific File associated with the assistant or the message. Generated when
the assistant uses the "file_search" tool to search files.
properties: *97
required: *98
title: File citation
type: object
MessageDeltaContentTextAnnotationsFilePathObject:
description: A URL for the file that's generated when the assistant used the
`code_interpreter` tool to generate a file.
properties: *99
required: *100
title: File path
type: object
MessageDeltaContentTextObject:
description: The text content that is part of a message.
properties: *96
required: *101
title: Text
type: object
MessageDeltaObject:
description: |
Represents a message delta i.e. any changed fields on a message during streaming.
properties: *93
required: *106
title: Message delta object
type: object
MessageObject:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
MessageRequestContentTextObject:
description: The text content that is part of a message.
properties: *210
required: *211
title: Text
type: object
MessageStreamEvent:
oneOf: *76
Model:
description: Describes an OpenAI model offering that can be used with the API.
properties: *303
required: *304
title: Model
ModifyAssistantRequest:
additionalProperties: false
properties: &324
description:
description: |
The description of the assistant. The maximum length is 512 characters.
maxLength: 512
nullable: true
type: string
instructions:
description: |
The system instructions that the assistant uses. The maximum length is 256,000 characters.
maxLength: 256000
nullable: true
type: string
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
description: |
ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
name:
description: |
The name of the assistant. The maximum length is 256 characters.
maxLength: 256
nullable: true
type: string
response_format:
description: |
Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4 Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
nullable: true
oneOf: *4
x-oaiExpandable: true
temperature:
default: 1
description: |
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
example: 1
maximum: 2
minimum: 0
nullable: true
type: number
tool_resources:
description: |
A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
Overrides the list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
properties:
vector_store_ids:
description: |
Overrides the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.
items:
type: string
maxItems: 1
type: array
type: object
type: object
tools:
default: []
description: |
A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`.
items:
oneOf:
- properties: *11
required: *12
title: Code interpreter tool
type: object
- properties: *13
required: *16
title: FileSearch tool
type: object
- properties: *17
required: *20
title: Function tool
type: object
x-oaiExpandable: true
maxItems: 128
type: array
top_p:
default: 1
description: |
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
example: 1
maximum: 1
minimum: 0
nullable: true
type: number
type: object
ModifyMessageRequest:
additionalProperties: false
properties: &325
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
type: object
ModifyRunRequest:
additionalProperties: false
properties: &326
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
type: object
ModifyThreadRequest:
additionalProperties: false
properties: &327
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
tool_resources:
description: |
A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs.
nullable: true
properties:
code_interpreter:
properties:
file_ids:
default: []
description: |
A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.
items:
type: string
maxItems: 20
type: array
type: object
file_search:
properties:
vector_store_ids:
description: |
The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread.
items:
type: string
maxItems: 1
type: array
type: object
type: object
type: object
OpenAIFile:
description: The `File` object represents a document that has been uploaded
to OpenAI.
properties: *293
required: *294
title: OpenAIFile
OtherChunkingStrategyResponseParam:
additionalProperties: false
description: This is returned when the chunking strategy is unknown. Typically,
this is because the file was indexed before the `chunking_strategy` concept
was introduced in the API.
properties: *316
required: *317
title: Other Chunking Strategy
type: object
ParallelToolCalls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling/parallel-function-calling)
during tool use.
type: boolean
Project:
description: Represents an individual project.
properties: &328
app_use_case:
description: A description of your business, project, or use case. [Why
we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
archived_at:
description: The Unix timestamp (in seconds) of when the project was archived
or `null`.
nullable: true
type: integer
business_website:
description: Your business URL, or if you don't have one yet, a URL to your
LinkedIn or other social media. [Why we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
created_at:
description: The Unix timestamp (in seconds) of when the project was created.
type: integer
id:
description: The identifier, which can be referenced in API endpoints
type: string
name:
description: The name of the project. This appears in reporting.
type: string
object:
description: The object type, which is always `organization.project`
enum:
- organization.project
type: string
status:
description: '`active` or `archived`'
enum:
- active
- archived
type: string
required: &329
- id
- object
- name
- created_at
- status
type: object
ProjectApiKey:
description: Represents an individual API key in a project.
properties: &330
created_at:
description: The Unix timestamp (in seconds) of when the API key was created
type: integer
id:
description: The identifier, which can be referenced in API endpoints
type: string
name:
description: The name of the API key
type: string
object:
description: The object type, which is always `organization.project.api_key`
enum:
- organization.project.api_key
type: string
owner:
properties:
service_account:
description: Represents an individual service account in a project.
properties: &331
created_at:
description: The Unix timestamp (in seconds) of when the service
account was created
type: integer
id:
description: The identifier, which can be referenced in API endpoints
type: string
name:
description: The name of the service account
type: string
object:
description: The object type, which is always `organization.project.service_account`
enum:
- organization.project.service_account
type: string
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &332
- object
- id
- name
- role
- created_at
type: object
type:
description: '`user` or `service_account`'
enum:
- user
- service_account
type: string
user:
description: Represents an individual user in a project.
properties: &333
added_at:
description: The Unix timestamp (in seconds) of when the project
was added.
type: integer
email:
description: The email address of the user
type: string
id:
description: The identifier, which can be referenced in API endpoints
type: string
name:
description: The name of the user
type: string
object:
description: The object type, which is always `organization.project.user`
enum:
- organization.project.user
type: string
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &334
- object
- id
- name
- email
- role
- added_at
type: object
type: object
redacted_value:
description: The redacted value of the API key
type: string
required: &335
- object
- redacted_value
- name
- created_at
- id
- owner
type: object
ProjectApiKeyDeleteResponse:
properties: &336
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.api_key.deleted
type: string
required: &337
- object
- id
- deleted
type: object
ProjectApiKeyListResponse:
properties: &338
data:
items:
description: Represents an individual API key in a project.
properties: *330
required: *335
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
required: &339
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectCreateRequest:
properties: &340
app_use_case:
description: A description of your business, project, or use case. [Why
we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
business_website:
description: Your business URL, or if you don't have one yet, a URL to your
LinkedIn or other social media. [Why we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
name:
description: The friendly name of the project, this name appears in reports.
type: string
required: &341
- name
type: object
ProjectListResponse:
properties: &342
data:
items:
description: Represents an individual project.
properties: *328
required: *329
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
required: &343
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectServiceAccount:
description: Represents an individual service account in a project.
properties: *331
required: *332
type: object
ProjectServiceAccountApiKey:
properties: &344
created_at:
type: integer
id:
type: string
name:
type: string
object:
description: The object type, which is always `organization.project.service_account.api_key`
enum:
- organization.project.service_account.api_key
type: string
value:
type: string
required: &345
- object
- value
- name
- created_at
- id
type: object
ProjectServiceAccountCreateRequest:
properties: &346
name:
description: The name of the service account being created.
type: string
required: &347
- name
type: object
ProjectServiceAccountCreateResponse:
properties: &348
api_key:
properties: *344
required: *345
type: object
created_at:
type: integer
id:
type: string
name:
type: string
object:
enum:
- organization.project.service_account
type: string
role:
description: Service accounts can only have one role of type `member`
enum:
- member
type: string
required: &349
- object
- id
- name
- role
- created_at
- api_key
type: object
ProjectServiceAccountDeleteResponse:
properties: &350
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.service_account.deleted
type: string
required: &351
- object
- id
- deleted
type: object
ProjectServiceAccountListResponse:
properties: &352
data:
items:
description: Represents an individual service account in a project.
properties: *331
required: *332
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
required: &353
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectUpdateRequest:
properties: &354
app_use_case:
description: A description of your business, project, or use case. [Why
we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
business_website:
description: Your business URL, or if you don't have one yet, a URL to your
LinkedIn or other social media. [Why we need this information](https://help.openai.com/en/articles/9824607-api-platform-verifications).
type: string
name:
description: The updated name of the project, this name appears in reports.
type: string
required: &355
- name
type: object
ProjectUser:
description: Represents an individual user in a project.
properties: *333
required: *334
type: object
ProjectUserCreateRequest:
properties: &356
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
user_id:
description: The ID of the user.
type: string
required: &357
- user_id
- role
type: object
ProjectUserDeleteResponse:
properties: &358
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.user.deleted
type: string
required: &359
- object
- id
- deleted
type: object
ProjectUserListResponse:
properties: &360
data:
items:
description: Represents an individual user in a project.
properties: *333
required: *334
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
type: string
required: &361
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectUserUpdateRequest:
properties: &362
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &363
- role
type: object
ResponseFormatJsonObject:
properties: *7
required: *8
type: object
ResponseFormatJsonSchema:
properties: *9
required: *10
type: object
ResponseFormatJsonSchemaSchema:
additionalProperties: true
description: The schema for the response format, described as a JSON Schema
object.
type: object
ResponseFormatText:
properties: *5
required: *6
type: object
RunCompletionUsage:
description: Usage statistics related to the run. This value will be `null`
if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.).
nullable: true
properties: *34
required: *35
type: object
RunObject:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
RunStepCompletionUsage:
description: Usage statistics related to the run step. This value will be `null`
while the run step's status is `in_progress`.
nullable: true
properties: *57
required: *58
type: object
RunStepDeltaObject:
description: |
Represents a run step delta i.e. any changed fields on a run step during streaming.
properties: *60
required: *75
title: Run step delta object
type: object
RunStepDeltaStepDetailsMessageCreationObject:
description: Details of the message creation by the run step.
properties: *61
required: *62
title: Message creation
type: object
RunStepDeltaStepDetailsToolCallsCodeObject:
description: Details of the Code Interpreter tool call the run step was involved
in.
properties: *64
required: *69
title: Code interpreter tool call
type: object
RunStepDeltaStepDetailsToolCallsCodeOutputImageObject:
properties: *67
required: *68
title: Code interpreter image output
type: object
RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject:
description: Text output from the Code Interpreter tool call as part of a run
step.
properties: *65
required: *66
title: Code interpreter log output
type: object
RunStepDeltaStepDetailsToolCallsFileSearchObject:
properties: *70
required: *71
title: File search tool call
type: object
RunStepDeltaStepDetailsToolCallsFunctionObject:
properties: *72
required: *73
title: Function tool call
type: object
RunStepDeltaStepDetailsToolCallsObject:
description: Details of the tool call.
properties: *63
required: *74
title: Tool calls
type: object
RunStepDetailsMessageCreationObject:
description: Details of the message creation by the run step.
properties: *39
required: *40
title: Message creation
type: object
RunStepDetailsToolCallsCodeObject:
description: Details of the Code Interpreter tool call the run step was involved
in.
properties: *42
required: *47
title: Code Interpreter tool call
type: object
RunStepDetailsToolCallsCodeOutputImageObject:
properties: *45
required: *46
title: Code Interpreter image output
type: object
RunStepDetailsToolCallsCodeOutputLogsObject:
description: Text output from the Code Interpreter tool call as part of a run
step.
properties: *43
required: *44
title: Code Interpreter log output
type: object
RunStepDetailsToolCallsFileSearchObject:
properties: *48
required: *53
title: File search tool call
type: object
RunStepDetailsToolCallsFileSearchRankingOptionsObject:
description: The ranking options for the file search.
properties: *49
required: *50
title: File search tool call ranking options
type: object
RunStepDetailsToolCallsFileSearchResultObject:
description: A result instance of the file search.
properties: *51
required: *52
title: File search tool call result
type: object
x-oaiTypeLabel: map
RunStepDetailsToolCallsFunctionObject:
properties: *54
required: *55
title: Function tool call
type: object
RunStepDetailsToolCallsObject:
description: Details of the tool call.
properties: *41
required: *56
title: Tool calls
type: object
RunStepObject:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
RunStepStreamEvent:
oneOf: *37
RunStreamEvent:
oneOf: *25
RunToolCallObject:
description: Tool call objects
properties: *27
required: *28
type: object
StaticChunkingStrategy:
additionalProperties: false
properties: *171
required: *172
type: object
StaticChunkingStrategyRequestParam:
additionalProperties: false
properties: *170
required: *173
title: Static Chunking Strategy
type: object
StaticChunkingStrategyResponseParam:
additionalProperties: false
properties: *314
required: *315
title: Static Chunking Strategy
type: object
SubmitToolOutputsRunRequest:
additionalProperties: false
properties: &364
stream:
description: |
If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message.
nullable: true
type: boolean
tool_outputs:
description: A list of tools for which the outputs are being submitted.
items:
properties:
output:
description: The output of the tool call to be submitted to continue
the run.
type: string
tool_call_id:
description: The ID of the tool call in the `required_action` object
within the run object the output is being submitted for.
type: string
type: object
type: array
required: &365
- tool_outputs
type: object
ThreadObject:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *23
required: *24
title: Thread
type: object
ThreadStreamEvent:
oneOf: *22
TranscriptionSegment:
properties: *229
required: *230
type: object
TranscriptionWord:
properties: *231
required: *232
type: object
TruncationObject:
description: Controls for how a thread will be truncated prior to the run. Use
this to control the intial context window of the run.
properties: *32
required: *33
title: Thread Truncation Controls
type: object
UpdateVectorStoreRequest:
additionalProperties: false
properties: &366
expires_after:
description: The expiration policy for a vector store.
nullable: true
properties: *247
required: *248
title: Vector store expiration policy
type: object
metadata:
description: |
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
nullable: true
type: object
x-oaiTypeLabel: map
name:
description: The name of the vector store.
nullable: true
type: string
type: object
Upload:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: &367
bytes:
description: The intended number of bytes to be uploaded.
type: integer
created_at:
description: The Unix timestamp (in seconds) for when the Upload was created.
type: integer
expires_at:
description: The Unix timestamp (in seconds) for when the Upload was created.
type: integer
file:
description: The ready File object after the Upload is completed.
nullable: true
properties: *293
required: *294
title: OpenAIFile
filename:
description: The name of the file to be uploaded.
type: string
id:
description: The Upload unique identifier, which can be referenced in API
endpoints.
type: string
object:
description: The object type, which is always "upload".
enum:
- upload
type: string
purpose:
description: The intended purpose of the file. [Please refer here](/docs/api-reference/files/object#files/object-purpose)
for acceptable values.
type: string
status:
description: The status of the Upload.
enum:
- pending
- completed
- cancelled
- expired
type: string
required: &368
- bytes
- created_at
- expires_at
- filename
- id
- purpose
- status
- step_number
title: Upload
type: object
UploadPart:
description: |
The upload Part represents a chunk of bytes we can add to an Upload object.
properties: &369
created_at:
description: The Unix timestamp (in seconds) for when the Part was created.
type: integer
id:
description: The upload Part unique identifier, which can be referenced
in API endpoints.
type: string
object:
description: The object type, which is always `upload.part`.
enum:
- upload.part
type: string
upload_id:
description: The ID of the Upload object that this Part was added to.
type: string
required: &370
- created_at
- id
- object
- upload_id
title: UploadPart
type: object
User:
description: Represents an individual `user` within an organization.
properties: &371
added_at:
description: The Unix timestamp (in seconds) of when the user was added.
type: integer
email:
description: The email address of the user
type: string
id:
description: The identifier, which can be referenced in API endpoints
type: string
name:
description: The name of the user
type: string
object:
description: The object type, which is always `organization.user`
enum:
- organization.user
type: string
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
required: &372
- object
- id
- name
- email
- role
- added_at
type: object
UserDeleteResponse:
properties: &373
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.user.deleted
type: string
required: &374
- object
- id
- deleted
type: object
UserListResponse:
properties: &375
data:
items:
description: Represents an individual `user` within an organization.
properties: *371
required: *372
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
required: &376
- object
- data
- first_id
- last_id
- has_more
type: object
UserRoleUpdateRequest:
properties: &377
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
required: &378
- role
type: object
VectorStoreExpirationAfter:
description: The expiration policy for a vector store.
properties: *247
required: *248
title: Vector store expiration policy
type: object
VectorStoreFileBatchObject:
description: A batch of files attached to a vector store.
properties: &379
created_at:
description: The Unix timestamp (in seconds) for when the vector store files
batch was created.
type: integer
file_counts:
properties:
cancelled:
description: The number of files that where cancelled.
type: integer
completed:
description: The number of files that have been processed.
type: integer
failed:
description: The number of files that have failed to process.
type: integer
in_progress:
description: The number of files that are currently being processed.
type: integer
total:
description: The total number of files.
type: integer
required:
- in_progress
- completed
- cancelled
- failed
- total
type: object
id:
description: The identifier, which can be referenced in API endpoints.
type: string
object:
description: The object type, which is always `vector_store.file_batch`.
enum:
- vector_store.files_batch
type: string
status:
description: The status of the vector store files batch, which can be either
`in_progress`, `completed`, `cancelled` or `failed`.
enum:
- in_progress
- completed
- cancelled
- failed
type: string
vector_store_id:
description: The ID of the [vector store](/docs/api-reference/vector-stores/object)
that the [File](/docs/api-reference/files) is attached to.
type: string
required: &380
- id
- object
- created_at
- vector_store_id
- status
- file_counts
title: Vector store file batch
type: object
VectorStoreFileObject:
description: A list of files attached to a vector store.
properties: *313
required: *318
title: Vector store files
type: object
VectorStoreObject:
description: A vector store is a collection of processed files can be used by
the `file_search` tool.
properties: *321
required: *322
title: Vector store
type: object
securitySchemes:
ApiKeyAuth:
scheme: bearer
type: http
info:
contact:
name: OpenAI Support
url: https://help.openai.com/
description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference
for more details.
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
termsOfService: https://openai.com/policies/terms-of-use
title: OpenAI API
version: 2.3.0
openapi: 3.0.0
paths:
/assistants:
get:
operationId: listAssistants
parameters:
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *286
required: *287
type: object
description: OK
summary: Returns a list of assistants.
tags:
- Assistants
post:
operationId: createAssistant
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *178
required: *179
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an `assistant` that can call the model and
use tools.
properties: *3
required: *21
title: Assistant
type: object
description: OK
summary: Create an assistant with a model and instructions.
tags:
- Assistants
/assistants/{assistant_id}:
delete:
operationId: deleteAssistant
parameters:
- description: |
The ID of the assistant to delete.
in: path
name: assistant_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *249
required: *250
type: object
description: OK
summary: Delete an assistant.
tags:
- Assistants
get:
operationId: getAssistant
parameters:
- description: |
The ID of the assistant to retrieve.
in: path
name: assistant_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an `assistant` that can call the model and
use tools.
properties: *3
required: *21
title: Assistant
type: object
description: OK
summary: Retrieves an assistant.
tags:
- Assistants
post:
operationId: modifyAssistant
parameters:
- description: |
The ID of the assistant to modify.
in: path
name: assistant_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *324
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an `assistant` that can call the model and
use tools.
properties: *3
required: *21
title: Assistant
type: object
description: OK
summary: Modifies an assistant.
tags:
- Assistants
/audio/speech:
post:
operationId: createSpeech
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *219
required: *220
type: object
required: true
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
headers:
Transfer-Encoding:
description: chunked
schema:
type: string
summary: Generates audio from the input text.
tags:
- Audio
/audio/transcriptions:
post:
operationId: createTranscription
requestBody:
content:
multipart/form-data:
schema:
additionalProperties: false
properties: *224
required: *225
type: object
required: true
responses:
'200':
content:
application/json:
schema:
oneOf:
- description: Represents a transcription response returned by model,
based on the provided input.
properties: *226
required: *227
type: object
- description: Represents a verbose json transcription response returned
by model, based on the provided input.
properties: *228
required: *233
type: object
description: OK
summary: Transcribes audio into the input language.
tags:
- Audio
/audio/translations:
post:
operationId: createTranslation
requestBody:
content:
multipart/form-data:
schema:
additionalProperties: false
properties: *234
required: *235
type: object
required: true
responses:
'200':
content:
application/json:
schema:
oneOf:
- properties: *236
required: *237
type: object
- properties: *238
required: *239
type: object
description: OK
summary: Translates audio into English.
tags:
- Audio
/batches:
get:
operationId: listBatches
parameters:
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
responses:
'200':
content:
application/json:
schema:
properties: *290
required: *291
type: object
description: Batch listed successfully.
summary: List your organization's batches.
tags:
- Batch
post:
operationId: createBatch
requestBody:
content:
application/json:
schema:
properties:
completion_window:
description: The time frame within which the batch should be processed.
Currently only `24h` is supported.
enum:
- 24h
type: string
endpoint:
description: The endpoint to be used for all requests in the batch.
Currently `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions`
are supported. Note that `/v1/embeddings` batches are also restricted
to a maximum of 50,000 embedding inputs across all requests in
the batch.
enum:
- /v1/chat/completions
- /v1/embeddings
- /v1/completions
type: string
input_file_id:
description: |
The ID of an uploaded file that contains requests for the new batch.
See [upload file](/docs/api-reference/files/create) for how to upload a file.
Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 100 MB in size.
type: string
metadata:
additionalProperties:
type: string
description: Optional custom metadata for the batch.
nullable: true
type: object
required:
- input_file_id
- endpoint
- completion_window
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *123
required: *124
type: object
description: Batch created successfully.
summary: Creates and executes a batch from an uploaded file of requests
tags:
- Batch
/batches/{batch_id}:
get:
operationId: retrieveBatch
parameters:
- description: |
The ID of the batch to retrieve.
in: path
name: batch_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *123
required: *124
type: object
description: Batch retrieved successfully.
summary: Retrieves a batch.
tags:
- Batch
/batches/{batch_id}/cancel:
post:
operationId: cancelBatch
parameters:
- description: |
The ID of the batch to cancel.
in: path
name: batch_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *123
required: *124
type: object
description: Batch is cancelling. Returns the cancelling batch's details.
summary: Cancels an in-progress batch. The batch will be in status `cancelling`
for up to 10 minutes, before changing to `cancelled`, where it will have partial
results (if any) available in the output file.
tags:
- Batch
/chat/completions:
post:
operationId: createChatCompletion
requestBody:
content:
application/json:
schema:
properties: *180
required: *182
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a chat completion response returned by model,
based on the provided input.
properties: *183
required: *185
type: object
description: OK
summary: Creates a model response for the given chat conversation.
tags:
- Chat
/completions:
post:
operationId: createCompletion
requestBody:
content:
application/json:
schema:
properties: *186
required: *187
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
properties: *188
required: *189
type: object
description: OK
summary: Creates a completion for the provided prompt and parameters.
tags:
- Completions
/embeddings:
post:
operationId: createEmbedding
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *190
required: *191
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *192
required: *195
type: object
description: OK
summary: Creates an embedding vector representing the input text.
tags:
- Embeddings
/files:
get:
operationId: listFiles
parameters:
- description: |
Only return files with the given purpose.
in: query
name: purpose
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *292
required: *295
type: object
description: OK
summary: Returns a list of files that belong to the user's organization.
tags:
- Files
post:
operationId: createFile
requestBody:
content:
multipart/form-data:
schema:
additionalProperties: false
properties: *196
required: *197
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: The `File` object represents a document that has been
uploaded to OpenAI.
properties: *293
required: *294
title: OpenAIFile
description: OK
summary: |
Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and the size of all files uploaded by one organization can be up to 100 GB.
The Assistants API supports files up to 2 million tokens and of specific file types. See the [Assistants Tools guide](/docs/assistants/tools) for details.
The Fine-tuning API only supports `.jsonl` files. The input also has certain required formats for fine-tuning [chat](/docs/api-reference/fine-tuning/chat-input) or [completions](/docs/api-reference/fine-tuning/completions-input) models.
The Batch API only supports `.jsonl` files up to 100 MB in size. The input also has a specific required [format](/docs/api-reference/batch/request-input).
Please [contact us](https://help.openai.com/) if you need to increase these storage limits.
tags:
- Files
/files/{file_id}:
delete:
operationId: deleteFile
parameters:
- description: |
The ID of the file to use for this request.
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *251
required: *252
type: object
description: OK
summary: Delete a file.
tags:
- Files
get:
operationId: retrieveFile
parameters:
- description: |
The ID of the file to use for this request.
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: The `File` object represents a document that has been
uploaded to OpenAI.
properties: *293
required: *294
title: OpenAIFile
description: OK
summary: Returns information about a specific file.
tags:
- Files
/files/{file_id}/content:
get:
operationId: downloadFile
parameters:
- description: |
The ID of the file to use for this request.
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: string
description: OK
summary: Returns the contents of the specified file.
tags:
- Files
/fine_tuning/jobs:
get:
operationId: listPaginatedFineTuningJobs
parameters:
- description: |
Identifier for the last job from the previous pagination request.
in: query
name: after
required: false
schema:
type: string
- description: |
Number of fine-tuning jobs to retrieve.
in: query
name: limit
required: false
schema:
default: 20
type: integer
responses:
'200':
content:
application/json:
schema:
properties: *306
required: *307
type: object
description: OK
summary: |
List your organization's fine-tuning jobs
tags:
- Fine-tuning
post:
operationId: createFineTuningJob
requestBody:
content:
application/json:
schema:
properties: *198
required: *199
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: *269
required: *270
title: FineTuningJob
type: object
description: OK
summary: |
Creates a fine-tuning job which begins the process of creating a new model from a given dataset.
Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.
[Learn more about fine-tuning](/docs/guides/fine-tuning)
tags:
- Fine-tuning
/fine_tuning/jobs/{fine_tuning_job_id}:
get:
operationId: retrieveFineTuningJob
parameters:
- description: |
The ID of the fine-tuning job.
in: path
name: fine_tuning_job_id
required: true
schema:
example: ft-AF1WoRqd3aJAHsqc9NY7iL8F
type: string
responses:
'200':
content:
application/json:
schema:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: *269
required: *270
title: FineTuningJob
type: object
description: OK
summary: |
Get info about a fine-tuning job.
[Learn more about fine-tuning](/docs/guides/fine-tuning)
tags:
- Fine-tuning
/fine_tuning/jobs/{fine_tuning_job_id}/cancel:
post:
operationId: cancelFineTuningJob
parameters:
- description: |
The ID of the fine-tuning job to cancel.
in: path
name: fine_tuning_job_id
required: true
schema:
example: ft-AF1WoRqd3aJAHsqc9NY7iL8F
type: string
responses:
'200':
content:
application/json:
schema:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: *269
required: *270
title: FineTuningJob
type: object
description: OK
summary: |
Immediately cancel a fine-tune job.
tags:
- Fine-tuning
/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints:
get:
operationId: listFineTuningJobCheckpoints
parameters:
- description: |
The ID of the fine-tuning job to get checkpoints for.
in: path
name: fine_tuning_job_id
required: true
schema:
example: ft-AF1WoRqd3aJAHsqc9NY7iL8F
type: string
- description: |
Identifier for the last checkpoint ID from the previous pagination
request.
in: query
name: after
required: false
schema:
type: string
- description: |
Number of checkpoints to retrieve.
in: query
name: limit
required: false
schema:
default: 10
type: integer
responses:
'200':
content:
application/json:
schema:
properties: *296
required: *297
type: object
description: OK
summary: |
List checkpoints for a fine-tuning job.
tags:
- Fine-tuning
/fine_tuning/jobs/{fine_tuning_job_id}/events:
get:
operationId: listFineTuningEvents
parameters:
- description: |
The ID of the fine-tuning job to get events for.
in: path
name: fine_tuning_job_id
required: true
schema:
example: ft-AF1WoRqd3aJAHsqc9NY7iL8F
type: string
- description: |
Identifier for the last event from the previous pagination request.
in: query
name: after
required: false
schema:
type: string
- description: "Number of events to retrieve.\n"
in: query
name: limit
required: false
schema:
default: 20
type: integer
responses:
'200':
content:
application/json:
schema:
properties: *298
required: *299
type: object
description: OK
summary: |
Get status updates for a fine-tuning job.
tags:
- Fine-tuning
/images/edits:
post:
operationId: createImageEdit
requestBody:
content:
multipart/form-data:
schema:
properties: *200
required: *203
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *276
required: *277
description: OK
summary: Creates an edited or extended image given an original image and a prompt.
tags:
- Images
/images/generations:
post:
operationId: createImage
requestBody:
content:
application/json:
schema:
properties: *204
required: *206
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *276
required: *277
description: OK
summary: Creates an image given a prompt.
tags:
- Images
/images/variations:
post:
operationId: createImageVariation
requestBody:
content:
multipart/form-data:
schema:
properties: *207
required: *208
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *276
required: *277
description: OK
summary: Creates a variation of a given image.
tags:
- Images
/models:
get:
operationId: listModels
responses:
'200':
content:
application/json:
schema:
properties: *302
required: *305
type: object
description: OK
summary: Lists the currently available models, and provides basic information
about each one such as the owner and availability.
tags:
- Models
/models/{model}:
delete:
operationId: deleteModel
parameters:
- description: "The model to delete\n"
in: path
name: model
required: true
schema:
example: ft:gpt-4o-mini:acemeco:suffix:abc123
type: string
responses:
'200':
content:
application/json:
schema:
properties: *255
required: *256
type: object
description: OK
summary: Delete a fine-tuned model. You must have the Owner role in your organization
to delete a model.
tags:
- Models
get:
operationId: retrieveModel
parameters:
- description: |
The ID of the model to use for this request
in: path
name: model
required: true
schema:
example: gpt-4o-mini
type: string
responses:
'200':
content:
application/json:
schema:
description: Describes an OpenAI model offering that can be used with
the API.
properties: *303
required: *304
title: Model
description: OK
summary: Retrieves a model instance, providing basic information about the model
such as the owner and permissioning.
tags:
- Models
/moderations:
post:
operationId: createModeration
requestBody:
content:
application/json:
schema:
properties: *213
required: *214
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents if a given text input is potentially harmful.
properties: *215
required: *216
type: object
description: OK
summary: Classifies if text is potentially harmful.
tags:
- Moderations
/organization/audit_logs:
get:
operationId: list-audit-logs
parameters:
- description: |
Return only events whose C<effective_at> (Unix seconds) is in this
range.
in: query
name: effective_at
required: false
schema:
properties:
gt:
description: Return only events whose `effective_at` (Unix seconds)
is greater than this value.
type: integer
gte:
description: Return only events whose `effective_at` (Unix seconds)
is greater than or equal to this value.
type: integer
lt:
description: Return only events whose `effective_at` (Unix seconds)
is less than this value.
type: integer
lte:
description: Return only events whose `effective_at` (Unix seconds)
is less than or equal to this value.
type: integer
type: object
- description: |
Return only events for these projects.
in: query
name: project_ids[]
required: false
schema:
items:
type: string
type: array
- description: |
Return only events with a C<type> in one of these values. For example,
C<project.created>. For all options, see the documentation for the
L<audit log
object|https://platform.openai.com/docs/api-reference/audit-logs/object
>.
in: query
name: event_types[]
required: false
schema:
items:
description: The event type.
enum: *119
type: string
x-oaiExpandable: true
type: array
- description: |
Return only events performed by these actors. Can be a user ID, a
service account ID, or an api key tracking ID.
in: query
name: actor_ids[]
required: false
schema:
items:
type: string
type: array
- description: |
Return only events performed by users with these emails.
in: query
name: actor_emails[]
required: false
schema:
items:
type: string
type: array
- description: |
Return only events performed on these targets. For example, a project
ID updated.
in: query
name: resource_ids[]
required: false
schema:
items:
type: string
type: array
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *288
required: *289
type: object
description: Audit logs listed successfully.
summary: List user actions and configuration changes within this organization.
tags:
- Audit Logs
/organization/invites:
get:
operationId: list-invites
parameters:
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *282
required: *283
type: object
description: Invites listed successfully.
summary: Returns a list of invites in the organization.
tags:
- Invites
post:
operationId: inviteUser
requestBody:
content:
application/json:
schema:
properties: *284
required: *285
type: object
description: The invite request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual `invite` to the organization.
properties: *278
required: *279
type: object
description: User invited successfully.
summary: Create an invite for a user to the organization. The invite must be
accepted by the user before they have access to the organization.
tags:
- Invites
/organization/invites/{invite_id}:
delete:
operationId: delete-invite
parameters:
- description: |
The ID of the invite to delete.
in: path
name: invite_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *280
required: *281
type: object
description: Invite deleted successfully.
summary: Delete an invite. If the invite has already been accepted, it cannot
be deleted.
tags:
- Invites
get:
operationId: retrieve-invite
parameters:
- description: |
The ID of the invite to retrieve.
in: path
name: invite_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual `invite` to the organization.
properties: *278
required: *279
type: object
description: Invite retrieved successfully.
summary: Retrieves an invite.
tags:
- Invites
/organization/projects:
get:
operationId: list-projects
parameters:
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
- description: |
If C<true> returns all projects including those that have been
C<archived>. Archived projects are not included by default.
in: query
name: include_archived
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
schema:
properties: *342
required: *343
type: object
description: Projects listed successfully.
summary: Returns a list of projects.
tags:
- Projects
post:
operationId: create-project
requestBody:
content:
application/json:
schema:
properties: *340
required: *341
type: object
description: The project create request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *328
required: *329
type: object
description: Project created successfully.
summary: Create a new project in the organization. Projects can be created and
archived, but cannot be deleted.
tags:
- Projects
/organization/projects/{project_id}:
get:
operationId: retrieve-project
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *328
required: *329
type: object
description: Project retrieved successfully.
summary: Retrieves a project.
tags:
- Projects
post:
operationId: modify-project
requestBody:
content:
application/json:
schema:
properties: *354
required: *355
type: object
description: The project update request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *328
required: *329
type: object
description: Project updated successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response when updating the default project.
summary: Modifies a project in the organization.
tags:
- Projects
/organization/projects/{project_id}/api_keys:
get:
operationId: list-project-api-keys
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *338
required: *339
type: object
description: Project API keys listed successfully.
summary: Returns a list of API keys in the project.
tags:
- Projects
/organization/projects/{project_id}/api_keys/{key_id}:
delete:
operationId: delete-project-api-key
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: "The ID of the API key.\n"
in: path
name: key_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *336
required: *337
type: object
description: Project API key deleted successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response for various conditions.
summary: Deletes an API key from the project.
tags:
- Projects
get:
operationId: retrieve-project-api-key
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: "The ID of the API key.\n"
in: path
name: key_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual API key in a project.
properties: *330
required: *335
type: object
description: Project API key retrieved successfully.
summary: Retrieves an API key in the project.
tags:
- Projects
/organization/projects/{project_id}/archive:
post:
operationId: archive-project
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *328
required: *329
type: object
description: Project archived successfully.
summary: Archives a project in the organization. Archived projects cannot be
used or updated.
tags:
- Projects
/organization/projects/{project_id}/service_accounts:
get:
operationId: list-project-service-accounts
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *352
required: *353
type: object
description: Project service accounts listed successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response when project is archived.
summary: Returns a list of service accounts in the project.
tags:
- Projects
post:
operationId: create-project-service-account
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties: *346
required: *347
type: object
description: The project service account create request payload.
required: true
responses:
'200':
content:
application/json:
schema:
properties: *348
required: *349
type: object
description: Project service account created successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response when project is archived.
summary: Creates a new service account in the project. This also returns an
unredacted API key for the service account.
tags:
- Projects
/organization/projects/{project_id}/service_accounts/{service_account_id}:
delete:
operationId: delete-project-service-account
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: |
The ID of the service account.
in: path
name: service_account_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *350
required: *351
type: object
description: Project service account deleted successfully.
summary: Deletes a service account from the project.
tags:
- Projects
get:
operationId: retrieve-project-service-account
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: |
The ID of the service account.
in: path
name: service_account_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual service account in a project.
properties: *331
required: *332
type: object
description: Project service account retrieved successfully.
summary: Retrieves a service account in the project.
tags:
- Projects
/organization/projects/{project_id}/users:
get:
operationId: list-project-users
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *360
required: *361
type: object
description: Project users listed successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response when project is archived.
summary: Returns a list of users in the project.
tags:
- Projects
post:
operationId: create-project-user
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties: *356
required: *357
type: object
description: The project user create request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual user in a project.
properties: *333
required: *334
type: object
description: User added to project successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response for various conditions.
summary: Adds a user to the project. Users must already be members of the organization
to be added to a project.
tags:
- Projects
/organization/projects/{project_id}/users/{user_id}:
delete:
operationId: delete-project-user
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: "The ID of the user.\n"
in: path
name: user_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *358
required: *359
type: object
description: Project user deleted successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response for various conditions.
summary: Deletes a user from the project.
tags:
- Projects
get:
operationId: retrieve-project-user
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: "The ID of the user.\n"
in: path
name: user_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual user in a project.
properties: *333
required: *334
type: object
description: Project user retrieved successfully.
summary: Retrieves a user in the project.
tags:
- Projects
post:
operationId: modify-project-user
requestBody:
content:
application/json:
schema:
properties: *362
required: *363
type: object
description: The project user update request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual user in a project.
properties: *333
required: *334
type: object
description: Project user's role updated successfully.
'400':
content:
application/json:
schema:
properties: *263
required: *264
type: object
description: Error response for various conditions.
summary: Modifies a user's role in the project.
tags:
- Projects
/organization/users:
get:
operationId: list-users
parameters:
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *375
required: *376
type: object
description: Users listed successfully.
summary: Lists all of the users in the organization.
tags:
- Users
/organization/users/{user_id}:
delete:
operationId: delete-user
parameters:
- description: "The ID of the user.\n"
in: path
name: user_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *373
required: *374
type: object
description: User deleted successfully.
summary: Deletes a user from the organization.
tags:
- Users
get:
operationId: retrieve-user
parameters:
- description: "The ID of the user.\n"
in: path
name: user_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an individual `user` within an organization.
properties: *371
required: *372
type: object
description: User retrieved successfully.
summary: Retrieves a user by their identifier.
tags:
- Users
post:
operationId: modify-user
requestBody:
content:
application/json:
schema:
properties: *377
required: *378
type: object
description: The new user role to modify. This must be one of `owner` or `member`.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual `user` within an organization.
properties: *371
required: *372
type: object
description: User role updated successfully.
summary: Modifies a user's role in the organization.
tags:
- Users
/threads:
post:
operationId: createThread
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *222
type: object
responses:
'200':
content:
application/json:
schema:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *23
required: *24
title: Thread
type: object
description: OK
summary: Create a thread.
tags:
- Assistants
/threads/runs:
post:
operationId: createThreadAndRun
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *221
required: *223
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: Create a thread and run it in one request.
tags:
- Assistants
/threads/{thread_id}:
delete:
operationId: deleteThread
parameters:
- description: |
The ID of the thread to delete.
in: path
name: thread_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *257
required: *258
type: object
description: OK
summary: Delete a thread.
tags:
- Assistants
get:
operationId: getThread
parameters:
- description: |
The ID of the thread to retrieve.
in: path
name: thread_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *23
required: *24
title: Thread
type: object
description: OK
summary: Retrieves a thread.
tags:
- Assistants
post:
operationId: modifyThread
parameters:
- description: |
The ID of the thread to modify. Only the C<metadata> can be modified.
in: path
name: thread_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *327
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *23
required: *24
title: Thread
type: object
description: OK
summary: Modifies a thread.
tags:
- Assistants
/threads/{thread_id}/messages:
get:
operationId: listMessages
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> the
messages belong to.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
- description: |
Filter messages by the run ID that generated them.
in: query
name: run_id
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *300
required: *301
description: OK
summary: Returns a list of messages for a given thread.
tags:
- Assistants
post:
operationId: createMessage
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> to
create a message for.
in: path
name: thread_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *209
required: *212
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
description: OK
summary: Create a message.
tags:
- Assistants
/threads/{thread_id}/messages/{message_id}:
delete:
operationId: deleteMessage
parameters:
- description: |
The ID of the thread to which this message belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the message to delete.
in: path
name: message_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *253
required: *254
type: object
description: OK
summary: Deletes a message.
tags:
- Assistants
get:
operationId: getMessage
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> to
which this message belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the message to retrieve.
in: path
name: message_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
description: OK
summary: Retrieve a message.
tags:
- Assistants
post:
operationId: modifyMessage
parameters:
- description: |
The ID of the thread to which this message belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the message to modify.
in: path
name: message_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *325
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *77
required: *92
title: The message object
type: object
description: OK
summary: Modifies a message.
tags:
- Assistants
/threads/{thread_id}/runs:
get:
operationId: listRuns
parameters:
- description: |
The ID of the thread the run belongs to.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *310
required: *311
type: object
description: OK
summary: Returns a list of runs belonging to a thread.
tags:
- Assistants
post:
operationId: createRun
parameters:
- description: "The ID of the thread to run.\n"
in: path
name: thread_id
required: true
schema:
type: string
- description: |
A list of additional fields to include in the response. Currently the
only supported value is
C<step_details.tool_calls[*].file_search.results[*].content> to fetch
the file search result content.
See the L<file search tool
documentation|https://platform.openai.com/docs/assistants/tools/file-se
arch/customizing-file-search-settings> for more information.
in: query
name: include[]
schema:
items:
enum:
- step_details.tool_calls[*].file_search.results[*].content
type: string
type: array
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *217
required: *218
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: Create a run.
tags:
- Assistants
/threads/{thread_id}/runs/{run_id}:
get:
operationId: getRun
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> that
was run.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the run to retrieve.
in: path
name: run_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: Retrieves a run.
tags:
- Assistants
post:
operationId: modifyRun
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> that
was run.
in: path
name: thread_id
required: true
schema:
type: string
- description: "The ID of the run to modify.\n"
in: path
name: run_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *326
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: Modifies a run.
tags:
- Assistants
/threads/{thread_id}/runs/{run_id}/cancel:
post:
operationId: cancelRun
parameters:
- description: |
The ID of the thread to which this run belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: "The ID of the run to cancel.\n"
in: path
name: run_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: Cancels a run that is `in_progress`.
tags:
- Assistants
/threads/{thread_id}/runs/{run_id}/steps:
get:
operationId: listRunSteps
parameters:
- description: |
The ID of the thread the run and run steps belong to.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the run the run steps belong to.
in: path
name: run_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
- description: |
A list of additional fields to include in the response. Currently the
only supported value is
C<step_details.tool_calls[*].file_search.results[*].content> to fetch
the file search result content.
See the L<file search tool
documentation|https://platform.openai.com/docs/assistants/tools/file-se
arch/customizing-file-search-settings> for more information.
in: query
name: include[]
schema:
items:
enum:
- step_details.tool_calls[*].file_search.results[*].content
type: string
type: array
responses:
'200':
content:
application/json:
schema:
properties: *308
required: *309
description: OK
summary: Returns a list of run steps belonging to a run.
tags:
- Assistants
/threads/{thread_id}/runs/{run_id}/steps/{step_id}:
get:
operationId: getRunStep
parameters:
- description: |
The ID of the thread to which the run and run step belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the run to which the run step belongs.
in: path
name: run_id
required: true
schema:
type: string
- description: |
The ID of the run step to retrieve.
in: path
name: step_id
required: true
schema:
type: string
- description: |
A list of additional fields to include in the response. Currently the
only supported value is
C<step_details.tool_calls[*].file_search.results[*].content> to fetch
the file search result content.
See the L<file search tool
documentation|https://platform.openai.com/docs/assistants/tools/file-se
arch/customizing-file-search-settings> for more information.
in: query
name: include[]
schema:
items:
enum:
- step_details.tool_calls[*].file_search.results[*].content
type: string
type: array
responses:
'200':
content:
application/json:
schema:
description: |
Represents a step in execution of a run.
properties: *38
required: *59
title: Run steps
type: object
description: OK
summary: Retrieves a run step.
tags:
- Assistants
/threads/{thread_id}/runs/{run_id}/submit_tool_outputs:
post:
operationId: submitToolOuputsToRun
parameters:
- description: |
The ID of the
L<thread|https://platform.openai.com/docs/api-reference/threads> to
which this run belongs.
in: path
name: thread_id
required: true
schema:
type: string
- description: |
The ID of the run that requires the tool output submission.
in: path
name: run_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *364
required: *365
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *26
required: *36
title: A run on a thread
type: object
description: OK
summary: |
When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request.
tags:
- Assistants
/uploads:
post:
operationId: createUpload
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *240
required: *241
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: *367
required: *368
title: Upload
type: object
description: OK
summary: |
Creates an intermediate [Upload](/docs/api-reference/uploads/object) object that you can add [Parts](/docs/api-reference/uploads/part-object) to. Currently, an Upload can accept at most 8 GB in total and expires after an hour after you create it.
Once you complete the Upload, we will create a [File](/docs/api-reference/files/object) object that contains all the parts you uploaded. This File is usable in the rest of our platform as a regular File object.
For certain `purpose`s, the correct `mime_type` must be specified. Please refer to documentation for the supported MIME types for your use case:
- [Assistants](/docs/assistants/tools/file-search/supported-files)
For guidance on the proper filename extensions for each purpose, please follow the documentation on [creating a File](/docs/api-reference/files/create).
tags:
- Uploads
/uploads/{upload_id}/cancel:
post:
operationId: cancelUpload
parameters:
- description: "The ID of the Upload.\n"
in: path
name: upload_id
required: true
schema:
example: upload_abc123
type: string
responses:
'200':
content:
application/json:
schema:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: *367
required: *368
title: Upload
type: object
description: OK
summary: |
Cancels the Upload. No Parts may be added after an Upload is cancelled.
tags:
- Uploads
/uploads/{upload_id}/complete:
post:
operationId: completeUpload
parameters:
- description: "The ID of the Upload.\n"
in: path
name: upload_id
required: true
schema:
example: upload_abc123
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *174
required: *175
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: *367
required: *368
title: Upload
type: object
description: OK
summary: "Completes the [Upload](/docs/api-reference/uploads/object). \n\nWithin
the returned Upload object, there is a nested [File](/docs/api-reference/files/object)
object that is ready to use in the rest of the platform.\n\nYou can specify
the order of the Parts by passing in an ordered list of the Part IDs.\n\nThe
number of bytes uploaded upon completion must match the number of bytes initially
specified when creating the Upload object. No Parts may be added after an
Upload is completed.\n"
tags:
- Uploads
/uploads/{upload_id}/parts:
post:
operationId: addUploadPart
parameters:
- description: "The ID of the Upload.\n"
in: path
name: upload_id
required: true
schema:
example: upload_abc123
type: string
requestBody:
content:
multipart/form-data:
schema:
additionalProperties: false
properties: *1
required: *2
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The upload Part represents a chunk of bytes we can add to an Upload object.
properties: *369
required: *370
title: UploadPart
type: object
description: OK
summary: "Adds a [Part](/docs/api-reference/uploads/part-object) to an [Upload](/docs/api-reference/uploads/object)
object. A Part represents a chunk of bytes from the file you are trying to
upload. \n\nEach Part can be at most 64 MB, and you can add Parts until you
hit the Upload maximum of 8 GB.\n\nIt is possible to add multiple Parts in
parallel. You can decide the intended order of the Parts when you [complete
the Upload](/docs/api-reference/uploads/complete).\n"
tags:
- Uploads
/vector_stores:
get:
operationId: listVectorStores
parameters:
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *320
required: *323
description: OK
summary: Returns a list of vector stores.
tags:
- Vector Stores
post:
operationId: createVectorStore
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *246
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A vector store is a collection of processed files can
be used by the `file_search` tool.
properties: *321
required: *322
title: Vector store
type: object
description: OK
summary: Create a vector store.
tags:
- Vector Stores
/vector_stores/{vector_store_id}:
delete:
operationId: deleteVectorStore
parameters:
- description: |
The ID of the vector store to delete.
in: path
name: vector_store_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *261
required: *262
type: object
description: OK
summary: Delete a vector store.
tags:
- Vector Stores
get:
operationId: getVectorStore
parameters:
- description: |
The ID of the vector store to retrieve.
in: path
name: vector_store_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: A vector store is a collection of processed files can
be used by the `file_search` tool.
properties: *321
required: *322
title: Vector store
type: object
description: OK
summary: Retrieves a vector store.
tags:
- Vector Stores
post:
operationId: modifyVectorStore
parameters:
- description: |
The ID of the vector store to modify.
in: path
name: vector_store_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *366
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A vector store is a collection of processed files can
be used by the `file_search` tool.
properties: *321
required: *322
title: Vector store
type: object
description: OK
summary: Modifies a vector store.
tags:
- Vector Stores
/vector_stores/{vector_store_id}/file_batches:
post:
operationId: createVectorStoreFileBatch
parameters:
- description: |
The ID of the vector store for which to create a File Batch.
in: path
name: vector_store_id
required: true
schema:
example: vs_abc123
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *242
required: *243
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A batch of files attached to a vector store.
properties: *379
required: *380
title: Vector store file batch
type: object
description: OK
summary: Create a vector store file batch.
tags:
- Vector Stores
/vector_stores/{vector_store_id}/file_batches/{batch_id}:
get:
operationId: getVectorStoreFileBatch
parameters:
- description: |
The ID of the vector store that the file batch belongs to.
in: path
name: vector_store_id
required: true
schema:
example: vs_abc123
type: string
- description: |
The ID of the file batch being retrieved.
in: path
name: batch_id
required: true
schema:
example: vsfb_abc123
type: string
responses:
'200':
content:
application/json:
schema:
description: A batch of files attached to a vector store.
properties: *379
required: *380
title: Vector store file batch
type: object
description: OK
summary: Retrieves a vector store file batch.
tags:
- Vector Stores
/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel:
post:
operationId: cancelVectorStoreFileBatch
parameters:
- description: |
The ID of the vector store that the file batch belongs to.
in: path
name: vector_store_id
required: true
schema:
type: string
- description: |
The ID of the file batch to cancel.
in: path
name: batch_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: A batch of files attached to a vector store.
properties: *379
required: *380
title: Vector store file batch
type: object
description: OK
summary: Cancel a vector store file batch. This attempts to cancel the processing
of files in this batch as soon as possible.
tags:
- Vector Stores
/vector_stores/{vector_store_id}/file_batches/{batch_id}/files:
get:
operationId: listFilesInVectorStoreBatch
parameters:
- description: |
The ID of the vector store that the files belong to.
in: path
name: vector_store_id
required: true
schema:
type: string
- description: |
The ID of the file batch that the files belong to.
in: path
name: batch_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
- description: |
Filter by file status. One of C<in_progress>, C<completed>, C<failed>,
C<cancelled>.
in: query
name: filter
schema:
enum:
- in_progress
- completed
- failed
- cancelled
type: string
responses:
'200':
content:
application/json:
schema:
properties: *312
required: *319
description: OK
summary: Returns a list of vector store files in a batch.
tags:
- Vector Stores
/vector_stores/{vector_store_id}/files:
get:
operationId: listVectorStoreFiles
parameters:
- description: |
The ID of the vector store that the files belong to.
in: path
name: vector_store_id
required: true
schema:
type: string
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
in: query
name: limit
required: false
schema:
default: 20
type: integer
- description: |
Sort order by the C timestamp of the objects. C for
ascending order and C for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the next
page of the list.
in: query
name: after
schema:
type: string
- description: |
A cursor for use in pagination. C is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, ending with objIfoo in order to fetch the previous
page of the list.
in: query
name: before
schema:
type: string
- description: |
Filter by file status. One of C<in_progress>, C<completed>, C<failed>,
C<cancelled>.
in: query
name: filter
schema:
enum:
- in_progress
- completed
- failed
- cancelled
type: string
responses:
'200':
content:
application/json:
schema:
properties: *312
required: *319
description: OK
summary: Returns a list of vector store files.
tags:
- Vector Stores
post:
operationId: createVectorStoreFile
parameters:
- description: |
The ID of the vector store for which to create a File.
in: path
name: vector_store_id
required: true
schema:
example: vs_abc123
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *244
required: *245
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A list of files attached to a vector store.
properties: *313
required: *318
title: Vector store files
type: object
description: OK
summary: Create a vector store file by attaching a [File](/docs/api-reference/files)
to a [vector store](/docs/api-reference/vector-stores/object).
tags:
- Vector Stores
/vector_stores/{vector_store_id}/files/{file_id}:
delete:
operationId: deleteVectorStoreFile
parameters:
- description: |
The ID of the vector store that the file belongs to.
in: path
name: vector_store_id
required: true
schema:
type: string
- description: "The ID of the file to delete.\n"
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *259
required: *260
type: object
description: OK
summary: Delete a vector store file. This will remove the file from the vector
store but the file itself will not be deleted. To delete the file, use the
[delete file](/docs/api-reference/files/delete) endpoint.
tags:
- Vector Stores
get:
operationId: getVectorStoreFile
parameters:
- description: |
The ID of the vector store that the file belongs to.
in: path
name: vector_store_id
required: true
schema:
example: vs_abc123
type: string
- description: |
The ID of the file being retrieved.
in: path
name: file_id
required: true
schema:
example: file-abc123
type: string
responses:
'200':
content:
application/json:
schema:
description: A list of files attached to a vector store.
properties: *313
required: *318
title: Vector store files
type: object
description: OK
summary: Retrieves a vector store file.
tags:
- Vector Stores
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
tags:
- description: Build Assistants that can call models and use tools.
name: Assistants
- description: Turn audio into text or text into audio.
name: Audio
- description: Given a list of messages comprising a conversation, the model will
return a response.
name: Chat
- description: Given a prompt, the model will return one or more predicted completions,
and can also return the probabilities of alternative tokens at each position.
name: Completions
- description: Get a vector representation of a given input that can be easily consumed
by machine learning models and algorithms.
name: Embeddings
- description: Manage fine-tuning jobs to tailor a model to your specific training
data.
name: Fine-tuning
- description: Create large batches of API requests to run asynchronously.
name: Batch
- description: Files are used to upload documents that can be used with features like
Assistants and Fine-tuning.
name: Files
- description: Use Uploads to upload large files in multiple parts.
name: Uploads
- description: Given a prompt and/or an input image, the model will generate a new
image.
name: Images
- description: List and describe the various models available in the API.
name: Models
- description: Given a input text, outputs if the model classifies it as potentially
harmful.
name: Moderations
- description: List user actions and configuration changes within this organization.
name: Audit LogsCOPYRIGHT AND LICENSE
Copyright (C) 2023-2024 by Nelson Ferraz
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.0 or, at your option, any later version of Perl 5 you may have available.