11/23/23, 7:33 PM API Reference - OpenAI API

Documentation API reference Examples Forum Help

Introduction
You can interact with the API through HTTP requests from any language, via our official
Python bindings, our official Node.js library, or a community-maintained library.

To install the official Python bindings, run the following command:

pip install openai

To install the official Node.js library, run the following command in your Node.js project
directory:

npm install openai@^4.0.0

Authentication
The OpenAI API uses API keys for authentication. Visit your API Keys page to retrieve the
API key you'll use in your requests.

Remember that your API key is a secret! Do not share it with others or expose it in any
client-side code (browsers, apps). Production requests must be routed through your own
backend server where your API key can be securely loaded from an environment variable
or key management service.

All API requests should include your API key in an Authorization HTTP header as
follows:

Authorization: Bearer OPENAI_API_KEY

Organization (optional)

https://platform.openai.com/docs/api-reference/chat/object 1/116
11/23/23, 7:33 PM API Reference - OpenAI API

For users who belong to multiple organizations, you can pass a header to specify which
organization is used for an API request. Usage from these API requests will count as usage
for the specified organization.

Example curl command:

1 curl https://api.openai.com/v1/models \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "OpenAI-Organization: org-l9tegHQ5p4LkViUOfcSPjQWo"

Example with the openai Python package:

1 from openai import OpenAI

2
3 client = OpenAI(
4 organization='org-l9tegHQ5p4LkViUOfcSPjQWo',
5 )
6 client.models.list()

Example with the openai Node.js package:

1 import { Configuration, OpenAIApi } from "openai";

2 const configuration = new Configuration({
3 organization: "org-l9tegHQ5p4LkViUOfcSPjQWo",
4 apiKey: process.env.OPENAI_API_KEY,
5 });
6 const openai = new OpenAIApi(configuration);
7 const response = await openai.listEngines();

Organization IDs can be found on your Organization settings page.

Making requests
You can paste the command below into your terminal to run your first API request. Make
sure to replace $OPENAI_API_KEY with your secret API key.

https://platform.openai.com/docs/api-reference/chat/object 2/116
11/23/23, 7:33 PM API Reference - OpenAI API

1 curl https://api.openai.com/v1/chat/completions \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "model": "gpt-3.5-turbo",
6 "messages": [{"role": "user", "content": "Say this is a test!
7 "temperature": 0.7
8 }'

This request queries the gpt-3.5-turbo model (which under the hood points to the latest
gpt-3.5-turbo model variant) to complete the text starting with a prompt of "Say this is a
test". You should get a response back that resembles the following:

1 {
2 "id": "chatcmpl-abc123",
3 "object": "chat.completion",
4 "created": 1677858242,
5 "model": "gpt-3.5-turbo-1106",
6 "usage": {
7 "prompt_tokens": 13,
8 "completion_tokens": 7,
9 "total_tokens": 20
10 },
11 "choices": [
12 {
13 "message": {
14 "role": "assistant",
15 "content": "\n\nThis is a test!"
16 },
17 "finish_reason": "stop",
18 "index": 0
19 }
20 ]
21 }

Now that you've generated your first chat completion, let's break down the response
object. We can see the finish_reason is stop which means the API returned the full
chat completion generated by the model without running into any limits. In the choices
https://platform.openai.com/docs/api-reference/chat/object 3/116
11/23/23, 7:33 PM API Reference - OpenAI API

list, we only generated a single message but you can set the n parameter to generate
multiple messages choices.

Audio
Learn how to turn audio into text or text into audio.

Related guide: Speech to text

Create speech
POST https://api.openai.com/v1/audio/speech

Generates audio from the input text.

Request body

model string Required

One of the available TTS models: tts-1 or tts-1-hd

input string Required

The text to generate audio for. The maximum length is 4096 characters.

voice string Required

The voice to use when generating the audio. Supported voices are alloy , echo , fable ,
onyx , nova , and shimmer . Previews of the voices are available in the Text to speech guide.

response_format string Optional Defaults to mp3

The format to audio in. Supported formats are mp3 , opus , aac , and flac .

speed number Optional Defaults to 1

The speed of the generated audio. Select a value from 0.25 to 4.0 . 1.0 is the default.

Returns

https://platform.openai.com/docs/api-reference/chat/object 4/116
11/23/23, 7:33 PM API Reference - OpenAI API

The audio file content.

Example request curl Copy

1 curl https://api.openai.com/v1/audio/speech \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "model": "tts-1",
6 "input": "The quick brown fox jumped over the lazy dog.",
7 "voice": "alloy"
8 }' \
9 --output speech.mp3

Create transcription
POST https://api.openai.com/v1/audio/transcriptions

Transcribes audio into the input language.

Request body

file file Required

The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg,
mpga, m4a, ogg, wav, or webm.

model string Required

ID of the model to use. Only whisper-1 is currently available.

language string Optional

The language of the input audio. Supplying the input language in ISO-639-1 format will improve
accuracy and latency.

prompt string Optional

An optional text to guide the model's style or continue a previous audio segment. The prompt
should match the audio language.

https://platform.openai.com/docs/api-reference/chat/object 5/116
11/23/23, 7:33 PM API Reference - OpenAI API

response_format string Optional Defaults to json

The format of the transcript output, in one of these options: json , text , srt ,
verbose_json , or vtt .

temperature number Optional Defaults to 0

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 to automatically increase the temperature until certain thresholds
are hit.

Returns

The transcribed text.

Example request curl Copy

1 curl https://api.openai.com/v1/audio/transcriptions \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: multipart/form-data" \
4 -F file="@/path/to/file/audio.mp3" \
5 -F model="whisper-1"

Response Copy

1 {
2 "text": "Imagine the wildest idea that you've ever had, and you're curious
3 }

Create translation
POST https://api.openai.com/v1/audio/translations

Translates audio into English.

Request body

https://platform.openai.com/docs/api-reference/chat/object 6/116
11/23/23, 7:33 PM API Reference - OpenAI API

file file Required

The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg,
mpga, m4a, ogg, wav, or webm.

model string Required

ID of the model to use. Only whisper-1 is currently available.

prompt string Optional

An optional text to guide the model's style or continue a previous audio segment. The prompt
should be in English.

response_format string Optional Defaults to json

The format of the transcript output, in one of these options: json , text , srt ,
verbose_json , or vtt .

temperature number Optional Defaults to 0

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 to automatically increase the temperature until certain thresholds
are hit.

Returns

The translated text.

Example request curl Copy

1 curl https://api.openai.com/v1/audio/translations \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: multipart/form-data" \
4 -F file="@/path/to/file/german.m4a" \
5 -F model="whisper-1"

Response Copy

1 {
2 "text": "Hello, my name is Wolfgang and I come from Germany. Where are you
3 }

https://platform.openai.com/docs/api-reference/chat/object 7/116
11/23/23, 7:33 PM API Reference - OpenAI API

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

Related guide: Chat Completions

The chat completion object

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

id string
A unique identifier for the chat completion.

choices array
A list of chat completion choices. Can be more than one if n is greater than 1.
Show properties

created integer
The Unix timestamp (in seconds) of when the chat completion was created.

model string
The model used for the chat completion.

system_fingerprint string
This fingerprint represents the backend configuration that the model runs with.

Can be used in conjunction with the seed request parameter to understand when backend
changes have been made that might impact determinism.

object string
The object type, which is always chat.completion .

usage object
Usage statistics for the completion request.
Show properties

https://platform.openai.com/docs/api-reference/chat/object 8/116
11/23/23, 7:33 PM API Reference - OpenAI API

The chat completion object Copy

1 {
2 "id": "chatcmpl-123",
3 "object": "chat.completion",
4 "created": 1677652288,
5 "model": "gpt-3.5-turbo-0613",
6 "system_fingerprint": "fp_44709d6fcb",
7 "choices": [{
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "\n\nHello there, how may I assist you today?",
12 },
13 "finish_reason": "stop"
14 }],
15 "usage": {
16 "prompt_tokens": 9,
17 "completion_tokens": 12,
18 "total_tokens": 21
19 }
20 }

The chat completion chunk object

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

id string
A unique identifier for the chat completion. Each chunk has the same ID.

choices array
A list of chat completion choices. Can be more than one if n is greater than 1.
Show properties

created integer
The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the
same timestamp.

model string

https://platform.openai.com/docs/api-reference/chat/object 9/116
11/23/23, 7:33 PM API Reference - OpenAI API

The model to generate the completion.

system_fingerprint string
This fingerprint represents the backend configuration that the model runs with. Can be used in
conjunction with the seed request parameter to understand when backend changes have been
made that might impact determinism.

object string
The object type, which is always chat.completion.chunk .

The chat completion chunk object Copy

1 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"
2
3 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"
4
5 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"
6
7 ....
8
9 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"
10
11 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"
12
13 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"

Create chat completion

POST https://api.openai.com/v1/chat/completions

Creates a model response for the given chat conversation.

Request body

messages array Required

A list of messages comprising the conversation so far. Example Python code.
Show possible types

https://platform.openai.com/docs/api-reference/chat/object 10/116
11/23/23, 7:33 PM API Reference - OpenAI API

model string Required

ID of the model to use. See the model endpoint compatibility table for details on which models
work with the Chat API.

frequency_penalty number or null Optional Defaults to 0

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.

logit_bias map Optional Defaults to null

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.

max_tokens integer or null Optional Defaults to inf

The maximum number of tokens to generate in the chat completion.

The total length of input tokens and generated tokens is limited by the model's context length.
Example Python code for counting tokens.

n integer or null Optional Defaults to 1

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.

presence_penalty number or null Optional Defaults to 0

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.

response_format object Optional

An object specifying the format that the model must output.

Setting to { "type": "json_object" } enables JSON mode, which guarantees 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

https://platform.openai.com/docs/api-reference/chat/object 11/116
11/23/23, 7:33 PM API Reference - OpenAI API

finish_reason="length" , which indicates the generation exceeded max_tokens or the

conversation exceeded the max context length.
Show properties

seed integer or null Optional

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.

stop string / array / null Optional Defaults to null

Up to 4 sequences where the API will stop generating further tokens.

stream boolean or null Optional Defaults to false

If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-
sent events as they become available, with the stream terminated by a data: [DONE]
message. Example Python code.

temperature number or null Optional Defaults to 1

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.

top_p number or null Optional Defaults to 1

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.

tools array Optional

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.
Show properties

tool_choice string or object Optional

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 {"type:
"function", "function": {"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.

https://platform.openai.com/docs/api-reference/chat/object 12/116
11/23/23, 7:33 PM API Reference - OpenAI API

Show possible types

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

function_call Deprecated string or object Optional

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.
Show possible types

functions Deprecated array Optional

Deprecated in favor of tools .

A list of functions the model may generate JSON inputs for.

Show properties

Returns

Returns a chat completion object, or a streamed sequence of chat completion chunk objects if
the request is streamed.

Default Image input Streaming Functions

Example request gpt-3.5-turbo curl Copy

1 curl https://api.openai.com/v1/chat/completions \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "model": "gpt-3.5-turbo",
6 "messages": [
7 {
8 "role": "system",
9 "content": "You are a helpful assistant."
10 },
https://platform.openai.com/docs/api-reference/chat/object 13/116
11/23/23, 7:33 PM API Reference - OpenAI API

11 {
12 "role": "user",
13 "content": "Hello!"
14 }
15 ]
16 }'

Response Copy

1 {
2 "id": "chatcmpl-123",
3 "object": "chat.completion",
4 "created": 1677652288,
5 "model": "gpt-3.5-turbo-0613",
6 "system_fingerprint": "fp_44709d6fcb",
7 "choices": [{
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "\n\nHello there, how may I assist you today?",
12 },
13 "finish_reason": "stop"
14 }],
15 "usage": {
16 "prompt_tokens": 9,
17 "completion_tokens": 12,
18 "total_tokens": 21
19 }
20 }

