OpenAI combined a powerful AI model and a chatbot experience—and the rest is history. But ChatGPT may not be best for your workflow, especially when you want to automate your AI prompts with complete flexibility.
With the OpenAI API, you can send your requests directly to OpenAI’s AI models. You’ll get the responses straight inside your software or platform of choice, so you can store, use, or combine that data—and even pull it into your own product, so your customers can have the power of OpenAI inside your app.
This complete guide explores all the features of the OpenAI API. There’s also a step-by-step guide on how to use the OpenAI API—including how to create an OpenAI API key—and start integrating it into your apps.
Before you begin: How to use an API
If you have a basic understanding of how software works, you’ll have an ok time following this API connection tutorial. If not, you may need a few extra resources.
I’d suggest starting with Zapier’s article on how to use an API to understand how methods, calls, and responses work. On top of that, look up (or ask ChatGPT) what JSON is and how it helps computers communicate over APIs without errors. Don’t worry—It’s not code: it’s simply a data notation language.
If APIs and JSON are familiar concepts to you, let’s begin.
Table of contents:
What is the OpenAI API?
The OpenAI API is an interface that offers connectors between OpenAI’s AI models and your apps. When you call the API endpoints, you can pass your instructions—often with deeper settings than a ChatGPT prompt—and get the response back on the platform you’re using to make the call. The features available, instructions, and results will vary depending on the model and endpoint you want to use.
Right now, the OpenAI API gives access to the following flagship models:
-
GPT-4o, the fastest and most affordable multimodal model
-
GPT-4, the previous high-intelligence model
-
GPT-3.5 Turbo, a fast model for simpler tasks
But that’s not the end of it. OpenAI also has models that’ll help you with image generation, speech recognition, or running complex tasks with simple agents.
What can you do with the OpenAI API?
GPT-4o (multimodal)
OpenAI’s newest model, GPT-4o, is multimodal, which means it can take in multiple data types, including text, audio, and images. It can read text, hear audio, and see images with impressive accuracy, and it can also respond with any combination of media depending on the request.
Text generation
Beyond GPT-4o, OpenAI has two models that focus on text generation.
For basic reasoning tasks and simple questions, GPT-3.5 Turbo offers a fast, cost-effective option when you need to analyze text, do a quick sentiment analysis, or categorize data.
If you need more intelligence, GPT-4 used to be the go-to model for higher-quality reasoning and responses. However, with the release of GPT-4o, this model is no longer the fastest, most intelligent, or most efficient.
Function calling
Function calling lets AI models use tools and interact with other APIs to run actions across external systems. For example, when you ask ChatGPT to visit a website in the chat, the model uses function calling to run a search and get the results.
When configured correctly, you can update data, run logic, or start complex workflows in any system you have access to, making it easier to automate actions across your work apps or enterprise platforms.
Function calling is available for both GPT-4o and GPT-4 models.
Embeddings
Embeddings help AI models understand the context of a prompt, improving the output quality. For example, if you’re creating an AI text adventure, you can run a request to the embeddings API for the words “forest,” “wolves,” and “treasure.” Then, when the user asks to continue the story, and you pass those embeddings with the prompt, the story will include those three elements instead of others.
Fine-tuning
Fine-tuning is training a GPT model with your data, so you can use it for more specific tasks. This adjusts the entire model based on your dataset, meaning you don’t have to use long system instructions or prompts to get the best results. It’s an expensive and time-consuming process reserved for machine learning professionals—or perhaps a very persistent and resourceful techie like you?
Image generation
DALL·E 3, the latest version of OpenAI’s image generator, can take a text prompt and turn it into any kind of image you’d like. Its predecessor, DALL·E 2, also has basic image editing abilities and can create variations of an original image.
Text-to-speech and speech-to-text
Here, GPT-4o can reliably run both tasks, but it may be too expensive to use it. If you’re looking for more efficiency, you can use the regular TTS model for performance tasks and TTS HD for higher-quality results.
Speech recognition
If you need to detect speech or language and translate what’s being said, the Whisper model can help. While there’s an open source version you can use on your infrastructure, the OpenAI API offers better performance.
Moderation
Running a community? You can use the moderation API to analyze user-generated content and score it for categories such as hate, threat, self-harm, or violence. The API returns a score you can bring into your system to flag offensive messages or automatically hide them.
Assistants
OpenAI Assistants are almost AI agents: they can run tasks that involve function calling, code interpretation, and file search. Using a thread to collaborate with the user or other assistants, they’ll keep moving forward until they meet the objective.
Find inspiration in the OpenAI library
OpenAI has an example library with prompts you can copy or tweak depending on your needs. Here are some prompt examples you’ll find there:
Brainstorm new use cases in the OpenAI playground
Prompt engineering is a fundamental part of interacting with the OpenAI API. Optimizing the prompts you’re passing in the API call will improve the output quality. The OpenAI Playground can help you brainstorm the best system instructions, and it offers advanced tools to help you change elements:
-
Temperature changes the model’s creativity level
-
Frequency penalties determine how varied should the responses be
-
Presence penalties control how much the model will stay on topic
It’s not just about playing with the generative models. You’ll be able to access other features such as the Assistants playground, the fine-tuning interface, and file storage, among other things. Take a look at the left-side menu to see everything.
Spend some time running your experiments here. Once you find a collection of prompts that give you consistent results, start saving them in a document. You’ll need to input them as part of the API call—which I’ll get into very soon.
OpenAI API pricing
The OpenAI API runs a pay-as-you-go pricing structure. This means that you get charged based on the content type, length, or task that you pass on to an AI model, as well as the output it generates.
Here’s the gist of the pricing so you know what to expect.
OpenAI API pricing for text generation
Pricing is done by million tokens (around 750,000 words), with different pricing for input and output.
-
GPT-4o: input at $5 per million tokens, output at $15 per million tokens.
-
GPT-3.5 Turbo: input at $0.50 per million tokens, output at $1.50 per million tokens
GPT-4o computer vision pricing
This is the model that can “see” images. Pricing is by image size and resolution, with each 768×768 image costing $0.003825.
OpenAI API embedding pricing
Large embedding tasks will cost you $0.13 per million tokens.
OpenAI API fine-tuning pricing
Fine-tuning a GPT-3.5 model will cost $8 per training with a million tokens, $3 for input, and $6 for output.
OpenAI API pricing for image generation
Each DALL·E 3 HD image at the highest resolution will cost you $0.12.
OpenAI API pricing for audio
Whisper costs $0.006 per minute of audio processed. TTS standard goes for $15 and TTS HD for $30, both per million characters (not tokens).
OpenAI Assistants API pricing
Here you’ll pay per task, with each code interpreter run costing $0.03 per session and file search costing $0.10 per vector-storage GB.
Managing your OpenAI billing and credits
To connect to these models and run tasks, you need to add a payment method and buy credit in advance. Then, as you run calls with your API key, you’ll see the costs on your OpenAI account page, and your balance will be reduced according to usage.
How to set up OpenAI API connections
Grab some snacks, set your phone to Do Not Disturb, and let’s start cooking.
-
Create an OpenAI account
-
Create a project (optional)
-
Generate a new OpenAI API key
-
Add credits to your OpenAI account
-
Open the API documentation and reference
-
Build a new request
-
Set up authorization with your API key
-
Pass your prompts
-
Add more details to the request
-
Integrate it with your apps
Step 1: Create an OpenAI account
If you haven’t already, go to the OpenAI platform, and create an account.
Step 2: Create a project (optional)
You’re logged in. Before we move to grabbing our API keys, you can organize them by project if you’d like. This lets you collaborate with your team, set custom billing limits, and have better visibility over usage.
If you want to use this feature, on the top left of the screen, click Default project and then Create project. (You can also access the Organization overview page from here.)
Step 3: Create an OpenAI API key
Since the OpenAI API isn’t free, you need to create an API key so the platform knows who you are and who to bill the work to. To generate an OpenAI API key, look to top-right side of the screen, and click Dashboard.
This is the OpenAI Playground that I mentioned before. It has all the tools for testing and developing with the OpenAI API. After you read the welcome message pop-up, you can click Get Started to continue.
Close the pop-up. On the left-side menu, click API keys.
On the top right of the screen, click Create new secret key. Note: you can only create an API key once you verify your account with your phone number.
A pop-up appears with your API key settings. I’ll walk you through all of these in just a second.
On the Owned by radio buttons, choose one:
-
You is better for personal use. Check this option if you’re going to be the only person making API calls. It’s useful for integrating the OpenAI models with other apps you use that support API connections.
-
Service account is for team or organizational use. This adds more security layers on the OpenAI platform, so it’s suitable if multiple people will be using this key for API calls through the app you’re building.
Very important: Regardless of the settings here, you need to keep this API key safe at all times. If someone finds your key, they could use it themselves, consuming credits, ruining training jobs you have going on, or even using it as an attack vector if you have OpenAI Assistants plugged into your systems. If this happens, you can discard the affected key and generate a new one. Don’t share this key with anyone who doesn’t need it, and if you’re publishing an app to the public web, be sure to read up on your API security best practices.
Under Name, give your API key an appropriate name or service name ID.
If you created a project to manage your API keys, click the dropdown to select it. Otherwise, you can leave it on its default setting.
The last setting lets you adjust the Permissions this key has:
-
All gives full access to all API features.
-
Restricted lets you choose which models and tasks this key has access to. For example, if you’re only using text generation, you can set Model capabilities to Write and all others to None.
-
Read only blocks all writing requests, which is useful for pulling data into external systems.
Consider setting it to the lowest privilege level necessary to do what you need.
Once you’ve adjusted these settings, click Create secret key, and the platform will generate one for you. You won’t be able to see this key again: copy and paste it to a safe place for now, and consider disposing of it after you’ve set up the call in the next step.
Once you click Done, the new key is added to the list. You can always delete or edit the name or permissions going forward.
Step 4: Add credits to your OpenAI account
You won’t be able to use the API if you don’t add a few credits. On the top right of the screen, click the cogwheel icon to go to the Settings page.
On the left-side menu, click Billing.
Follow the instructions to add a payment method: they’re very similar to every other SaaS app you use. I bought $10 worth of credits to play around—you can do the same if you’d like.
Once complete, you’ll see your pay-as-you-go credit on the page.
Click the Dashboard link on the top right to go back to the OpenAI platform.
Step 5: Open the API documentation and reference pages
Making and structuring the API call varies based on the API features that you want to use. To understand how to proceed, you need to find:
Leveraging everything the API offers means you’ll have to become familiar with these pages over time. Always remember to come back and read a bit more if you’re running into trouble or brainstorming a new use case.
You can navigate back and forth between the documentation and API reference by using the links at the top right of the screen.
For this example, I want to use the chat completions endpoint, so I’m going to navigate to the corresponding page in the API reference. First, we need to copy the endpoint URL () and make a mental note of the HTTP method, which in this case is POST.
Step 6: Build a new request
To help you grasp how this works, I’ll be using Postman, an API design platform, to make a call asking for a text generation task. But you can replicate the steps whether you’re using code, an internal tool builder, or a no-code app builder.
If you want to follow along, create a free account in Postman. After logging in to the dashboard, on the New API Request tab, click New Request.
Paste the endpoint URL on the large input field at the top. Also click the dropdown displaying the GET method, and change it to POST.
Postman will offer to set up quick authentication for OpenAI: I recommend you skip this part for the sake of learning. Later, you can use all the shortcuts you want to save time.
Learning through mistakes, part 1
Setting up new API calls is more hike up a mountain than stroll on the beach: it takes effort and trial and error to make it to the top. Let’s go step by step and make a few mistakes to understand how to handle obstacles. Click the Send button, and see what happens.
We have an error: HTTP 401 Unauthorized means we don’t have authorization to call this endpoint. On the console at the bottom of the screen, you’ll see the OpenAI API platform returns an informative error message: we haven’t passed our secret API key. The platform doesn’t know who we are or who to bill the generation work to.
Step 7: Set up authorization with your OpenAI API key
Whenever you run into an error, the next best action to take is to go back to the API reference and documentation to understand how to fix it. In this case, we need to take a look at the API authorization page.
On this page, OpenAI explains how to authenticate with the API endpoint.
Postman has a dedicated tab for authentication: under the endpoint input field, click Authorization.
Expand the Auth Type dropdown and click Bearer Token. (We know it’s a bearer token because of the “Authorization: Bearer OPENAI_API_KEY” rule from the documentation two images above.)
To the right of this dropdown, paste the secret API key that you got before.
Learning through mistakes, part 2
That should solve authentication. Let’s keep teasing the OpenAI API to learn how it works. Click the Send button again.
Oops. Look at the response below the request.
We’re authenticated, but we still got an HTTP 400 Bad Request error: this means we didn’t pass a request to the platform, or that our request misses mandatory parameters—in this case, the error message says we didn’t choose an AI model. But that’s not the only thing we didn’t choose: we also passed an empty request.
The API reference page has a request template we can use to solve this error. Back on the OpenAI create chat completion API reference page, take a look at the right side.
This request includes cURL for people using a command line to send and receive data from servers. Here’s a breakdown of what this example means:
curl \
The cURL command followed by the endpoint link starts the command line connection to the endpoint URL. The backslash at the end here is to change the line for readability; it has no impact on the request.
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
The lines prefixed with -H flags are the request headers. These give additional context to the receiving server, letting it know how to process this call. In this case, we have the “Content-Type: application/JSON”, which tells what kind of data we’ll be passing and the “Authorization: Bearer”, where you’d insert your API key for authentication. Since I’m using Postman, I don’t need these headers. But depending on which platform you’re using to make the call, you may need to pass them.
-d '{
"model": "gpt-3.5-turbo-16k",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
}'
Finally, the -d flag prefixed line shows the request’s data, also known as body or payload. Everything that follows this tag is written in JSON.
I’m going to copy the body of the request without the -d flag or the single quotes at the beginning and end. Be careful when copying: if a single character is missing or is added, the call will return an error.
Back in Postman, click on the Body tab. Then, on the radio selectors below, choose raw. Click on line 1 and paste the JSON there.
When that’s done, click the Send button.
If you’ve followed all the steps to the letter until now, you’ll see an HTTP 200 OK status code: your request was received and sent to the selected OpenAI model, and you’ve got a response.
I’ve highlighted the status code as well as the reply I got from the AI model.
Note: Every request you’re sending now consumes credit based on token usage.
Step 8: Pass your prompts
Ok, you can now send data to an OpenAI model via the API. But this isn’t useful if you can’t pass your own prompts, so let’s change the values in the JSON body. Let me highlight the request values you can change:
Here’s what each of these do:
-
“model”: lets you select which AI model you want to use. In my example, I’m using GPT-3.5 Turbo (gpt-3.5-turbo-16k). You can select other models by writing their system name in the value field—for example, “gpt-4-turbo”. See the full model list here.
-
“messages”: determines what you’re sending to the selected model. In this case, there are two sets of messages you’re sending:
-
“role”: “system”, is used to pass the system instructions to the model, controlling how it’s going to behave (like the instructions when building a new GPT). “content”: “You are a helpful assistant” determines the system message. You can change the text in bold; leave all others as they are.
-
“role”: “user”, labels the following “content”: “Hello!” pair as what the user is passing to the model. This is the equivalent of writing your prompt down in ChatGPT. You can change that text, but leave all others as they are.
-
With this info, let’s make changes to the instructions and user message. Here’s what I did: