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 openaiTo install the official Node.js library, run the following command in your Node.js project directory:
npm install openai@^4.0.0The 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_KEYFor 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 against the specified organization's subscription quota.
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:
1
2
3
4
5
import os
import openai
openai.organization = "YOUR_ORG_ID"
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.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.
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-0613",
"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.
Learn how to turn audio into text.
Related guide: Speech to text
post https://api.openai.com/v1/audio/transcriptions
Transcribes audio into the input language.
The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language.
The format of the transcript output, in one of these options: json, text, srt, verbose_json, or vtt.
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.
The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency.
The transcriped text.
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"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."
}post https://api.openai.com/v1/audio/translations
Translates audio into English.
The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
An optional text to guide the model's style or continue a previous audio segment. The prompt should be in English.
The format of the transcript output, in one of these options: json, text, srt, verbose_json, or vtt.
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.
The translated text.
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"1
2
3
{
"text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}Given a list of messages comprising a conversation, the model will return a response.
Related guide: Chat completions
Represents a chat completion response returned by model, based on the provided input.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-3.5-turbo-0613",
"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
}
}Represents a streamed chunk of a chat completion response returned by model, based on the provided input.
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"id": "chatcmpl-123",
"object": "chat.completion.chunk",
"created": 1677652288,
"model": "gpt-3.5-turbo",
"choices": [{
"index": 0,
"delta": {
"content": "Hello",
},
"finish_reason": "stop"
}]
}post https://api.openai.com/v1/chat/completions
Creates a model response for the given chat conversation.
ID of the model to use. See the model endpoint compatibility table for details on which models work with the Chat API.
A list of messages comprising the conversation so far. Example Python code.
Controls how the model responds to function calls. none means the model does not call a function, and responds to the end-user. auto means the model can pick between an end-user 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.
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.
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.
How many chat completion choices to generate for each input message.
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.
Up to 4 sequences where the API will stop generating further tokens.
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.
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.
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.
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.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
Returns a chat completion object, or a streamed sequence of chat completion chunk objects if the request is streamed.
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!"
}
]
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-3.5-turbo-0613",
"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
}
}Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position. We recommend most users use our Chat completions API. Learn more
Related guide: Legacy Completions
Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"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
}
}post https://api.openai.com/v1/completions
Creates a completion for the provided prompt and parameters.
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.
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.
The suffix that comes after a completion of inserted text.
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.
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.
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.
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.
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.
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.
Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
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.
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.
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.
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.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
Returns a completion object, or a sequence of completion objects if the request is streamed.
1
2
3
4
5
6
7
8
9
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
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
"object": "text_completion",
"created": 1589478378,
"model": "gpt-3.5-turbo-instruct",
"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
}
}Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
Related guide: Embeddings
Represents an embedding vector returned by embedding endpoint.
The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the embedding guide.
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
}post https://api.openai.com/v1/embeddings
Creates an embedding vector representing the input text.
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.
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. Each input must not exceed the max input tokens for the model (8191 tokens for text-embedding-ada-002) and cannot be an empty string. Example Python code for counting tokens.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
A list of embedding objects.
1
2
3
4
5
6
7
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"
}'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
}
}Manage fine-tuning jobs to tailor a model to your specific training data.
Related guide: fine-tune models
The fine_tuning.job object represents a fine-tuning job that has been created through the API.
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.
The name of the fine-tuned model that is being created. The value will be null if the fine-tuning job is still running.
The current status of the fine-tuning job, which can be either validating_files, queued, running, succeeded, failed, or cancelled.
The hyperparameters used for the fine-tuning job. See the fine-tuning guide for more details.
The file ID used for training. You can retrieve the training data with the Files API.
The file ID used for validation. You can retrieve the validation results with the Files API.
The compiled results file ID(s) for the fine-tuning job. You can retrieve the results with the Files API.
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"object": "fine_tuning.job",
"id": "ft-zRdUkP4QeZqeYjDcQL0wwam1",
"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
}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.
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.
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.
The name of the model to fine-tune. You can select one of the supported models.
A fine-tuning.job object.
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-abc123"
"model": "gpt-3.5-turbo",
}'1
2
3
4
5
6
7
8
9
10
11
12
{
"object": "fine_tuning.job",
"id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
"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",
}get https://api.openai.com/v1/fine_tuning/jobs
List your organization's fine-tuning jobs
A list of paginated fine-tuning job objects.
1
2
curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \
-H "Authorization: Bearer $OPENAI_API_KEY"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
}get https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}
Get info about a fine-tuning job.
The fine-tuning object with the given ID.
1
2
curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"object": "fine_tuning.job",
"id": "ft-zRdUkP4QeZqeYjDcQL0wwam1",
"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
}post https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/cancel
Immediately cancel a fine-tune job.
The cancelled fine-tuning object.
1
2
curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"object": "fine_tuning.job",
"id": "ft-gleYLJhWh1YFufiy29AahVpj",
"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"
}get https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/events
Get status updates for a fine-tuning job.
A list of fine-tuning event objects.
1
2
curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \
-H "Authorization: Bearer $OPENAI_API_KEY"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 are used to upload documents that can be used with features like fine-tuning.
The File object represents a document that has been uploaded to OpenAI.
The current status of the file, which can be either uploaded, processed, pending, error, deleting or deleted.
1
2
3
4
5
6
7
8
9
10
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"filename": "my_file.jsonl",
"purpose": "fine-tune",
"status": "uploaded",
"status_details": null
}get https://api.openai.com/v1/files
Returns a list of files that belong to the user's organization.
A list of file objects.
1
2
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY"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": "train.jsonl",
"purpose": "search"
},
{
"id": "file-abc123",
"object": "file",
"bytes": 140,
"created_at": 1613779121,
"filename": "puppy.jsonl",
"purpose": "search"
}
],
"object": "list"
}post https://api.openai.com/v1/files
Upload a file that contains document(s) to be used across various endpoints/features. Currently, the size of all the files uploaded by one organization can be up to 1 GB. Please contact us if you need to increase the storage limit.
Name of the JSON Lines file to be uploaded.
If the purpose is set to "fine-tune", the file will be used for fine-tuning.
The intended purpose of the uploaded documents.
Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
The uploaded file object.
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"1
2
3
4
5
6
7
8
9
{
"id": "file-abc123",
"object": "file",
"bytes": 140,
"created_at": 1613779121,
"filename": "mydata.jsonl",
"purpose": "fine-tune",
"status": "uploaded" | "processed" | "pending" | "error"
}delete https://api.openai.com/v1/files/{file_id}
Delete a file.
Deletion status.
1
2
3
curl https://api.openai.com/v1/files/file-abc123 \
-X DELETE \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
{
"id": "file-abc123",
"object": "file",
"deleted": true
}get https://api.openai.com/v1/files/{file_id}
Returns information about a specific file.
The file object matching the specified ID.
1
2
curl https://api.openai.com/v1/files/file-abc123 \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
7
8
{
"id": "file-abc123",
"object": "file",
"bytes": 140,
"created_at": 1613779657,
"filename": "mydata.jsonl",
"purpose": "fine-tune"
}get https://api.openai.com/v1/files/{file_id}/content
Returns the contents of the specified file.
The file content.
1
2
curl https://api.openai.com/v1/files/file-abc123/content \
-H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonlGiven a prompt and/or an input image, the model will generate a new image.
Related guide: Image generation
Represents the url or the content of an image generated by the OpenAI API.
1
2
3
{
"url": "..."
}post https://api.openai.com/v1/images/generations
Creates an image given a prompt.
A text description of the desired image(s). The maximum length is 1000 characters.
The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
The format in which the generated images are returned. Must be one of url or b64_json.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
Returns a list of image objects.
1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"prompt": "A cute baby sea otter",
"n": 2,
"size": "1024x1024"
}'1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}post https://api.openai.com/v1/images/edits
Creates an edited or extended image given an original image and a prompt.
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.
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.
A text description of the desired image(s). The maximum length is 1000 characters.
The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
The format in which the generated images are returned. Must be one of url or b64_json.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
Returns a list of image objects.
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"1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}post https://api.openai.com/v1/images/variations
Creates a variation of a given image.
The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
The format in which the generated images are returned. Must be one of url or b64_json.
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
Returns a list of image objects.
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"1
2
3
4
5
6
7
8
9
10
11
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}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.
Describes an OpenAI model offering that can be used with the API.
1
2
3
4
5
6
{
"id": "davinci",
"object": "model",
"created": 1686935002,
"owned_by": "openai"
}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.
A list of model objects.
1
2
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"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"
}get https://api.openai.com/v1/models/{model}
Retrieves a model instance, providing basic information about the model such as the owner and permissioning.
The model object matching the specified ID.
1
2
curl https://api.openai.com/v1/models/gpt-3.5-turbo-instruct \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
{
"id": "gpt-3.5-turbo-instruct",
"object": "model",
"created": 1686935002,
"owned_by": "openai"
}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.
Deletion status.
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"1
2
3
4
5
{
"id": "ft:gpt-3.5-turbo:acemeco:suffix:abc123",
"object": "model",
"deleted": true
}Given a input text, outputs if the model classifies it as violating OpenAI's content policy.
Related guide: Moderations
Represents policy compliance report by OpenAI's content moderation model against a given input.
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,
}
}
]
}post https://api.openai.com/v1/moderations
Classifies if text violates OpenAI's Content Policy
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.
A moderation object.
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."
}'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,
}
}
]
}Manage legacy fine-tuning jobs to tailor a model to your specific training data.
We recommend transitioning to the updating fine-tuning API
The FineTune object represents a legacy fine-tune job that has been created through the API.
The current status of the fine-tuning job, which can be either created, running, succeeded, failed, or cancelled.
The hyperparameters used for the fine-tuning job. See the fine-tuning guide for more details.
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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
"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-train"
}
],
"updated_at": 1614807865,
}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.
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.
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.
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.
The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
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.
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.
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.
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.
The number of classes in a classification task.
This parameter is required for multiclass classification.
The positive class in binary classification.
This parameter is needed to generate precision, recall, and F1 metrics when doing binary classification.
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.
A fine-tune object.
1
2
3
4
5
6
curl https://api.openai.com/v1/fine-tunes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"training_file": "file-abc123"
}'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
36
{
"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-train"
}
],
"updated_at": 1614807352,
}get https://api.openai.com/v1/fine-tunes
List your organization's fine-tuning jobs
A list of fine-tune objects.
1
2
curl https://api.openai.com/v1/fine-tunes \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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,
},
{ ... },
{ ... }
]
}get https://api.openai.com/v1/fine-tunes/{fine_tune_id}
Gets info about the fine-tune job.
The fine-tune object with the given ID.
1
2
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
-H "Authorization: Bearer $OPENAI_API_KEY"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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
"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-train"
}
],
"updated_at": 1614807865,
}post https://api.openai.com/v1/fine-tunes/{fine_tune_id}/cancel
Immediately cancel a fine-tune job.
The cancelled fine-tune object.
1
2
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \
-H "Authorization: Bearer $OPENAI_API_KEY"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"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-train"
}
],
"updated_at": 1614807789,
}get https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events
Get fine-grained status updates for a fine-tune job.
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.
A list of fine-tune event objects.
1
2
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \
-H "Authorization: Bearer $OPENAI_API_KEY"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
{
"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."
}
]
}Given a prompt and an instruction, the model will return an edited version of the prompt.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"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
}
}post https://api.openai.com/v1/edits
Creates a new edit for the provided input, instruction, and parameters.
ID of the model to use. You can use the text-davinci-edit-001 or code-davinci-edit-001 model with this endpoint.
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.
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 an edit object.
1
2
3
4
5
6
7
8
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"
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"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
}
}