Embeddings
Get a vector representation of a given input that can be easily consumed by machine
learning models and algorithms.

Related guide: Embeddings

The embedding object

Represents an embedding vector returned by embedding endpoint.
https://platform.openai.com/docs/api-reference/chat/object 14/116
11/23/23, 7:33 PM API Reference - OpenAI API

index integer
The index of the embedding in the list of embeddings.

embedding array
The embedding vector, which is a list of floats. The length of vector depends on the model as
listed in the embedding guide.

object string
The object type, which is always "embedding".

The embedding object Copy

1 {
2 "object": "embedding",
3 "embedding": [
4 0.0023064255,
5 -0.009327292,
6 .... (1536 floats total for ada-002)
7 -0.0028842222,
8 ],
9 "index": 0
10 }

Create embeddings
POST https://api.openai.com/v1/embeddings

Creates an embedding vector representing the input text.

Request body

input string or array Required

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 for counting tokens.
Show possible types

https://platform.openai.com/docs/api-reference/chat/object 15/116
11/23/23, 7:33 PM API Reference - OpenAI API

model string Required

ID of the model to use. You can use the List models API to see all of your available models, or see
our Model overview for descriptions of them.

encoding_format string Optional Defaults to float

The format to return the embeddings in. Can be either float or base64 .

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

Returns

A list of embedding objects.

Example request curl Copy

1 curl https://api.openai.com/v1/embeddings \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "input": "The food was delicious and the waiter...",
6 "model": "text-embedding-ada-002",
7 "encoding_format": "float"
8 }'

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "object": "embedding",
6 "embedding": [
7 0.0023064255,
8 -0.009327292,
9 .... (1536 floats total for ada-002)
10 -0.0028842222,
11 ],
12 "index": 0
13 }

https://platform.openai.com/docs/api-reference/chat/object 16/116
11/23/23, 7:33 PM API Reference - OpenAI API

14 ],
15 "model": "text-embedding-ada-002",
16 "usage": {
17 "prompt_tokens": 8,
18 "total_tokens": 8
19 }
20 }

Fine-tuning
Manage fine-tuning jobs to tailor a model to your specific training data.

Related guide: Fine-tune models

The fine-tuning job object

The fine_tuning.job object represents a fine-tuning job that has been created
through the API.

id string
The object identifier, which can be referenced in the API endpoints.

created_at integer
The Unix timestamp (in seconds) for when the fine-tuning job was created.

error object or null

For fine-tuning jobs that have failed , this will contain more information on the cause of the
failure.
Show properties

fine_tuned_model string or null

The name of the fine-tuned model that is being created. The value will be null if the fine-tuning job
is still running.

finished_at integer or null

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.

https://platform.openai.com/docs/api-reference/chat/object 17/116
11/23/23, 7:33 PM API Reference - OpenAI API

hyperparameters object
The hyperparameters used for the fine-tuning job. See the fine-tuning guide for more details.
Show properties

model string
The base model that is being fine-tuned.

object string
The object type, which is always "fine_tuning.job".

organization_id string
The organization that owns the fine-tuning job.

result_files array
The compiled results file ID(s) for the fine-tuning job. You can retrieve the results with the Files
API.

status string
The current status of the fine-tuning job, which can be either validating_files , queued ,
running , succeeded , failed , or cancelled .

trained_tokens integer or null

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.

training_file string
The file ID used for training. You can retrieve the training data with the Files API.

validation_file string or null

The file ID used for validation. You can retrieve the validation results with the Files API.

The fine-tuning job object Copy

1 {
2 "object": "fine_tuning.job",
3 "id": "ftjob-abc123",
4 "model": "davinci-002",
5 "created_at": 1692661014,
6 "finished_at": 1692661190,
7 "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy",
8 "organization_id": "org-123",

https://platform.openai.com/docs/api-reference/chat/object 18/116
11/23/23, 7:33 PM API Reference - OpenAI API

9 "result_files": [
10 "file-abc123"
11 ],
12 "status": "succeeded",
13 "validation_file": null,
14 "training_file": "file-abc123",
15 "hyperparameters": {
16 "n_epochs": 4,
17 },
18 "trained_tokens": 5768
19 }

Create fine-tuning job

POST https://api.openai.com/v1/fine_tuning/jobs

Creates a job that fine-tunes a specified 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

Request body

model string Required

The name of the model to fine-tune. You can select one of the supported models.

training_file string Required

The ID of an uploaded file that contains training data.

See upload file 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 .

See the fine-tuning guide for more details.

hyperparameters object Optional

The hyperparameters used for the fine-tuning job.
Show properties

https://platform.openai.com/docs/api-reference/chat/object 19/116
11/23/23, 7:33 PM API Reference - OpenAI API

suffix string or null Optional Defaults to null

A string of up to 18 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-
3.5-turbo:openai:custom-model-name:7p4lURel .

validation_file string or null Optional

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 for more details.

Returns

A fine-tuning.job object.

Default Epochs Validation file

Example request curl Copy

1 curl https://api.openai.com/v1/fine_tuning/jobs \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo",
6 "model": "gpt-3.5-turbo"
7 }'

Response Copy

1 {
2 "object": "fine_tuning.job",
3 "id": "ftjob-abc123",
4 "model": "gpt-3.5-turbo-0613",
5 "created_at": 1614807352,
6 "fine_tuned_model": null,
7 "organization_id": "org-123",
8 "result_files": [],
https://platform.openai.com/docs/api-reference/chat/object 20/116
11/23/23, 7:33 PM API Reference - OpenAI API

9 "status": "queued",
10 "validation_file": null,
11 "training_file": "file-abc123",
12 }

List fine-tuning jobs

GET https://api.openai.com/v1/fine_tuning/jobs

List your organization's fine-tuning jobs

Query parameters

after string Optional

Identifier for the last job from the previous pagination request.

limit integer Optional Defaults to 20

Number of fine-tuning jobs to retrieve.

Returns

A list of paginated fine-tuning job objects.

Example request curl Copy

1 curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "object": "fine_tuning.job.event",
6 "id": "ft-event-TjX0lMfOniCZX64t9PUQT5hn",
7 "created_at": 1689813489,

https://platform.openai.com/docs/api-reference/chat/object 21/116
11/23/23, 7:33 PM API Reference - OpenAI API

8 "level": "warn",
9 "message": "Fine tuning process stopping due to job cancellation",
10 "data": null,
11 "type": "message"
12 },
13 { ... },
14 { ... }
15 ], "has_more": true
16 }

Retrieve fine-tuning job

GET https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}

Get info about a fine-tuning job.

Learn more about fine-tuning

Path parameters

fine_tuning_job_id string Required

The ID of the fine-tuning job.

Returns

The fine-tuning object with the given ID.

Example request curl Copy

1 curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "object": "fine_tuning.job",
3 "id": "ftjob-abc123",
https://platform.openai.com/docs/api-reference/chat/object 22/116
11/23/23, 7:33 PM API Reference - OpenAI API

4 "model": "davinci-002",
5 "created_at": 1692661014,
6 "finished_at": 1692661190,
7 "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy",
8 "organization_id": "org-123",
9 "result_files": [
10 "file-abc123"
11 ],
12 "status": "succeeded",
13 "validation_file": null,
14 "training_file": "file-abc123",
15 "hyperparameters": {
16 "n_epochs": 4,
17 },
18 "trained_tokens": 5768
19 }

Cancel fine-tuning
POST https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/cancel

Immediately cancel a fine-tune job.

Path parameters

fine_tuning_job_id string Required

The ID of the fine-tuning job to cancel.

Returns

The cancelled fine-tuning object.

Example request curl Copy

1 curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \

2 -H "Authorization: Bearer $OPENAI_API_KEY"

https://platform.openai.com/docs/api-reference/chat/object 23/116
11/23/23, 7:33 PM API Reference - OpenAI API

Response Copy

1 {
2 "object": "fine_tuning.job",
3 "id": "ftjob-abc123",
4 "model": "gpt-3.5-turbo-0613",
5 "created_at": 1689376978,
6 "fine_tuned_model": null,
7 "organization_id": "org-123",
8 "result_files": [],
9 "hyperparameters": {
10 "n_epochs": "auto"
11 },
12 "status": "cancelled",
13 "validation_file": "file-abc123",
14 "training_file": "file-abc123"
15 }

The fine-tuning job event object

Fine-tuning job event object

id string

created_at integer

level string

message string

object string

The fine-tuning job event object Copy

1 {
2 "object": "fine_tuning.job.event",
3 "id": "ftevent-abc123"
4 "created_at": 1677610602,
5 "level": "info",

https://platform.openai.com/docs/api-reference/chat/object 24/116
11/23/23, 7:33 PM API Reference - OpenAI API

6 "message": "Created fine-tuning job"

7 }

List fine-tuning events

GET https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/events

Get status updates for a fine-tuning job.

Path parameters

fine_tuning_job_id string Required

The ID of the fine-tuning job to get events for.

Query parameters

after string Optional

Identifier for the last event from the previous pagination request.

limit integer Optional Defaults to 20

Number of events to retrieve.

Returns

A list of fine-tuning event objects.

Example request curl Copy

1 curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "object": "list",

https://platform.openai.com/docs/api-reference/chat/object 25/116
11/23/23, 7:33 PM API Reference - OpenAI API

3 "data": [
4 {
5 "object": "fine_tuning.job.event",
6 "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm",
7 "created_at": 1692407401,
8 "level": "info",
9 "message": "Fine tuning job successfully completed",
10 "data": null,
11 "type": "message"
12 },
13 {
14 "object": "fine_tuning.job.event",
15 "id": "ft-event-tyiGuB72evQncpH87xe505Sv",
16 "created_at": 1692407400,
17 "level": "info",
18 "message": "New fine-tuned model created: ft:gpt-3.5-turbo:openai::7p4
19 "data": null,
20 "type": "message"
21 }
22 ],
23 "has_more": true
24 }

Files
Files are used to upload documents that can be used with features like Assistants and
Fine-tuning.

The File object

The File object represents a document that has been uploaded to OpenAI.

id string
The file identifier, which can be referenced in the API endpoints.

bytes integer
The size of the file, in bytes.

https://platform.openai.com/docs/api-reference/chat/object 26/116
11/23/23, 7:33 PM API Reference - OpenAI API

created_at integer
The Unix timestamp (in seconds) for when the file was created.

filename string
The name of the file.

object string
The object type, which is always file .

purpose string
The intended purpose of the file. Supported values are fine-tune , fine-tune-results ,
assistants , and assistants_output .

status Deprecated string

Deprecated. The current status of the file, which can be either uploaded , processed , or
error .

status_details Deprecated string

Deprecated. For details on why a fine-tuning training file failed validation, see the error field on
fine_tuning.job .

The File object Copy

1 {
2 "id": "file-abc123",
3 "object": "file",
4 "bytes": 120000,
5 "created_at": 1677610602,
6 "filename": "salesOverview.pdf",
7 "purpose": "assistants",
8 }

List files
GET https://api.openai.com/v1/files

Returns a list of files that belong to the user's organization.

https://platform.openai.com/docs/api-reference/chat/object 27/116
11/23/23, 7:33 PM API Reference - OpenAI API

Query parameters

purpose string Optional

Only return files with the given purpose.

Returns

A list of File objects.

Example request curl Copy

1 curl https://api.openai.com/v1/files \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "data": [
3 {
4 "id": "file-abc123",
5 "object": "file",
6 "bytes": 175,
7 "created_at": 1613677385,
8 "filename": "salesOverview.pdf",
9 "purpose": "assistants",
10 },
11 {
12 "id": "file-abc123",
13 "object": "file",
14 "bytes": 140,
15 "created_at": 1613779121,
16 "filename": "puppy.jsonl",
17 "purpose": "fine-tune",
18 }
19 ],
20 "object": "list"
21 }

https://platform.openai.com/docs/api-reference/chat/object 28/116
11/23/23, 7:33 PM API Reference - OpenAI API

