Access the OpenAI API with curl

This is a simple tutorial that shows you how to access the OpenAI API with curl, an easy-to-use command line tool. A first step towards integrating LLMs into your programs.

Image generated with Midjourney

In the realm of Artificial Intelligence, accessing LLM (Large Language Models) APIs has become a critical skill for developers looking to leverage the power of advanced natural language processing. This guide will walk you through the steps of using curl, a command-line tool, to interact with these APIs, particularly focusing on how to make requests to retrieve embeddings for phrases and answers to prompts in a conversational manner.

What are LLM APIs?

LLM APIs provide programmatic access to large language models, such as those developed by OpenAI (e.g. GPT-4) or Google (e. g. Gemini Pro). These APIs allow you to perform a variety of NLP tasks, including generating text, translating languages, summarizing content, and more, by simply sending HTTP requests.

Before diving into the technical details, it's important to note that accessing LLM APIs is not free. These services usually operate on a pay-as-you-go model, where costs are incurred based on the amount of data processed or the number of requests made. Always check the pricing details on the provider's website to understand the costs associated with using their API.

Please note that OpenAI has announced that you will need to pre-purchase credits to use the API from 8 March 2024.

What is curl?

Curl is a command-line tool used for transferring data with URLs. It supports a multitude of protocols, making it a versatile tool for interacting with APIs over the internet. Its simplicity and wide availability on various operating systems make it an excellent choice for quick API testing and automation tasks.

Curl is usually pre-installed. You can verify by typing curl --version in your terminal on Unix-based systems like macOS or Windows Subsystem for Linux (WSL)¹.

API key

Once logged in, navigate to the API section and generate a new API key. This key will authenticate your requests to the API.

Source: https://platform.openai.com/docs/overview

As you will no longer have access to the API key on the OpenAI website, I recommend that you save it in a safe place.

Open the terminal app on your Mac or a shell on your Windows system with WSL installed by visiting the Windows Start menu and typing the name of your installed distributions. For example: "Ubuntu". This will open Ubuntu in its own console window.

To keep your key secure and easily referenceable, use an environment variable². On Unix-based systems like macOS or WSL, you can do this by running:

export OPENAI_API_KEY='your_api_key_here'

Get a list of all available models

Use curl to Send a Request: Let's start with retrieving an list of all available. The environment variable $OPENAI_API_KEY is automatically replaced by the value you assigned with export.

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Organization: org-rMiY5wajJGtAGj0G4fbkHxcn" 

This returns a list of models:

{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "model",
      "created": 1698785189,
      "owned_by": "system"
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1705953180,
      "owned_by": "system"
    },
    ...
}

Here you can find more information about the models provided by OpenAI.

Create an embedding

Now let’s use the text-embedding-3-large model to embed the text “Hello, world!”.

curl -X POST \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input": "Hello, world!", "model": "text-embedding-3-large"}' \
  https://api.openai.com/v1/embeddings

This returns a vector with the embedding:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.005830363,
        -0.024080755,
        -0.02201979,
        ...
     }
   ]
}

Here you can find more information about embeddings.

Crate an image

And finally, let's use the model dall-e-3 to generate an image.

curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "a fluffy black cat",     
    "n": 1,
    "size": "1024x1024"
  }'

You will receive a download link:

{
  "created": 1709557575,
  "data": [
    {
      "revised_prompt": "Imagine a black cat in all its glory. The cat's coat is the colour of the darkest midnight, truly captivating. This feline's fur is remarkably fluffy, with each strand catching the light to show off an array of silken textures. The cat carries itself with dignity and poise, ears pointed upright in a perfect showcase of feline alertness. Its tail sways hypnotically back and forth, like a plume of dark smoke dancing in the wind. This cat is truly a sight to behold, an embodiment of grace and soft fluffiness.",
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-rMiY5wajJGtAGj0G4fbkHxcn/user-b3sdUEUeR0iriTump2uUkRLc/img-XGzvsSM9uuwkvbKT6pxkJYqm.png?st=2024-03-04T12%3A06%3A15Z&se=2024-03-04T14%3A06%3A15Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2024-03-04T13%3A01%3A08Z&ske=2024-03-05T13%3A01%3A08Z&sks=b&skv=2021-08-06&sig=%2B2tLFxFcyndSIZB9AdZRHuEvytEK31f97HY0z6fjkPk%3D"
    }
  ]
}

Copy the link and download the image with the browser.

Image created with Dall-E 3

API, Documentation, and Reference

For a comprehensive understanding of what you can achieve with the OpenAI API, it's crucial to consult the official documentation. This will offer insights into the various parameters, limits, and features available, enabling you to tailor your requests to suit your specific needs.

In summary, accessing LLM APIs using curl is a straightforward process that opens up a world of possibilities in the domain of natural language processing. Whether you're building applications that interact with users in natural language, analyzing text, or automating content creation, mastering this skill is a valuable addition to your development toolkit.

Go further

Now you can integrate API requests into your calls. OpenAI offers SDKs that allow you to access the API more conveniently in Python or Node.js. There are also several community libraries for other languages.

1. Follow the instructions here to install WSL: https://learn.microsoft.com/en-us/windows/wsl/install

2. Unless you store the assignment in a shell script this assignment will be lost. For permanent storage I recommend to store the key in a safe place.