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:
To install the official Node.js library, run the following command in your Node.js project directory:
npm install openai@^4.0.0
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
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 against the specified organization’s subscription quota.
Example curl command:
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Organization: org-fCjgkQdhhwrfvZe34uBrCCfN"
Example with the openai Python package:
import os
import openai
openai.organization = "org-fCjgkQdhhwrfvZe34uBrCCfN"
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.list()
Example with the openai Node.js package:
import { Configuration, OpenAIApi } from "openai";
const configuration = new Configuration({
organization: "org-fCjgkQdhhwrfvZe34uBrCCfN",
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.
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Say this is a test!"}],
"temperature": 0.7
}'
This request queries the gpt-3.5-turbo model (which under the hood points to the latest gpt-3.5-turbo model variant) to complete the text starting with a prompt of “Say this is a test”. You should get a response back that resembles the following:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "gpt-3.5-turbo-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.
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.
ID of the model to use. Only whisper-1 is currently available.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
audio_file = open("audio.mp3", "rb")
transcript = openai.Audio.transcribe("whisper-1", audio_file)
{
"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.
ID of the model to use. Only whisper-1 is currently available.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
audio_file = open("german.m4a", "rb")
transcript = openai.Audio.translate("whisper-1", audio_file)
{
"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.
A unique identifier for the chat completion.
The object type, which is always chat.completion.
The Unix timestamp (in seconds) of when the chat completion was created.
The model used for the chat completion.
A list of chat completion choices. Can be more than one if n is greater than 1.
Usage statistics for the completion request.
{
"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.
A unique identifier for the chat completion. Each chunk has the same ID.
The object type, which is always chat.completion.chunk.
The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.
The model to generate the completion.
A list of chat completion choices. Can be more than one if n is greater than 1.
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","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","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
....
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":" today"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"?"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
post https://api.openai.com/v1/chat/completions
Creates a model response for the given chat conversation.
A list of functions the model may generate JSON inputs for.
Controls how the model calls functions. “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.
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.
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.
No StreamingStreamingFunction calling
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
completion = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
print(completion.choices[0].message)
{
"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).
A unique identifier for the completion.
The object type, which is always “text_completion”
The Unix timestamp (in seconds) of when the completion was created.
The model used for completion.
The list of completion choices the model generated for the input prompt.
Usage statistics for the completion request.
{
"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.
Echo back the prompt in addition to the completion
Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Completion.create(
model="gpt-3.5-turbo-instruct",
prompt="Say this is a test",
max_tokens=7,
temperature=0
)
{
"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 index of the embedding in the list of embeddings.
The object type, which is always “embedding”.
The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the embedding guide.
{
"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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Embedding.create(
model="text-embedding-ada-002",
input="The food was delicious and the waiter..."
)
{
"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
}
}
The fine_tuning.job object represents a fine-tuning job that has been created through the API.
The object identifier, which can be referenced in the API endpoints.
The object type, which is always “fine_tuning.job”.
The Unix timestamp (in seconds) for when the fine-tuning job was created.
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 base model that is being fine-tuned.
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 organization that owns the fine-tuning job.
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.
For fine-tuning jobs that have failed, this will contain more information on the cause of the failure.
{
"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
}
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 hyperparameters used for the fine-tuning job.
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.
No hyperparametersHyperparametersValidation file
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTuningJob.create(training_file="file-abc123", model="gpt-3.5-turbo")
{
"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"
}
get https://api.openai.com/v1/fine_tuning/jobs
List your organization’s fine-tuning jobs
Identifier for the last job from the previous pagination request.
Number of fine-tuning jobs to retrieve.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTuningJob.list()
{
"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}
The ID of the fine-tuning job.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTuningJob.retrieve("ftjob-abc123")
{
"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
}
post https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/cancel
Immediately cancel a fine-tune job.
The ID of the fine-tuning job to cancel.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTuningJob.cancel("ftjob-abc123")
{
"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"
}
{
"object": "event",
"id": "ftevent-abc123"
"created_at": 1677610602,
"level": "info",
"message": "Created fine-tuning job"
}
get https://api.openai.com/v1/fine_tuning/jobs/{fine_tuning_job_id}/events
Get status updates for a fine-tuning job.
The ID of the fine-tuning job to get events for.
Identifier for the last event from the previous pagination request.
Number of events to retrieve.
A list of fine-tuning event objects.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTuningJob.list_events(id="ftjob-abc123", limit=2)
{
"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 file identifier, which can be referenced in the API endpoints.
The object type, which is always “file”.
The size of the file in bytes.
The Unix timestamp (in seconds) for when the file was created.
The intended purpose of the file. Currently, only “fine-tune” is supported.
The current status of the file, which can be either uploaded, processed, pending, error, deleting or deleted.
Additional details about the status of the file. If the file is in the error state, this will include a message describing the error.
{
"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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.list()
{
"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 can 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.
The file object (not file name) 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 file.
Use “fine-tune” for fine-tuning. This allows us to validate the format of the uploaded file is correct for fine-tuning.
The uploaded file object.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.create(
file=open("mydata.jsonl", "rb"),
purpose='fine-tune'
)
{
"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.
The ID of the file to use for this request.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.delete("file-abc123")
{
"id": "file-abc123",
"object": "file",
"deleted": true
}
get https://api.openai.com/v1/files/{file_id}
Returns information about a specific file.
The ID of the file to use for this request.
The file object matching the specified ID.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.File.retrieve("file-abc123")
{
"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 ID of the file to use for this request.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
content = openai.File.download("file-abc123")
Given 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.
The URL of the generated image, if response_format is url (default).
The base64-encoded JSON of the generated image, if response_format is b64_json.
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 number of images to generate. Must be between 1 and 10.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create(
prompt="A cute baby sea otter",
n=2,
size="1024x1024"
)
{
"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 number of images to generate. Must be between 1 and 10.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create_edit(
image=open("otter.png", "rb"),
mask=open("mask.png", "rb"),
prompt="A cute baby sea otter wearing a beret",
n=2,
size="1024x1024"
)
{
"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 number of images to generate. Must be between 1 and 10.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Image.create_variation(
image=open("otter.png", "rb"),
n=2,
size="1024x1024"
)
{
"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.
The model identifier, which can be referenced in the API endpoints.
The object type, which is always “model”.
The Unix timestamp (in seconds) when the model was created.
The organization that owns the model.
{
"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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.list()
{
"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 ID of the model to use for this request
The model object matching the specified ID.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.retrieve("gpt-3.5-turbo-instruct")
{
"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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.delete("ft:gpt-3.5-turbo:acemeco:suffix:abc123")
{
"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.
The unique identifier for the moderation request.
The model used to generate the moderation results.
A list of moderation objects.
{
"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-6,
"hate": 0.010696256,
"harassment": 0.29842457,
"self-harm": 1.5236925e-8,
"sexual/minors": 5.7246268e-8,
"hate/threatening": 0.0060676364,
"violence/graphic": 4.435014e-6,
"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
The input text to classify
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Moderation.create(
input="I want to kill them.",
)
{
"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-6,
"hate": 0.010696256,
"harassment": 0.29842457,
"self-harm": 1.5236925e-8,
"sexual/minors": 5.7246268e-8,
"hate/threatening": 0.0060676364,
"violence/graphic": 4.435014e-6,
"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 object identifier, which can be referenced in the API endpoints.
The object type, which is always “fine-tune”.
The Unix timestamp (in seconds) for when the fine-tuning job was created.
The Unix timestamp (in seconds) for when the fine-tuning job was last updated.
The base model that is being fine-tuned.
The name of the fine-tuned model that is being created.
The organization that owns the fine-tuning job.
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.
The list of files used for training.
The list of files used for validation.
The compiled results files for the fine-tuning job.
The list of events that have been observed in the lifecycle of the FineTune job.
{
"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 string of up to 40 characters that will be added to your fine-tuned model name.
For example, a suffix of “custom-model-name” would produce a model name like ada:ft-your-org:custom-model-name-2022-02-15-04-21-04.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.create(training_file="file-abc123")
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
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list()
{
"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}
The ID of the fine-tune job
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.retrieve(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
{
"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 ID of the fine-tune job to cancel
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.cancel(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
{
"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,
}
{
"object": "event",
"created_at": 1677610602,
"level": "info",
"message": "Created fine-tune job"
}
get https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events
Get fine-grained status updates for a fine-tune job.
The ID of the fine-tune job to get events for.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list_events(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
{
"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.
The object type, which is always edit.
The Unix timestamp (in seconds) of when the edit was created.
A list of edit choices. Can be more than one if n is greater than 1.
Usage statistics for the completion request.
{
"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.
The input text to use as a starting point for the edit.
The instruction that tells the model how to edit the prompt.
How many edits to generate for the input and instruction.
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.
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Edit.create(
model="text-davinci-edit-001",
input="What day of the wek is it?",
instruction="Fix the spelling mistakes"
)
{
"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
}
}