Upload file
POST https://api.openai.com/v1/files

Upload a file that can be used across various endpoints. The size of all the files
uploaded by one organization can be up to 100 GB.

The size of individual files can be a maximum of 512 MB. See the Assistants Tools
guide to learn more about the types of files supported. The Fine-tuning API only
supports .jsonl files.

Please contact us if you need to increase these storage limits.

Request body

file file Required

The File object (not file name) to be uploaded.

purpose string Required

The intended purpose of the uploaded file.

Use "fine-tune" for Fine-tuning and "assistants" for Assistants and Messages. This allows us to
validate the format of the uploaded file is correct for fine-tuning.

Returns

The uploaded File object.

Example request curl Copy

1 curl https://api.openai.com/v1/files \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -F purpose="fine-tune" \
4 -F file="@mydata.jsonl"

Response Copy

1 {
2 "id": "file-abc123",
https://platform.openai.com/docs/api-reference/chat/object 29/116
11/23/23, 7:33 PM API Reference - OpenAI API

3 "object": "file",
4 "bytes": 120000,
5 "created_at": 1677610602,
6 "filename": "mydata.jsonl",
7 "purpose": "fine-tune",
8 }

Delete file
DELETE https://api.openai.com/v1/files/{file_id}

Delete a file.

Path parameters

file_id string Required

The ID of the file to use for this request.

Returns

Deletion status.

Example request curl Copy

1 curl https://api.openai.com/v1/files/file-abc123 \
2 -X DELETE \
3 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "id": "file-abc123",
3 "object": "file",
4 "deleted": true
5 }

https://platform.openai.com/docs/api-reference/chat/object 30/116
11/23/23, 7:33 PM API Reference - OpenAI API

Retrieve file
GET https://api.openai.com/v1/files/{file_id}

Returns information about a specific file.

Path parameters

file_id string Required

The ID of the file to use for this request.

Returns

The File object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/files/file-abc123 \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "id": "file-abc123",
3 "object": "file",
4 "bytes": 120000,
5 "created_at": 1677610602,
6 "filename": "mydata.jsonl",
7 "purpose": "fine-tune",
8 }

Retrieve file content

GET https://api.openai.com/v1/files/{file_id}/content

https://platform.openai.com/docs/api-reference/chat/object 31/116
11/23/23, 7:33 PM API Reference - OpenAI API

Returns the contents of the specified file.

Path parameters

file_id string Required

The ID of the file to use for this request.

Returns

The file content.

Example request curl Copy

1 curl https://api.openai.com/v1/files/file-abc123/content \
2 -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl

Images
Given a prompt and/or an input image, the model will generate a new image.

Related guide: Image generation

The image object

Represents the url or the content of an image generated by the OpenAI API.

b64_json string
The base64-encoded JSON of the generated image, if response_format is b64_json .

url string
The URL of the generated image, if response_format is url (default).

revised_prompt string

https://platform.openai.com/docs/api-reference/chat/object 32/116
11/23/23, 7:33 PM API Reference - OpenAI API

The prompt that was used to generate the image, if there was any revision to the prompt.

The image object Copy

1 {
2 "url": "...",
3 "revised_prompt": "..."
4 }

Create image
POST https://api.openai.com/v1/images/generations

Creates an image given a prompt.

Request body

prompt string Required

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 .

model string Optional Defaults to dall-e-2

The model to use for image generation.

n integer or null Optional Defaults to 1

The number of images to generate. Must be between 1 and 10. For dall-e-3 , only n=1 is
supported.

quality string Optional Defaults to standard

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 .

response_format string or null Optional Defaults to url

The format in which the generated images are returned. Must be one of url or b64_json .

size string or null Optional Defaults to 1024x1024

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

https://platform.openai.com/docs/api-reference/chat/object 33/116
11/23/23, 7:33 PM API Reference - OpenAI API

models.

style string or null Optional Defaults to vivid

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 .

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

Returns

Returns a list of image objects.

Example request curl Copy

1 curl https://api.openai.com/v1/images/generations \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "model": "dall-e-3",
6 "prompt": "A cute baby sea otter",
7 "n": 1,
8 "size": "1024x1024"
9 }'

Response Copy

1 {
2 "created": 1589478378,
3 "data": [
4 {
5 "url": "https://..."
6 },
7 {
8 "url": "https://..."
9 }
10 ]
11 }

https://platform.openai.com/docs/api-reference/chat/object 34/116
11/23/23, 7:33 PM API Reference - OpenAI API

Create image edit

POST https://api.openai.com/v1/images/edits

Creates an edited or extended image given an original image and a prompt.

Request body

image file Required

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.

prompt string Required

A text description of the desired image(s). The maximum length is 1000 characters.

mask file Optional

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 .

model string Optional Defaults to dall-e-2

The model to use for image generation. Only dall-e-2 is supported at this time.

n integer or null Optional Defaults to 1

The number of images to generate. Must be between 1 and 10.

size string or null Optional Defaults to 1024x1024

The size of the generated images. Must be one of 256x256 , 512x512 , or 1024x1024 .

response_format string or null Optional Defaults to url

The format in which the generated images are returned. Must be one of url or b64_json .

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

Returns

https://platform.openai.com/docs/api-reference/chat/object 35/116
11/23/23, 7:33 PM API Reference - OpenAI API

Returns a list of image objects.

Example request curl Copy

1 curl https://api.openai.com/v1/images/edits \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -F image="@otter.png" \
4 -F mask="@mask.png" \
5 -F prompt="A cute baby sea otter wearing a beret" \
6 -F n=2 \
7 -F size="1024x1024"

Response Copy

1 {
2 "created": 1589478378,
3 "data": [
4 {
5 "url": "https://..."
6 },
7 {
8 "url": "https://..."
9 }
10 ]
11 }

Create image variation

POST https://api.openai.com/v1/images/variations

Creates a variation of a given image.

Request body

image file Required

The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and
square.

https://platform.openai.com/docs/api-reference/chat/object 36/116
11/23/23, 7:33 PM API Reference - OpenAI API

model string Optional Defaults to dall-e-2

The model to use for image generation. Only dall-e-2 is supported at this time.

n integer or null Optional Defaults to 1

The number of images to generate. Must be between 1 and 10. For dall-e-3 , only n=1 is
supported.

response_format string or null Optional Defaults to url

The format in which the generated images are returned. Must be one of url or b64_json .

size string or null Optional Defaults to 1024x1024

The size of the generated images. Must be one of 256x256 , 512x512 , or 1024x1024 .

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

Returns

Returns a list of image objects.

Example request curl Copy

1 curl https://api.openai.com/v1/images/variations \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -F image="@otter.png" \
4 -F n=2 \
5 -F size="1024x1024"

Response Copy

1 {
2 "created": 1589478378,
3 "data": [
4 {
5 "url": "https://..."
6 },
7 {
8 "url": "https://..."
9 }

https://platform.openai.com/docs/api-reference/chat/object 37/116
11/23/23, 7:33 PM API Reference - OpenAI API

10 ]
11 }

Models
List and describe the various models available in the API. You can refer to the Models
documentation to understand what models are available and the differences between
them.

The model object

Describes an OpenAI model offering that can be used with the API.

id string
The model identifier, which can be referenced in the API endpoints.

created integer
The Unix timestamp (in seconds) when the model was created.

object string
The object type, which is always "model".

owned_by string
The organization that owns the model.

The model object Copy

1 {
2 "id": "davinci",
3 "object": "model",
4 "created": 1686935002,
5 "owned_by": "openai"
6 }

https://platform.openai.com/docs/api-reference/chat/object 38/116
11/23/23, 7:33 PM API Reference - OpenAI API

List models
GET https://api.openai.com/v1/models

Lists the currently available models, and provides basic information about each one
such as the owner and availability.

Returns

A list of model objects.

Example request curl Copy

1 curl https://api.openai.com/v1/models \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "model-id-0",
6 "object": "model",
7 "created": 1686935002,
8 "owned_by": "organization-owner"
9 },
10 {
11 "id": "model-id-1",
12 "object": "model",
13 "created": 1686935002,
14 "owned_by": "organization-owner",
15 },
16 {
17 "id": "model-id-2",
18 "object": "model",
19 "created": 1686935002,
20 "owned_by": "openai"
21 },
22 ],

https://platform.openai.com/docs/api-reference/chat/object 39/116
11/23/23, 7:33 PM API Reference - OpenAI API

23 "object": "list"
24 }

Retrieve model
GET https://api.openai.com/v1/models/{model}

Retrieves a model instance, providing basic information about the model such as the
owner and permissioning.

Path parameters

model string Required

The ID of the model to use for this request

Returns

The model object matching the specified ID.

Example request gpt-3.5-turbo-instruct curl Copy

1 curl https://api.openai.com/v1/models/gpt-3.5-turbo-instruct \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response gpt-3.5-turbo-instruct Copy

1 {
2 "id": "gpt-3.5-turbo-instruct",
3 "object": "model",
4 "created": 1686935002,
5 "owned_by": "openai"
6 }

https://platform.openai.com/docs/api-reference/chat/object 40/116
11/23/23, 7:33 PM API Reference - OpenAI API

Delete fine-tune model

DELETE https://api.openai.com/v1/models/{model}

Delete a fine-tuned model. You must have the Owner role in your organization to
delete a model.

Path parameters

model string Required

The model to delete

Returns

Deletion status.

Example request curl Copy

1 curl https://api.openai.com/v1/models/ft:gpt-3.5-turbo:acemeco:suffix:abc123
2 -X DELETE \
3 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "id": "ft:gpt-3.5-turbo:acemeco:suffix:abc123",
3 "object": "model",
4 "deleted": true
5 }

Moderations
Given a input text, outputs if the model classifies it as violating OpenAI's content policy.

https://platform.openai.com/docs/api-reference/chat/object 41/116
11/23/23, 7:33 PM API Reference - OpenAI API

Related guide: Moderations

The moderation object

Represents policy compliance report by OpenAI's content moderation model against
a given input.

id string
The unique identifier for the moderation request.

model string
The model used to generate the moderation results.

results array
A list of moderation objects.
Show properties

The moderation object Copy

1 {
2 "id": "modr-XXXXX",
3 "model": "text-moderation-005",
4 "results": [
5 {
6 "flagged": true,
7 "categories": {
8 "sexual": false,
9 "hate": false,
10 "harassment": false,
11 "self-harm": false,
12 "sexual/minors": false,
13 "hate/threatening": false,
14 "violence/graphic": false,
15 "self-harm/intent": false,
16 "self-harm/instructions": false,
17 "harassment/threatening": true,
18 "violence": true,
19 },
20 "category_scores": {
21 "sexual": 1.2282071e-06,
22 "hate": 0.010696256,

https://platform.openai.com/docs/api-reference/chat/object 42/116
11/23/23, 7:33 PM API Reference - OpenAI API

23 "harassment": 0.29842457,
24 "self-harm": 1.5236925e-08,
25 "sexual/minors": 5.7246268e-08,
26 "hate/threatening": 0.0060676364,
27 "violence/graphic": 4.435014e-06,
28 "self-harm/intent": 8.098441e-10,
29 "self-harm/instructions": 2.8498655e-11,
30 "harassment/threatening": 0.63055265,
31 "violence": 0.99011886,
32 }
33 }
34 ]
35 }

Create moderation
POST https://api.openai.com/v1/moderations

Classifies if text violates OpenAI's Content Policy

Request body

input string or array Required

The input text to classify

model string Optional Defaults to text-moderation-latest

Two content moderations models are available: text-moderation-stable and text-
moderation-latest .

The default is text-moderation-latest which will be automatically upgraded over time. This
ensures you are always using our most accurate model. If you use text-moderation-stable ,
we will provide advanced notice before updating the model. Accuracy of text-moderation-
stable may be slightly lower than for text-moderation-latest .

Returns

A moderation object.

https://platform.openai.com/docs/api-reference/chat/object 43/116
11/23/23, 7:33 PM API Reference - OpenAI API

Example request curl Copy

1 curl https://api.openai.com/v1/moderations \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "input": "I want to kill them."
6 }'

Response Copy

1 {
2 "id": "modr-XXXXX",
3 "model": "text-moderation-005",
4 "results": [
5 {
6 "flagged": true,
7 "categories": {
8 "sexual": false,
9 "hate": false,
10 "harassment": false,
11 "self-harm": false,
12 "sexual/minors": false,
13 "hate/threatening": false,
14 "violence/graphic": false,
15 "self-harm/intent": false,
16 "self-harm/instructions": false,
17 "harassment/threatening": true,
18 "violence": true,
19 },
20 "category_scores": {
21 "sexual": 1.2282071e-06,
22 "hate": 0.010696256,
23 "harassment": 0.29842457,
24 "self-harm": 1.5236925e-08,
25 "sexual/minors": 5.7246268e-08,
26 "hate/threatening": 0.0060676364,
27 "violence/graphic": 4.435014e-06,
28 "self-harm/intent": 8.098441e-10,
29 "self-harm/instructions": 2.8498655e-11,
30 "harassment/threatening": 0.63055265,
31 "violence": 0.99011886,
32 }
33 }
34 ]
35 }

https://platform.openai.com/docs/api-reference/chat/object 44/116
11/23/23, 7:33 PM API Reference - OpenAI API

Assistants Beta

Build assistants that can call models and use tools to perform tasks.

Get started with the Assistants API

The assistant object Beta

Represents an assistant that can call the model and use tools.

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always assistant .

created_at integer
The Unix timestamp (in seconds) for when the assistant was created.

name string or null

The name of the assistant. The maximum length is 256 characters.

description string or null

The description of the assistant. The maximum length is 512 characters.

model string
ID of the model to use. You can use the List models API to see all of your available models, or see
our Model overview for descriptions of them.

instructions string or null

The system instructions that the assistant uses. The maximum length is 32768 characters.

tools array
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 , retrieval , or function .
Show possible types

https://platform.openai.com/docs/api-reference/chat/object 45/116
11/23/23, 7:33 PM API Reference - OpenAI API

file_ids array
A list of file IDs attached to this assistant. There can be a maximum of 20 files attached to the
assistant. Files are ordered by their creation date in ascending order.

metadata map
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

The assistant object Copy

1 {
2 "id": "asst_abc123",
3 "object": "assistant",
4 "created_at": 1698984975,
5 "name": "Math Tutor",
6 "description": null,
7 "model": "gpt-4",
8 "instructions": "You are a personal math tutor. When asked a question, wri
9 "tools": [
10 {
11 "type": "code_interpreter"
12 }
13 ],
14 "file_ids": [],
15 "metadata": {}
16 }

Create assistant Beta

POST https://api.openai.com/v1/assistants

Create an assistant with a model and instructions.

Request body

model Required

https://platform.openai.com/docs/api-reference/chat/object 46/116
11/23/23, 7:33 PM API Reference - OpenAI API

ID of the model to use. You can use the List models API to see all of your available models, or see
our Model overview for descriptions of them.

name string or null Optional

The name of the assistant. The maximum length is 256 characters.

description string or null Optional

The description of the assistant. The maximum length is 512 characters.

instructions string or null Optional

The system instructions that the assistant uses. The maximum length is 32768 characters.

tools array Optional Defaults to []

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 , retrieval , or function .
Show possible types

file_ids array Optional Defaults to []

A list of file IDs attached to this assistant. There can be a maximum of 20 files attached to the
assistant. Files are ordered by their creation date in ascending order.

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

An assistant object.

Code Interpreter Files

Example request curl Copy

1 curl "https://api.openai.com/v1/assistants" \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "instructions": "You are a personal math tutor. When asked a question, w

https://platform.openai.com/docs/api-reference/chat/object 47/116
11/23/23, 7:33 PM API Reference - OpenAI API

7 "name": "Math Tutor",

8 "tools": [{"type": "code_interpreter"}],
9 "model": "gpt-4"
10 }'

Response Copy

1 {
2 "id": "asst_abc123",
3 "object": "assistant",
4 "created_at": 1698984975,
5 "name": "Math Tutor",
6 "description": null,
7 "model": "gpt-4",
8 "instructions": "You are a personal math tutor. When asked a question, wri
9 "tools": [
10 {
11 "type": "code_interpreter"
12 }
13 ],
14 "file_ids": [],
15 "metadata": {}
16 }

Retrieve assistant Beta

GET https://api.openai.com/v1/assistants/{assistant_id}

Retrieves an assistant.

Path parameters

assistant_id string Required

The ID of the assistant to retrieve.

Returns

https://platform.openai.com/docs/api-reference/chat/object 48/116
11/23/23, 7:33 PM API Reference - OpenAI API

The assistant object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "asst_abc123",
3 "object": "assistant",
4 "created_at": 1699009709,
5 "name": "HR Helper",
6 "description": null,
7 "model": "gpt-4",
8 "instructions": "You are an HR bot, and you have access to files to answer
9 "tools": [
10 {
11 "type": "retrieval"
12 }
13 ],
14 "file_ids": [
15 "file-abc123"
16 ],
17 "metadata": {}
18 }

Modify assistant Beta

POST https://api.openai.com/v1/assistants/{assistant_id}

Modifies an assistant.

Path parameters

https://platform.openai.com/docs/api-reference/chat/object 49/116
11/23/23, 7:33 PM API Reference - OpenAI API

assistant_id string Required

The ID of the assistant to modify.

Request body

model Optional
ID of the model to use. You can use the List models API to see all of your available models, or see
our Model overview for descriptions of them.

name string or null Optional

The name of the assistant. The maximum length is 256 characters.

description string or null Optional

The description of the assistant. The maximum length is 512 characters.

instructions string or null Optional

The system instructions that the assistant uses. The maximum length is 32768 characters.

tools array Optional Defaults to []

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 , retrieval , or function .
Show possible types

file_ids array Optional Defaults to []

A list of File IDs attached to this assistant. There can be a maximum of 20 files attached to the
assistant. Files are ordered by their creation date in ascending order. If a file was previosuly
attached to the list but does not show up in the list, it will be deleted from the assistant.

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

The modified assistant object.

https://platform.openai.com/docs/api-reference/chat/object 50/116
11/23/23, 7:33 PM API Reference - OpenAI API

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "instructions": "You are an HR bot, and you have access to files to an
7 "tools": [{"type": "retrieval"}],
8 "model": "gpt-4",
9 "file_ids": ["file-abc123", "file-abc456"]
10 }'

Response Copy

1 {
2 "id": "asst_abc123",
3 "object": "assistant",
4 "created_at": 1699009709,
5 "name": "HR Helper",
6 "description": null,
7 "model": "gpt-4",
8 "instructions": "You are an HR bot, and you have access to files to answer
9 "tools": [
10 {
11 "type": "retrieval"
12 }
13 ],
14 "file_ids": [
15 "file-abc123",
16 "file-abc456"
17 ],
18 "metadata": {}
19 }

Delete assistant Beta

DELETE https://api.openai.com/v1/assistants/{assistant_id}

Delete an assistant.

https://platform.openai.com/docs/api-reference/chat/object 51/116
11/23/23, 7:33 PM API Reference - OpenAI API

Path parameters

assistant_id string Required

The ID of the assistant to delete.

Returns

Deletion status

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -X DELETE

Response Copy

1 {
2 "id": "asst_abc123",
3 "object": "assistant.deleted",
4 "deleted": true
5 }

List assistants Beta

GET https://api.openai.com/v1/assistants

Returns a list of assistants.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

https://platform.openai.com/docs/api-reference/chat/object 52/116
11/23/23, 7:33 PM API Reference - OpenAI API

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent
call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of assistant objects.

Example request curl Copy

1 curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "asst_abc123",
6 "object": "assistant",
7 "created_at": 1698982736,
8 "name": "Coding Tutor",
9 "description": null,
10 "model": "gpt-4",
11 "instructions": "You are a helpful assistant designed to make me bette
12 "tools": [],
13 "file_ids": [],
14 "metadata": {}

https://platform.openai.com/docs/api-reference/chat/object 53/116
11/23/23, 7:33 PM API Reference - OpenAI API

15 },
16 {
17 "id": "asst_abc456",
18 "object": "assistant",
19 "created_at": 1698982718,
20 "name": "My Assistant",
21 "description": null,
22 "model": "gpt-4",
23 "instructions": "You are a helpful assistant designed to make me bette
24 "tools": [],
25 "file_ids": [],
26 "metadata": {}
27 },
28 {
29 "id": "asst_abc789",
30 "object": "assistant",
31 "created_at": 1698982643,
32 "name": null,
33 "description": null,
34 "model": "gpt-4",
35 "instructions": null,
36 "tools": [],
37 "file_ids": [],
38 "metadata": {}
39 }
40 ],
41 "first_id": "asst_abc123",
42 "last_id": "asst_abc789",
43 "has_more": false
44 }

The assistant file object Beta

A list of Files attached to an assistant .

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always assistant.file .

created_at integer

https://platform.openai.com/docs/api-reference/chat/object 54/116
11/23/23, 7:33 PM API Reference - OpenAI API

The Unix timestamp (in seconds) for when the assistant file was created.

assistant_id string
The assistant ID that the file is attached to.

The assistant file object Copy

1 {
2 "id": "file-abc123",
3 "object": "assistant.file",
4 "created_at": 1699055364,
5 "assistant_id": "asst_abc123"
6 }

Create assistant file Beta

POST https://api.openai.com/v1/assistants/{assistant_id}/files

Create an assistant file by attaching a File to an assistant.

Path parameters

assistant_id string Required

The ID of the assistant for which to create a File.

Request body

file_id string Required

A File ID (with purpose="assistants" ) that the assistant should use. Useful for tools like
retrieval and code_interpreter that can access files.

Returns

An assistant file object.

https://platform.openai.com/docs/api-reference/chat/object 55/116
11/23/23, 7:33 PM API Reference - OpenAI API

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123/files \
2 -H 'Authorization: Bearer $OPENAI_API_KEY"' \
3 -H 'Content-Type: application/json' \
4 -H 'OpenAI-Beta: assistants=v1' \
5 -d '{
6 "file_id": "file-abc123"
7 }'

Response Copy

1 {
2 "id": "file-abc123",
3 "object": "assistant.file",
4 "created_at": 1699055364,
5 "assistant_id": "asst_abc123"
6 }

Retrieve assistant file Beta

GET https://api.openai.com/v1/assistants/{assistant_id}/files/{file_id}

Retrieves an AssistantFile.

Path parameters

assistant_id string Required

The ID of the assistant who the file belongs to.

file_id string Required

The ID of the file we're getting.

Returns

The assistant file object matching the specified ID.

https://platform.openai.com/docs/api-reference/chat/object 56/116
11/23/23, 7:33 PM API Reference - OpenAI API

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \
2 -H 'Authorization: Bearer $OPENAI_API_KEY"' \
3 -H 'Content-Type: application/json' \
4 -H 'OpenAI-Beta: assistants=v1'

Response Copy

1 {
2 "id": "file-abc123",
3 "object": "assistant.file",
4 "created_at": 1699055364,
5 "assistant_id": "asst_abc123"
6 }

Delete assistant file Beta

DELETE https://api.openai.com/v1/assistants/{assistant_id}/files/{file_id}

Delete an assistant file.

Path parameters

assistant_id string Required

The ID of the assistant that the file belongs to.

file_id string Required

The ID of the file to delete.

Returns

Deletion status

Example request curl Copy

https://platform.openai.com/docs/api-reference/chat/object 57/116
11/23/23, 7:33 PM API Reference - OpenAI API

1 curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -X DELETE

Response Copy

