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) 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: curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Organization: org-Xfr9LdmeiHcpH7BYivImaHI1" Example with the openai Python package: from openai import OpenAI client = OpenAI( organization='org-Xfr9LdmeiHcpH7BYivImaHI1', ) client.models.list() Example with the openai Node.js package: import { Configuration, OpenAIApi } from "openai"; const configuration = new Configuration({ organization: "org-Xfr9LdmeiHcpH7BYivImaHI1", apiKey: process.env.OPENAI_API_KEY, }); const openai = new OpenAIApi(configuration); 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. curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Say this is a test!"}], "temperature": 0.7 }' 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: { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1677858242, "model": "gpt-3.5-turbo-1106", "usage": { "prompt_tokens": 13, "completion_tokens": 7, "total_tokens": 20 }, "choices": [ { "message": { "role": "assistant", "content": "\n\nThis is a test!" }, "finish_reason": "stop", "index": 0 } ] } 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 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 The audio file content. Example request curl curl curl https://api.openai.com/v1/audio/speech \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy" }' \ --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. 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 curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="whisper-1" Response { "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." } Create translation POST https://api.openai.com/v1/audio/translations Translates audio into English. Request body 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 curl curl https://api.openai.com/v1/audio/translations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/german.m4a" \ -F model="whisper-1" Response { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" } 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 The chat completion object { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } } 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 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 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]} .... {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":" today"},"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"?"},"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} 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 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. 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 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. 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. Example request gpt-3.5-turbo gpt-3.5-turbo curl curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] }' Response { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-3.5-turbo-0613", "system_fingerprint": "fp_44709d6fcb", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } } 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. 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 { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, .... (1536 floats total for ada-002) -0.0028842222, ], "index": 0 } 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 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 curl curl https://api.openai.com/v1/embeddings \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "The food was delicious and the waiter...", "model": "text-embedding-ada-002", "encoding_format": "float" }' Response { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, .... (1536 floats total for ada-002) -0.0028842222, ], "index": 0 } ], "model": "text-embedding-ada-002", "usage": { "prompt_tokens": 8, "total_tokens": 8 } } 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. 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 { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "davinci-002", "created_at": 1692661014, "finished_at": 1692661190, "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", "organization_id": "org-123", "result_files": [ "file-abc123" ], "status": "succeeded", "validation_file": null, "training_file": "file-abc123", "hyperparameters": { "n_epochs": 4, }, "trained_tokens": 5768 } 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 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. Example request curl curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo", "model": "gpt-3.5-turbo" }' Response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-3.5-turbo-0613", "created_at": 1614807352, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", } 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 curl curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-TjX0lMfOniCZX64t9PUQT5hn", "created_at": 1689813489, "level": "warn", "message": "Fine tuning process stopping due to job cancellation", "data": null, "type": "message" }, { ... }, { ... } ], "has_more": true } 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 curl curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "davinci-002", "created_at": 1692661014, "finished_at": 1692661190, "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", "organization_id": "org-123", "result_files": [ "file-abc123" ], "status": "succeeded", "validation_file": null, "training_file": "file-abc123", "hyperparameters": { "n_epochs": 4, }, "trained_tokens": 5768 } 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 curl curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-3.5-turbo-0613", "created_at": 1689376978, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "hyperparameters": { "n_epochs": "auto" }, "status": "cancelled", "validation_file": "file-abc123", "training_file": "file-abc123" } 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 { "object": "fine_tuning.job.event", "id": "ftevent-abc123" "created_at": 1677610602, "level": "info", "message": "Created fine-tuning job" } 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 curl curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm", "created_at": 1692407401, "level": "info", "message": "Fine tuning job successfully completed", "data": null, "type": "message" }, { "object": "fine_tuning.job.event", "id": "ft-event-tyiGuB72evQncpH87xe505Sv", "created_at": 1692407400, "level": "info", "message": "New fine-tuned model created: ft:gpt-3.5-turbo:openai::7p4lURel", "data": null, "type": "message" } ], "has_more": true } 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. 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 { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "salesOverview.pdf", "purpose": "assistants", } List files GET https://api.openai.com/v1/files Returns a list of files that belong to the user's organization. Query parameters purpose string Optional Only return files with the given purpose. Returns A list of File objects. Example request curl curl curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "data": [ { "id": "file-abc123", "object": "file", "bytes": 175, "created_at": 1613677385, "filename": "salesOverview.pdf", "purpose": "assistants", }, { "id": "file-abc123", "object": "file", "bytes": 140, "created_at": 1613779121, "filename": "puppy.jsonl", "purpose": "fine-tune", } ], "object": "list" } 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 curl curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F purpose="fine-tune" \ -F file="@mydata.jsonl" Response { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "mydata.jsonl", "purpose": "fine-tune", } 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 curl curl https://api.openai.com/v1/files/file-abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "id": "file-abc123", "object": "file", "deleted": true } 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 curl curl https://api.openai.com/v1/files/file-abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "mydata.jsonl", "purpose": "fine-tune", } Retrieve file content GET https://api.openai.com/v1/files/{file_id}/content 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 curl curl https://api.openai.com/v1/files/file-abc123/content \ -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 The prompt that was used to generate the image, if there was any revision to the prompt. The image object { "url": "...", "revised_prompt": "..." } 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 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 curl curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "dall-e-3", "prompt": "A cute baby sea otter", "n": 1, "size": "1024x1024" }' Response { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } 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 Returns a list of image objects. Example request curl curl curl https://api.openai.com/v1/images/edits \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F image="@otter.png" \ -F mask="@mask.png" \ -F prompt="A cute baby sea otter wearing a beret" \ -F n=2 \ -F size="1024x1024" Response { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } 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. 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 curl curl https://api.openai.com/v1/images/variations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F image="@otter.png" \ -F n=2 \ -F size="1024x1024" Response { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } 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 { "id": "davinci", "object": "model", "created": 1686935002, "owned_by": "openai" } 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 curl curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "list", "data": [ { "id": "model-id-0", "object": "model", "created": 1686935002, "owned_by": "organization-owner" }, { "id": "model-id-1", "object": "model", "created": 1686935002, "owned_by": "organization-owner", }, { "id": "model-id-2", "object": "model", "created": 1686935002, "owned_by": "openai" }, ], "object": "list" } 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 gpt-3.5-turbo-instruct curl curl curl https://api.openai.com/v1/models/gpt-3.5-turbo-instruct \ -H "Authorization: Bearer $OPENAI_API_KEY" Response gpt-3.5-turbo-instruct gpt-3.5-turbo-instruct { "id": "gpt-3.5-turbo-instruct", "object": "model", "created": 1686935002, "owned_by": "openai" } 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 curl curl https://api.openai.com/v1/models/ft:gpt-3.5-turbo:acemeco:suffix:abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "id": "ft:gpt-3.5-turbo:acemeco:suffix:abc123", "object": "model", "deleted": true } Moderations Given a input text, outputs if the model classifies it as violating OpenAI's content policy. 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 { "id": "modr-XXXXX", "model": "text-moderation-005", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": false, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true, }, "category_scores": { "sexual": 1.2282071e-06, "hate": 0.010696256, "harassment": 0.29842457, "self-harm": 1.5236925e-08, "sexual/minors": 5.7246268e-08, "hate/threatening": 0.0060676364, "violence/graphic": 4.435014e-06, "self-harm/intent": 8.098441e-10, "self-harm/instructions": 2.8498655e-11, "harassment/threatening": 0.63055265, "violence": 0.99011886, } } ] } 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. Example request curl curl curl https://api.openai.com/v1/moderations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "input": "I want to kill them." }' Response { "id": "modr-XXXXX", "model": "text-moderation-005", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": false, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true, }, "category_scores": { "sexual": 1.2282071e-06, "hate": 0.010696256, "harassment": 0.29842457, "self-harm": 1.5236925e-08, "sexual/minors": 5.7246268e-08, "hate/threatening": 0.0060676364, "violence/graphic": 4.435014e-06, "self-harm/intent": 8.098441e-10, "self-harm/instructions": 2.8498655e-11, "harassment/threatening": 0.63055265, "violence": 0.99011886, } } ] } AssistantsBeta Build assistants that can call models and use tools to perform tasks. Get started with the Assistants API The assistant objectBeta 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 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 { "id": "asst_abc123", "object": "assistant", "created_at": 1698984975, "name": "Math Tutor", "description": null, "model": "gpt-4", "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "tools": [ { "type": "code_interpreter" } ], "file_ids": [], "metadata": {} } Create assistantBeta POST https://api.openai.com/v1/assistants Create an assistant with a model and instructions. Request body model 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. 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. Example request curl curl curl "https://api.openai.com/v1/assistants" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "name": "Math Tutor", "tools": [{"type": "code_interpreter"}], "model": "gpt-4" }' Response { "id": "asst_abc123", "object": "assistant", "created_at": 1698984975, "name": "Math Tutor", "description": null, "model": "gpt-4", "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "tools": [ { "type": "code_interpreter" } ], "file_ids": [], "metadata": {} } Retrieve assistantBeta 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 The assistant object matching the specified ID. Example request curl curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "asst_abc123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-4", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "retrieval" } ], "file_ids": [ "file-abc123" ], "metadata": {} } Modify assistantBeta POST https://api.openai.com/v1/assistants/{assistant_id} Modifies an assistant. Path parameters 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. Example request curl curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [{"type": "retrieval"}], "model": "gpt-4", "file_ids": ["file-abc123", "file-abc456"] }' Response { "id": "asst_abc123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-4", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [ { "type": "retrieval" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": {} } Delete assistantBeta DELETE https://api.openai.com/v1/assistants/{assistant_id} Delete an assistant. Path parameters assistant_id string Required The ID of the assistant to delete. Returns Deletion status Example request curl curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -X DELETE Response { "id": "asst_abc123", "object": "assistant.deleted", "deleted": true } List assistantsBeta 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. 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 curl curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "asst_abc123", "object": "assistant", "created_at": 1698982736, "name": "Coding Tutor", "description": null, "model": "gpt-4", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "file_ids": [], "metadata": {} }, { "id": "asst_abc456", "object": "assistant", "created_at": 1698982718, "name": "My Assistant", "description": null, "model": "gpt-4", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "file_ids": [], "metadata": {} }, { "id": "asst_abc789", "object": "assistant", "created_at": 1698982643, "name": null, "description": null, "model": "gpt-4", "instructions": null, "tools": [], "file_ids": [], "metadata": {} } ], "first_id": "asst_abc123", "last_id": "asst_abc789", "has_more": false } The assistant file objectBeta 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 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 { "id": "file-abc123", "object": "assistant.file", "created_at": 1699055364, "assistant_id": "asst_abc123" } Create assistant fileBeta 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. Example request curl curl curl https://api.openai.com/v1/assistants/asst_abc123/files \ -H 'Authorization: Bearer $OPENAI_API_KEY"' \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v1' \ -d '{ "file_id": "file-abc123" }' Response { "id": "file-abc123", "object": "assistant.file", "created_at": 1699055364, "assistant_id": "asst_abc123" } Retrieve assistant fileBeta 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. Example request curl curl curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \ -H 'Authorization: Bearer $OPENAI_API_KEY"' \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v1' Response { "id": "file-abc123", "object": "assistant.file", "created_at": 1699055364, "assistant_id": "asst_abc123" } Delete assistant fileBeta 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 curl curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" \ -X DELETE Response { id: "file-abc123", object: "assistant.file.deleted", deleted: true } List assistant filesBeta 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 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 curl curl https://api.openai.com/v1/assistants/asst_abc123/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "file-abc123", "object": "assistant.file", "created_at": 1699060412, "assistant_id": "asst_abc123" }, { "id": "file-abc456", "object": "assistant.file", "created_at": 1699060412, "assistant_id": "asst_abc123" } ], "first_id": "file-abc123", "last_id": "file-abc456", "has_more": false } ThreadsBeta Create threads that assistants can interact with. Related guide: Assistants The thread objectBeta 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 { "id": "thread_abc123", "object": "thread", "created_at": 1698107661, "metadata": {} } Create threadBeta 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. Example request curl curl curl https://api.openai.com/v1/threads \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '' Response { "id": "thread_abc123", "object": "thread", "created_at": 1699012949, "metadata": {} } Retrieve threadBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "thread_abc123", "object": "thread", "created_at": 1699014083, "metadata": {} } Modify threadBeta POST https://api.openai.com/v1/threads/{thread_id} 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 curl curl https://api.openai.com/v1/threads/thread_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "metadata": { "modified": "true", "user": "abc123" } }' Response { "id": "thread_abc123", "object": "thread", "created_at": 1699014083, "metadata": { "modified": "true", "user": "abc123" } } Delete threadBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -X DELETE Response { "id": "thread_abc123", "object": "thread.deleted", "deleted": true } MessagesBeta Create messages within threads Related guide: Assistants The message objectBeta 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 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 { "id": "msg_abc123", "object": "thread.message", "created_at": 1698983503, "thread_id": "thread_abc123", "role": "assistant", "content": [ { "type": "text", "text": { "value": "Hi! How can I help you today?", "annotations": [] } } ], "file_ids": [], "assistant_id": "asst_abc123", "run_id": "run_abc123", "metadata": {} } Create messageBeta POST https://api.openai.com/v1/threads/{thread_id}/messages Create a message. Path parameters thread_id string Required 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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "role": "user", "content": "How does AI work? Explain it in simple terms." }' Response { "id": "msg_abc123", "object": "thread.message", "created_at": 1699017614, "thread_id": "thread_abc123", "role": "user", "content": [ { "type": "text", "text": { "value": "How does AI work? Explain it in simple terms.", "annotations": [] } } ], "file_ids": [], "assistant_id": null, "run_id": null, "metadata": {} } Retrieve messageBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "msg_abc123", "object": "thread.message", "created_at": 1699017614, "thread_id": "thread_abc123", "role": "user", "content": [ { "type": "text", "text": { "value": "How does AI work? Explain it in simple terms.", "annotations": [] } } ], "file_ids": [], "assistant_id": null, "run_id": null, "metadata": {} } Modify messageBeta 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 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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "metadata": { "modified": "true", "user": "abc123" } }' Response { "id": "msg_abc123", "object": "thread.message", "created_at": 1699017614, "thread_id": "thread_abc123", "role": "user", "content": [ { "type": "text", "text": { "value": "How does AI work? Explain it in simple terms.", "annotations": [] } } ], "file_ids": [], "assistant_id": null, "run_id": null, "metadata": { "modified": "true", "user": "abc123" } } List messagesBeta 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 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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "msg_abc123", "object": "thread.message", "created_at": 1699016383, "thread_id": "thread_abc123", "role": "user", "content": [ { "type": "text", "text": { "value": "How does AI work? Explain it in simple terms.", "annotations": [] } } ], "file_ids": [], "assistant_id": null, "run_id": null, "metadata": {} }, { "id": "msg_abc456", "object": "thread.message", "created_at": 1699016383, "thread_id": "thread_abc123", "role": "user", "content": [ { "type": "text", "text": { "value": "Hello, what is AI?", "annotations": [] } } ], "file_ids": [ "file-abc123" ], "assistant_id": null, "run_id": null, "metadata": {} } ], "first_id": "msg_abc123", "last_id": "msg_abc456", "has_more": false } The message file objectBeta 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. The message file object { "id": "file-abc123", "object": "thread.message.file", "created_at": 1698107661, "message_id": "message_QLoItBbqwyAJEzlTy4y9kOMM", "file_id": "file-abc123" } Retrieve message fileBeta GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files/file-abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "file-abc123", "object": "thread.message.file", "created_at": 1699061776, "message_id": "msg_abc123" } List message filesBeta GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files 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. 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 curl curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "file-abc123", "object": "thread.message.file", "created_at": 1699061776, "message_id": "msg_abc123" }, { "id": "file-abc123", "object": "thread.message.file", "created_at": 1699061776, "message_id": "msg_abc123" } ], "first_id": "file-abc123", "last_id": "file-abc123", "has_more": false } RunsBeta Represents an execution run on a thread. Related guide: Assistants The run objectBeta 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 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 { "id": "run_abc123", "object": "thread.run", "created_at": 1698107661, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699073476, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699073498, "last_error": null, "model": "gpt-4", "instructions": null, "tools": [{"type": "retrieval"}, {"type": "code_interpreter"}], "file_ids": [], "metadata": {} } Create runBeta 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. 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "assistant_id": "asst_abc123" }' Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699063290, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "queued", "started_at": 1699063290, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699063291, "last_error": null, "model": "gpt-4", "instructions": null, "tools": [ { "type": "code_interpreter" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": {} } Retrieve runBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699075072, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699075072, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699075073, "last_error": null, "model": "gpt-3.5-turbo", "instructions": null, "tools": [ { "type": "code_interpreter" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": {} } Modify runBeta 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. 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "metadata": { "user_id": "user_abc123" } }' Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699075072, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699075072, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699075073, "last_error": null, "model": "gpt-3.5-turbo", "instructions": null, "tools": [ { "type": "code_interpreter" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": { "user_id": "user_abc123" } } List runsBeta 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 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "run_abc123", "object": "thread.run", "created_at": 1699075072, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699075072, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699075073, "last_error": null, "model": "gpt-3.5-turbo", "instructions": null, "tools": [ { "type": "code_interpreter" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": {} }, { "id": "run_abc456", "object": "thread.run", "created_at": 1699063290, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699063290, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699063291, "last_error": null, "model": "gpt-3.5-turbo", "instructions": null, "tools": [ { "type": "code_interpreter" } ], "file_ids": [ "file-abc123", "file-abc456" ], "metadata": {} } ], "first_id": "run_abc123", "last_id": "run_abc456", "has_more": false } Submit tool outputs to runBeta POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/submit_tool_outputs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "tool_outputs": [ { "tool_call_id": "call_abc123", "output": "28C" } ] }' Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699075592, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "queued", "started_at": 1699075592, "expires_at": 1699076192, "cancelled_at": null, "failed_at": null, "completed_at": null, "last_error": null, "model": "gpt-4", "instructions": "You tell the weather.", "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Determine weather in my location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": [ "c", "f" ] } }, "required": [ "location" ] } } } ], "file_ids": [], "metadata": {} } Cancel a runBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v1" \ -X POST Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699076126, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "cancelling", "started_at": 1699076126, "expires_at": 1699076726, "cancelled_at": null, "failed_at": null, "completed_at": null, "last_error": null, "model": "gpt-4", "instructions": "You summarize books.", "tools": [ { "type": "retrieval" } ], "file_ids": [], "metadata": {} } Create thread and runBeta 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 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 curl curl https://api.openai.com/v1/threads/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" \ -d '{ "assistant_id": "asst_abc123", "thread": { "messages": [ {"role": "user", "content": "Explain deep learning to a 5 year old."} ] } }' Response { "id": "run_abc123", "object": "thread.run", "created_at": 1699076792, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "queued", "started_at": null, "expires_at": 1699077392, "cancelled_at": null, "failed_at": null, "completed_at": null, "last_error": null, "model": "gpt-4", "instructions": "You are a helpful assistant.", "tools": [], "file_ids": [], "metadata": {} } The run step objectBeta 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. 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 { "id": "step_abc123", "object": "thread.run.step", "created_at": 1699063291, "run_id": "run_abc123", "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "type": "message_creation", "status": "completed", "cancelled_at": null, "completed_at": 1699063291, "expired_at": null, "failed_at": null, "last_error": null, "step_details": { "type": "message_creation", "message_creation": { "message_id": "msg_abc123" } } } Retrieve run stepBeta 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "id": "step_abc123", "object": "thread.run.step", "created_at": 1699063291, "run_id": "run_abc123", "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "type": "message_creation", "status": "completed", "cancelled_at": null, "completed_at": 1699063291, "expired_at": null, "failed_at": null, "last_error": null, "step_details": { "type": "message_creation", "message_creation": { "message_id": "msg_abc123" } } } List run stepsBeta 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. 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 curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v1" Response { "object": "list", "data": [ { "id": "step_abc123", "object": "thread.run.step", "created_at": 1699063291, "run_id": "run_abc123", "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "type": "message_creation", "status": "completed", "cancelled_at": null, "completed_at": 1699063291, "expired_at": null, "failed_at": null, "last_error": null, "step_details": { "type": "message_creation", "message_creation": { "message_id": "msg_abc123" } } } ], "first_id": "step_abc123", "last_id": "step_abc456", "has_more": false } CompletionsLegacy 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 objectLegacy 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. 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 { "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, "model": "gpt-3.5-turbo", "choices": [ { "text": "\n\nThis is indeed a test", "index": 0, "logprobs": null, "finish_reason": "length" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 7, "total_tokens": 12 } } Create completionLegacy POST https://api.openai.com/v1/completions Creates a completion for the provided prompt and parameters. 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 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. 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. Example request gpt-3.5-turbo-instruct gpt-3.5-turbo-instruct curl curl curl https://api.openai.com/v1/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo-instruct", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0 }' Response gpt-3.5-turbo-instruct gpt-3.5-turbo-instruct { "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, "model": "gpt-3.5-turbo-instruct", "system_fingerprint": "fp_44709d6fcb", "choices": [ { "text": "\n\nThis is indeed a test", "index": 0, "logprobs": null, "finish_reason": "length" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 7, "total_tokens": 12 } } EditsDeprecated 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 objectDeprecated 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 { "object": "edit", "created": 1589478378, "choices": [ { "text": "What day of the week is it?", "index": 0, } ], "usage": { "prompt_tokens": 25, "completion_tokens": 32, "total_tokens": 57 } } Create editDeprecated 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 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 text-davinci-edit-001 curl curl curl https://api.openai.com/v1/edits \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "text-davinci-edit-001", "input": "What day of the wek is it?", "instruction": "Fix the spelling mistakes" }' Response { "object": "edit", "created": 1589478378, "choices": [ { "text": "What day of the week is it?", "index": 0, } ], "usage": { "prompt_tokens": 25, "completion_tokens": 32, "total_tokens": 57 } } Fine-tunesDeprecated 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 objectDeprecated 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 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 { "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "events": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." }, { "object": "fine-tune-event", "created_at": 1614807356, "level": "info", "message": "Job started." }, { "object": "fine-tune-event", "created_at": 1614807861, "level": "info", "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Uploaded result files: file-abc123." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Job succeeded." } ], "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20", "hyperparams": { "batch_size": 4, "learning_rate_multiplier": 0.1, "n_epochs": 4, "prompt_loss_weight": 0.1, }, "organization_id": "org-123", "result_files": [ { "id": "file-abc123", "object": "file", "bytes": 81509, "created_at": 1614807863, "filename": "compiled_results.csv", "purpose": "fine-tune-results" } ], "status": "succeeded", "validation_files": [], "training_files": [ { "id": "file-abc123", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune" } ], "updated_at": 1614807865, } Create fine-tuneDeprecated 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. 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 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 curl curl https://api.openai.com/v1/fine-tunes \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123" }' Response { "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "events": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." } ], "fine_tuned_model": null, "hyperparams": { "batch_size": 4, "learning_rate_multiplier": 0.1, "n_epochs": 4, "prompt_loss_weight": 0.1, }, "organization_id": "org-123", "result_files": [], "status": "pending", "validation_files": [], "training_files": [ { "id": "file-abc123", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune-results" } ], "updated_at": 1614807352, } List fine-tunesDeprecated 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 curl curl https://api.openai.com/v1/fine-tunes \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "list", "data": [ { "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "fine_tuned_model": null, "hyperparams": { ... }, "organization_id": "org-123", "result_files": [], "status": "pending", "validation_files": [], "training_files": [ { ... } ], "updated_at": 1614807352, }, { ... }, { ... } ] } Retrieve fine-tuneDeprecated 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 curl curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "events": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." }, { "object": "fine-tune-event", "created_at": 1614807356, "level": "info", "message": "Job started." }, { "object": "fine-tune-event", "created_at": 1614807861, "level": "info", "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Uploaded result files: file-abc123." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Job succeeded." } ], "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20", "hyperparams": { "batch_size": 4, "learning_rate_multiplier": 0.1, "n_epochs": 4, "prompt_loss_weight": 0.1, }, "organization_id": "org-123", "result_files": [ { "id": "file-abc123", "object": "file", "bytes": 81509, "created_at": 1614807863, "filename": "compiled_results.csv", "purpose": "fine-tune-results" } ], "status": "succeeded", "validation_files": [], "training_files": [ { "id": "file-abc123", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune" } ], "updated_at": 1614807865, } Cancel fine-tuneDeprecated 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 The cancelled fine-tune object. Example request curl curl curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7", "object": "fine-tune", "model": "curie", "created_at": 1614807770, "events": [ { ... } ], "fine_tuned_model": null, "hyperparams": { ... }, "organization_id": "org-123", "result_files": [], "status": "cancelled", "validation_files": [], "training_files": [ { "id": "file-abc123", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune" } ], "updated_at": 1614807789, } The fine-tune event objectDeprecated Fine-tune event object created_at integer level string message string object string The fine-tune event object { "object": "fine-tune-event", "created_at": 1677610602, "level": "info", "message": "Created fine-tune job" } List fine-tune eventsDeprecated GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events Get fine-grained status updates for a fine-tune job. Path parameters fine_tune_id string Required The ID of the fine-tune job to get events for. Query parameters stream boolean Optional Defaults to false Whether to stream events for the fine-tune job. If set to true, events will be sent as data-only server-sent events as they become available. The stream will terminate with a data: [DONE] message when the job is finished (succeeded, cancelled, or failed). If set to false, only events generated so far will be returned. Returns A list of fine-tune event objects. Example request curl curl curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \ -H "Authorization: Bearer $OPENAI_API_KEY" Response { "object": "list", "data": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." }, { "object": "fine-tune-event", "created_at": 1614807356, "level": "info", "message": "Job started." }, { "object": "fine-tune-event", "created_at": 1614807861, "level": "info", "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Uploaded result files: file-abc123" }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Job succeeded." } ] }