아래는 어떤 내용인가요?

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:


1
2
3
curl https://api.openai.com/v1/models \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H "OpenAI-Organization: YOUR_ORG_ID"
Example with the openai Python package:

Upgrade to 
Python SDK v1.2
 with pip install --upgrade openai

1
2
3
4
5
6
from openai import OpenAI  client = OpenAI(  organization='YOUR_ORG_ID', ) client.models.list()
Example with the openai Node.js package:


1
2
3
4
5
6
7
import { Configuration, OpenAIApi } from "openai"; const configuration = new Configuration({  organization: "YOUR_ORG_ID",  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.


1
2
3
4
5
6
7
8
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:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{  "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


Copy‍
1
2
3
4
5
6
7
8
9
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


Copy‍
1
2
3
4
5
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

Copy‍
1
2
3
{  "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


Copy‍
1
2
3
4
5
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

Copy‍
1
2
3
{  "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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{  "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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
{"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.


Default‍

Image input‍

Streaming‍

Functions‍
Example request
gpt-3.5-turbo

gpt-3.5-turbo
curl


Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{  "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

Copy‍
1
2
3
4
5
6
7
8
9
10
{  "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) and cannot be an empty string. Example Python code for counting tokens.

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

encoding_format
string
Optional
Defaults to float
The format to return the embeddings in. Can be either float or base64.

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

Returns
A list of embedding objects.

Example request
curl


Copy‍
1
2
3
4
5
6
7
8
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{  "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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "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.


Default‍

Epochs‍

Validation file‍
Example request
curl


Copy‍
1
2
3
4
5
6
7
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "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


Copy‍
1
2
curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \  -H "Authorization: Bearer $OPENAI_API_KEY"
Response

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{  "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

Copy‍
1
2
3
4
5
6
7
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{  "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

Copy‍
1
2
3
4
5
6
7
8
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{  "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
string
Required
The File object (not file name) to be uploaded.

purpose
string
Required
The intended purpose of the uploaded file.

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

Returns
The uploaded File object.

Example request
curl


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

Copy‍
1
2
3
4
5
6
7
8
{  "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


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

Copy‍
1
2
3
4
5
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
{  "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


Copy‍
1
2
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

Copy‍
1
2
3
4
{  "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


Copy‍
1
2
3
4
5
6
7
8
9
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
{  "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
string
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
string
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


Copy‍
1
2
3
4
5
6
7
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
{  "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
string
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


Copy‍
1
2
3
4
5
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
{  "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



Copy‍
1
2
3
4
5
6
{  "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


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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{  "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


Copy‍
1
2
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

Copy‍
1
2
3
4
5
6
{  "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


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

Copy‍
1
2
3
4
5
{  "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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{  "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


Copy‍
1
2
3
4
5
6
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{  "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,  }  }  ] }
Assistants
Beta
Build assistants that can call models and use tools to perform tasks.

Get started with the Assistants API

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

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

object
string
The object type, which is always assistant.

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

name
string or null
The name of the assistant. The maximum length is 256 characters.

description
string or null
The description of the assistant. The maximum length is 512 characters.

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

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

tools
array
A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, retrieval, or function.


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

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

The assistant object

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{  "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 assistant
Beta
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.


Code Interpreter‍

Files‍
Example request
curl


Copy‍
1
2
3
4
5
6
7
8
9
10
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{  "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 assistant
Beta
GET
 
https://api.openai.com/v1/assistants/{assistant_id}

Retrieves an assistant.

Path parameters
assistant_id
string
Required
The ID of the assistant to retrieve.

Returns
The assistant object matching the specified ID.

Example request
curl


Copy‍
1
2
3
4
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

Copy‍
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{  "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 assistant
Beta
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

Option