1 {
2 id: "file-abc123",
3 object: "assistant.file.deleted",
4 deleted: true
5 }

List assistant files Beta

GET https://api.openai.com/v1/assistants/{assistant_id}/files

Returns a list of assistant files.

Path parameters

assistant_id string Required

The ID of the assistant the file belongs to.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent

https://platform.openai.com/docs/api-reference/chat/object 58/116
11/23/23, 7:33 PM API Reference - OpenAI API

call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of assistant file objects.

Example request curl Copy

1 curl https://api.openai.com/v1/assistants/asst_abc123/files \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "file-abc123",
6 "object": "assistant.file",
7 "created_at": 1699060412,
8 "assistant_id": "asst_abc123"
9 },
10 {
11 "id": "file-abc456",
12 "object": "assistant.file",
13 "created_at": 1699060412,
14 "assistant_id": "asst_abc123"
15 }
16 ],
17 "first_id": "file-abc123",
18 "last_id": "file-abc456",
19 "has_more": false
20 }

https://platform.openai.com/docs/api-reference/chat/object 59/116
11/23/23, 7:33 PM API Reference - OpenAI API

Threads Beta

Create threads that assistants can interact with.

Related guide: Assistants

The thread object Beta

Represents a thread that contains messages.

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always thread .

created_at integer
The Unix timestamp (in seconds) for when the thread was created.

metadata map
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

The thread object Copy

1 {
2 "id": "thread_abc123",
3 "object": "thread",
4 "created_at": 1698107661,
5 "metadata": {}
6 }

Create thread Beta

https://platform.openai.com/docs/api-reference/chat/object 60/116
11/23/23, 7:33 PM API Reference - OpenAI API

POST https://api.openai.com/v1/threads

Create a thread.

Request body

messages array Optional

A list of messages to start the thread with.
Show properties

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

A thread object.

Empty Messages

Example request curl Copy

1 curl https://api.openai.com/v1/threads \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d ''

Response Copy

1 {
2 "id": "thread_abc123",
3 "object": "thread",
4 "created_at": 1699012949,
5 "metadata": {}
6 }

https://platform.openai.com/docs/api-reference/chat/object 61/116
11/23/23, 7:33 PM API Reference - OpenAI API

Retrieve thread Beta

GET https://api.openai.com/v1/threads/{thread_id}

Retrieves a thread.

Path parameters

thread_id string Required

The ID of the thread to retrieve.

Returns

The thread object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "thread_abc123",
3 "object": "thread",
4 "created_at": 1699014083,
5 "metadata": {}
6 }

Modify thread Beta

POST https://api.openai.com/v1/threads/{thread_id}

https://platform.openai.com/docs/api-reference/chat/object 62/116
11/23/23, 7:33 PM API Reference - OpenAI API

Modifies a thread.

Path parameters

thread_id string Required

The ID of the thread to modify. Only the metadata can be modified.

Request body

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

The modified thread object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "metadata": {
7 "modified": "true",
8 "user": "abc123"
9 }
10 }'

Response Copy

1 {
2 "id": "thread_abc123",
3 "object": "thread",
4 "created_at": 1699014083,
5 "metadata": {
6 "modified": "true",
7 "user": "abc123"

https://platform.openai.com/docs/api-reference/chat/object 63/116
11/23/23, 7:33 PM API Reference - OpenAI API

8 }
9 }

Delete thread Beta

DELETE https://api.openai.com/v1/threads/{thread_id}

Delete a thread.

Path parameters

thread_id string Required

The ID of the thread to delete.

Returns

Deletion status

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -X DELETE

Response Copy

1 {
2 "id": "thread_abc123",
3 "object": "thread.deleted",
4 "deleted": true
5 }

https://platform.openai.com/docs/api-reference/chat/object 64/116
11/23/23, 7:33 PM API Reference - OpenAI API

Messages Beta

Create messages within threads

Related guide: Assistants

The message object Beta

Represents a message within a thread.

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always thread.message .

created_at integer
The Unix timestamp (in seconds) for when the message was created.

thread_id string
The thread ID that this message belongs to.

role string
The entity that produced the message. One of user or assistant .

content array
The content of the message in array of text and/or images.
Show possible types

assistant_id string or null

If applicable, the ID of the assistant that authored this message.

run_id string or null

If applicable, the ID of the run associated with the authoring of this message.

file_ids array

https://platform.openai.com/docs/api-reference/chat/object 65/116
11/23/23, 7:33 PM API Reference - OpenAI API

A list of file IDs that the assistant should use. Useful for tools like retrieval and code_interpreter
that can access files. A maximum of 10 files can be attached to a message.

metadata map
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

The message object Copy

1 {
2 "id": "msg_abc123",
3 "object": "thread.message",
4 "created_at": 1698983503,
5 "thread_id": "thread_abc123",
6 "role": "assistant",
7 "content": [
8 {
9 "type": "text",
10 "text": {
11 "value": "Hi! How can I help you today?",
12 "annotations": []
13 }
14 }
15 ],
16 "file_ids": [],
17 "assistant_id": "asst_abc123",
18 "run_id": "run_abc123",
19 "metadata": {}
20 }

Create message Beta

POST https://api.openai.com/v1/threads/{thread_id}/messages

Create a message.

Path parameters

thread_id string Required

https://platform.openai.com/docs/api-reference/chat/object 66/116
11/23/23, 7:33 PM API Reference - OpenAI API

The ID of the thread to create a message for.

Request body

role string Required

The role of the entity that is creating the message. Currently only user is supported.

content string Required

The content of the message.

file_ids array Optional Defaults to []

A list of File IDs that the message should use. There can be a maximum of 10 files attached to a
message. Useful for tools like retrieval and code_interpreter that can access and use
files.

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

A message object.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/messages \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "role": "user",
7 "content": "How does AI work? Explain it in simple terms."
8 }'

Response Copy

1 {
2 "id": "msg_abc123",
3 "object": "thread.message",
https://platform.openai.com/docs/api-reference/chat/object 67/116
11/23/23, 7:33 PM API Reference - OpenAI API

4 "created_at": 1699017614,
5 "thread_id": "thread_abc123",
6 "role": "user",
7 "content": [
8 {
9 "type": "text",
10 "text": {
11 "value": "How does AI work? Explain it in simple terms.",
12 "annotations": []
13 }
14 }
15 ],
16 "file_ids": [],
17 "assistant_id": null,
18 "run_id": null,
19 "metadata": {}
20 }

Retrieve message Beta

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

Retrieve a message.

Path parameters

thread_id string Required

The ID of the thread to which this message belongs.

message_id string Required

The ID of the message to retrieve.

Returns

The message object matching the specified ID.

Example request curl Copy

https://platform.openai.com/docs/api-reference/chat/object 68/116
11/23/23, 7:33 PM API Reference - OpenAI API

1 curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "msg_abc123",
3 "object": "thread.message",
4 "created_at": 1699017614,
5 "thread_id": "thread_abc123",
6 "role": "user",
7 "content": [
8 {
9 "type": "text",
10 "text": {
11 "value": "How does AI work? Explain it in simple terms.",
12 "annotations": []
13 }
14 }
15 ],
16 "file_ids": [],
17 "assistant_id": null,
18 "run_id": null,
19 "metadata": {}
20 }

Modify message Beta

POST https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

Modifies a message.

Path parameters

thread_id string Required

The ID of the thread to which this message belongs.

message_id string Required

https://platform.openai.com/docs/api-reference/chat/object 69/116
11/23/23, 7:33 PM API Reference - OpenAI API

The ID of the message to modify.

Request body

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

The modified message object.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "metadata": {
7 "modified": "true",
8 "user": "abc123"
9 }
10 }'

Response Copy

1 {
2 "id": "msg_abc123",
3 "object": "thread.message",
4 "created_at": 1699017614,
5 "thread_id": "thread_abc123",
6 "role": "user",
7 "content": [
8 {
9 "type": "text",
10 "text": {
11 "value": "How does AI work? Explain it in simple terms.",
12 "annotations": []

https://platform.openai.com/docs/api-reference/chat/object 70/116
11/23/23, 7:33 PM API Reference - OpenAI API

13 }
14 }
15 ],
16 "file_ids": [],
17 "assistant_id": null,
18 "run_id": null,
19 "metadata": {
20 "modified": "true",
21 "user": "abc123"
22 }
23 }

List messages Beta

GET https://api.openai.com/v1/threads/{thread_id}/messages

Returns a list of messages for a given thread.

Path parameters

thread_id string Required

The ID of the thread the messages belong to.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent
call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

https://platform.openai.com/docs/api-reference/chat/object 71/116
11/23/23, 7:33 PM API Reference - OpenAI API

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of message objects.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/messages \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "msg_abc123",
6 "object": "thread.message",
7 "created_at": 1699016383,
8 "thread_id": "thread_abc123",
9 "role": "user",
10 "content": [
11 {
12 "type": "text",
13 "text": {
14 "value": "How does AI work? Explain it in simple terms.",
15 "annotations": []
16 }
17 }
18 ],
19 "file_ids": [],
20 "assistant_id": null,
21 "run_id": null,
22 "metadata": {}
23 },
24 {
25 "id": "msg_abc456",
26 "object": "thread.message",

https://platform.openai.com/docs/api-reference/chat/object 72/116
11/23/23, 7:33 PM API Reference - OpenAI API

27 "created_at": 1699016383,
28 "thread_id": "thread_abc123",
29 "role": "user",
30 "content": [
31 {
32 "type": "text",
33 "text": {
34 "value": "Hello, what is AI?",
35 "annotations": []
36 }
37 }
38 ],
39 "file_ids": [
40 "file-abc123"
41 ],
42 "assistant_id": null,
43 "run_id": null,
44 "metadata": {}
45 }
46 ],
47 "first_id": "msg_abc123",
48 "last_id": "msg_abc456",
49 "has_more": false
50 }

The message file object Beta

A list of files attached to a message .

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always thread.message.file .

created_at integer
The Unix timestamp (in seconds) for when the message file was created.

message_id string
The ID of the message that the File is attached to.

https://platform.openai.com/docs/api-reference/chat/object 73/116
11/23/23, 7:33 PM API Reference - OpenAI API

The message file object Copy

1 {
2 "id": "file-abc123",
3 "object": "thread.message.file",
4 "created_at": 1698107661,
5 "message_id": "message_QLoItBbqwyAJEzlTy4y9kOMM",
6 "file_id": "file-abc123"
7 }

Retrieve message file Beta

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/fil
es/{file_id}

Retrieves a message file.

Path parameters

thread_id string Required

The ID of the thread to which the message and File belong.

message_id string Required

The ID of the message the file belongs to.

file_id string Required

The ID of the file being retrieved.

Returns

The message file object.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/file
2 -H "Authorization: Bearer $OPENAI_API_KEY" \

https://platform.openai.com/docs/api-reference/chat/object 74/116
11/23/23, 7:33 PM API Reference - OpenAI API

3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "file-abc123",
3 "object": "thread.message.file",
4 "created_at": 1699061776,
5 "message_id": "msg_abc123"
6 }

List message files Beta

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/fil
es

Returns a list of message files.

Path parameters

thread_id string Required

The ID of the thread that the message and files belong to.

message_id string Required

The ID of the message that the files belongs to.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

https://platform.openai.com/docs/api-reference/chat/object 75/116
11/23/23, 7:33 PM API Reference - OpenAI API

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent
call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of message file objects.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/file
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "file-abc123",
6 "object": "thread.message.file",
7 "created_at": 1699061776,
8 "message_id": "msg_abc123"
9 },
10 {
11 "id": "file-abc123",
12 "object": "thread.message.file",
13 "created_at": 1699061776,
14 "message_id": "msg_abc123"
15 }
16 ],
17 "first_id": "file-abc123",
18 "last_id": "file-abc123",

https://platform.openai.com/docs/api-reference/chat/object 76/116
11/23/23, 7:33 PM API Reference - OpenAI API

