OpenAPI-Client-OpenAI/lib/OpenAPI/Client/OpenAI/Schema.pod
=encoding UTF-8
=head1 NAME
OpenAPI::Client::OpenAI::Schema - OpenAI API client Schema
=head1 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.
=head1 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
AdminApiKey:
properties: &3
created_at:
example: 1711471533
format: int64
type: integer
id:
example: key_abc
type: string
name:
example: Administration Key
type: string
object:
example: organization.admin_api_key
type: string
owner:
properties:
created_at:
example: 1711471533
format: int64
type: integer
id:
example: sa_456
type: string
name:
example: My Service Account
type: string
role:
example: member
type: string
type:
example: service_account
type: string
type: object
redacted_value:
example: sk-admin...def
type: string
value:
example: sk-admin-1234abcd
type: string
type: object
ApiKeyList:
properties: &4
data:
items:
properties: *3
type: object
type: array
first_id:
example: key_abc
type: string
has_more:
example: false
type: boolean
last_id:
example: key_xyz
type: string
object:
example: list
type: string
type: object
AssistantObject:
description: Represents an `assistant` that can call the model and use tools.
properties: &5
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:
additionalProperties: &6
type: string
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
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) 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
x-stainless-const: true
response_format:
allOf:
- 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: &7
- description: "`auto` is the default value\n"
enum:
- auto
type: string
x-stainless-const: true
- properties: &8
type:
description: 'The type of response format being defined: `text`'
enum:
- text
type: string
x-stainless-const: true
required: &9
- type
type: object
- properties: &10
type:
description: 'The type of response format being defined: `json_object`'
enum:
- json_object
type: string
x-stainless-const: true
required: &11
- type
type: object
- properties: &12
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:
- name
type: object
type:
description: 'The type of response format being defined: `json_schema`'
enum:
- json_schema
type: string
x-stainless-const: true
required: &13
- type
- json_schema
type: object
x-oaiExpandable: true
- nullable: 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: &14
type:
description: 'The type of tool being defined: `code_interpreter`'
enum:
- code_interpreter
type: string
x-stainless-const: true
required: &15
- type
title: Code interpreter tool
type: object
- properties: &16
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: &17
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: &18
- 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
x-stainless-const: true
required: &19
- type
title: FileSearch tool
type: object
- properties: &20
function:
properties: &21
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: &22
- name
type: object
type:
description: 'The type of tool being defined: `function`'
enum:
- function
type: string
x-stainless-const: true
required: &23
- 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: &24
- 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: &25
- 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: &26
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to
an object. This can be\nuseful for storing additional information
about the object in a structured\nformat, and querying for objects
via API or the dashboard. \n\nKeys are strings with a maximum
length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread`.
enum:
- thread
type: string
x-stainless-const: true
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: &27
- id
- object
- created_at
- tool_resources
- metadata
title: Thread
type: object
enabled:
description: Whether to enable input audio transcription.
type: boolean
event:
enum:
- thread.created
type: string
x-stainless-const: true
required:
- event
- data
type: object
- oneOf: &28
- 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: &29
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to
an object. This can be\nuseful for storing additional information
about the object in a structured\nformat, and querying for objects
via API or the dashboard. \n\nKeys are strings with a maximum
length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
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
x-stainless-const: true
parallel_tool_calls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-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: &30
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
x-stainless-const: true
required: &31
- 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
x-stainless-const: true
required:
- type
- submit_tool_outputs
type: object
response_format:
allOf:
- 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: *7
x-oaiExpandable: true
- nullable: 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:
allOf:
- 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: &32
- 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: &33
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: &34
- type
type: object
x-oaiExpandable: true
- nullable: true
tools:
default: []
description: The list of tools that the [assistant](/docs/api-reference/assistants)
used for this run.
items:
oneOf:
- properties: *14
required: *15
title: Code interpreter tool
type: object
- properties: *16
required: *19
title: FileSearch tool
type: object
- properties: *20
required: *23
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:
allOf:
- 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: &35
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: &36
- type
title: Thread Truncation Controls
type: object
- nullable: true
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: &37
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: &38
- prompt_tokens
- completion_tokens
- total_tokens
type: object
required: &39
- 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
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.queued
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.in_progress
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.requires_action
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.completed
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.incomplete
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.failed
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.cancelling
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.cancelled
type: string
x-stainless-const: true
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: *29
required: *39
title: A run on a thread
type: object
event:
enum:
- thread.run.expired
type: string
x-stainless-const: true
required:
- event
- data
type: object
- oneOf: &40
- 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: &41
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to
an object. This can be\nuseful for storing additional information
about the object in a structured\nformat, and querying for objects
via API or the dashboard. \n\nKeys are strings with a maximum
length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread.run.step`.
enum:
- thread.run.step
type: string
x-stainless-const: true
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: &42
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
x-stainless-const: true
required: &43
- type
- message_creation
title: Message creation
type: object
- description: Details of the tool call.
properties: &44
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: &45
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: &46
logs:
description: The text output from the
Code Interpreter tool call.
type: string
type:
description: Always `logs`.
enum:
- logs
type: string
x-stainless-const: true
required: &47
- type
- logs
title: Code Interpreter log output
type: object
- properties: &48
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
x-stainless-const: true
required: &49
- 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
x-stainless-const: true
required: &50
- id
- type
- code_interpreter
title: Code Interpreter tool call
type: object
- properties: &51
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: &52
ranker:
description: The ranker used for the file
search.
enum:
- default_2024_08_21
type: string
x-stainless-const: true
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: &53
- 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: &54
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
x-stainless-const: true
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: &55
- 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
x-stainless-const: true
required: &56
- id
- type
- file_search
title: File search tool call
type: object
- properties: &57
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
x-stainless-const: true
required: &58
- id
- type
- function
title: Function tool call
type: object
x-oaiExpandable: true
type: array
type:
description: Always `tool_calls`.
enum:
- tool_calls
type: string
x-stainless-const: true
required: &59
- 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: &60
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: &61
- prompt_tokens
- completion_tokens
- total_tokens
type: object
required: &62
- 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
x-stainless-const: true
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: *41
required: *62
title: Run steps
type: object
event:
enum:
- thread.run.step.in_progress
type: string
x-stainless-const: true
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: &63
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: &64
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
x-stainless-const: true
required: &65
- type
title: Message creation
type: object
- description: Details of the tool call.
properties: &66
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: &67
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: &68
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
x-stainless-const: true
required: &69
- index
- type
title: Code interpreter log output
type: object
- properties: &70
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
x-stainless-const: true
required: &71
- 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
x-stainless-const: true
required: &72
- index
- type
title: Code interpreter tool call
type: object
- properties: &73
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
x-stainless-const: true
required: &74
- index
- type
- file_search
title: File search tool call
type: object
- properties: &75
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
x-stainless-const: true
required: &76
- index
- type
title: Function tool call
type: object
x-oaiExpandable: true
type: array
type:
description: Always `tool_calls`.
enum:
- tool_calls
type: string
x-stainless-const: true
required: &77
- 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
x-stainless-const: true
required: &78
- id
- object
- delta
title: Run step delta object
type: object
event:
enum:
- thread.run.step.delta
type: string
x-stainless-const: true
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: *41
required: *62
title: Run steps
type: object
event:
enum:
- thread.run.step.completed
type: string
x-stainless-const: true
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: *41
required: *62
title: Run steps
type: object
event:
enum:
- thread.run.step.failed
type: string
x-stainless-const: true
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: *41
required: *62
title: Run steps
type: object
event:
enum:
- thread.run.step.cancelled
type: string
x-stainless-const: true
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: *41
required: *62
title: Run steps
type: object
event:
enum:
- thread.run.step.expired
type: string
x-stainless-const: true
required:
- event
- data
type: object
- oneOf: &79
- 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: &80
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: *14
required: *15
title: Code interpreter tool
type: object
- properties: &81
type:
description: 'The type of tool being defined: `file_search`'
enum:
- file_search
type: string
x-stainless-const: true
required: &82
- 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: &83
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
x-stainless-const: true
required: &84
- type
- image_file
title: Image file
type: object
- description: References an image URL in the content of a message.
properties: &85
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
x-stainless-const: true
required: &86
- type
- image_url
title: Image URL
type: object
- description: The text content that is part of a message.
properties: &87
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: &88
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
x-stainless-const: true
required: &89
- 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: &90
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
x-stainless-const: true
required: &91
- 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
x-stainless-const: true
required: &92
- type
- text
title: Text
type: object
- description: The refusal content generated by the assistant.
properties: &93
refusal:
nullable: false
type: string
type:
description: Always `refusal`.
enum:
- refusal
type: string
x-stainless-const: true
required: &94
- 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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to
an object. This can be\nuseful for storing additional information
about the object in a structured\nformat, and querying for objects
via API or the dashboard. \n\nKeys are strings with a maximum
length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `thread.message`.
enum:
- thread.message
type: string
x-stainless-const: true
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: &95
- 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
x-stainless-const: true
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: *80
required: *95
title: The message object
type: object
event:
enum:
- thread.message.in_progress
type: string
x-stainless-const: true
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: &96
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: &97
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
x-stainless-const: true
required: &98
- index
- type
title: Image file
type: object
- description: The text content that is part of a message.
properties: &99
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: &100
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
x-stainless-const: true
required: &101
- 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: &102
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
x-stainless-const: true
required: &103
- 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
x-stainless-const: true
required: &104
- index
- type
title: Text
type: object
- description: The refusal content that is part of a message.
properties: &105
index:
description: The index of the refusal part in the message.
type: integer
refusal:
type: string
type:
description: Always `refusal`.
enum:
- refusal
type: string
x-stainless-const: true
required: &106
- index
- type
title: Refusal
type: object
- description: References an image URL in the content of a
message.
properties: &107
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
x-stainless-const: true
required: &108
- 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
x-stainless-const: true
required: &109
- id
- object
- delta
title: Message delta object
type: object
event:
enum:
- thread.message.delta
type: string
x-stainless-const: true
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: *80
required: *95
title: The message object
type: object
event:
enum:
- thread.message.completed
type: string
x-stainless-const: true
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: *80
required: *95
title: The message object
type: object
event:
enum:
- thread.message.incomplete
type: string
x-stainless-const: true
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: &110
data:
properties: &111
code:
nullable: true
type: string
message:
nullable: false
type: string
param:
nullable: true
type: string
type:
nullable: false
type: string
required: &112
- type
- message
- param
- code
type: object
event:
enum:
- error
type: string
x-stainless-const: true
required: &113
- event
- data
type: object
- description: Occurs when a stream ends.
properties: &114
data:
enum:
- '[DONE]'
type: string
x-stainless-const: true
event:
enum:
- done
type: string
x-stainless-const: true
required: &115
- event
- data
type: object
AssistantSupportedModels:
enum: &116
- o3-mini
- o3-mini-2025-01-31
- o1
- o1-2024-12-17
- gpt-4o
- gpt-4o-2024-11-20
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- 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
AssistantToolsCode:
properties: *14
required: *15
title: Code interpreter tool
type: object
AssistantToolsFileSearch:
properties: *16
required: *19
title: FileSearch tool
type: object
AssistantToolsFileSearchTypeOnly:
properties: *81
required: *82
title: FileSearch tool
type: object
AssistantToolsFunction:
properties: *20
required: *23
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: *7
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: *32
x-oaiExpandable: true
AssistantsNamedToolChoice:
description: Specifies a tool the model should use. Use to force the model to
call a specific tool.
properties: *33
required: *34
type: object
AudioResponseFormat:
default: json
description: |
The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.
enum: &117
- json
- text
- srt
- verbose_json
- vtt
type: string
AuditLog:
description: A log of a user action or configuration change within this organization.
properties: &118
actor:
description: The actor who performed the audit logged action.
properties: &119
api_key:
description: The API Key used to perform the audit logged action.
properties: &120
id:
description: The tracking id of the API key.
type: string
service_account:
description: The service account that performed the audit logged
action.
properties: &121
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: &122
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: &123
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: *122
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
rate_limit.deleted:
description: The details for events with this `type`.
properties:
id:
description: The rate limit ID
type: string
type: object
rate_limit.updated:
description: The details for events with this `type`.
properties:
changes_requested:
description: The payload used to update the rate limits.
properties:
batch_1_day_max_input_tokens:
description: The maximum batch input tokens per day. Only relevant
for certain models.
type: integer
max_audio_megabytes_per_1_minute:
description: The maximum audio megabytes per minute. Only relevant
for certain models.
type: integer
max_images_per_1_minute:
description: The maximum images per minute. Only relevant for certain
models.
type: integer
max_requests_per_1_day:
description: The maximum requests per day. Only relevant for certain
models.
type: integer
max_requests_per_1_minute:
description: The maximum requests per minute.
type: integer
max_tokens_per_1_minute:
description: The maximum tokens per minute.
type: integer
type: object
id:
description: The rate limit 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: &124
- 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
- rate_limit.updated
- rate_limit.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: &125
- id
- type
- effective_at
- actor
type: object
AuditLogActor:
description: The actor who performed the audit logged action.
properties: *119
type: object
AuditLogActorApiKey:
description: The API Key used to perform the audit logged action.
properties: *120
type: object
AuditLogActorServiceAccount:
description: The service account that performed the audit logged action.
properties: *121
type: object
AuditLogActorSession:
description: The session in which the audit logged action was performed.
properties: *123
type: object
AuditLogActorUser:
description: The user who performed the audit logged action.
properties: *122
type: object
AuditLogEventType:
description: The event type.
enum: *124
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: &126
type:
description: Always `auto`.
enum:
- auto
type: string
x-stainless-const: true
required: &127
- type
title: Auto Chunking Strategy
type: object
Batch:
properties: &128
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
object:
description: The object type, which is always `batch`.
enum:
- batch
type: string
x-stainless-const: true
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: &129
- 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
x-stainless-const: true
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: &130
name:
description: The name of the function to call.
type: string
required: &131
- name
type: object
ChatCompletionFunctions:
deprecated: true
properties: &132
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: &133
- name
type: object
ChatCompletionMessageToolCall:
properties: &134
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
x-stainless-const: true
required: &135
- id
- type
- function
type: object
ChatCompletionMessageToolCallChunk:
properties: &136
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
x-stainless-const: true
required: &137
- index
type: object
ChatCompletionMessageToolCalls:
description: The tool calls generated by the model, such as function calls.
items: &138
properties: *134
required: *135
type: object
type: array
ChatCompletionModalities:
description: |
Output types that you would like the model to generate for this request.
Most models are capable of generating text, which is the default:
`["text"]`
The `gpt-4o-audio-preview` model can also be used to [generate audio](/docs/guides/audio). To
request that this model generate both text and audio responses, you can
use:
`["text", "audio"]`
items: &139
enum:
- text
- audio
type: string
nullable: true
type: array
ChatCompletionNamedToolChoice:
description: Specifies a tool the model should use. Use to force the model to
call a specific function.
properties: &140
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
x-stainless-const: true
required: &141
- type
- function
type: object
ChatCompletionRequestAssistantMessage:
description: |
Messages sent by the model in response to user messages.
properties: &142
audio:
description: "Data about a previous audio response from the model. \n[Learn
more](/docs/guides/audio).\n"
nullable: true
properties:
id:
description: |
Unique identifier for a previous audio response from the model.
type: string
required:
- id
type: object
x-oaiExpandable: true
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: &143
- description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: &144
text:
description: The text content.
type: string
type:
description: The type of the content part.
enum:
- text
type: string
x-stainless-const: true
required: &145
- type
- text
title: Text content part
type: object
- properties: &146
refusal:
description: The refusal message generated by the model.
type: string
type:
description: The type of the content part.
enum:
- refusal
type: string
x-stainless-const: true
required: &147
- type
- refusal
title: Refusal content part
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
x-oaiExpandable: true
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
x-stainless-const: true
tool_calls:
description: The tool calls generated by the model, such as function calls.
items: *138
type: array
required: &148
- role
title: Assistant message
type: object
ChatCompletionRequestAssistantMessageContentPart:
oneOf: *143
x-oaiExpandable: true
ChatCompletionRequestDeveloperMessage:
description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, `developer` messages
replace the previous `system` messages.
properties: &149
content:
description: The contents of the developer message.
oneOf:
- description: The contents of the developer message.
title: Text content
type: string
- description: An array of content parts with a defined type. For developer
messages, only type `text` is supported.
items:
description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
title: Text content part
type: object
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 `developer`.
enum:
- developer
type: string
x-stainless-const: true
required: &150
- content
- role
title: Developer message
type: object
ChatCompletionRequestFunctionMessage:
deprecated: true
properties: &151
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
x-stainless-const: true
required: &152
- role
- content
- name
title: Function message
type: object
ChatCompletionRequestMessage:
oneOf: &153
- description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, `developer` messages
replace the previous `system` messages.
properties: *149
required: *150
title: Developer message
type: object
- description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
properties: &154
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: &155
- description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
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
x-stainless-const: true
required: &156
- content
- role
title: System message
type: object
- description: |
Messages sent by an end user, containing prompts or additional context
information.
properties: &157
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. Supported
options differ based on the [model](/docs/models) being used to generate
the response. Can contain text, image, or audio inputs.
items:
oneOf: &158
- description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
title: Text content part
type: object
- description: |
Learn about [image inputs](/docs/guides/vision).
properties: &159
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
x-stainless-const: true
required: &160
- type
- image_url
title: Image content part
type: object
- description: |
Learn about [audio inputs](/docs/guides/audio).
properties: &161
input_audio:
properties:
data:
description: Base64 encoded audio data.
type: string
format:
description: |
The format of the encoded audio data. Currently supports "wav" and "mp3".
enum:
- wav
- mp3
type: string
required:
- data
- format
type: object
type:
description: The type of the content part. Always `input_audio`.
enum:
- input_audio
type: string
x-stainless-const: true
required: &162
- type
- input_audio
title: Audio 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
x-stainless-const: true
required: &163
- content
- role
title: User message
type: object
- description: |
Messages sent by the model in response to user messages.
properties: *142
required: *148
title: Assistant message
type: object
- properties: &164
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: &165
- description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
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
x-stainless-const: true
tool_call_id:
description: Tool call that this message is responding to.
type: string
required: &166
- role
- content
- tool_call_id
title: Tool message
type: object
- deprecated: true
properties: *151
required: *152
title: Function message
type: object
x-oaiExpandable: true
ChatCompletionRequestMessageContentPartAudio:
description: |
Learn about [audio inputs](/docs/guides/audio).
properties: *161
required: *162
title: Audio content part
type: object
ChatCompletionRequestMessageContentPartImage:
description: |
Learn about [image inputs](/docs/guides/vision).
properties: *159
required: *160
title: Image content part
type: object
ChatCompletionRequestMessageContentPartRefusal:
properties: *146
required: *147
title: Refusal content part
type: object
ChatCompletionRequestMessageContentPartText:
description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
title: Text content part
type: object
ChatCompletionRequestSystemMessage:
description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
properties: *154
required: *156
title: System message
type: object
ChatCompletionRequestSystemMessageContentPart:
oneOf: *155
x-oaiExpandable: true
ChatCompletionRequestToolMessage:
properties: *164
required: *166
title: Tool message
type: object
ChatCompletionRequestToolMessageContentPart:
oneOf: *165
x-oaiExpandable: true
ChatCompletionRequestUserMessage:
description: |
Messages sent by an end user, containing prompts or additional context
information.
properties: *157
required: *163
title: User message
type: object
ChatCompletionRequestUserMessageContentPart:
oneOf: *158
x-oaiExpandable: true
ChatCompletionResponseMessage:
description: A chat completion message generated by the model.
properties: &167
audio:
description: |
If the audio output modality is requested, this object contains data
about the audio response from the model. [Learn more](/docs/guides/audio).
nullable: true
properties:
data:
description: |
Base64 encoded audio bytes generated by the model, in the format
specified in the request.
type: string
expires_at:
description: |
The Unix timestamp (in seconds) for when this audio response will
no longer be accessible on the server for use in multi-turn
conversations.
type: integer
id:
description: Unique identifier for this audio response.
type: string
transcript:
description: Transcript of the audio generated by the model.
type: string
required:
- id
- expires_at
- data
- transcript
type: object
x-oaiExpandable: true
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
x-stainless-const: true
tool_calls:
description: The tool calls generated by the model, such as function calls.
items: *138
type: array
required: &168
- role
- content
- refusal
type: object
ChatCompletionRole:
description: The role of the author of a message
enum:
- developer
- 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: &169
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: &170
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:
- developer
- system
- user
- assistant
- tool
type: string
tool_calls:
items:
properties: *136
required: *137
type: object
type: array
type: object
ChatCompletionTokenLogprob:
properties: &171
bytes: &172
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: &173
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: &174
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: *172
logprob: *173
token: *174
required:
- token
- logprob
- bytes
type: object
type: array
required: &175
- token
- logprob
- bytes
- top_logprobs
type: object
ChatCompletionTool:
properties: &176
function:
properties: *21
required: *22
type: object
type:
description: The type of the tool. Currently, only `function` is supported.
enum:
- function
type: string
x-stainless-const: true
required: &177
- 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: &178
- 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: *140
required: *141
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: &179
- additionalProperties: false
description: The default strategy. This strategy currently uses a `max_chunk_size_tokens`
of `800` and `chunk_overlap_tokens` of `400`.
properties: *126
required: *127
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties: &180
static:
additionalProperties: false
properties: &181
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: &182
- max_chunk_size_tokens
- chunk_overlap_tokens
type: object
type:
description: Always `static`.
enum:
- static
type: string
x-stainless-const: true
required: &183
- type
- static
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
CompleteUploadRequest:
additionalProperties: false
properties: &184
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: &185
- part_ids
type: object
CompletionUsage:
description: Usage statistics for the completion request.
properties: &186
completion_tokens:
default: 0
description: Number of tokens in the generated completion.
type: integer
completion_tokens_details:
description: Breakdown of tokens used in a completion.
properties:
accepted_prediction_tokens:
default: 0
description: |
When using Predicted Outputs, the number of tokens in the
prediction that appeared in the completion.
type: integer
audio_tokens:
default: 0
description: Audio input tokens generated by the model.
type: integer
reasoning_tokens:
default: 0
description: Tokens generated by the model for reasoning.
type: integer
rejected_prediction_tokens:
default: 0
description: |
When using Predicted Outputs, the number of tokens in the
prediction that did not appear in the completion. However, like
reasoning tokens, these tokens are still counted in the total
completion tokens for purposes of billing, output, and context window
limits.
type: integer
type: object
prompt_tokens:
default: 0
description: Number of tokens in the prompt.
type: integer
prompt_tokens_details:
description: Breakdown of tokens used in the prompt.
properties:
audio_tokens:
default: 0
description: Audio input tokens present in the prompt.
type: integer
cached_tokens:
default: 0
description: Cached tokens present in the prompt.
type: integer
type: object
total_tokens:
default: 0
description: Total number of tokens used in the request (prompt + completion).
type: integer
required: &187
- prompt_tokens
- completion_tokens
- total_tokens
type: object
CostsResult:
description: The aggregated costs details of the specific time bucket.
properties: &188
amount:
description: The monetary value in its associated currency.
properties:
currency:
description: Lowercase ISO-4217 currency e.g. "usd"
type: string
value:
description: The numeric value of the cost.
type: number
type: object
line_item:
description: When `group_by=line_item`, this field provides the line item
of the grouped costs result.
nullable: true
type: string
object:
enum:
- organization.costs.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped costs result.
nullable: true
type: string
required: &189
- object
type: object
CreateAssistantRequest:
additionalProperties: false
properties: &190
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum: *116
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) 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
reasoning_effort:
default: medium
description: "**o1 and o3-mini models only** \n\nConstrains effort on reasoning
for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently
supported values are `low`, `medium`, and `high`. Reducing\nreasoning
effort can result in faster responses and fewer tokens used\non reasoning
in a response.\n"
enum: &191
- low
- medium
- high
nullable: true
type: string
response_format:
allOf:
- 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: *7
x-oaiExpandable: true
- nullable: 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
x-stainless-const: true
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
x-stainless-const: true
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached
to an object. This can be\nuseful for storing additional
information about the object in a structured\nformat, and
querying for objects via API or the dashboard. \n\nKeys
are strings with a maximum length of 64 characters. Values
are strings\nwith a maximum length of 512 characters.\n"
nullable: true
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: *14
required: *15
title: Code interpreter tool
type: object
- properties: *16
required: *19
title: FileSearch tool
type: object
- properties: *20
required: *23
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: &192
- 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: *167
required: *168
type: object
required:
- finish_reason
- index
- message
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
x-stainless-const: true
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: *186
required: *187
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: &193
audio:
description: |
Parameters for audio output. Required when audio output is requested with
`modalities: ["audio"]`. [Learn more](/docs/guides/audio).
nullable: true
properties:
format:
description: |
Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`,
`opus`, or `pcm16`.
enum:
- wav
- mp3
- flac
- opus
- pcm16
type: string
voice:
description: |
The voice the model uses to respond. Supported voices are `ash`, `ballad`, `coral`, `sage`, and `verse` (also supported but not recommended are `alloy`, `echo`, and `shimmer`; these voices are less expressive).
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
required:
- voice
- format
type: object
x-oaiExpandable: true
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.
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: *130
required: *131
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: *132
required: *133
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. Depending on the
[model](/docs/models) you use, different message types (modalities) are
supported, like [text](/docs/guides/text-generation),
[images](/docs/guides/vision), and [audio](/docs/guides/audio).
items:
oneOf: *153
x-oaiExpandable: true
minItems: 1
type: array
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
modalities:
description: |
Output types that you would like the model to generate for this request.
Most models are capable of generating text, which is the default:
`["text"]`
The `gpt-4o-audio-preview` model can also be used to [generate audio](/docs/guides/audio). To
request that this model generate both text and audio responses, you can
use:
`["text", "audio"]`
items: *139
nullable: true
type: array
model:
anyOf:
- type: string
- enum:
- o3-mini
- o3-mini-2025-01-31
- o1
- o1-2024-12-17
- o1-preview
- o1-preview-2024-09-12
- o1-mini
- o1-mini-2024-09-12
- gpt-4o
- gpt-4o-2024-11-20
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- gpt-4o-audio-preview
- gpt-4o-audio-preview-2024-10-01
- gpt-4o-audio-preview-2024-12-17
- gpt-4o-mini-audio-preview
- gpt-4o-mini-audio-preview-2024-12-17
- 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#configuring-parallel-function-calling)
during tool use.
type: boolean
prediction:
description: |
Configuration for a [Predicted Output](/docs/guides/predicted-outputs),
which can greatly improve response times when large parts of the model
response are known ahead of time. This is most common when you are
regenerating a file with only minor changes to most of the content.
nullable: true
oneOf:
- description: |
Static predicted output content, such as the content of a text file that is
being regenerated.
properties: &194
content:
description: |
The content that should be matched when generating a model response.
If generated tokens would match this content, the entire model response
can be returned much more quickly.
oneOf:
- description: |
The content used for a Predicted Output. This is often the
text of a file you are regenerating with minor changes.
title: Text content
type: string
- description: An array of content parts with a defined type. Supported
options differ based on the [model](/docs/models) being used to
generate the response. Can contain text inputs.
items:
description: |
Learn about [text inputs](/docs/guides/text-generation).
properties: *144
required: *145
title: Text content part
type: object
minItems: 1
title: Array of content parts
type: array
x-oaiExpandable: true
type:
description: |
The type of the predicted content you want to provide. This type is
currently always `content`.
enum:
- content
type: string
x-stainless-const: true
required: &195
- type
- content
title: Static Content
type: object
x-oaiExpandable: true
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.
maximum: 2
minimum: -2
nullable: true
type: number
reasoning_effort:
default: medium
description: "**o1 and o3-mini models only** \n\nConstrains effort on reasoning
for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently
supported values are `low`, `medium`, and `high`. Reducing\nreasoning
effort can result in faster responses and fewer tokens used\non reasoning
in a response.\n"
enum: *191
nullable: true
type: string
response_format:
description: |
An object specifying the format that the model must output.
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: *8
required: *9
type: object
- properties: *10
required: *11
type: object
- properties: *12
required: *13
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.
format: int64
nullable: true
type: integer
service_tier:
default: auto
description: |
Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:
- If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted.
- 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 guarantee.
- If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarantee.
- When not set, the default behavior is 'auto'.
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
store:
default: false
description: "Whether or not to store the output of this chat completion
request for \nuse in our [model distillation](/docs/guides/distillation)
or\n[evals](/docs/guides/evals) products.\n"
nullable: true
type: boolean
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: *169
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: *178
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: *176
required: *177
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:
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: &196
- model
- messages
type: object
CreateChatCompletionResponse:
description: Represents a chat completion response returned by model, based
on the provided input.
properties: &197
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:
description: Log probability information for the choice.
nullable: true
properties:
content:
description: A list of message content tokens with log probability
information.
items:
properties: *171
required: *175
type: object
nullable: true
type: array
refusal:
description: A list of message refusal tokens with log probability
information.
items:
properties: *171
required: *175
type: object
nullable: true
type: array
required:
- content
- refusal
type: object
message:
description: A chat completion message generated by the model.
properties: *167
required: *168
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
x-stainless-const: true
service_tier:
description: The service tier used for processing 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: *186
required: *187
type: object
required: &198
- 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: &199
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: *170
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:
description: Log probability information for the choice.
nullable: true
properties:
content:
description: A list of message content tokens with log probability
information.
items:
properties: *171
required: *175
type: object
nullable: true
type: array
refusal:
description: A list of message refusal tokens with log probability
information.
items:
properties: *171
required: *175
type: object
nullable: true
type: array
required:
- content
- refusal
type: object
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
x-stainless-const: true
service_tier:
description: The service tier used for processing 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.
nullable: true
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: &200
- choices
- created
- id
- model
- object
type: object
CreateCompletionRequest:
properties: &201
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)
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) 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)
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.
format: int64
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: *169
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:
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: &202
- 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: &203
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
x-stainless-const: true
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: *186
required: *187
type: object
required: &204
- id
- object
- created
- model
- choices
type: object
CreateEmbeddingRequest:
additionalProperties: false
properties: &205
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. Some models may also impose a limit on total number of tokens summed across inputs.
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) for descriptions of them.
example: text-embedding-3-small
x-oaiTypeLabel: string
user:
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: &206
- model
- input
type: object
CreateEmbeddingResponse:
properties: &207
data:
description: The list of embeddings generated by the model.
items:
description: |
Represents an embedding vector returned by embedding endpoint.
properties: &208
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
x-stainless-const: true
required: &209
- 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
x-stainless-const: true
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: &210
- object
- model
- data
- usage
type: object
CreateFileRequest:
additionalProperties: false
properties: &211
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: &212
- file
- purpose
type: object
CreateFineTuningJobRequest:
properties: &213
hyperparameters:
deprecated: true
description: |
The hyperparameters used for the fine-tuning job.
This value is now deprecated in favor of `method`, and should be passed in under the `method` parameter.
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
x-stainless-const: true
- 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
x-stainless-const: true
- 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
x-stainless-const: true
- 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
x-stainless-const: true
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
method:
description: The method used for fine-tuning.
properties: &214
dpo:
description: Configuration for the DPO fine-tuning method.
properties: &215
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
x-stainless-const: true
- maximum: 256
minimum: 1
type: integer
beta:
default: auto
description: |
The beta value for the DPO method. A higher beta value will increase the weight of the penalty between the policy and reference model.
oneOf:
- enum:
- auto
type: string
x-stainless-const: true
- exclusiveMinimum: true
maximum: 2
minimum: 0
type: number
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
x-stainless-const: true
- 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
x-stainless-const: true
- maximum: 50
minimum: 1
type: integer
type: object
type: object
supervised:
description: Configuration for the supervised fine-tuning method.
properties: &216
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
x-stainless-const: true
- 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
x-stainless-const: true
- 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
x-stainless-const: true
- maximum: 50
minimum: 1
type: integer
type: object
type: object
type:
description: The type of method. Is either `supervised` or `dpo`.
enum:
- supervised
- dpo
type: string
type: object
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), [completions](/docs/api-reference/fine-tuning/completions-input) format, or if the fine-tuning method uses the [preference](/docs/api-reference/fine-tuning/preference-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: &217
- model
- training_file
type: object
CreateImageEditRequest:
properties: &218
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
x-stainless-const: true
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:
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:
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:
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: &219
- prompt
- image
type: object
CreateImageRequest:
properties: &220
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:
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:
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:
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:
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: &221
- prompt
type: object
CreateImageVariationRequest:
properties: &222
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
x-stainless-const: true
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.
For `dall-e-3`, only `n=1` is supported.
example: 1
maximum: 10
minimum: 1
nullable: true
type: integer
response_format:
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:
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:
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: &223
- image
type: object
CreateMessageRequest:
additionalProperties: false
properties: &224
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: *14
required: *15
title: Code interpreter tool
type: object
- properties: *81
required: *82
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).
items:
oneOf:
- description: References an image [File](/docs/api-reference/files)
in the content of a message.
properties: *83
required: *84
title: Image file
type: object
- description: References an image URL in the content of a message.
properties: *85
required: *86
title: Image URL
type: object
- description: The text content that is part of a message.
properties: &225
text:
description: Text content to be sent to the model
type: string
type:
description: Always `text`.
enum:
- text
type: string
x-stainless-const: true
required: &226
- type
- text
title: Text
type: object
x-oaiExpandable: true
minItems: 1
title: Array of content parts
type: array
x-oaiExpandable: true
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
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: &227
- role
- content
type: object
CreateModerationRequest:
properties: &228
input:
description: |
Input (or inputs) to classify. Can be a single string, an array of strings, or
an array of multi-modal input objects similar to other models.
oneOf:
- default: ''
description: A string of text to classify for moderation.
example: I want to kill them.
type: string
- description: An array of strings to classify for moderation.
items:
default: ''
example: I want to kill them.
type: string
type: array
- description: An array of multi-modal inputs to the moderation model.
items:
oneOf:
- description: An object describing an image to classify.
properties:
image_url:
description: Contains either an image URL or a data URL for a
base64 encoded image.
properties:
url:
description: Either a URL of the image or the base64 encoded
image data.
example: https://example.com/image.jpg
format: uri
type: string
required:
- url
type: object
type:
description: Always `image_url`.
enum:
- image_url
type: string
x-stainless-const: true
required:
- type
- image_url
type: object
- description: An object describing text to classify.
properties:
text:
description: A string of text to classify.
example: I want to kill them
type: string
type:
description: Always `text`.
enum:
- text
type: string
x-stainless-const: true
required:
- type
- text
type: object
x-oaiExpandable: true
type: array
x-oaiExpandable: true
model:
anyOf:
- type: string
- enum:
- omni-moderation-latest
- omni-moderation-2024-09-26
- text-moderation-latest
- text-moderation-stable
type: string
default: omni-moderation-latest
description: |
The content moderation model you would like to use. Learn more in
[the moderation guide](/docs/guides/moderation), and learn about
available models [here](/docs/models#moderation).
example: omni-moderation-2024-09-26
nullable: false
x-oaiTypeLabel: string
required: &229
- input
type: object
CreateModerationResponse:
description: Represents if a given text input is potentially harmful.
properties: &230
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
illicit:
description: Content that includes instructions or advice that
facilitate the planning or execution of wrongdoing, or that
gives advice or instruction on how to commit illicit acts. For
example, "how to shoplift" would fit this category.
nullable: true
type: boolean
illicit/violent:
description: Content that includes instructions or advice that
facilitate the planning or execution of wrongdoing that also
includes violence, or that gives advice or instruction on the
procurement of any weapon.
nullable: true
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
- illicit
- illicit/violent
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
type: object
category_applied_input_types:
description: A list of the categories along with the input type(s)
that the score applies to.
properties:
harassment:
description: The applied input type(s) for the category 'harassment'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
harassment/threatening:
description: The applied input type(s) for the category 'harassment/threatening'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
hate:
description: The applied input type(s) for the category 'hate'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
hate/threatening:
description: The applied input type(s) for the category 'hate/threatening'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
illicit:
description: The applied input type(s) for the category 'illicit'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
illicit/violent:
description: The applied input type(s) for the category 'illicit/violent'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
self-harm:
description: The applied input type(s) for the category 'self-harm'.
items:
enum:
- text
- image
type: string
type: array
self-harm/instructions:
description: The applied input type(s) for the category 'self-harm/instructions'.
items:
enum:
- text
- image
type: string
type: array
self-harm/intent:
description: The applied input type(s) for the category 'self-harm/intent'.
items:
enum:
- text
- image
type: string
type: array
sexual:
description: The applied input type(s) for the category 'sexual'.
items:
enum:
- text
- image
type: string
type: array
sexual/minors:
description: The applied input type(s) for the category 'sexual/minors'.
items:
enum:
- text
type: string
x-stainless-const: true
type: array
violence:
description: The applied input type(s) for the category 'violence'.
items:
enum:
- text
- image
type: string
type: array
violence/graphic:
description: The applied input type(s) for the category 'violence/graphic'.
items:
enum:
- text
- image
type: string
type: array
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- illicit
- illicit/violent
- 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
illicit:
description: The score for the category 'illicit'.
type: number
illicit/violent:
description: The score for the category 'illicit/violent'.
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
- illicit
- illicit/violent
- 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
- category_applied_input_types
type: object
type: array
required: &231
- id
- model
- results
type: object
CreateRunRequest:
additionalProperties: false
properties: &232
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: *224
required: *227
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum: *116
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#configuring-parallel-function-calling)
during tool use.
type: boolean
reasoning_effort:
default: medium
description: "**o1 and o3-mini models only** \n\nConstrains effort on reasoning
for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently
supported values are `low`, `medium`, and `high`. Reducing\nreasoning
effort can result in faster responses and fewer tokens used\non reasoning
in a response.\n"
enum: *191
nullable: true
type: string
response_format:
allOf:
- 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: *7
x-oaiExpandable: true
- nullable: 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:
allOf:
- 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: *32
x-oaiExpandable: true
- nullable: 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: *14
required: *15
title: Code interpreter tool
type: object
- properties: *16
required: *19
title: FileSearch tool
type: object
- properties: *20
required: *23
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:
allOf:
- 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: *35
required: *36
title: Thread Truncation Controls
type: object
- nullable: true
required: &233
- assistant_id
type: object
CreateSpeechRequest:
additionalProperties: false
properties: &234
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
description: The speed of the generated audio. Select a value from `0.25`
to `4.0`. `1.0` is the default.
maximum: 4
minimum: 0.25
type: number
voice:
description: The voice to use when generating the audio. Supported voices
are `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage` and
`shimmer`. Previews of the voices are available in the [Text to speech
guide](/docs/guides/text-to-speech#voice-options).
enum:
- alloy
- ash
- coral
- echo
- fable
- onyx
- nova
- sage
- shimmer
type: string
required: &235
- model
- input
- voice
type: object
CreateThreadAndRunRequest:
additionalProperties: false
properties: &236
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum:
- gpt-4o
- gpt-4o-2024-11-20
- gpt-4o-2024-08-06
- gpt-4o-2024-05-13
- 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#configuring-parallel-function-calling)
during tool use.
type: boolean
response_format:
allOf:
- 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: *7
x-oaiExpandable: true
- nullable: 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: "Options to create a new thread. If no thread is provided when
running a \nrequest, an empty thread will be created.\n"
properties: &237
messages:
description: A list of [messages](/docs/api-reference/messages) to start
the thread with.
items:
additionalProperties: false
properties: *224
required: *227
type: object
type: array
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values
are strings\nwith a maximum length of 512 characters.\n"
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
x-stainless-const: true
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
x-stainless-const: true
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached
to an object. This can be\nuseful for storing additional
information about the object in a structured\nformat,
and querying for objects via API or the dashboard. \n\nKeys
are strings with a maximum length of 64 characters.
Values are strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
type: object
x-oaiExpandable: true
maxItems: 1
type: array
type: object
type: object
type: object
tool_choice:
allOf:
- 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: *32
x-oaiExpandable: true
- nullable: 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: *14
required: *15
title: Code interpreter tool
type: object
- properties: *16
required: *19
title: FileSearch tool
type: object
- properties: *20
required: *23
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:
allOf:
- 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: *35
required: *36
title: Thread Truncation Controls
type: object
- nullable: true
required: &238
- assistant_id
type: object
CreateThreadRequest:
additionalProperties: false
description: "Options to create a new thread. If no thread is provided when
running a \nrequest, an empty thread will be created.\n"
properties: *237
type: object
CreateTranscriptionRequest:
additionalProperties: false
properties: &239
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) (e.g. `en`) format will improve accuracy and latency.
type: string
model:
anyOf:
- type: string
- enum:
- whisper-1
type: string
x-stainless-const: true
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 output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.
enum: *117
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: &240
- file
- model
type: object
CreateTranscriptionResponseJson:
description: Represents a transcription response returned by model, based on
the provided input.
properties: &241
text:
description: The transcribed text.
type: string
required: &242
- text
type: object
CreateTranscriptionResponseVerboseJson:
description: Represents a verbose json transcription response returned by model,
based on the provided input.
properties: &243
duration:
description: The duration of the input audio.
type: number
language:
description: The language of the input audio.
type: string
segments:
description: Segments of the transcribed text and their corresponding details.
items:
properties: &244
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: &245
- 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: &246
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: &247
- word
- start
- end
type: object
type: array
required: &248
- language
- duration
- text
type: object
CreateTranslationRequest:
additionalProperties: false
properties: &249
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
x-stainless-const: true
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 output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.
enum: *117
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: &250
- file
- model
type: object
CreateTranslationResponseJson:
properties: &251
text:
type: string
required: &252
- text
type: object
CreateTranslationResponseVerboseJson:
properties: &253
duration:
description: The duration of the input audio.
type: number
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: *244
required: *245
type: object
type: array
text:
description: The translated text.
type: string
required: &254
- language
- duration
- text
type: object
CreateUploadRequest:
additionalProperties: false
properties: &255
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: &256
- filename
- purpose
- bytes
- mime_type
type: object
CreateVectorStoreFileBatchRequest:
additionalProperties: false
properties: &257
chunking_strategy:
description: The chunking strategy used to chunk the file(s). If not set,
will use the `auto` strategy.
oneOf: *179
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: &258
- file_ids
type: object
CreateVectorStoreFileRequest:
additionalProperties: false
properties: &259
chunking_strategy:
description: The chunking strategy used to chunk the file(s). If not set,
will use the `auto` strategy.
oneOf: *179
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: &260
- file_id
type: object
CreateVectorStoreRequest:
additionalProperties: false
properties: &261
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: *126
required: *127
title: Auto Chunking Strategy
type: object
- additionalProperties: false
properties: *180
required: *183
title: Static Chunking Strategy
type: object
type: object
x-oaiExpandable: true
expires_after:
description: The expiration policy for a vector store.
properties: &262
anchor:
description: 'Anchor timestamp after which the expiration policy applies.
Supported anchors: `last_active_at`.'
enum:
- last_active_at
type: string
x-stainless-const: true
days:
description: The number of days after the anchor time that the vector
store will expire.
maximum: 365
minimum: 1
type: integer
required: &263
- 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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
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: &264
deleted:
type: boolean
id:
type: string
object:
enum:
- assistant.deleted
type: string
x-stainless-const: true
required: &265
- id
- object
- deleted
type: object
DeleteFileResponse:
properties: &266
deleted:
type: boolean
id:
type: string
object:
enum:
- file
type: string
x-stainless-const: true
required: &267
- id
- object
- deleted
type: object
DeleteMessageResponse:
properties: &268
deleted:
type: boolean
id:
type: string
object:
enum:
- thread.message.deleted
type: string
x-stainless-const: true
required: &269
- id
- object
- deleted
type: object
DeleteModelResponse:
properties: &270
deleted:
type: boolean
id:
type: string
object:
type: string
required: &271
- id
- object
- deleted
type: object
DeleteThreadResponse:
properties: &272
deleted:
type: boolean
id:
type: string
object:
enum:
- thread.deleted
type: string
x-stainless-const: true
required: &273
- id
- object
- deleted
type: object
DeleteVectorStoreFileResponse:
properties: &274
deleted:
type: boolean
id:
type: string
object:
enum:
- vector_store.file.deleted
type: string
x-stainless-const: true
required: &275
- id
- object
- deleted
type: object
DeleteVectorStoreResponse:
properties: &276
deleted:
type: boolean
id:
type: string
object:
enum:
- vector_store.deleted
type: string
x-stainless-const: true
required: &277
- id
- object
- deleted
type: object
DoneEvent:
description: Occurs when a stream ends.
properties: *114
required: *115
type: object
Embedding:
description: |
Represents an embedding vector returned by embedding endpoint.
properties: *208
required: *209
type: object
Error:
properties: *111
required: *112
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: *110
required: *113
type: object
ErrorResponse:
properties: &278
error:
properties: *111
required: *112
type: object
required: &279
- 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: *17
required: *18
title: File search tool call ranking options
type: object
FineTuneChatCompletionRequestAssistantMessage:
allOf: &280
- 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
- description: |
Messages sent by the model in response to user messages.
properties: *142
required: *148
title: Assistant message
type: object
required: &281
- role
FineTuneChatRequestInput:
description: The per-line training example of a fine-tuning input file for chat
models using the supervised method.
properties:
functions:
deprecated: true
description: A list of functions the model may generate JSON inputs for.
items:
deprecated: true
properties: *132
required: *133
type: object
maxItems: 128
minItems: 1
type: array
messages:
items:
oneOf:
- description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
properties: *154
required: *156
title: System message
type: object
- description: |
Messages sent by an end user, containing prompts or additional context
information.
properties: *157
required: *163
title: User message
type: object
- allOf: *280
required: *281
- properties: *164
required: *166
title: Tool message
type: object
- deprecated: true
properties: *151
required: *152
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#configuring-parallel-function-calling)
during tool use.
type: boolean
tools:
description: A list of tools the model may generate JSON inputs for.
items:
properties: *176
required: *177
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
FineTuneDPOMethod:
description: Configuration for the DPO fine-tuning method.
properties: *215
type: object
FineTuneMethod:
description: The method used for fine-tuning.
properties: *214
type: object
FineTunePreferenceRequestInput:
description: The per-line training example of a fine-tuning input file for chat
models using the dpo method.
properties:
input:
properties:
messages:
items:
oneOf:
- description: |
Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
properties: *154
required: *156
title: System message
type: object
- description: |
Messages sent by an end user, containing prompts or additional context
information.
properties: *157
required: *163
title: User message
type: object
- allOf: *280
required: *281
- properties: *164
required: *166
title: Tool message
type: object
- deprecated: true
properties: *151
required: *152
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#configuring-parallel-function-calling)
during tool use.
type: boolean
tools:
description: A list of tools the model may generate JSON inputs for.
items:
properties: *176
required: *177
type: object
type: array
type: object
non_preferred_completion:
description: The non-preferred completion message for the output.
items:
oneOf:
- description: |
Messages sent by the model in response to user messages.
properties: *142
required: *148
title: Assistant message
type: object
x-oaiExpandable: true
maxItems: 1
type: array
preferred_completion:
description: The preferred completion message for the output.
items:
oneOf:
- description: |
Messages sent by the model in response to user messages.
properties: *142
required: *148
title: Assistant message
type: object
x-oaiExpandable: true
maxItems: 1
type: array
type: object
FineTuneSupervisedMethod:
description: Configuration for the supervised fine-tuning method.
properties: *216
type: object
FineTuningIntegration:
properties: &282
type:
description: The type of the integration being enabled for the fine-tuning
job
enum:
- wandb
type: string
x-stainless-const: true
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: &283
- 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: &284
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. This value
will only be returned when running `supervised` jobs.
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
x-stainless-const: true
- 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
x-stainless-const: true
- 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
x-stainless-const: true
- maximum: 50
minimum: 1
type: integer
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: *282
required: *283
title: Fine-Tuning Job Integration
type: object
x-oaiExpandable: true
maxItems: 5
nullable: true
type: array
method:
description: The method used for fine-tuning.
properties: *214
type: object
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
x-stainless-const: true
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: &285
- 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: &286
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
x-stainless-const: true
step_number:
description: The step number that the checkpoint was created at.
type: integer
required: &287
- 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: &288
created_at:
description: The Unix timestamp (in seconds) for when the fine-tuning job
was created.
type: integer
data:
description: The data associated with the event.
type: object
id:
description: The object identifier.
type: string
level:
description: The log level of the event.
enum:
- info
- warn
- error
type: string
message:
description: The message of the event.
type: string
object:
description: The object type, which is always "fine_tuning.job.event".
enum:
- fine_tuning.job.event
type: string
x-stainless-const: true
type:
description: The type of event.
enum:
- message
- metrics
type: string
required: &289
- id
- object
- created_at
- level
- message
type: object
FunctionObject:
properties: *21
required: *22
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: &290
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: &291
created:
type: integer
data:
items:
description: Represents the url or the content of an image generated by
the OpenAI API.
properties: *290
type: object
type: array
required: &292
- created
- data
Invite:
description: Represents an individual `invite` to the organization.
properties: &293
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
x-stainless-const: true
projects:
description: The projects that were granted membership upon acceptance of
the invite.
items:
properties:
id:
description: Project's public ID
type: string
role:
description: Project membership role
enum:
- member
- owner
type: string
type: object
type: array
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
status:
description: '`accepted`,`expired`, or `pending`'
enum:
- accepted
- expired
- pending
type: string
required: &294
- object
- id
- email
- role
- status
- invited_at
- expires_at
type: object
InviteDeleteResponse:
properties: &295
deleted:
type: boolean
id:
type: string
object:
description: The object type, which is always `organization.invite.deleted`
enum:
- organization.invite.deleted
type: string
x-stainless-const: true
required: &296
- object
- id
- deleted
type: object
InviteListResponse:
properties: &297
data:
items:
description: Represents an individual `invite` to the organization.
properties: *293
required: *294
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
x-stainless-const: true
required: &298
- object
- data
type: object
InviteRequest:
properties: &299
email:
description: Send an email to this address
type: string
projects:
description: An array of projects to which membership is granted at the
same time the org invite is accepted. If omitted, the user will be invited
to the default project for compatibility with legacy behavior.
items:
properties:
id:
description: Project's public ID
type: string
role:
description: Project membership role
enum:
- member
- owner
type: string
required:
- id
- role
type: object
type: array
role:
description: '`owner` or `reader`'
enum:
- reader
- owner
type: string
required: &300
- email
- role
type: object
ListAssistantsResponse:
properties: &301
data:
items:
description: Represents an `assistant` that can call the model and use
tools.
properties: *5
required: *24
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: &302
- object
- data
- first_id
- last_id
- has_more
type: object
ListAuditLogsResponse:
properties: &303
data:
items:
description: A log of a user action or configuration change within this
organization.
properties: *118
required: *125
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
x-stainless-const: true
required: &304
- object
- data
- first_id
- last_id
- has_more
type: object
ListBatchesResponse:
properties: &305
data:
items:
properties: *128
required: *129
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
x-stainless-const: true
required: &306
- object
- data
- has_more
type: object
ListFilesResponse:
properties: &307
data:
items:
description: The `File` object represents a document that has been uploaded
to OpenAI.
properties: &308
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
x-stainless-const: true
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: &309
- id
- object
- bytes
- created_at
- filename
- purpose
- status
title: OpenAIFile
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: &310
- object
- data
- first_id
- last_id
- has_more
type: object
ListFineTuningJobCheckpointsResponse:
properties: &311
data:
items:
description: |
The `fine_tuning.job.checkpoint` object represents a model checkpoint for a fine-tuning job that is ready to use.
properties: *286
required: *287
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
x-stainless-const: true
required: &312
- object
- data
- has_more
type: object
ListFineTuningJobEventsResponse:
properties: &313
data:
items:
description: Fine-tuning job event object
properties: *288
required: *289
type: object
type: array
has_more:
type: boolean
object:
enum:
- list
type: string
x-stainless-const: true
required: &314
- object
- data
- has_more
type: object
ListMessagesResponse:
properties: &315
data:
items:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *80
required: *95
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: &316
- object
- data
- first_id
- last_id
- has_more
ListModelsResponse:
properties: &317
data:
items:
description: Describes an OpenAI model offering that can be used with
the API.
properties: &318
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
x-stainless-const: true
owned_by:
description: The organization that owns the model.
type: string
required: &319
- id
- object
- created
- owned_by
title: Model
type: array
object:
enum:
- list
type: string
x-stainless-const: true
required: &320
- object
- data
type: object
ListPaginatedFineTuningJobsResponse:
properties: &321
data:
items:
description: |
The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
properties: *284
required: *285
title: FineTuningJob
type: object
type: array
has_more:
type: boolean
object:
enum:
- list
type: string
x-stainless-const: true
required: &322
- object
- data
- has_more
type: object
ListRunStepsResponse:
properties: &323
data:
items:
description: |
Represents a step in execution of a run.
properties: *41
required: *62
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: &324
- object
- data
- first_id
- last_id
- has_more
ListRunsResponse:
properties: &325
data:
items:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: &326
- 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: *26
required: *27
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: &327
data:
items:
description: A list of files attached to a vector store.
properties: &328
chunking_strategy:
description: The strategy used to chunk the file.
oneOf:
- additionalProperties: false
properties: &329
static:
additionalProperties: false
properties: *181
required: *182
type: object
type:
description: Always `static`.
enum:
- static
type: string
x-stainless-const: true
required: &330
- 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: &331
type:
description: Always `other`.
enum:
- other
type: string
x-stainless-const: true
required: &332
- 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
x-stainless-const: true
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: &333
- 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: &334
- object
- data
- first_id
- last_id
- has_more
ListVectorStoresResponse:
properties: &335
data:
items:
description: A vector store is a collection of processed files can be
used by the `file_search` tool.
properties: &336
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: *262
required: *263
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an
object. This can be\nuseful for storing additional information about
the object in a structured\nformat, and querying for objects via
API or the dashboard. \n\nKeys are strings with a maximum length
of 64 characters. Values are strings\nwith a maximum length of 512
characters.\n"
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
x-stainless-const: true
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: &337
- 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: &338
- 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: *83
required: *84
title: Image file
type: object
MessageContentImageUrlObject:
description: References an image URL in the content of a message.
properties: *85
required: *86
title: Image URL
type: object
MessageContentRefusalObject:
description: The refusal content generated by the assistant.
properties: *93
required: *94
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: *88
required: *89
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: *90
required: *91
title: File path
type: object
MessageContentTextObject:
description: The text content that is part of a message.
properties: *87
required: *92
title: Text
type: object
MessageDeltaContentImageFileObject:
description: References an image [File](/docs/api-reference/files) in the content
of a message.
properties: *97
required: *98
title: Image file
type: object
MessageDeltaContentImageUrlObject:
description: References an image URL in the content of a message.
properties: *107
required: *108
title: Image URL
type: object
MessageDeltaContentRefusalObject:
description: The refusal content that is part of a message.
properties: *105
required: *106
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: *100
required: *101
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: *102
required: *103
title: File path
type: object
MessageDeltaContentTextObject:
description: The text content that is part of a message.
properties: *99
required: *104
title: Text
type: object
MessageDeltaObject:
description: |
Represents a message delta i.e. any changed fields on a message during streaming.
properties: *96
required: *109
title: Message delta object
type: object
MessageObject:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *80
required: *95
title: The message object
type: object
MessageRequestContentTextObject:
description: The text content that is part of a message.
properties: *225
required: *226
title: Text
type: object
MessageStreamEvent:
oneOf: *79
Metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object. This
can be\nuseful for storing additional information about the object in a structured\nformat,
and querying for objects via API or the dashboard. \n\nKeys are strings with
a maximum length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
Model:
description: Describes an OpenAI model offering that can be used with the API.
properties: *318
required: *319
title: Model
ModifyAssistantRequest:
additionalProperties: false
properties: &339
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:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
model:
anyOf:
- type: string
- enum: *116
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) for descriptions of them.
name:
description: |
The name of the assistant. The maximum length is 256 characters.
maxLength: 256
nullable: true
type: string
reasoning_effort:
default: medium
description: "**o1 and o3-mini models only** \n\nConstrains effort on reasoning
for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently
supported values are `low`, `medium`, and `high`. Reducing\nreasoning
effort can result in faster responses and fewer tokens used\non reasoning
in a response.\n"
enum: *191
nullable: true
type: string
response_format:
allOf:
- 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: *7
x-oaiExpandable: true
- nullable: 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: *14
required: *15
title: Code interpreter tool
type: object
- properties: *16
required: *19
title: FileSearch tool
type: object
- properties: *20
required: *23
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: &340
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
type: object
ModifyRunRequest:
additionalProperties: false
properties: &341
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
type: object
ModifyThreadRequest:
additionalProperties: false
properties: &342
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
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: *308
required: *309
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: *331
required: *332
title: Other Chunking Strategy
type: object
ParallelToolCalls:
default: true
description: Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling)
during tool use.
type: boolean
PredictionContent:
description: |
Static predicted output content, such as the content of a text file that is
being regenerated.
properties: *194
required: *195
title: Static Content
type: object
Project:
description: Represents an individual project.
properties: &343
archived_at:
description: The Unix timestamp (in seconds) of when the project was archived
or `null`.
nullable: true
type: integer
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
x-stainless-const: true
status:
description: '`active` or `archived`'
enum:
- active
- archived
type: string
required: &344
- id
- object
- name
- created_at
- status
type: object
ProjectApiKey:
description: Represents an individual API key in a project.
properties: &345
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
x-stainless-const: true
owner:
properties:
service_account:
description: Represents an individual service account in a project.
properties: &346
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
x-stainless-const: true
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &347
- 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: &348
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
x-stainless-const: true
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &349
- object
- id
- name
- email
- role
- added_at
type: object
type: object
redacted_value:
description: The redacted value of the API key
type: string
required: &350
- object
- redacted_value
- name
- created_at
- id
- owner
type: object
ProjectApiKeyDeleteResponse:
properties: &351
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.api_key.deleted
type: string
x-stainless-const: true
required: &352
- object
- id
- deleted
type: object
ProjectApiKeyListResponse:
properties: &353
data:
items:
description: Represents an individual API key in a project.
properties: *345
required: *350
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
x-stainless-const: true
required: &354
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectCreateRequest:
properties: &355
name:
description: The friendly name of the project, this name appears in reports.
type: string
required: &356
- name
type: object
ProjectListResponse:
properties: &357
data:
items:
description: Represents an individual project.
properties: *343
required: *344
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
x-stainless-const: true
required: &358
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectRateLimit:
description: Represents a project rate limit config.
properties: &359
batch_1_day_max_input_tokens:
description: The maximum batch input tokens per day. Only present for relevant
models.
type: integer
id:
description: The identifier, which can be referenced in API endpoints.
type: string
max_audio_megabytes_per_1_minute:
description: The maximum audio megabytes per minute. Only present for relevant
models.
type: integer
max_images_per_1_minute:
description: The maximum images per minute. Only present for relevant models.
type: integer
max_requests_per_1_day:
description: The maximum requests per day. Only present for relevant models.
type: integer
max_requests_per_1_minute:
description: The maximum requests per minute.
type: integer
max_tokens_per_1_minute:
description: The maximum tokens per minute.
type: integer
model:
description: The model this rate limit applies to.
type: string
object:
description: The object type, which is always `project.rate_limit`
enum:
- project.rate_limit
type: string
x-stainless-const: true
required: &360
- object
- id
- model
- max_requests_per_1_minute
- max_tokens_per_1_minute
type: object
ProjectRateLimitListResponse:
properties: &361
data:
items:
description: Represents a project rate limit config.
properties: *359
required: *360
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
x-stainless-const: true
required: &362
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectRateLimitUpdateRequest:
properties: &363
batch_1_day_max_input_tokens:
description: The maximum batch input tokens per day. Only relevant for certain
models.
type: integer
max_audio_megabytes_per_1_minute:
description: The maximum audio megabytes per minute. Only relevant for certain
models.
type: integer
max_images_per_1_minute:
description: The maximum images per minute. Only relevant for certain models.
type: integer
max_requests_per_1_day:
description: The maximum requests per day. Only relevant for certain models.
type: integer
max_requests_per_1_minute:
description: The maximum requests per minute.
type: integer
max_tokens_per_1_minute:
description: The maximum tokens per minute.
type: integer
type: object
ProjectServiceAccount:
description: Represents an individual service account in a project.
properties: *346
required: *347
type: object
ProjectServiceAccountApiKey:
properties: &364
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
x-stainless-const: true
value:
type: string
required: &365
- object
- value
- name
- created_at
- id
type: object
ProjectServiceAccountCreateRequest:
properties: &366
name:
description: The name of the service account being created.
type: string
required: &367
- name
type: object
ProjectServiceAccountCreateResponse:
properties: &368
api_key:
properties: *364
required: *365
type: object
created_at:
type: integer
id:
type: string
name:
type: string
object:
enum:
- organization.project.service_account
type: string
x-stainless-const: true
role:
description: Service accounts can only have one role of type `member`
enum:
- member
type: string
x-stainless-const: true
required: &369
- object
- id
- name
- role
- created_at
- api_key
type: object
ProjectServiceAccountDeleteResponse:
properties: &370
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.service_account.deleted
type: string
x-stainless-const: true
required: &371
- object
- id
- deleted
type: object
ProjectServiceAccountListResponse:
properties: &372
data:
items:
description: Represents an individual service account in a project.
properties: *346
required: *347
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
x-stainless-const: true
required: &373
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectUpdateRequest:
properties: &374
name:
description: The updated name of the project, this name appears in reports.
type: string
required: &375
- name
type: object
ProjectUser:
description: Represents an individual user in a project.
properties: *348
required: *349
type: object
ProjectUserCreateRequest:
properties: &376
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
user_id:
description: The ID of the user.
type: string
required: &377
- user_id
- role
type: object
ProjectUserDeleteResponse:
properties: &378
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.project.user.deleted
type: string
x-stainless-const: true
required: &379
- object
- id
- deleted
type: object
ProjectUserListResponse:
properties: &380
data:
items:
description: Represents an individual user in a project.
properties: *348
required: *349
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
type: string
required: &381
- object
- data
- first_id
- last_id
- has_more
type: object
ProjectUserUpdateRequest:
properties: &382
role:
description: '`owner` or `member`'
enum:
- owner
- member
type: string
required: &383
- role
type: object
RealtimeClientEventConversationItemCreate:
description: "Add a new Item to the Conversation's context, including messages,
function \ncalls, and function call responses. This event can be used both
to populate a \n\"history\" of the conversation and to add new items mid-stream,
but has the \ncurrent limitation that it cannot populate assistant audio messages.\n\nIf
successful, the server will respond with a `conversation.item.created` \nevent,
otherwise an `error` event will be sent.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
item:
description: The item to add to the conversation.
properties: &384
arguments:
description: |
The arguments of the function call (for `function_call` items).
type: string
call_id:
description: "The ID of the function call (for `function_call` and \n`function_call_output`
items). If passed on a `function_call_output` \nitem, the server will
check that a `function_call` item with the same \nID exists in the
conversation history.\n"
type: string
content:
description: "The content of the message, applicable for `message` items.
\n- Message items of role `system` support only `input_text` content\n-
Message items of role `user` support `input_text` and `input_audio`
\n content\n- Message items of role `assistant` support `text` content.\n"
items:
properties:
audio:
description: |
Base64-encoded audio bytes, used for `input_audio` content type.
type: string
id:
description: |
ID of a previous conversation item to reference (for `item_reference`
content types in `response.create` events). These can reference both
client and server created items.
type: string
text:
description: |
The text content, used for `input_text` and `text` content types.
type: string
transcript:
description: |
The transcript of the audio, used for `input_audio` content type.
type: string
type:
description: |
The content type (`input_text`, `input_audio`, `item_reference`, `text`).
enum:
- input_audio
- input_text
- item_reference
- text
type: string
type: object
x-oaiExpandable: true
type: array
x-oaiExpandable: true
id:
description: "The unique ID of the item, this can be generated by the
client to help \nmanage server-side context, but is not required because
the server will \ngenerate one if not provided.\n"
type: string
name:
description: |
The name of the function being called (for `function_call` items).
type: string
object:
description: |
Identifier for the API object being returned - always `realtime.item`.
enum:
- realtime.item
type: string
x-stainless-const: true
output:
description: |
The output of the function call (for `function_call_output` items).
type: string
role:
description: "The role of the message sender (`user`, `assistant`, `system`),
only \napplicable for `message` items.\n"
enum:
- user
- assistant
- system
type: string
status:
description: "The status of the item (`completed`, `incomplete`). These
have no effect \non the conversation, but are accepted for consistency
with the \n`conversation.item.created` event.\n"
enum:
- completed
- incomplete
type: string
type:
description: |
The type of the item (`message`, `function_call`, `function_call_output`).
enum:
- message
- function_call
- function_call_output
type: string
type: object
x-oaiExpandable: true
previous_item_id:
description: "The ID of the preceding item after which the new item will
be inserted. \nIf not set, the new item will be appended to the end of
the conversation.\nIf set to `root`, the new item will be added to the
beginning of the conversation.\nIf set to an existing ID, it allows an
item to be inserted mid-conversation. If the\nID cannot be found, an error
will be returned and the item will not be added.\n"
type: string
type:
description: The event type, must be `conversation.item.create`.
enum:
- conversation.item.create
type: string
x-stainless-const: true
required:
- type
- item
type: object
RealtimeClientEventConversationItemDelete:
description: "Send this event when you want to remove any item from the conversation
\nhistory. The server will respond with a `conversation.item.deleted` event,
\nunless the item does not exist in the conversation history, in which case
the \nserver will respond with an error.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
item_id:
description: The ID of the item to delete.
type: string
type:
description: The event type, must be `conversation.item.delete`.
enum:
- conversation.item.delete
type: string
x-stainless-const: true
required:
- type
- item_id
type: object
RealtimeClientEventConversationItemTruncate:
description: "Send this event to truncate a previous assistant message’s audio.
The server \nwill produce audio faster than realtime, so this event is useful
when the user \ninterrupts to truncate audio that has already been sent to
the client but not \nyet played. This will synchronize the server's understanding
of the audio with \nthe client's playback.\n\nTruncating audio will delete
the server-side text transcript to ensure there \nis not text in the context
that hasn't been heard by the user.\n\nIf successful, the server will respond
with a `conversation.item.truncated` \nevent. \n"
properties:
audio_end_ms:
description: "Inclusive duration up to which audio is truncated, in milliseconds.
If \nthe audio_end_ms is greater than the actual audio duration, the server
\nwill respond with an error.\n"
type: integer
content_index:
description: The index of the content part to truncate. Set this to 0.
type: integer
event_id:
description: Optional client-generated ID used to identify this event.
type: string
item_id:
description: "The ID of the assistant message item to truncate. Only assistant
message \nitems can be truncated.\n"
type: string
type:
description: The event type, must be `conversation.item.truncate`.
enum:
- conversation.item.truncate
type: string
x-stainless-const: true
required:
- type
- item_id
- content_index
- audio_end_ms
type: object
RealtimeClientEventInputAudioBufferAppend:
description: "Send this event to append audio bytes to the input audio buffer.
The audio \nbuffer is temporary storage you can write to and later commit.
In Server VAD \nmode, the audio buffer is used to detect speech and the server
will decide \nwhen to commit. When Server VAD is disabled, you must commit
the audio buffer\nmanually.\n\nThe client may choose how much audio to place
in each event up to a maximum \nof 15 MiB, for example streaming smaller chunks
from the client may allow the \nVAD to be more responsive. Unlike made other
client events, the server will \nnot send a confirmation response to this
event.\n"
properties:
audio:
description: "Base64-encoded audio bytes. This must be in the format specified
by the \n`input_audio_format` field in the session configuration.\n"
type: string
event_id:
description: Optional client-generated ID used to identify this event.
type: string
type:
description: The event type, must be `input_audio_buffer.append`.
enum:
- input_audio_buffer.append
type: string
x-stainless-const: true
required:
- type
- audio
type: object
RealtimeClientEventInputAudioBufferClear:
description: "Send this event to clear the audio bytes in the buffer. The server
will \nrespond with an `input_audio_buffer.cleared` event.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
type:
description: The event type, must be `input_audio_buffer.clear`.
enum:
- input_audio_buffer.clear
type: string
x-stainless-const: true
required:
- type
type: object
RealtimeClientEventInputAudioBufferCommit:
description: "Send this event to commit the user input audio buffer, which will
create a \nnew user message item in the conversation. This event will produce
an error \nif the input audio buffer is empty. When in Server VAD mode, the
client does \nnot need to send this event, the server will commit the audio
buffer \nautomatically.\n\nCommitting the input audio buffer will trigger
input audio transcription \n(if enabled in session configuration), but it
will not create a response \nfrom the model. The server will respond with
an `input_audio_buffer.committed` \nevent.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
type:
description: The event type, must be `input_audio_buffer.commit`.
enum:
- input_audio_buffer.commit
type: string
x-stainless-const: true
required:
- type
type: object
RealtimeClientEventResponseCancel:
description: "Send this event to cancel an in-progress response. The server
will respond \nwith a `response.cancelled` event or an error if there is no
response to \ncancel.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
response_id:
description: "A specific response ID to cancel - if not provided, will cancel
an \nin-progress response in the default conversation.\n"
type: string
type:
description: The event type, must be `response.cancel`.
enum:
- response.cancel
type: string
x-stainless-const: true
required:
- type
type: object
RealtimeClientEventResponseCreate:
description: "This event instructs the server to create a Response, which means
triggering \nmodel inference. When in Server VAD mode, the server will create
Responses \nautomatically.\n\nA Response will include at least one Item, and
may have two, in which case \nthe second will be a function call. These Items
will be appended to the \nconversation history.\n\nThe server will respond
with a `response.created` event, events for Items \nand content created, and
finally a `response.done` event to indicate the \nResponse is complete.\n\nThe
`response.create` event includes inference configuration like \n`instructions`,
and `temperature`. These fields will override the Session's \nconfiguration
for this Response only.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
response:
description: Create a new Realtime response with these parameters
properties: &385
conversation:
description: "Controls which conversation the response is added to.
Currently supports\n`auto` and `none`, with `auto` as the default
value. The `auto` value\nmeans that the contents of the response will
be added to the default\nconversation. Set this to `none` to create
an out-of-band response which \nwill not add items to default conversation.\n"
oneOf:
- type: string
- default: auto
enum:
- auto
- none
type: string
input:
description: |
Input items to include in the prompt for the model. Using this field
creates a new context for this Response instead of using the default
conversation. An empty array `[]` will clear the context for this Response.
Note that this can include references to items from the default conversation.
items:
description: The item to add to the conversation.
properties: &386
arguments:
description: |
The arguments of the function call (for `function_call` items).
type: string
call_id:
description: "The ID of the function call (for `function_call`
and \n`function_call_output` items). If passed on a `function_call_output`
\nitem, the server will check that a `function_call` item with
the same \nID exists in the conversation history.\n"
type: string
content:
description: "The content of the message, applicable for `message`
items. \n- Message items of role `system` support only `input_text`
content\n- Message items of role `user` support `input_text`
and `input_audio` \n content\n- Message items of role `assistant`
support `text` content.\n"
items:
properties:
audio:
description: |
Base64-encoded audio bytes, used for `input_audio` content type.
type: string
id:
description: |
ID of a previous conversation item to reference (for `item_reference`
content types in `response.create` events). These can reference both
client and server created items.
type: string
text:
description: |
The text content, used for `input_text` and `text` content types.
type: string
transcript:
description: |
The transcript of the audio, used for `input_audio` content type.
type: string
type:
description: |
The content type (`input_text`, `input_audio`, `item_reference`, `text`).
enum:
- input_audio
- input_text
- item_reference
- text
type: string
type: object
x-oaiExpandable: true
type: array
x-oaiExpandable: true
id:
description: |
For an item of type (`message` | `function_call` | `function_call_output`)
this field allows the client to assign the unique ID of the item. It is
not required because the server will generate one if not provided.
For an item of type `item_reference`, this field is required and is a
reference to any item that has previously existed in the conversation.
type: string
name:
description: |
The name of the function being called (for `function_call` items).
type: string
object:
description: |
Identifier for the API object being returned - always `realtime.item`.
enum:
- realtime.item
type: string
x-stainless-const: true
output:
description: |
The output of the function call (for `function_call_output` items).
type: string
role:
description: "The role of the message sender (`user`, `assistant`,
`system`), only \napplicable for `message` items.\n"
enum:
- user
- assistant
- system
type: string
status:
description: "The status of the item (`completed`, `incomplete`).
These have no effect \non the conversation, but are accepted
for consistency with the \n`conversation.item.created` event.\n"
enum:
- completed
- incomplete
type: string
type:
description: |
The type of the item (`message`, `function_call`, `function_call_output`, `item_reference`).
enum:
- message
- function_call
- function_call_output
type: string
type: object
x-oaiExpandable: true
type: array
instructions:
description: "The default system instructions (i.e. system message)
prepended to model \ncalls. This field allows the client to guide
the model on desired \nresponses. The model can be instructed on response
content and format, \n(e.g. \"be extremely succinct\", \"act friendly\",
\"here are examples of good \nresponses\") and on audio behavior (e.g.
\"talk quickly\", \"inject emotion \ninto your voice\", \"laugh frequently\").
The instructions are not guaranteed \nto be followed by the model,
but they provide guidance to the model on the \ndesired behavior.\n\nNote
that the server sets default instructions which will be used if this
\nfield is not set and are visible in the `session.created` event
at the \nstart of the session.\n"
type: string
max_response_output_tokens:
description: |
Maximum number of output tokens for a single assistant response,
inclusive of tool calls. Provide an integer between 1 and 4096 to
limit output tokens, or `inf` for the maximum available tokens for a
given model. Defaults to `inf`.
oneOf:
- type: integer
- enum:
- inf
type: string
x-stainless-const: true
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values
are strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
modalities:
description: |
The set of modalities the model can respond with. To disable audio,
set this to ["text"].
items:
enum:
- text
- audio
type: string
type: array
output_audio_format:
description: |
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
temperature:
description: |
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
type: number
tool_choice:
description: "How the model chooses tools. Options are `auto`, `none`,
`required`, or \nspecify a function, like `{\"type\": \"function\",
\"function\": {\"name\": \"my_function\"}}`.\n"
type: string
tools:
description: Tools (functions) available to the model.
items:
properties:
description:
description: "The description of the function, including guidance
on when and how \nto call it, and guidance about what to tell
the user when calling \n(if anything).\n"
type: string
name:
description: The name of the function.
type: string
parameters:
description: Parameters of the function in JSON Schema.
type: object
type:
description: The type of the tool, i.e. `function`.
enum:
- function
type: string
x-stainless-const: true
type: object
type: array
voice:
description: "The voice the model uses to respond. Voice cannot be changed
during the \nsession once the model has responded with audio at least
once. Current \nvoice options are `alloy`, `ash`, `ballad`, `coral`,
`echo` `sage`, \n`shimmer` and `verse`.\n"
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
type: object
type:
description: The event type, must be `response.create`.
enum:
- response.create
type: string
x-stainless-const: true
required:
- type
type: object
RealtimeClientEventSessionUpdate:
description: "Send this event to update the session’s default configuration.
The client may \nsend this event at any time to update the session configuration,
and any \nfield may be updated at any time, except for \"voice\". The server
will respond \nwith a `session.updated` event that shows the full effective
configuration. \nOnly fields that are present are updated, thus the correct
way to clear a \nfield like \"instructions\" is to pass an empty string.\n"
properties:
event_id:
description: Optional client-generated ID used to identify this event.
type: string
session:
description: Realtime session object configuration.
properties: &387
input_audio_format:
description: "The format of input audio. Options are `pcm16`, `g711_ulaw`,
or `g711_alaw`.\nFor `pcm16`, input audio must be 16-bit PCM at a
24kHz sample rate, \nsingle channel (mono), and little-endian byte
order.\n"
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
input_audio_transcription:
description: |
Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously through [OpenAI Whisper transcription](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as rough guidance rather than the representation understood by the model. The client can optionally set the language and prompt for transcription, these fields will be passed to the Whisper API.
properties:
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) (e.g. `en`) format
will improve accuracy and latency.
type: string
model:
description: "The model to use for transcription, `whisper-1` is
the only currently \nsupported model.\n"
type: 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
type: object
instructions:
description: "The default system instructions (i.e. system message)
prepended to model \ncalls. This field allows the client to guide
the model on desired \nresponses. The model can be instructed on response
content and format, \n(e.g. \"be extremely succinct\", \"act friendly\",
\"here are examples of good \nresponses\") and on audio behavior (e.g.
\"talk quickly\", \"inject emotion \ninto your voice\", \"laugh frequently\").
The instructions are not guaranteed \nto be followed by the model,
but they provide guidance to the model on the \ndesired behavior.\n\nNote
that the server sets default instructions which will be used if this
\nfield is not set and are visible in the `session.created` event
at the \nstart of the session.\n"
type: string
max_response_output_tokens:
description: |
Maximum number of output tokens for a single assistant response,
inclusive of tool calls. Provide an integer between 1 and 4096 to
limit output tokens, or `inf` for the maximum available tokens for a
given model. Defaults to `inf`.
oneOf:
- type: integer
- enum:
- inf
type: string
x-stainless-const: true
modalities:
description: |
The set of modalities the model can respond with. To disable audio,
set this to ["text"].
items:
enum:
- text
- audio
type: string
model:
description: |
The Realtime model used for this session.
enum:
- gpt-4o-realtime-preview
- gpt-4o-realtime-preview-2024-10-01
- gpt-4o-realtime-preview-2024-12-17
- gpt-4o-mini-realtime-preview
- gpt-4o-mini-realtime-preview-2024-12-17
type: string
output_audio_format:
description: |
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
For `pcm16`, output audio is sampled at a rate of 24kHz.
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
temperature:
description: |
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
type: number
tool_choice:
description: "How the model chooses tools. Options are `auto`, `none`,
`required`, or \nspecify a function.\n"
type: string
tools:
description: Tools (functions) available to the model.
items:
properties:
description:
description: "The description of the function, including guidance
on when and how \nto call it, and guidance about what to tell
the user when calling \n(if anything).\n"
type: string
name:
description: The name of the function.
type: string
parameters:
description: Parameters of the function in JSON Schema.
type: object
type:
description: The type of the tool, i.e. `function`.
enum:
- function
type: string
x-stainless-const: true
type: object
type: array
turn_detection:
description: "Configuration for turn detection. Can be set to `null`
to turn off. Server \nVAD means that the model will detect the start
and end of speech based on \naudio volume and respond at the end of
user speech.\n"
properties:
create_response:
default: true
description: |
Whether or not to automatically generate a response when VAD is
enabled. `true` by default.
type: boolean
prefix_padding_ms:
description: "Amount of audio to include before the VAD detected
speech (in \nmilliseconds). Defaults to 300ms.\n"
type: integer
silence_duration_ms:
description: "Duration of silence to detect speech stop (in milliseconds).
Defaults \nto 500ms. With shorter values the model will respond
more quickly, \nbut may jump in on short pauses from the user.\n"
type: integer
threshold:
description: "Activation threshold for VAD (0.0 to 1.0), this defaults
to 0.5. A \nhigher threshold will require louder audio to activate
the model, and \nthus might perform better in noisy environments.\n"
type: number
type:
description: |
Type of turn detection, only `server_vad` is currently supported.
type: string
type: object
voice:
description: "The voice the model uses to respond. Voice cannot be changed
during the \nsession once the model has responded with audio at least
once. Current \nvoice options are `alloy`, `ash`, `ballad`, `coral`,
`echo` `sage`, \n`shimmer` and `verse`.\n"
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
type: object
type:
description: The event type, must be `session.update`.
enum:
- session.update
type: string
x-stainless-const: true
required:
- type
- session
type: object
RealtimeConversationItem:
description: The item to add to the conversation.
properties: *384
type: object
x-oaiExpandable: true
RealtimeConversationItemWithReference:
description: The item to add to the conversation.
properties: *386
type: object
x-oaiExpandable: true
RealtimeResponse:
description: The response resource.
properties: &388
conversation_id:
description: |
Which conversation the response is added to, determined by the `conversation`
field in the `response.create` event. If `auto`, the response will be added to
the default conversation and the value of `conversation_id` will be an id like
`conv_1234`. If `none`, the response will not be added to any conversation and
the value of `conversation_id` will be `null`. If responses are being triggered
by server VAD, the response will be added to the default conversation, thus
the `conversation_id` will be an id like `conv_1234`.
type: string
id:
description: The unique ID of the response.
type: string
max_output_tokens:
description: |
Maximum number of output tokens for a single assistant response,
inclusive of tool calls, that was used in this response.
oneOf:
- type: integer
- enum:
- inf
type: string
x-stainless-const: true
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
modalities:
description: |
The set of modalities the model used to respond. If there are multiple modalities,
the model will pick one, for example if `modalities` is `["text", "audio"]`, the model
could be responding in either text or audio.
items:
enum:
- text
- audio
type: string
type: array
object:
description: The object type, must be `realtime.response`.
enum:
- realtime.response
type: string
x-stainless-const: true
output:
description: The list of output items generated by the response.
items:
description: The item to add to the conversation.
properties: *384
type: object
x-oaiExpandable: true
type: array
output_audio_format:
description: |
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
status:
description: "The final status of the response (`completed`, `cancelled`,
`failed`, or \n`incomplete`).\n"
enum:
- completed
- cancelled
- failed
- incomplete
type: string
status_details:
description: Additional details about the status.
properties:
error:
description: "A description of the error that caused the response to
fail, \npopulated when the `status` is `failed`.\n"
properties:
code:
description: Error code, if any.
type: string
type:
description: The type of error.
type: string
type: object
reason:
description: "The reason the Response did not complete. For a `cancelled`
Response, \none of `turn_detected` (the server VAD detected a new
start of speech) \nor `client_cancelled` (the client sent a cancel
event). For an \n`incomplete` Response, one of `max_output_tokens`
or `content_filter` \n(the server-side safety filter activated and
cut off the response).\n"
enum:
- turn_detected
- client_cancelled
- max_output_tokens
- content_filter
type: string
type:
description: "The type of error that caused the response to fail, corresponding
\nwith the `status` field (`completed`, `cancelled`, `incomplete`,
\n`failed`).\n"
enum:
- completed
- cancelled
- failed
- incomplete
type: string
type: object
temperature:
description: |
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
type: number
usage:
description: "Usage statistics for the Response, this will correspond to
billing. A \nRealtime API session will maintain a conversation context
and append new \nItems to the Conversation, thus output from previous
turns (text and \naudio tokens) will become the input for later turns.\n"
properties:
input_token_details:
description: Details about the input tokens used in the Response.
properties:
audio_tokens:
description: The number of audio tokens used in the Response.
type: integer
cached_tokens:
description: The number of cached tokens used in the Response.
type: integer
text_tokens:
description: The number of text tokens used in the Response.
type: integer
type: object
input_tokens:
description: "The number of input tokens used in the Response, including
text and \naudio tokens.\n"
type: integer
output_token_details:
description: Details about the output tokens used in the Response.
properties:
audio_tokens:
description: The number of audio tokens used in the Response.
type: integer
text_tokens:
description: The number of text tokens used in the Response.
type: integer
type: object
output_tokens:
description: "The number of output tokens sent in the Response, including
text and \naudio tokens.\n"
type: integer
total_tokens:
description: "The total number of tokens in the Response including input
and output \ntext and audio tokens.\n"
type: integer
type: object
voice:
description: "The voice the model used to respond.\nCurrent voice options
are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, \n`shimmer` and
`verse`.\n"
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
type: object
RealtimeResponseCreateParams:
description: Create a new Realtime response with these parameters
properties: *385
type: object
RealtimeServerEventConversationCreated:
description: |
Returned when a conversation is created. Emitted right after session creation.
properties:
conversation:
description: The conversation resource.
properties:
id:
description: The unique ID of the conversation.
type: string
object:
description: The object type, must be `realtime.conversation`.
type: string
type: object
event_id:
description: The unique ID of the server event.
type: string
type:
description: The event type, must be `conversation.created`.
enum:
- conversation.created
type: string
x-stainless-const: true
required:
- event_id
- type
- conversation
type: object
RealtimeServerEventConversationItemCreated:
description: "Returned when a conversation item is created. There are several
scenarios that \nproduce this event:\n - The server is generating a Response,
which if successful will produce \n either one or two Items, which will
be of type `message` \n (role `assistant`) or type `function_call`.\n -
The input audio buffer has been committed, either by the client or the \n
\ server (in `server_vad` mode). The server will take the content of the
\n input audio buffer and add it to a new user message Item.\n - The client
has sent a `conversation.item.create` event to add a new Item \n to the
Conversation.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
item:
description: The item to add to the conversation.
properties: *384
type: object
x-oaiExpandable: true
previous_item_id:
description: "The ID of the preceding item in the Conversation context,
allows the \nclient to understand the order of the conversation.\n"
type: string
type:
description: The event type, must be `conversation.item.created`.
enum:
- conversation.item.created
type: string
x-stainless-const: true
required:
- event_id
- type
- previous_item_id
- item
type: object
RealtimeServerEventConversationItemDeleted:
description: "Returned when an item in the conversation is deleted by the client
with a \n`conversation.item.delete` event. This event is used to synchronize
the \nserver's understanding of the conversation history with the client's
view.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item that was deleted.
type: string
type:
description: The event type, must be `conversation.item.deleted`.
enum:
- conversation.item.deleted
type: string
x-stainless-const: true
required:
- event_id
- type
- item_id
type: object
RealtimeServerEventConversationItemInputAudioTranscriptionCompleted:
description: "This event is the output of audio transcription for user audio
written to the \nuser audio buffer. Transcription begins when the input audio
buffer is \ncommitted by the client or server (in `server_vad` mode). Transcription
runs \nasynchronously with Response creation, so this event may come before
or after \nthe Response events.\n\nRealtime API models accept audio natively,
and thus input transcription is a \nseparate process run on a separate ASR
(Automatic Speech Recognition) model, \ncurrently always `whisper-1`. Thus
the transcript may diverge somewhat from \nthe model's interpretation, and
should be treated as a rough guide.\n"
properties:
content_index:
description: The index of the content part containing the audio.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the user message item containing the audio.
type: string
transcript:
description: The transcribed text.
type: string
type:
description: |
The event type, must be
`conversation.item.input_audio_transcription.completed`.
enum:
- conversation.item.input_audio_transcription.completed
type: string
x-stainless-const: true
required:
- event_id
- type
- item_id
- content_index
- transcript
type: object
RealtimeServerEventConversationItemInputAudioTranscriptionFailed:
description: "Returned when input audio transcription is configured, and a transcription
\nrequest for a user message failed. These events are separate from other
\n`error` events so that the client can identify the related Item.\n"
properties:
content_index:
description: The index of the content part containing the audio.
type: integer
error:
description: Details of the transcription error.
properties:
code:
description: Error code, if any.
type: string
message:
description: A human-readable error message.
type: string
param:
description: Parameter related to the error, if any.
type: string
type:
description: The type of error.
type: string
type: object
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the user message item.
type: string
type:
description: |
The event type, must be
`conversation.item.input_audio_transcription.failed`.
enum:
- conversation.item.input_audio_transcription.failed
type: string
x-stainless-const: true
required:
- event_id
- type
- item_id
- content_index
- error
type: object
RealtimeServerEventConversationItemTruncated:
description: "Returned when an earlier assistant audio message item is truncated
by the \nclient with a `conversation.item.truncate` event. This event is used
to \nsynchronize the server's understanding of the audio with the client's
playback.\n\nThis action will truncate the audio and remove the server-side
text transcript \nto ensure there is no text in the context that hasn't been
heard by the user.\n"
properties:
audio_end_ms:
description: |
The duration up to which the audio was truncated, in milliseconds.
type: integer
content_index:
description: The index of the content part that was truncated.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the assistant message item that was truncated.
type: string
type:
description: The event type, must be `conversation.item.truncated`.
enum:
- conversation.item.truncated
type: string
x-stainless-const: true
required:
- event_id
- type
- item_id
- content_index
- audio_end_ms
type: object
RealtimeServerEventError:
description: "Returned when an error occurs, which could be a client problem
or a server \nproblem. Most errors are recoverable and the session will stay
open, we \nrecommend to implementors to monitor and log error messages by
default.\n"
properties:
error:
description: Details of the error.
properties:
code:
description: Error code, if any.
nullable: true
type: string
event_id:
description: |
The event_id of the client event that caused the error, if applicable.
nullable: true
type: string
message:
description: A human-readable error message.
type: string
param:
description: Parameter related to the error, if any.
nullable: true
type: string
type:
description: |
The type of error (e.g., "invalid_request_error", "server_error").
type: string
required:
- type
- message
type: object
event_id:
description: The unique ID of the server event.
type: string
type:
description: The event type, must be `error`.
enum:
- error
type: string
x-stainless-const: true
required:
- event_id
- type
- error
type: object
RealtimeServerEventInputAudioBufferCleared:
description: "Returned when the input audio buffer is cleared by the client
with a \n`input_audio_buffer.clear` event.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
type:
description: The event type, must be `input_audio_buffer.cleared`.
enum:
- input_audio_buffer.cleared
type: string
x-stainless-const: true
required:
- event_id
- type
type: object
RealtimeServerEventInputAudioBufferCommitted:
description: "Returned when an input audio buffer is committed, either by the
client or \nautomatically in server VAD mode. The `item_id` property is the
ID of the user\nmessage item that will be created, thus a `conversation.item.created`
event \nwill also be sent to the client.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the user message item that will be created.
type: string
previous_item_id:
description: |
The ID of the preceding item after which the new item will be inserted.
type: string
type:
description: The event type, must be `input_audio_buffer.committed`.
enum:
- input_audio_buffer.committed
type: string
x-stainless-const: true
required:
- event_id
- type
- previous_item_id
- item_id
type: object
RealtimeServerEventInputAudioBufferSpeechStarted:
description: "Sent by the server when in `server_vad` mode to indicate that
speech has been \ndetected in the audio buffer. This can happen any time audio
is added to the \nbuffer (unless speech is already detected). The client may
want to use this \nevent to interrupt audio playback or provide visual feedback
to the user. \n\nThe client should expect to receive a `input_audio_buffer.speech_stopped`
event \nwhen speech stops. The `item_id` property is the ID of the user message
item \nthat will be created when speech stops and will also be included in
the \n`input_audio_buffer.speech_stopped` event (unless the client manually
commits \nthe audio buffer during VAD activation).\n"
properties:
audio_start_ms:
description: "Milliseconds from the start of all audio written to the buffer
during the \nsession when speech was first detected. This will correspond
to the \nbeginning of audio sent to the model, and thus includes the \n`prefix_padding_ms`
configured in the Session.\n"
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: |
The ID of the user message item that will be created when speech stops.
type: string
type:
description: The event type, must be `input_audio_buffer.speech_started`.
enum:
- input_audio_buffer.speech_started
type: string
x-stainless-const: true
required:
- event_id
- type
- audio_start_ms
- item_id
type: object
RealtimeServerEventInputAudioBufferSpeechStopped:
description: "Returned in `server_vad` mode when the server detects the end
of speech in \nthe audio buffer. The server will also send an `conversation.item.created`
\nevent with the user message item that is created from the audio buffer.\n"
properties:
audio_end_ms:
description: "Milliseconds since the session started when speech stopped.
This will \ncorrespond to the end of audio sent to the model, and thus
includes the \n`min_silence_duration_ms` configured in the Session.\n"
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the user message item that will be created.
type: string
type:
description: The event type, must be `input_audio_buffer.speech_stopped`.
enum:
- input_audio_buffer.speech_stopped
type: string
x-stainless-const: true
required:
- event_id
- type
- audio_end_ms
- item_id
type: object
RealtimeServerEventRateLimitsUpdated:
description: "Emitted at the beginning of a Response to indicate the updated
rate limits. \nWhen a Response is created some tokens will be \"reserved\"
for the output \ntokens, the rate limits shown here reflect that reservation,
which is then \nadjusted accordingly once the Response is completed.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
rate_limits:
description: List of rate limit information.
items:
properties:
limit:
description: The maximum allowed value for the rate limit.
type: integer
name:
description: |
The name of the rate limit (`requests`, `tokens`).
enum:
- requests
- tokens
type: string
remaining:
description: The remaining value before the limit is reached.
type: integer
reset_seconds:
description: Seconds until the rate limit resets.
type: number
type: object
type: array
type:
description: The event type, must be `rate_limits.updated`.
enum:
- rate_limits.updated
type: string
x-stainless-const: true
required:
- event_id
- type
- rate_limits
type: object
RealtimeServerEventResponseAudioDelta:
description: Returned when the model-generated audio is updated.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
delta:
description: Base64-encoded audio data delta.
type: string
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.audio.delta`.
enum:
- response.audio.delta
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- delta
type: object
RealtimeServerEventResponseAudioDone:
description: |
Returned when the model-generated audio is done. Also emitted when a Response
is interrupted, incomplete, or cancelled.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.audio.done`.
enum:
- response.audio.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
type: object
RealtimeServerEventResponseAudioTranscriptDelta:
description: |
Returned when the model-generated transcription of audio output is updated.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
delta:
description: The transcript delta.
type: string
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.audio_transcript.delta`.
enum:
- response.audio_transcript.delta
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- delta
type: object
RealtimeServerEventResponseAudioTranscriptDone:
description: |
Returned when the model-generated transcription of audio output is done
streaming. Also emitted when a Response is interrupted, incomplete, or
cancelled.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
transcript:
description: The final transcript of the audio.
type: string
type:
description: The event type, must be `response.audio_transcript.done`.
enum:
- response.audio_transcript.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- transcript
type: object
RealtimeServerEventResponseContentPartAdded:
description: |
Returned when a new content part is added to an assistant message item during
response generation.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item to which the content part was added.
type: string
output_index:
description: The index of the output item in the response.
type: integer
part:
description: The content part that was added.
properties:
audio:
description: Base64-encoded audio data (if type is "audio").
type: string
text:
description: The text content (if type is "text").
type: string
transcript:
description: The transcript of the audio (if type is "audio").
type: string
type:
description: The content type ("text", "audio").
enum:
- audio
- text
type: string
type: object
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.content_part.added`.
enum:
- response.content_part.added
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- part
type: object
RealtimeServerEventResponseContentPartDone:
description: |
Returned when a content part is done streaming in an assistant message item.
Also emitted when a Response is interrupted, incomplete, or cancelled.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
part:
description: The content part that is done.
properties:
audio:
description: Base64-encoded audio data (if type is "audio").
type: string
text:
description: The text content (if type is "text").
type: string
transcript:
description: The transcript of the audio (if type is "audio").
type: string
type:
description: The content type ("text", "audio").
enum:
- audio
- text
type: string
type: object
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.content_part.done`.
enum:
- response.content_part.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- part
type: object
RealtimeServerEventResponseCreated:
description: |
Returned when a new Response is created. The first event of response creation,
where the response is in an initial state of `in_progress`.
properties:
event_id:
description: The unique ID of the server event.
type: string
response:
description: The response resource.
properties: *388
type: object
type:
description: The event type, must be `response.created`.
enum:
- response.created
type: string
x-stainless-const: true
required:
- event_id
- type
- response
type: object
RealtimeServerEventResponseDone:
description: "Returned when a Response is done streaming. Always emitted, no
matter the \nfinal state. The Response object included in the `response.done`
event will \ninclude all output Items in the Response but will omit the raw
audio data.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
response:
description: The response resource.
properties: *388
type: object
type:
description: The event type, must be `response.done`.
enum:
- response.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response
type: object
RealtimeServerEventResponseFunctionCallArgumentsDelta:
description: |
Returned when the model-generated function call arguments are updated.
properties:
call_id:
description: The ID of the function call.
type: string
delta:
description: The arguments delta as a JSON string.
type: string
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the function call item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: |
The event type, must be `response.function_call_arguments.delta`.
enum:
- response.function_call_arguments.delta
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- call_id
- delta
type: object
RealtimeServerEventResponseFunctionCallArgumentsDone:
description: |
Returned when the model-generated function call arguments are done streaming.
Also emitted when a Response is interrupted, incomplete, or cancelled.
properties:
arguments:
description: The final arguments as a JSON string.
type: string
call_id:
description: The ID of the function call.
type: string
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the function call item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: |
The event type, must be `response.function_call_arguments.done`.
enum:
- response.function_call_arguments.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- call_id
- arguments
type: object
RealtimeServerEventResponseOutputItemAdded:
description: Returned when a new Item is created during Response generation.
properties:
event_id:
description: The unique ID of the server event.
type: string
item:
description: The item to add to the conversation.
properties: *384
type: object
x-oaiExpandable: true
output_index:
description: The index of the output item in the Response.
type: integer
response_id:
description: The ID of the Response to which the item belongs.
type: string
type:
description: The event type, must be `response.output_item.added`.
enum:
- response.output_item.added
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- output_index
- item
type: object
RealtimeServerEventResponseOutputItemDone:
description: "Returned when an Item is done streaming. Also emitted when a Response
is \ninterrupted, incomplete, or cancelled.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
item:
description: The item to add to the conversation.
properties: *384
type: object
x-oaiExpandable: true
output_index:
description: The index of the output item in the Response.
type: integer
response_id:
description: The ID of the Response to which the item belongs.
type: string
type:
description: The event type, must be `response.output_item.done`.
enum:
- response.output_item.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- output_index
- item
type: object
RealtimeServerEventResponseTextDelta:
description: Returned when the text value of a "text" content part is updated.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
delta:
description: The text delta.
type: string
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
type:
description: The event type, must be `response.text.delta`.
enum:
- response.text.delta
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- delta
type: object
RealtimeServerEventResponseTextDone:
description: |
Returned when the text value of a "text" content part is done streaming. Also
emitted when a Response is interrupted, incomplete, or cancelled.
properties:
content_index:
description: The index of the content part in the item's content array.
type: integer
event_id:
description: The unique ID of the server event.
type: string
item_id:
description: The ID of the item.
type: string
output_index:
description: The index of the output item in the response.
type: integer
response_id:
description: The ID of the response.
type: string
text:
description: The final text content.
type: string
type:
description: The event type, must be `response.text.done`.
enum:
- response.text.done
type: string
x-stainless-const: true
required:
- event_id
- type
- response_id
- item_id
- output_index
- content_index
- text
type: object
RealtimeServerEventSessionCreated:
description: "Returned when a Session is created. Emitted automatically when
a new \nconnection is established as the first server event. This event will
contain \nthe default Session configuration.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
session:
description: Realtime session object configuration.
properties: &389
id:
description: |
Unique identifier for the session object.
type: string
input_audio_format:
description: "The format of input audio. Options are `pcm16`, `g711_ulaw`,
or `g711_alaw`.\nFor `pcm16`, input audio must be 16-bit PCM at a
24kHz sample rate, \nsingle channel (mono), and little-endian byte
order.\n"
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
input_audio_transcription:
description: "Configuration for input audio transcription, defaults
to off and can be \nset to `null` to turn off once on. Input audio
transcription is not native \nto the model, since the model consumes
audio directly. Transcription runs \nasynchronously through Whisper
and should be treated as rough guidance \nrather than the representation
understood by the model.\n"
properties:
model:
description: "The model to use for transcription, `whisper-1` is
the only currently \nsupported model.\n"
type: string
type: object
instructions:
description: "The default system instructions (i.e. system message)
prepended to model \ncalls. This field allows the client to guide
the model on desired \nresponses. The model can be instructed on response
content and format, \n(e.g. \"be extremely succinct\", \"act friendly\",
\"here are examples of good \nresponses\") and on audio behavior (e.g.
\"talk quickly\", \"inject emotion \ninto your voice\", \"laugh frequently\").
The instructions are not guaranteed \nto be followed by the model,
but they provide guidance to the model on the \ndesired behavior.\n\nNote
that the server sets default instructions which will be used if this
\nfield is not set and are visible in the `session.created` event
at the \nstart of the session.\n"
type: string
max_response_output_tokens:
description: |
Maximum number of output tokens for a single assistant response,
inclusive of tool calls. Provide an integer between 1 and 4096 to
limit output tokens, or `inf` for the maximum available tokens for a
given model. Defaults to `inf`.
oneOf:
- type: integer
- enum:
- inf
type: string
x-stainless-const: true
modalities:
description: |
The set of modalities the model can respond with. To disable audio,
set this to ["text"].
items:
enum:
- text
- audio
type: string
model:
anyOf:
- type: string
- enum:
- gpt-4o-realtime-preview
- gpt-4o-realtime-preview-2024-10-01
- gpt-4o-realtime-preview-2024-12-17
- gpt-4o-mini-realtime-preview
- gpt-4o-mini-realtime-preview-2024-12-17
type: string
description: |
The Realtime model used for this session.
output_audio_format:
description: |
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
For `pcm16`, output audio is sampled at a rate of 24kHz.
enum:
- pcm16
- g711_ulaw
- g711_alaw
type: string
temperature:
description: |
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
type: number
tool_choice:
description: "How the model chooses tools. Options are `auto`, `none`,
`required`, or \nspecify a function.\n"
type: string
tools:
description: Tools (functions) available to the model.
items:
properties:
description:
description: "The description of the function, including guidance
on when and how \nto call it, and guidance about what to tell
the user when calling \n(if anything).\n"
type: string
name:
description: The name of the function.
type: string
parameters:
description: Parameters of the function in JSON Schema.
type: object
type:
description: The type of the tool, i.e. `function`.
enum:
- function
type: string
x-stainless-const: true
type: object
type: array
turn_detection:
description: "Configuration for turn detection. Can be set to `null`
to turn off. Server \nVAD means that the model will detect the start
and end of speech based on \naudio volume and respond at the end of
user speech.\n"
nullable: true
properties:
prefix_padding_ms:
description: "Amount of audio to include before the VAD detected
speech (in \nmilliseconds). Defaults to 300ms.\n"
type: integer
silence_duration_ms:
description: "Duration of silence to detect speech stop (in milliseconds).
Defaults \nto 500ms. With shorter values the model will respond
more quickly, \nbut may jump in on short pauses from the user.\n"
type: integer
threshold:
description: "Activation threshold for VAD (0.0 to 1.0), this defaults
to 0.5. A \nhigher threshold will require louder audio to activate
the model, and \nthus might perform better in noisy environments.\n"
type: number
type:
description: |
Type of turn detection, only `server_vad` is currently supported.
enum:
- server_vad
type: string
x-stainless-const: true
type: object
voice:
description: "The voice the model uses to respond. Voice cannot be changed
during the \nsession once the model has responded with audio at least
once. Current \nvoice options are `alloy`, `ash`, `ballad`, `coral`,
`echo` `sage`, \n`shimmer` and `verse`.\n"
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
type: object
type:
description: The event type, must be `session.created`.
enum:
- session.created
type: string
x-stainless-const: true
required:
- event_id
- type
- session
type: object
RealtimeServerEventSessionUpdated:
description: "Returned when a session is updated with a `session.update` event,
unless \nthere is an error.\n"
properties:
event_id:
description: The unique ID of the server event.
type: string
session:
description: Realtime session object configuration.
properties: *389
type: object
type:
description: The event type, must be `session.updated`.
enum:
- session.updated
type: string
x-stainless-const: true
required:
- event_id
- type
- session
type: object
RealtimeSession:
description: Realtime session object configuration.
properties: *389
type: object
RealtimeSessionCreateRequest:
description: Realtime session object configuration.
properties: *387
type: object
RealtimeSessionCreateResponse:
description: |
A new Realtime session configuration, with an ephermeral key. Default TTL
for keys is one minute.
properties: &390
client_secret:
description: Ephemeral key returned by the API.
properties:
expires_at:
description: |
Timestamp for when the token expires. Currently, all tokens expire
after one minute.
type: integer
value:
description: |
Ephemeral key usable in client environments to authenticate connections
to the Realtime API. Use this in client-side environments rather than
a standard API token, which should only be used server-side.
type: string
required:
- value
- expires_at
type: object
input_audio_format:
description: |
The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
type: string
input_audio_transcription:
description: "Configuration for input audio transcription, defaults to off
and can be \nset to `null` to turn off once on. Input audio transcription
is not native \nto the model, since the model consumes audio directly.
Transcription runs \nasynchronously through Whisper and should be treated
as rough guidance \nrather than the representation understood by the model.\n"
properties:
model:
description: "The model to use for transcription, `whisper-1` is the
only currently \nsupported model.\n"
type: string
type: object
instructions:
description: "The default system instructions (i.e. system message) prepended
to model \ncalls. This field allows the client to guide the model on desired
\nresponses. The model can be instructed on response content and format,
\n(e.g. \"be extremely succinct\", \"act friendly\", \"here are examples
of good \nresponses\") and on audio behavior (e.g. \"talk quickly\", \"inject
emotion \ninto your voice\", \"laugh frequently\"). The instructions are
not guaranteed \nto be followed by the model, but they provide guidance
to the model on the \ndesired behavior.\n\nNote that the server sets default
instructions which will be used if this \nfield is not set and are visible
in the `session.created` event at the \nstart of the session.\n"
type: string
max_response_output_tokens:
description: |
Maximum number of output tokens for a single assistant response,
inclusive of tool calls. Provide an integer between 1 and 4096 to
limit output tokens, or `inf` for the maximum available tokens for a
given model. Defaults to `inf`.
oneOf:
- type: integer
- enum:
- inf
type: string
x-stainless-const: true
modalities:
description: |
The set of modalities the model can respond with. To disable audio,
set this to ["text"].
items:
enum:
- text
- audio
type: string
output_audio_format:
description: |
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
type: string
temperature:
description: |
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
type: number
tool_choice:
description: "How the model chooses tools. Options are `auto`, `none`, `required`,
or \nspecify a function.\n"
type: string
tools:
description: Tools (functions) available to the model.
items:
properties:
description:
description: "The description of the function, including guidance
on when and how \nto call it, and guidance about what to tell the
user when calling \n(if anything).\n"
type: string
name:
description: The name of the function.
type: string
parameters:
description: Parameters of the function in JSON Schema.
type: object
type:
description: The type of the tool, i.e. `function`.
enum:
- function
type: string
x-stainless-const: true
type: object
type: array
turn_detection:
description: "Configuration for turn detection. Can be set to `null` to
turn off. Server \nVAD means that the model will detect the start and
end of speech based on \naudio volume and respond at the end of user speech.\n"
properties:
prefix_padding_ms:
description: "Amount of audio to include before the VAD detected speech
(in \nmilliseconds). Defaults to 300ms.\n"
type: integer
silence_duration_ms:
description: "Duration of silence to detect speech stop (in milliseconds).
Defaults \nto 500ms. With shorter values the model will respond more
quickly, \nbut may jump in on short pauses from the user.\n"
type: integer
threshold:
description: "Activation threshold for VAD (0.0 to 1.0), this defaults
to 0.5. A \nhigher threshold will require louder audio to activate
the model, and \nthus might perform better in noisy environments.\n"
type: number
type:
description: |
Type of turn detection, only `server_vad` is currently supported.
type: string
type: object
voice:
description: "The voice the model uses to respond. Voice cannot be changed
during the \nsession once the model has responded with audio at least
once. Current \nvoice options are `alloy`, `ash`, `ballad`, `coral`, `echo`
`sage`, \n`shimmer` and `verse`.\n"
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
type: string
required: &391
- client_secret
type: object
ReasoningEffort:
default: medium
description: "**o1 and o3-mini models only** \n\nConstrains effort on reasoning
for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently
supported values are `low`, `medium`, and `high`. Reducing\nreasoning effort
can result in faster responses and fewer tokens used\non reasoning in a response.\n"
enum: *191
nullable: true
type: string
ResponseFormatJsonObject:
properties: *10
required: *11
type: object
ResponseFormatJsonSchema:
properties: *12
required: *13
type: object
ResponseFormatJsonSchemaSchema:
additionalProperties: true
description: The schema for the response format, described as a JSON Schema
object.
type: object
ResponseFormatText:
properties: *8
required: *9
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: *37
required: *38
type: object
RunObject:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: *60
required: *61
type: object
RunStepDeltaObject:
description: |
Represents a run step delta i.e. any changed fields on a run step during streaming.
properties: *63
required: *78
title: Run step delta object
type: object
RunStepDeltaStepDetailsMessageCreationObject:
description: Details of the message creation by the run step.
properties: *64
required: *65
title: Message creation
type: object
RunStepDeltaStepDetailsToolCallsCodeObject:
description: Details of the Code Interpreter tool call the run step was involved
in.
properties: *67
required: *72
title: Code interpreter tool call
type: object
RunStepDeltaStepDetailsToolCallsCodeOutputImageObject:
properties: *70
required: *71
title: Code interpreter image output
type: object
RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject:
description: Text output from the Code Interpreter tool call as part of a run
step.
properties: *68
required: *69
title: Code interpreter log output
type: object
RunStepDeltaStepDetailsToolCallsFileSearchObject:
properties: *73
required: *74
title: File search tool call
type: object
RunStepDeltaStepDetailsToolCallsFunctionObject:
properties: *75
required: *76
title: Function tool call
type: object
RunStepDeltaStepDetailsToolCallsObject:
description: Details of the tool call.
properties: *66
required: *77
title: Tool calls
type: object
RunStepDetailsMessageCreationObject:
description: Details of the message creation by the run step.
properties: *42
required: *43
title: Message creation
type: object
RunStepDetailsToolCallsCodeObject:
description: Details of the Code Interpreter tool call the run step was involved
in.
properties: *45
required: *50
title: Code Interpreter tool call
type: object
RunStepDetailsToolCallsCodeOutputImageObject:
properties: *48
required: *49
title: Code Interpreter image output
type: object
RunStepDetailsToolCallsCodeOutputLogsObject:
description: Text output from the Code Interpreter tool call as part of a run
step.
properties: *46
required: *47
title: Code Interpreter log output
type: object
RunStepDetailsToolCallsFileSearchObject:
properties: *51
required: *56
title: File search tool call
type: object
RunStepDetailsToolCallsFileSearchRankingOptionsObject:
description: The ranking options for the file search.
properties: *52
required: *53
title: File search tool call ranking options
type: object
RunStepDetailsToolCallsFileSearchResultObject:
description: A result instance of the file search.
properties: *54
required: *55
title: File search tool call result
type: object
x-oaiTypeLabel: map
RunStepDetailsToolCallsFunctionObject:
properties: *57
required: *58
title: Function tool call
type: object
RunStepDetailsToolCallsObject:
description: Details of the tool call.
properties: *44
required: *59
title: Tool calls
type: object
RunStepObject:
description: |
Represents a step in execution of a run.
properties: *41
required: *62
title: Run steps
type: object
RunStepStreamEvent:
oneOf: *40
RunStreamEvent:
oneOf: *28
RunToolCallObject:
description: Tool call objects
properties: *30
required: *31
type: object
StaticChunkingStrategy:
additionalProperties: false
properties: *181
required: *182
type: object
StaticChunkingStrategyRequestParam:
additionalProperties: false
properties: *180
required: *183
title: Static Chunking Strategy
type: object
StaticChunkingStrategyResponseParam:
additionalProperties: false
properties: *329
required: *330
title: Static Chunking Strategy
type: object
SubmitToolOutputsRunRequest:
additionalProperties: false
properties: &392
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: &393
- tool_outputs
type: object
ThreadObject:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *26
required: *27
title: Thread
type: object
ThreadStreamEvent:
oneOf: *25
TranscriptionSegment:
properties: *244
required: *245
type: object
TranscriptionWord:
properties: *246
required: *247
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: *35
required: *36
title: Thread Truncation Controls
type: object
UpdateVectorStoreRequest:
additionalProperties: false
properties: &394
expires_after:
allOf:
- description: The expiration policy for a vector store.
properties: *262
required: *263
title: Vector store expiration policy
type: object
- nullable: true
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to an object.
This can be\nuseful for storing additional information about the object
in a structured\nformat, and querying for objects via API or the dashboard.
\n\nKeys are strings with a maximum length of 64 characters. Values are
strings\nwith a maximum length of 512 characters.\n"
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: &395
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:
allOf:
- description: The `File` object represents a document that has been uploaded
to OpenAI.
properties: *308
required: *309
title: OpenAIFile
- description: The ready File object after the Upload is completed.
nullable: true
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
x-stainless-const: true
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: &396
- bytes
- created_at
- expires_at
- filename
- id
- purpose
- status
title: Upload
type: object
UploadPart:
description: |
The upload Part represents a chunk of bytes we can add to an Upload object.
properties: &397
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
x-stainless-const: true
upload_id:
description: The ID of the Upload object that this Part was added to.
type: string
required: &398
- created_at
- id
- object
- upload_id
title: UploadPart
type: object
UsageAudioSpeechesResult:
description: The aggregated audio speeches usage details of the specific time
bucket.
properties: &399
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
characters:
description: The number of characters processed.
type: integer
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.audio_speeches.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &400
- object
- characters
- num_model_requests
type: object
UsageAudioTranscriptionsResult:
description: The aggregated audio transcriptions usage details of the specific
time bucket.
properties: &401
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.audio_transcriptions.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
seconds:
description: The number of seconds processed.
type: integer
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &402
- object
- seconds
- num_model_requests
type: object
UsageCodeInterpreterSessionsResult:
description: The aggregated code interpreter sessions usage details of the specific
time bucket.
properties: &403
num_sessions:
description: The number of code interpreter sessions.
type: integer
object:
enum:
- organization.usage.code_interpreter_sessions.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
required: &404
- object
- sessions
type: object
UsageCompletionsResult:
description: The aggregated completions usage details of the specific time bucket.
properties: &405
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
batch:
description: When `group_by=batch`, this field tells whether the grouped
usage result is batch or not.
nullable: true
type: boolean
input_audio_tokens:
description: The aggregated number of audio input tokens used, including
cached tokens.
type: integer
input_cached_tokens:
description: The aggregated number of text input tokens that has been cached
from previous requests. For customers subscribe to scale tier, this includes
scale tier tokens.
type: integer
input_tokens:
description: The aggregated number of text input tokens used, including
cached tokens. For customers subscribe to scale tier, this includes scale
tier tokens.
type: integer
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.completions.result
type: string
x-stainless-const: true
output_audio_tokens:
description: The aggregated number of audio output tokens used.
type: integer
output_tokens:
description: The aggregated number of text output tokens used. For customers
subscribe to scale tier, this includes scale tier tokens.
type: integer
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &406
- object
- input_tokens
- output_tokens
- num_model_requests
type: object
UsageEmbeddingsResult:
description: The aggregated embeddings usage details of the specific time bucket.
properties: &407
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
input_tokens:
description: The aggregated number of input tokens used.
type: integer
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.embeddings.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &408
- object
- input_tokens
- num_model_requests
type: object
UsageImagesResult:
description: The aggregated images usage details of the specific time bucket.
properties: &409
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
images:
description: The number of images processed.
type: integer
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.images.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
size:
description: When `group_by=size`, this field provides the image size of
the grouped usage result.
nullable: true
type: string
source:
description: When `group_by=source`, this field provides the source of the
grouped usage result, possible values are `image.generation`, `image.edit`,
`image.variation`.
nullable: true
type: string
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &410
- object
- images
- num_model_requests
type: object
UsageModerationsResult:
description: The aggregated moderations usage details of the specific time bucket.
properties: &411
api_key_id:
description: When `group_by=api_key_id`, this field provides the API key
ID of the grouped usage result.
nullable: true
type: string
input_tokens:
description: The aggregated number of input tokens used.
type: integer
model:
description: When `group_by=model`, this field provides the model name of
the grouped usage result.
nullable: true
type: string
num_model_requests:
description: The count of requests made to the model.
type: integer
object:
enum:
- organization.usage.moderations.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides the project
ID of the grouped usage result.
nullable: true
type: string
user_id:
description: When `group_by=user_id`, this field provides the user ID of
the grouped usage result.
nullable: true
type: string
required: &412
- object
- input_tokens
- num_model_requests
type: object
UsageResponse:
properties: &413
data:
items:
properties: &414
end_time:
type: integer
object:
enum:
- bucket
type: string
x-stainless-const: true
result:
items:
oneOf:
- description: The aggregated completions usage details of the specific
time bucket.
properties: *405
required: *406
type: object
- description: The aggregated embeddings usage details of the specific
time bucket.
properties: *407
required: *408
type: object
- description: The aggregated moderations usage details of the specific
time bucket.
properties: *411
required: *412
type: object
- description: The aggregated images usage details of the specific
time bucket.
properties: *409
required: *410
type: object
- description: The aggregated audio speeches usage details of the
specific time bucket.
properties: *399
required: *400
type: object
- description: The aggregated audio transcriptions usage details
of the specific time bucket.
properties: *401
required: *402
type: object
- description: The aggregated vector stores usage details of the
specific time bucket.
properties: &415
object:
enum:
- organization.usage.vector_stores.result
type: string
x-stainless-const: true
project_id:
description: When `group_by=project_id`, this field provides
the project ID of the grouped usage result.
nullable: true
type: string
usage_bytes:
description: The vector stores usage in bytes.
type: integer
required: &416
- object
- usage_bytes
type: object
- description: The aggregated code interpreter sessions usage details
of the specific time bucket.
properties: *403
required: *404
type: object
- description: The aggregated costs details of the specific time
bucket.
properties: *188
required: *189
type: object
type: array
start_time:
type: integer
required: &417
- object
- start_time
- end_time
- result
type: object
type: array
has_more:
type: boolean
next_page:
type: string
object:
enum:
- page
type: string
x-stainless-const: true
required: &418
- object
- data
- has_more
- next_page
type: object
UsageTimeBucket:
properties: *414
required: *417
type: object
UsageVectorStoresResult:
description: The aggregated vector stores usage details of the specific time
bucket.
properties: *415
required: *416
type: object
User:
description: Represents an individual `user` within an organization.
properties: &419
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
x-stainless-const: true
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
required: &420
- object
- id
- name
- email
- role
- added_at
type: object
UserDeleteResponse:
properties: &421
deleted:
type: boolean
id:
type: string
object:
enum:
- organization.user.deleted
type: string
x-stainless-const: true
required: &422
- object
- id
- deleted
type: object
UserListResponse:
properties: &423
data:
items:
description: Represents an individual `user` within an organization.
properties: *419
required: *420
type: object
type: array
first_id:
type: string
has_more:
type: boolean
last_id:
type: string
object:
enum:
- list
type: string
x-stainless-const: true
required: &424
- object
- data
- first_id
- last_id
- has_more
type: object
UserRoleUpdateRequest:
properties: &425
role:
description: '`owner` or `reader`'
enum:
- owner
- reader
type: string
required: &426
- role
type: object
VectorStoreExpirationAfter:
description: The expiration policy for a vector store.
properties: *262
required: *263
title: Vector store expiration policy
type: object
VectorStoreFileBatchObject:
description: A batch of files attached to a vector store.
properties: &427
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
x-stainless-const: true
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: &428
- 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: *328
required: *333
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: *336
required: *337
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo in order to fetch the previous page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *301
required: *302
type: object
description: OK
summary: Returns a list of assistants.
tags:
- Assistants
post:
operationId: createAssistant
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *190
required: *192
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an `assistant` that can call the model and
use tools.
properties: *5
required: *24
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: *264
required: *265
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: *5
required: *24
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: *339
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an `assistant` that can call the model and
use tools.
properties: *5
required: *24
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: *234
required: *235
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: *239
required: *240
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: *241
required: *242
type: object
- description: Represents a verbose json transcription response returned
by model, based on the provided input.
properties: *243
required: *248
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: *249
required: *250
type: object
required: true
responses:
'200':
content:
application/json:
schema:
oneOf:
- properties: *251
required: *252
type: object
- properties: *253
required: *254
type: object
description: OK
summary: Translates audio into English.
tags:
- Audio
/batches:
get:
operationId: listBatches
parameters:
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *305
required: *306
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 200 MB in size.
type: string
metadata:
additionalProperties: *6
description: "Set of 16 key-value pairs that can be attached to
an object. This can be\nuseful for storing additional information
about the object in a structured\nformat, and querying for objects
via API or the dashboard. \n\nKeys are strings with a maximum
length of 64 characters. Values are strings\nwith a maximum length
of 512 characters.\n"
nullable: true
type: object
x-oaiTypeLabel: map
required:
- input_file_id
- endpoint
- completion_window
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *128
required: *129
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: *128
required: *129
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: *128
required: *129
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: *193
required: *196
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: *197
required: *198
type: object
text/event-stream:
schema:
description: Represents a streamed chunk of a chat completion response
returned by model, based on the provided input.
properties: *199
required: *200
type: object
description: OK
summary: "Creates a model response for the given chat conversation. Learn more
in the\n[text generation](/docs/guides/text-generation), [vision](/docs/guides/vision),\nand
[audio](/docs/guides/audio) guides.\n\nParameter support can differ depending
on the model used to generate the\nresponse, particularly for newer reasoning
models. Parameters that are only\nsupported for reasoning models are noted
below. For the current state of \nunsupported parameters in reasoning models,
\n[refer to the reasoning guide](/docs/guides/reasoning).\n"
tags:
- Chat
/completions:
post:
operationId: createCompletion
requestBody:
content:
application/json:
schema:
properties: *201
required: *202
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: *203
required: *204
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: *205
required: *206
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *207
required: *210
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
- description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 10,000, and the default is 10,000.
in: query
name: limit
required: false
schema:
default: 10000
type: integer
- description: |
Sort order by the C<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo in order to fetch the next page of the list.
in: query
name: after
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *307
required: *310
type: object
description: OK
summary: Returns a list of files.
tags:
- Files
post:
operationId: createFile
requestBody:
content:
multipart/form-data:
schema:
additionalProperties: false
properties: *211
required: *212
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: The `File` object represents a document that has been
uploaded to OpenAI.
properties: *308
required: *309
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 200 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: *266
required: *267
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: *308
required: *309
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: *321
required: *322
type: object
description: OK
summary: |
List your organization's fine-tuning jobs
tags:
- Fine-tuning
post:
operationId: createFineTuningJob
requestBody:
content:
application/json:
schema:
properties: *213
required: *217
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: *284
required: *285
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: *284
required: *285
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: *284
required: *285
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: *311
required: *312
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: *313
required: *314
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: *218
required: *219
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *291
required: *292
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: *220
required: *221
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *291
required: *292
description: OK
summary: Creates an image given a prompt.
tags:
- Images
/images/variations:
post:
operationId: createImageVariation
requestBody:
content:
multipart/form-data:
schema:
properties: *222
required: *223
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *291
required: *292
description: OK
summary: Creates a variation of a given image.
tags:
- Images
/models:
get:
operationId: listModels
responses:
'200':
content:
application/json:
schema:
properties: *317
required: *320
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: *270
required: *271
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: *318
required: *319
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: *228
required: *229
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents if a given text input is potentially harmful.
properties: *230
required: *231
type: object
description: OK
summary: |
Classifies if text and/or image inputs are potentially harmful. Learn
more in the [moderation guide](/docs/guides/moderation).
tags:
- Moderations
/organization/admin_api_keys:
get:
description: Retrieve a paginated list of organization admin API keys.
operationId: admin-api-keys-list
parameters:
- description: ~
in: query
name: after
required: false
schema:
description: Return keys with IDs that come after this ID in the pagination
order.
nullable: true
type: string
- description: ~
in: query
name: order
required: false
schema:
default: asc
description: Order results by creation time, ascending or descending.
enum:
- asc
- desc
type: string
- description: ~
in: query
name: limit
required: false
schema:
default: 20
description: Maximum number of keys to return.
type: integer
responses:
'200':
content:
application/json:
schema:
properties: *4
type: object
description: A list of organization API keys.
summary: List organization API keys
post:
description: Create a new admin-level API key for the organization.
operationId: admin-api-keys-create
requestBody:
content:
application/json:
schema:
properties:
name:
example: New Admin Key
type: string
required:
- name
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties: *3
type: object
description: The newly created admin API key.
summary: Create an organization admin API key
/organization/admin_api_keys/{key_id}:
delete:
description: Delete the specified admin API key.
operationId: admin-api-keys-delete
parameters:
- description: ~
in: path
name: key_id
required: true
schema:
description: The ID of the API key to be deleted.
type: string
responses:
'200':
content:
application/json:
schema:
properties:
deleted:
example: true
type: boolean
id:
example: key_abc
type: string
object:
example: organization.admin_api_key.deleted
type: string
type: object
description: Confirmation that the API key was deleted.
summary: Delete an organization admin API key
get:
description: Get details for a specific organization API key by its ID.
operationId: admin-api-keys-get
parameters:
- description: ~
in: path
name: key_id
required: true
schema:
description: The ID of the API key.
type: string
responses:
'200':
content:
application/json:
schema:
properties: *3
type: object
description: Details of the requested API key.
summary: Retrieve a single organization API key
/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: *124
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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo in order to fetch the previous page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *303
required: *304
type: object
description: Audit logs listed successfully.
summary: List user actions and configuration changes within this organization.
tags:
- Audit Logs
/organization/costs:
get:
operationId: usage-costs
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently only C<1d> is
supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1d
type: string
- description: |
Return only costs for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Group the costs by the specified fields. Support fields include
C<project_id>, C<line_item> and any combination of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- line_item
type: string
type: array
- description: |
A limit on the number of buckets to be returned. Limit can range
between 1 and 180, and the default is 7.
in: query
name: limit
required: false
schema:
default: 7
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Costs data retrieved successfully.
summary: Get costs details for the organization.
tags:
- Usage
/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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *297
required: *298
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: *299
required: *300
type: object
description: The invite request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual `invite` to the organization.
properties: *293
required: *294
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: *295
required: *296
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: *293
required: *294
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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *357
required: *358
type: object
description: Projects listed successfully.
summary: Returns a list of projects.
tags:
- Projects
post:
operationId: create-project
requestBody:
content:
application/json:
schema:
properties: *355
required: *356
type: object
description: The project create request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *343
required: *344
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: *343
required: *344
type: object
description: Project retrieved successfully.
summary: Retrieves a project.
tags:
- Projects
post:
operationId: modify-project
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties: *374
required: *375
type: object
description: The project update request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an individual project.
properties: *343
required: *344
type: object
description: Project updated successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *353
required: *354
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: *351
required: *352
type: object
description: Project API key deleted successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *345
required: *350
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: *343
required: *344
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}/rate_limits:
get:
operationId: list-project-rate-limits
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. The default is 100.
in: query
name: limit
required: false
schema:
default: 100
type: integer
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo in order to fetch the next page of the list.
in: query
name: after
required: false
schema:
type: string
- description: |
A cursor for use in pagination. C<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, beginning with objI<foo, your subsequent call can
include before=obj>foo in order to fetch the previous page of the list.
in: query
name: before
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *361
required: *362
type: object
description: Project rate limits listed successfully.
summary: Returns the rate limits per model for a project.
tags:
- Projects
/organization/projects/{project_id}/rate_limits/{rate_limit_id}:
post:
operationId: update-project-rate-limits
parameters:
- description: "The ID of the project.\n"
in: path
name: project_id
required: true
schema:
type: string
- description: "The ID of the rate limit.\n"
in: path
name: rate_limit_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties: *363
type: object
description: The project rate limit update request payload.
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a project rate limit config.
properties: *359
required: *360
type: object
description: Project rate limit updated successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
type: object
description: Error response for various conditions.
summary: Updates a project rate limit.
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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *372
required: *373
type: object
description: Project service accounts listed successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *366
required: *367
type: object
description: The project service account create request payload.
required: true
responses:
'200':
content:
application/json:
schema:
properties: *368
required: *369
type: object
description: Project service account created successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *370
required: *371
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: *346
required: *347
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<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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: *380
required: *381
type: object
description: Project users listed successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *376
required: *377
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: *348
required: *349
type: object
description: User added to project successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *378
required: *379
type: object
description: Project user deleted successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
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: *348
required: *349
type: object
description: Project user retrieved successfully.
summary: Retrieves a user in the project.
tags:
- Projects
post:
operationId: modify-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
requestBody:
content:
application/json:
schema:
properties: *382
required: *383
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: *348
required: *349
type: object
description: Project user's role updated successfully.
'400':
content:
application/json:
schema:
properties: *278
required: *279
type: object
description: Error response for various conditions.
summary: Modifies a user's role in the project.
tags:
- Projects
/organization/usage/audio_speeches:
get:
operationId: usage-audio-speeches
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model> or any combination
of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get audio speeches usage details for the organization.
tags:
- Usage
/organization/usage/audio_transcriptions:
get:
operationId: usage-audio-transcriptions
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model> or any combination
of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get audio transcriptions usage details for the organization.
tags:
- Usage
/organization/usage/code_interpreter_sessions:
get:
operationId: usage-code-interpreter-sessions
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get code interpreter sessions usage details for the organization.
tags:
- Usage
/organization/usage/completions:
get:
operationId: usage-completions
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
If C<true>, return batch jobs only. If C<false>, return non-batch jobs
only. By default, return both.
in: query
name: batch
required: false
schema:
type: boolean
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model>, C<batch> or any
combination of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
- batch
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get completions usage details for the organization.
tags:
- Usage
/organization/usage/embeddings:
get:
operationId: usage-embeddings
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model> or any combination
of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get embeddings usage details for the organization.
tags:
- Usage
/organization/usage/images:
get:
operationId: usage-images
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usages for these sources. Possible values are
C<image.generation>, C<image.edit>, C<image.variation> or any
combination of them.
in: query
name: sources
required: false
schema:
items:
enum:
- image.generation
- image.edit
- image.variation
type: string
type: array
- description: |
Return only usages for these image sizes. Possible values are
C<256x256>, C<512x512>, C<1024x1024>, C<1792x1792>, C<1024x1792> or any
combination of them.
in: query
name: sizes
required: false
schema:
items:
enum:
- 256x256
- 512x512
- 1024x1024
- 1792x1792
- 1024x1792
type: string
type: array
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model>, C<size>, C<source>
or any combination of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
- size
- source
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get images usage details for the organization.
tags:
- Usage
/organization/usage/moderations:
get:
operationId: usage-moderations
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these users.
in: query
name: user_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these API keys.
in: query
name: api_key_ids
required: false
schema:
items:
type: string
type: array
- description: |
Return only usage for these models.
in: query
name: models
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>, C<user_id>, C<api_key_id>, C<model> or any combination
of them.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
- user_id
- api_key_id
- model
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get moderations usage details for the organization.
tags:
- Usage
/organization/usage/vector_stores:
get:
operationId: usage-vector-stores
parameters:
- description: |
Start time (Unix seconds) of the query time range, inclusive.
in: query
name: start_time
required: true
schema:
type: integer
- description: |
End time (Unix seconds) of the query time range, exclusive.
in: query
name: end_time
required: false
schema:
type: integer
- description: |
Width of each time bucket in response. Currently C<1m>, C<1h> and C<1d>
are supported, default to C<1d>.
in: query
name: bucket_width
required: false
schema:
default: 1d
enum:
- 1m
- 1h
- 1d
type: string
- description: |
Return only usage for these projects.
in: query
name: project_ids
required: false
schema:
items:
type: string
type: array
- description: |
Group the usage data by the specified fields. Support fields include
C<project_id>.
in: query
name: group_by
required: false
schema:
items:
enum:
- project_id
type: string
type: array
- description: |
Specifies the number of buckets to return.
- C<bucket_width=1d>: default: 7, max: 31
- C<bucket_width=1h>: default: 24, max: 168
- C<bucket_width=1m>: default: 60, max: 1440
in: query
name: limit
required: false
schema:
type: integer
- description: |
A cursor for use in pagination. Corresponding to the C<next_page> field
from the previous response.
in: query
name: page
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *413
required: *418
type: object
description: Usage data retrieved successfully.
summary: Get vector stores usage details for the organization.
tags:
- Usage
/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<after> 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 objI<foo, your subsequent call can
include after=obj>foo in order to fetch the next page of the list.
in: query
name: after
required: false
schema:
type: string
- description: |
Filter by the email address of users.
in: query
name: emails
required: false
schema:
items:
type: string
type: array
responses:
'200':
content:
application/json:
schema:
properties: *423
required: *424
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: *421
required: *422
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: *419
required: *420
type: object
description: User retrieved successfully.
summary: Retrieves a user by their identifier.
tags:
- Users
post:
operationId: modify-user
parameters:
- description: "The ID of the user.\n"
in: path
name: user_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties: *425
required: *426
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: *419
required: *420
type: object
description: User role updated successfully.
summary: Modifies a user's role in the organization.
tags:
- Users
/realtime/sessions:
post:
operationId: create-realtime-session
requestBody:
content:
application/json:
schema:
description: Realtime session object configuration.
properties: *387
type: object
description: Create an ephemeral API key with the given session configuration.
required: true
responses:
'200':
content:
application/json:
schema:
description: |
A new Realtime session configuration, with an ephermeral key. Default TTL
for keys is one minute.
properties: *390
required: *391
type: object
description: Session created successfully.
summary: |
Create an ephemeral API token for use in client-side applications with the
Realtime API. Can be configured with the same session parameters as the
`session.update` client event.
It responds with a session object, plus a `client_secret` key which contains
a usable ephemeral API token that can be used to authenticate browser clients
for the Realtime API.
tags:
- Realtime
/threads:
post:
operationId: createThread
requestBody:
content:
application/json:
schema:
additionalProperties: false
description: "Options to create a new thread. If no thread is provided
when running a \nrequest, an empty thread will be created.\n"
properties: *237
type: object
responses:
'200':
content:
application/json:
schema:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *26
required: *27
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: *236
required: *238
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: *272
required: *273
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: *26
required: *27
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: *342
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a thread that contains [messages](/docs/api-reference/messages).
properties: *26
required: *27
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo 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: *315
required: *316
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: *224
required: *227
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *80
required: *95
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: *268
required: *269
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: *80
required: *95
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: *340
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents a message within a [thread](/docs/api-reference/threads).
properties: *80
required: *95
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo in order to fetch the previous page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *325
required: *326
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: *232
required: *233
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: *29
required: *39
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: *341
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: *29
required: *39
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo 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: *323
required: *324
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: *41
required: *62
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: *392
required: *393
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Represents an execution run on a [thread](/docs/api-reference/threads).
properties: *29
required: *39
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: *255
required: *256
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: *395
required: *396
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: *395
required: *396
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: *184
required: *185
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: |
The Upload object can accept byte chunks in the form of Parts.
properties: *395
required: *396
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: *397
required: *398
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo in order to fetch the previous page of the list.
in: query
name: before
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties: *335
required: *338
description: OK
summary: Returns a list of vector stores.
tags:
- Vector stores
post:
operationId: createVectorStore
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties: *261
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: *336
required: *337
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: *276
required: *277
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: *336
required: *337
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: *394
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: *336
required: *337
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: *257
required: *258
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A batch of files attached to a vector store.
properties: *427
required: *428
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: *427
required: *428
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: *427
required: *428
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo 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: *327
required: *334
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<created_at> timestamp of the objects. C<asc> for
ascending order and C<desc> for descending order.
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
A cursor for use in pagination. C<after> 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 objI<foo, your subsequent call can
include after=obj>foo 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<before> is an object ID that defines
your place in the list. For instance, if you make a list request and
receive 100 objects, starting with objI<foo, your subsequent call can
include before=obj>foo 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: *327
required: *334
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: *259
required: *260
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: A list of files attached to a vector store.
properties: *328
required: *333
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: *274
required: *275
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: *328
required: *333
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 text and/or image inputs, classifies if those inputs are potentially
harmful.
name: Moderations
- description: List user actions and configuration changes within this organization.
name: Audit Logs
=head1 COPYRIGHT 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.