19 "has_more": false
20 }

Runs Beta

Represents an execution run on a thread.

Related guide: Assistants

The run object Beta

Represents an execution run on a thread.

id string
The identifier, which can be referenced in API endpoints.

object string
The object type, which is always thread.run .

created_at integer
The Unix timestamp (in seconds) for when the run was created.

thread_id string
The ID of the thread that was executed on as a part of this run.

assistant_id string
The ID of the assistant used for execution of this run.

status string
The status of the run, which can be either queued , in_progress , requires_action ,
cancelling , cancelled , failed , completed , or expired .

required_action object or null

Details on the action required to continue the run. Will be null if no action is required.
Show properties

https://platform.openai.com/docs/api-reference/chat/object 77/116
11/23/23, 7:33 PM API Reference - OpenAI API

last_error object or null

The last error associated with this run. Will be null if there are no errors.
Show properties

expires_at integer
The Unix timestamp (in seconds) for when the run will expire.

started_at integer or null

The Unix timestamp (in seconds) for when the run was started.

cancelled_at integer or null

The Unix timestamp (in seconds) for when the run was cancelled.

failed_at integer or null

The Unix timestamp (in seconds) for when the run failed.

completed_at integer or null

The Unix timestamp (in seconds) for when the run was completed.

model string
The model that the assistant used for this run.

instructions string
The instructions that the assistant used for this run.

tools array
The list of tools that the assistant used for this run.
Show possible types

file_ids array
The list of File IDs the assistant used for this run.

metadata map
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

The run object Copy

https://platform.openai.com/docs/api-reference/chat/object 78/116
11/23/23, 7:33 PM API Reference - OpenAI API

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1698107661,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "completed",
8 "started_at": 1699073476,
9 "expires_at": null,
10 "cancelled_at": null,
11 "failed_at": null,
12 "completed_at": 1699073498,
13 "last_error": null,
14 "model": "gpt-4",
15 "instructions": null,
16 "tools": [{"type": "retrieval"}, {"type": "code_interpreter"}],
17 "file_ids": [],
18 "metadata": {}
19 }

Create run Beta

POST https://api.openai.com/v1/threads/{thread_id}/runs

Create a run.

Path parameters

thread_id string Required

The ID of the thread to run.

Request body

assistant_id string Required

The ID of the assistant to use to execute this run.

model string or null Optional

The ID of the Model 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.

https://platform.openai.com/docs/api-reference/chat/object 79/116
11/23/23, 7:33 PM API Reference - OpenAI API

instructions string or null Optional

Override the default system message of the assistant. This is useful for modifying the behavior on
a per-run basis.

tools array or null Optional

Override the tools the assistant can use for this run. This is useful for modifying the behavior on a
per-run basis.
Show possible types

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

A run object.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "assistant_id": "asst_abc123"
7 }'

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699063290,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "queued",
8 "started_at": 1699063290,
9 "expires_at": null,
10 "cancelled_at": null,
11 "failed_at": null,

https://platform.openai.com/docs/api-reference/chat/object 80/116
11/23/23, 7:33 PM API Reference - OpenAI API

12 "completed_at": 1699063291,
13 "last_error": null,
14 "model": "gpt-4",
15 "instructions": null,
16 "tools": [
17 {
18 "type": "code_interpreter"
19 }
20 ],
21 "file_ids": [
22 "file-abc123",
23 "file-abc456"
24 ],
25 "metadata": {}
26 }

Retrieve run Beta

GET https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

Retrieves a run.

Path parameters

thread_id string Required

The ID of the thread that was run.

run_id string Required

The ID of the run to retrieve.

Returns

The run object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \

https://platform.openai.com/docs/api-reference/chat/object 81/116
11/23/23, 7:33 PM API Reference - OpenAI API

3 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699075072,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "completed",
8 "started_at": 1699075072,
9 "expires_at": null,
10 "cancelled_at": null,
11 "failed_at": null,
12 "completed_at": 1699075073,
13 "last_error": null,
14 "model": "gpt-3.5-turbo",
15 "instructions": null,
16 "tools": [
17 {
18 "type": "code_interpreter"
19 }
20 ],
21 "file_ids": [
22 "file-abc123",
23 "file-abc456"
24 ],
25 "metadata": {}
26 }

Modify run Beta

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

Modifies a run.

Path parameters

thread_id string Required

The ID of the thread that was run.

https://platform.openai.com/docs/api-reference/chat/object 82/116
11/23/23, 7:33 PM API Reference - OpenAI API

run_id string Required

The ID of the run to modify.

Request body

metadata map Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

The modified run object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "metadata": {
7 "user_id": "user_abc123"
8 }
9 }'

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699075072,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "completed",
8 "started_at": 1699075072,
9 "expires_at": null,
10 "cancelled_at": null,
11 "failed_at": null,
12 "completed_at": 1699075073,
13 "last_error": null,
https://platform.openai.com/docs/api-reference/chat/object 83/116
11/23/23, 7:33 PM API Reference - OpenAI API

14 "model": "gpt-3.5-turbo",
15 "instructions": null,
16 "tools": [
17 {
18 "type": "code_interpreter"
19 }
20 ],
21 "file_ids": [
22 "file-abc123",
23 "file-abc456"
24 ],
25 "metadata": {
26 "user_id": "user_abc123"
27 }
28 }

List runs Beta

GET https://api.openai.com/v1/threads/{thread_id}/runs

Returns a list of runs belonging to a thread.

Path parameters

thread_id string Required

The ID of the thread the run belongs to.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent
https://platform.openai.com/docs/api-reference/chat/object 84/116
11/23/23, 7:33 PM API Reference - OpenAI API

call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of run objects.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "run_abc123",
6 "object": "thread.run",
7 "created_at": 1699075072,
8 "assistant_id": "asst_abc123",
9 "thread_id": "thread_abc123",
10 "status": "completed",
11 "started_at": 1699075072,
12 "expires_at": null,
13 "cancelled_at": null,
14 "failed_at": null,
15 "completed_at": 1699075073,
16 "last_error": null,
17 "model": "gpt-3.5-turbo",
18 "instructions": null,
19 "tools": [
20 {
21 "type": "code_interpreter"
22 }
23 ],
https://platform.openai.com/docs/api-reference/chat/object 85/116
11/23/23, 7:33 PM API Reference - OpenAI API

24 "file_ids": [
25 "file-abc123",
26 "file-abc456"
27 ],
28 "metadata": {}
29 },
30 {
31 "id": "run_abc456",
32 "object": "thread.run",
33 "created_at": 1699063290,
34 "assistant_id": "asst_abc123",
35 "thread_id": "thread_abc123",
36 "status": "completed",
37 "started_at": 1699063290,
38 "expires_at": null,
39 "cancelled_at": null,
40 "failed_at": null,
41 "completed_at": 1699063291,
42 "last_error": null,
43 "model": "gpt-3.5-turbo",
44 "instructions": null,
45 "tools": [
46 {
47 "type": "code_interpreter"
48 }
49 ],
50 "file_ids": [
51 "file-abc123",
52 "file-abc456"
53 ],
54 "metadata": {}
55 }
56 ],
57 "first_id": "run_abc123",
58 "last_id": "run_abc456",
59 "has_more": false
60 }

Submit tool outputs to run Beta

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_too
l_outputs

https://platform.openai.com/docs/api-reference/chat/object 86/116
11/23/23, 7:33 PM API Reference - OpenAI API

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.

Path parameters

thread_id string Required

The ID of the thread to which this run belongs.

run_id string Required

The ID of the run that requires the tool output submission.

Request body

tool_outputs array Required

A list of tools for which the outputs are being submitted.
Show properties

Returns

The modified run object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/submit_
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "tool_outputs": [
7 {
8 "tool_call_id": "call_abc123",
9 "output": "28C"
10 }
11 ]
12 }'

https://platform.openai.com/docs/api-reference/chat/object 87/116
11/23/23, 7:33 PM API Reference - OpenAI API

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699075592,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "queued",
8 "started_at": 1699075592,
9 "expires_at": 1699076192,
10 "cancelled_at": null,
11 "failed_at": null,
12 "completed_at": null,
13 "last_error": null,
14 "model": "gpt-4",
15 "instructions": "You tell the weather.",
16 "tools": [
17 {
18 "type": "function",
19 "function": {
20 "name": "get_weather",
21 "description": "Determine weather in my location",
22 "parameters": {
23 "type": "object",
24 "properties": {
25 "location": {
26 "type": "string",
27 "description": "The city and state e.g. San Francisco, CA"
28 },
29 "unit": {
30 "type": "string",
31 "enum": [
32 "c",
33 "f"
34 ]
35 }
36 },
37 "required": [
38 "location"
39 ]
40 }
41 }
42 }
43 ],
44 "file_ids": [],
45 "metadata": {}
46 }

https://platform.openai.com/docs/api-reference/chat/object 88/116
11/23/23, 7:33 PM API Reference - OpenAI API

Cancel a run Beta

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/cancel

Cancels a run that is in_progress .

Path parameters

thread_id string Required

The ID of the thread to which this run belongs.

run_id string Required

The ID of the run to cancel.

Returns

The modified run object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "OpenAI-Beta: assistants=v1" \
4 -X POST

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699076126,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "cancelling",
8 "started_at": 1699076126,
9 "expires_at": 1699076726,
10 "cancelled_at": null,
11 "failed_at": null,

https://platform.openai.com/docs/api-reference/chat/object 89/116
11/23/23, 7:33 PM API Reference - OpenAI API

12 "completed_at": null,
13 "last_error": null,
14 "model": "gpt-4",
15 "instructions": "You summarize books.",
16 "tools": [
17 {
18 "type": "retrieval"
19 }
20 ],
21 "file_ids": [],
22 "metadata": {}
23 }

Create thread and run Beta

POST https://api.openai.com/v1/threads/runs

Create a thread and run it in one request.

Request body

assistant_id string Required

The ID of the assistant to use to execute this run.

thread object Optional

Show properties

model string or null Optional

The ID of the Model 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.

instructions string or null Optional

Override the default system message of the assistant. This is useful for modifying the behavior on
a per-run basis.

tools array or null Optional

Override the tools the assistant can use for this run. This is useful for modifying the behavior on a
per-run basis.

metadata map Optional

https://platform.openai.com/docs/api-reference/chat/object 90/116
11/23/23, 7:33 PM API Reference - OpenAI API

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

Returns

A run object.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/runs \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1" \
5 -d '{
6 "assistant_id": "asst_abc123",
7 "thread": {
8 "messages": [
9 {"role": "user", "content": "Explain deep learning to a 5 year old
10 ]
11 }
12 }'

Response Copy

1 {
2 "id": "run_abc123",
3 "object": "thread.run",
4 "created_at": 1699076792,
5 "assistant_id": "asst_abc123",
6 "thread_id": "thread_abc123",
7 "status": "queued",
8 "started_at": null,
9 "expires_at": 1699077392,
10 "cancelled_at": null,
11 "failed_at": null,
12 "completed_at": null,
13 "last_error": null,
14 "model": "gpt-4",
15 "instructions": "You are a helpful assistant.",
16 "tools": [],
17 "file_ids": [],

https://platform.openai.com/docs/api-reference/chat/object 91/116
11/23/23, 7:33 PM API Reference - OpenAI API

18 "metadata": {}
19 }

The run step object Beta

Represents a step in execution of a run.

id string
The identifier of the run step, which can be referenced in API endpoints.

object string
The object type, which is always `thread.run.step``.

created_at integer
The Unix timestamp (in seconds) for when the run step was created.

assistant_id string
The ID of the assistant associated with the run step.

thread_id string
The ID of the thread that was run.

run_id string
The ID of the run that this run step is a part of.

type string
The type of run step, which can be either message_creation or tool_calls .

status string
The status of the run step, which can be either in_progress , cancelled , failed ,
completed , or expired .

step_details object
The details of the run step.
Show possible types

last_error object or null

The last error associated with this run step. Will be null if there are no errors.

https://platform.openai.com/docs/api-reference/chat/object 92/116
11/23/23, 7:33 PM API Reference - OpenAI API

Show properties

expired_at integer or null

The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the
parent run is expired.

cancelled_at integer or null

The Unix timestamp (in seconds) for when the run step was cancelled.

failed_at integer or null

The Unix timestamp (in seconds) for when the run step failed.

completed_at integer or null

The Unix timestamp (in seconds) for when the run step completed.

metadata map
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
additional information about the object in a structured format. Keys can be a maximum of 64
characters long and values can be a maxium of 512 characters long.

The run step object Copy

1 {
2 "id": "step_abc123",
3 "object": "thread.run.step",
4 "created_at": 1699063291,
5 "run_id": "run_abc123",
6 "assistant_id": "asst_abc123",
7 "thread_id": "thread_abc123",
8 "type": "message_creation",
9 "status": "completed",
10 "cancelled_at": null,
11 "completed_at": 1699063291,
12 "expired_at": null,
13 "failed_at": null,
14 "last_error": null,
15 "step_details": {
16 "type": "message_creation",
17 "message_creation": {
18 "message_id": "msg_abc123"
19 }
20 }
21 }

https://platform.openai.com/docs/api-reference/chat/object 93/116
11/23/23, 7:33 PM API Reference - OpenAI API

Retrieve run step Beta

GET https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps/{step
_id}

Retrieves a run step.

Path parameters

thread_id string Required

The ID of the thread to which the run and run step belongs.

run_id string Required

The ID of the run to which the run step belongs.

step_id string Required

The ID of the run step to retrieve.

Returns

The run step object matching the specified ID.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/st
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "id": "step_abc123",
3 "object": "thread.run.step",
4 "created_at": 1699063291,
5 "run_id": "run_abc123",
6 "assistant_id": "asst_abc123",

https://platform.openai.com/docs/api-reference/chat/object 94/116
11/23/23, 7:33 PM API Reference - OpenAI API

7 "thread_id": "thread_abc123",
8 "type": "message_creation",
9 "status": "completed",
10 "cancelled_at": null,
11 "completed_at": 1699063291,
12 "expired_at": null,
13 "failed_at": null,
14 "last_error": null,
15 "step_details": {
16 "type": "message_creation",
17 "message_creation": {
18 "message_id": "msg_abc123"
19 }
20 }
21 }

List run steps Beta

GET https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/steps

Returns a list of run steps belonging to a run.

Path parameters

thread_id string Required

The ID of the thread the run and run steps belong to.

run_id string Required

The ID of the run the run steps belong to.

Query parameters

limit integer Optional Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.

order string Optional Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc
for descending order.

https://platform.openai.com/docs/api-reference/chat/object 95/116
11/23/23, 7:33 PM API Reference - OpenAI API

after string Optional

A cursor for use in pagination. 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 obj_foo, your subsequent
call can include after=obj_foo in order to fetch the next page of the list.

before string Optional

A cursor for use in pagination. before 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 obj_foo, your subsequent
call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of run step objects.

Example request curl Copy

1 curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \
2 -H "Authorization: Bearer $OPENAI_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "OpenAI-Beta: assistants=v1"

Response Copy

1 {
2 "object": "list",
3 "data": [
4 {
5 "id": "step_abc123",
6 "object": "thread.run.step",
7 "created_at": 1699063291,
8 "run_id": "run_abc123",
9 "assistant_id": "asst_abc123",
10 "thread_id": "thread_abc123",
11 "type": "message_creation",
12 "status": "completed",
13 "cancelled_at": null,
14 "completed_at": 1699063291,
15 "expired_at": null,
16 "failed_at": null,
17 "last_error": null,
18 "step_details": {

https://platform.openai.com/docs/api-reference/chat/object 96/116
11/23/23, 7:33 PM API Reference - OpenAI API

19 "type": "message_creation",
20 "message_creation": {
21 "message_id": "msg_abc123"
22 }
23 }
24 }
25 ],
26 "first_id": "step_abc123",
27 "last_id": "step_abc456",
28 "has_more": false
29 }

Completions Legacy

Given a prompt, the model will return one or more predicted completions along with the
probabilities of alternative tokens at each position. Most developer should use our Chat
Completions API to leverage our best and newest models. Most models that support the
legacy Completions endpoint will be shut off on January 4th, 2024.

The completion object Legacy

Represents a completion response from the API. Note: both the streamed and non-
streamed response objects share the same shape (unlike the chat endpoint).

id string
A unique identifier for the completion.

choices array
The list of completion choices the model generated for the input prompt.
Show properties

created integer
The Unix timestamp (in seconds) of when the completion was created.

model string
The model used for completion.

https://platform.openai.com/docs/api-reference/chat/object 97/116
11/23/23, 7:33 PM API Reference - OpenAI API

system_fingerprint string
This fingerprint represents the backend configuration that the model runs with.

Can be used in conjunction with the seed request parameter to understand when backend
changes have been made that might impact determinism.

object string
The object type, which is always "text_completion"

usage object
Usage statistics for the completion request.
Show properties

The completion object Copy

1 {
2 "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
3 "object": "text_completion",
4 "created": 1589478378,
5 "model": "gpt-3.5-turbo",
6 "choices": [
7 {
8 "text": "\n\nThis is indeed a test",
9 "index": 0,
10 "logprobs": null,
11 "finish_reason": "length"
12 }
13 ],
14 "usage": {
15 "prompt_tokens": 5,
16 "completion_tokens": 7,
17 "total_tokens": 12
18 }
19 }

Create completion Legacy

POST https://api.openai.com/v1/completions

Creates a completion for the provided prompt and parameters.

https://platform.openai.com/docs/api-reference/chat/object 98/116
11/23/23, 7:33 PM API Reference - OpenAI API

Request body

model string Required

ID of the model to use. You can use the List models API to see all of your available models, or see
our Model overview for descriptions of them.

prompt string or array Required

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.

best_of integer or null Optional Defaults to 1

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 .

echo boolean or null Optional Defaults to false

Echo back the prompt in addition to the completion

frequency_penalty number or null Optional Defaults to 0

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.

logit_bias map Optional Defaults to null

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 (which works for both GPT-
2 and GPT-3) 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.

logprobs integer or null Optional Defaults to null

Include the log probabilities on the logprobs most likely 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
https://platform.openai.com/docs/api-reference/chat/object 99/116
11/23/23, 7:33 PM API Reference - OpenAI API

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.

max_tokens integer or null Optional Defaults to 16

The maximum number of tokens to generate in the completion.

The token count of your prompt plus max_tokens cannot exceed the model's context length.
Example Python code for counting tokens.

n integer or null Optional Defaults to 1

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 .

presence_penalty number or null Optional Defaults to 0

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.

seed integer or null Optional

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.

stop string / array / null Optional Defaults to null

Up to 4 sequences where the API will stop generating further tokens. The returned text will not
contain the stop sequence.

stream boolean or null Optional Defaults to false

Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent
events as they become available, with the stream terminated by a data: [DONE] message.
Example Python code.

suffix string or null Optional Defaults to null

The suffix that comes after a completion of inserted text.

temperature number or null Optional Defaults to 1

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.

https://platform.openai.com/docs/api-reference/chat/object 100/116
11/23/23, 7:33 PM API Reference - OpenAI API

top_p number or null Optional Defaults to 1

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.

user string Optional

A unique identifier representing your end-user, which can help OpenAI to monitor and detect
abuse. Learn more.

Returns

Returns a completion object, or a sequence of completion objects if the request is streamed.

No streaming Streaming

Example request gpt-3.5-turbo-instruct curl Copy

1 curl https://api.openai.com/v1/completions \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "model": "gpt-3.5-turbo-instruct",
6 "prompt": "Say this is a test",
7 "max_tokens": 7,
8 "temperature": 0
9 }'

Response gpt-3.5-turbo-instruct Copy

1 {
2 "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
3 "object": "text_completion",
4 "created": 1589478378,
5 "model": "gpt-3.5-turbo-instruct",
6 "system_fingerprint": "fp_44709d6fcb",
7 "choices": [
8 {
9 "text": "\n\nThis is indeed a test",
10 "index": 0,
11 "logprobs": null,

https://platform.openai.com/docs/api-reference/chat/object 101/116
11/23/23, 7:33 PM API Reference - OpenAI API

12 "finish_reason": "length"
13 }
14 ],
15 "usage": {
16 "prompt_tokens": 5,
17 "completion_tokens": 7,
18 "total_tokens": 12
19 }
20 }

Edits Deprecated

Given a prompt and an instruction, the model will return an edited version of the prompt.
The Edits endpoint is deprecated will be shut off on January 4th, 2024.

The edit object Deprecated

choices array
A list of edit choices. Can be more than one if n is greater than 1.
Show properties

object string
The object type, which is always edit .

created integer
The Unix timestamp (in seconds) of when the edit was created.

usage object
Usage statistics for the completion request.
Show properties

The edit object Copy

1 {
2 "object": "edit",
3 "created": 1589478378,

https://platform.openai.com/docs/api-reference/chat/object 102/116
11/23/23, 7:33 PM API Reference - OpenAI API

4 "choices": [
5 {
6 "text": "What day of the week is it?",
7 "index": 0,
8 }
9 ],
10 "usage": {
11 "prompt_tokens": 25,
12 "completion_tokens": 32,
13 "total_tokens": 57
14 }
15 }

Create edit Deprecated

POST https://api.openai.com/v1/edits

Creates a new edit for the provided input, instruction, and parameters.

Request body

instruction string Required

The instruction that tells the model how to edit the prompt.

model string Required

ID of the model to use. You can use the text-davinci-edit-001 or code-davinci-edit-
001 model with this endpoint.

input string or null Optional Defaults to ''

The input text to use as a starting point for the edit.

n integer or null Optional Defaults to 1

How many edits to generate for the input and instruction.

temperature number or null Optional Defaults to 1

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.

top_p number or null Optional Defaults to 1

https://platform.openai.com/docs/api-reference/chat/object 103/116
11/23/23, 7:33 PM API Reference - OpenAI API

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.

Returns

Returns an edit object.

Example request text-davinci-edit-001 curl Copy

1 curl https://api.openai.com/v1/edits \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "model": "text-davinci-edit-001",
6 "input": "What day of the wek is it?",
7 "instruction": "Fix the spelling mistakes"
8 }'

Response Copy

1 {
2 "object": "edit",
3 "created": 1589478378,
4 "choices": [
5 {
6 "text": "What day of the week is it?",
7 "index": 0,
8 }
9 ],
10 "usage": {
11 "prompt_tokens": 25,
12 "completion_tokens": 32,
13 "total_tokens": 57
14 }
15 }

https://platform.openai.com/docs/api-reference/chat/object 104/116
11/23/23, 7:33 PM API Reference - OpenAI API

Fine-tunes Deprecated

Manage fine-tuning jobs to tailor a model to your specific training data. The updated Fine-
tuning endpoint offers more capabilites and newer models.

The Fine-tunes endpoint will be shut off on January 4th, 2024.

The fine-tune object Deprecated

The FineTune object represents a legacy fine-tune job that has been created
through the API.

id string
The object identifier, which can be referenced in the API endpoints.

created_at integer
The Unix timestamp (in seconds) for when the fine-tuning job was created.

events array
The list of events that have been observed in the lifecycle of the FineTune job.
Show properties

fine_tuned_model string or null

The name of the fine-tuned model that is being created.

hyperparams object
The hyperparameters used for the fine-tuning job. See the fine-tuning guide for more details.
Show properties

model string
The base model that is being fine-tuned.

object string
The object type, which is always "fine-tune".

organization_id string

https://platform.openai.com/docs/api-reference/chat/object 105/116
11/23/23, 7:33 PM API Reference - OpenAI API

The organization that owns the fine-tuning job.

result_files array
The compiled results files for the fine-tuning job.

status string
The current status of the fine-tuning job, which can be either created , running ,
succeeded , failed , or cancelled .

training_files array
The list of files used for training.

updated_at integer
The Unix timestamp (in seconds) for when the fine-tuning job was last updated.

validation_files array
The list of files used for validation.

The fine-tune object Copy

1 {
2 "id": "ft-abc123",
3 "object": "fine-tune",
4 "model": "curie",
5 "created_at": 1614807352,
6 "events": [
7 {
8 "object": "fine-tune-event",
9 "created_at": 1614807352,
10 "level": "info",
11 "message": "Job enqueued. Waiting for jobs ahead to complete. Queue nu
12 },
13 {
14 "object": "fine-tune-event",
15 "created_at": 1614807356,
16 "level": "info",
17 "message": "Job started."
18 },
19 {
20 "object": "fine-tune-event",
21 "created_at": 1614807861,
22 "level": "info",
23 "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
24 },

https://platform.openai.com/docs/api-reference/chat/object 106/116
11/23/23, 7:33 PM API Reference - OpenAI API

25 {
26 "object": "fine-tune-event",
27 "created_at": 1614807864,
28 "level": "info",
29 "message": "Uploaded result files: file-abc123."
30 },
31 {
32 "object": "fine-tune-event",
33 "created_at": 1614807864,
34 "level": "info",
35 "message": "Job succeeded."
36 }
37 ],
38 "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20",
39 "hyperparams": {
40 "batch_size": 4,
41 "learning_rate_multiplier": 0.1,
42 "n_epochs": 4,
43 "prompt_loss_weight": 0.1,
44 },
45 "organization_id": "org-123",
46 "result_files": [
47 {
48 "id": "file-abc123",
49 "object": "file",
50 "bytes": 81509,
51 "created_at": 1614807863,
52 "filename": "compiled_results.csv",
53 "purpose": "fine-tune-results"
54 }
55 ],
56 "status": "succeeded",
57 "validation_files": [],
58 "training_files": [
59 {
60 "id": "file-abc123",
61 "object": "file",
62 "bytes": 1547276,
63 "created_at": 1610062281,
64 "filename": "my-data-train.jsonl",
65 "purpose": "fine-tune"
66 }
67 ],
68 "updated_at": 1614807865,
69 }

https://platform.openai.com/docs/api-reference/chat/object 107/116
11/23/23, 7:33 PM API Reference - OpenAI API

Create fine-tune Deprecated

POST https://api.openai.com/v1/fine-tunes

Creates a job that fine-tunes a specified 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

Request body

training_file string Required

The ID of an uploaded file that contains training data.

See upload file for how to upload a file.

Your dataset must be formatted as a JSONL file, where each training example is a JSON object
with the keys "prompt" and "completion". Additionally, you must upload your file with the purpose
fine-tune .

See the fine-tuning guide for more details.

batch_size integer or null Optional Defaults to null

The batch size to use for training. The batch size is the number of training examples used to train
a single forward and backward pass.

By default, the batch size will be dynamically configured to be ~0.2% of the number of examples in
the training set, capped at 256 - in general, we've found that larger batch sizes tend to work better
for larger datasets.

classification_betas array or null Optional Defaults to null

If this is provided, we calculate F-beta scores at the specified beta values. The F-beta score is a
generalization of F-1 score. This is only used for binary classification.

With a beta of 1 (i.e. the F-1 score), precision and recall are given the same weight. A larger beta
score puts more weight on recall and less on precision. A smaller beta score puts more weight on
precision and less on recall.

classification_n_classes integer or null Optional Defaults to null

The number of classes in a classification task.

This parameter is required for multiclass classification.

https://platform.openai.com/docs/api-reference/chat/object 108/116
11/23/23, 7:33 PM API Reference - OpenAI API

classification_positive_class string or null Optional Defaults to null

The positive class in binary classification.

This parameter is needed to generate precision, recall, and F1 metrics when doing binary
classification.

compute_classification_metrics boolean or null Optional Defaults to false

If set, we calculate classification-specific metrics such as accuracy and F-1 score using the
validation set at the end of every epoch. These metrics can be viewed in the results file.

In order to compute classification metrics, you must provide a validation_file . Additionally,

you must specify classification_n_classes for multiclass classification or
classification_positive_class for binary classification.

hyperparameters object Optional

The hyperparameters used for the fine-tuning job.
Show properties

learning_rate_multiplier number or null Optional Defaults to null

The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning
rate used for pretraining multiplied by this value.

By default, the learning rate multiplier is the 0.05, 0.1, or 0.2 depending on final batch_size
(larger learning rates tend to perform better with larger batch sizes). We recommend
experimenting with values in the range 0.02 to 0.2 to see what produces the best results.

model string Optional Defaults to curie

The name of the base model to fine-tune. You can select one of "ada", "babbage", "curie", "davinci",
or a fine-tuned model created after 2022-04-21 and before 2023-08-22. To learn more about
these models, see the Models documentation.

prompt_loss_weight number or null Optional Defaults to 0.01

The weight to use for loss on the prompt tokens. This controls how much the model tries to learn
to generate the prompt (as compared to the completion which always has a weight of 1.0), and can
add a stabilizing effect to training when completions are short.

If prompts are extremely long (relative to completions), it may make sense to reduce this weight
so as to avoid over-prioritizing learning the prompt.

suffix string or null Optional Defaults to null

A string of up to 40 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 ada:ft-
your-org:custom-model-name-2022-02-15-04-21-04 .

validation_file string or null Optional

https://platform.openai.com/docs/api-reference/chat/object 109/116
11/23/23, 7:33 PM API Reference - OpenAI API

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. Your train and validation data
should be mutually exclusive.

Your dataset must be formatted as a JSONL file, where each validation example is a JSON object
with the keys "prompt" and "completion". Additionally, you must upload your file with the purpose
fine-tune .

See the fine-tuning guide for more details.

Returns

A fine-tune object.

Example request curl Copy

1 curl https://api.openai.com/v1/fine-tunes \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer $OPENAI_API_KEY" \
4 -d '{
5 "training_file": "file-abc123"
6 }'

Response Copy

1 {
2 "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
3 "object": "fine-tune",
4 "model": "curie",
5 "created_at": 1614807352,
6 "events": [
7 {
8 "object": "fine-tune-event",
9 "created_at": 1614807352,
10 "level": "info",
11 "message": "Job enqueued. Waiting for jobs ahead to complete. Queue nu
12 }
13 ],
14 "fine_tuned_model": null,
15 "hyperparams": {
16 "batch_size": 4,
17 "learning_rate_multiplier": 0.1,
18 "n_epochs": 4,
https://platform.openai.com/docs/api-reference/chat/object 110/116
11/23/23, 7:33 PM API Reference - OpenAI API

19 "prompt_loss_weight": 0.1,
20 },
21 "organization_id": "org-123",
22 "result_files": [],
23 "status": "pending",
24 "validation_files": [],
25 "training_files": [
26 {
27 "id": "file-abc123",
28 "object": "file",
29 "bytes": 1547276,
30 "created_at": 1610062281,
31 "filename": "my-data-train.jsonl",
32 "purpose": "fine-tune-results"
33 }
34 ],
35 "updated_at": 1614807352,
36 }

List fine-tunes Deprecated

GET https://api.openai.com/v1/fine-tunes

List your organization's fine-tuning jobs

Returns

A list of fine-tune objects.

Example request curl Copy

1 curl https://api.openai.com/v1/fine-tunes \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "object": "list",
3 "data": [
https://platform.openai.com/docs/api-reference/chat/object 111/116
11/23/23, 7:33 PM API Reference - OpenAI API

4 {
5 "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
6 "object": "fine-tune",
7 "model": "curie",
8 "created_at": 1614807352,
9 "fine_tuned_model": null,
10 "hyperparams": { ... },
11 "organization_id": "org-123",
12 "result_files": [],
13 "status": "pending",
14 "validation_files": [],
15 "training_files": [ { ... } ],
16 "updated_at": 1614807352,
17 },
18 { ... },
19 { ... }
20 ]
21 }

Retrieve fine-tune Deprecated

GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}

Gets info about the fine-tune job.

Learn more about fine-tuning

Path parameters

fine_tune_id string Required

The ID of the fine-tune job

Returns

The fine-tune object with the given ID.

Example request curl Copy

https://platform.openai.com/docs/api-reference/chat/object 112/116
11/23/23, 7:33 PM API Reference - OpenAI API

1 curl https://api.openai.com/v1/fine-tunes/ft-abc123 \
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "id": "ft-abc123",
3 "object": "fine-tune",
4 "model": "curie",
5 "created_at": 1614807352,
6 "events": [
7 {
8 "object": "fine-tune-event",
9 "created_at": 1614807352,
10 "level": "info",
11 "message": "Job enqueued. Waiting for jobs ahead to complete. Queue nu
12 },
13 {
14 "object": "fine-tune-event",
15 "created_at": 1614807356,
16 "level": "info",
17 "message": "Job started."
18 },
19 {
20 "object": "fine-tune-event",
21 "created_at": 1614807861,
22 "level": "info",
23 "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
24 },
25 {
26 "object": "fine-tune-event",
27 "created_at": 1614807864,
28 "level": "info",
29 "message": "Uploaded result files: file-abc123."
30 },
31 {
32 "object": "fine-tune-event",
33 "created_at": 1614807864,
34 "level": "info",
35 "message": "Job succeeded."
36 }
37 ],
38 "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20",
39 "hyperparams": {
40 "batch_size": 4,
41 "learning_rate_multiplier": 0.1,
42 "n_epochs": 4,

https://platform.openai.com/docs/api-reference/chat/object 113/116
11/23/23, 7:33 PM API Reference - OpenAI API

43 "prompt_loss_weight": 0.1,
44 },
45 "organization_id": "org-123",
46 "result_files": [
47 {
48 "id": "file-abc123",
49 "object": "file",
50 "bytes": 81509,
51 "created_at": 1614807863,
52 "filename": "compiled_results.csv",
53 "purpose": "fine-tune-results"
54 }
55 ],
56 "status": "succeeded",
57 "validation_files": [],
58 "training_files": [
59 {
60 "id": "file-abc123",
61 "object": "file",
62 "bytes": 1547276,
63 "created_at": 1610062281,
64 "filename": "my-data-train.jsonl",
65 "purpose": "fine-tune"
66 }
67 ],
68 "updated_at": 1614807865,
69 }

Cancel fine-tune Deprecated

POST https://api.openai.com/v1/fine-tunes/{fine_tune_id}/cancel

Immediately cancel a fine-tune job.

Path parameters

fine_tune_id string Required

The ID of the fine-tune job to cancel

Returns
https://platform.openai.com/docs/api-reference/chat/object 114/116
11/23/23, 7:33 PM API Reference - OpenAI API

The cancelled fine-tune object.

Example request curl Copy

1 curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel
2 -H "Authorization: Bearer $OPENAI_API_KEY"

Response Copy

1 {
2 "id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7",
3 "object": "fine-tune",
4 "model": "curie",
5 "created_at": 1614807770,
6 "events": [ { ... } ],
7 "fine_tuned_model": null,
8 "hyperparams": { ... },
9 "organization_id": "org-123",
10 "result_files": [],
11 "status": "cancelled",
12 "validation_files": [],
13 "training_files": [
14 {
15 "id": "file-abc123",
16 "object": "file",
17 "bytes": 1547276,
18 "created_at": 1610062281,
19 "filename": "my-data-train.jsonl",
20 "purpose": "fine-tune"
21 }
22 ],
23 "updated_at": 1614807789,
24 }

The fine-tune event object Deprecated

Fine-tune event object

https://platform.openai.com/docs/api-reference/chat/object 115/116
11/23/23, 7:33 PM API Reference - OpenAI API

created_at integer

level string

message string

https://platform.openai.com/docs/api-reference/chat/object 116/116