Sign in Subscribe
Featured

Unified API Design – A look at OpenAI‐Style Endpoints

Andrew Smalley

• 4 min read
Unified API Design – A look at OpenAI‐Style Endpoints

Introduction

In this article, I will examine OpenAI's API endpoints. Whose design has led many GPT providers to adopt similar structures and JSON payloads. I will cover the significant endpoints, showing example payloads for each, how to call them using Python and cURL, and what responses to expect.

You'll find practical examples if you build chatbots, text generators, or audio and image applications.

1. Models Endpoint

Purpose: List all available models.

Request Examples

cURL

curl -X GET "https://api.openai.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

url = "https://api.openai.com/v1/models"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Sample Response

{
  "object": "list",
  "data": [
    {
      "id": "text-davinci-003",
      "object": "model",
      "created": 1649364045,
      "owned_by": "openai",
      "permission": [ /* ... */ ]
    },
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "created": 1677649420,
      "owned_by": "openai",
      "permission": [ /* ... */ ]
    }
    // ... additional models
  ]
}

2. Completions Endpoint

Purpose: Generate text completions from a given prompt.

Request Examples

cURL

curl -X POST "https://api.openai.com/v1/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "model": "text-davinci-003",
        "prompt": "Explain the theory of relativity in simple terms.",
        "max_tokens": 100,
        "temperature": 0.7,
        "top_p": 1.0,
        "n": 1,
        "stop": "\n"
      }'

Python

import requests
import json

url = "https://api.openai.com/v1/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "model": "text-davinci-003",
    "prompt": "Explain the theory of relativity in simple terms.",
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 1.0,
    "n": 1,
    "stop": "\n"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

Sample Response

{
  "id": "cmpl-6a1XYZ",
  "object": "text_completion",
  "created": 1693256789,
  "model": "text-davinci-003",
  "choices": [
    {
      "text": "The theory of relativity, developed by Albert Einstein, explains how time and space are linked for objects moving at a constant speed in a straight line. It introduced the idea that time can vary for different observers depending on their velocity and gravity.",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 90,
    "total_tokens": 110
  }
}

3. Chat Completions Endpoint

Purpose: Handle multi-turn conversations by accepting a list of messages.

Request Examples

cURL

curl -X POST "https://api.openai.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "model": "gpt-3.5-turbo",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Can you explain how photosynthesis works?"}
        ],
        "max_tokens": 150,
        "temperature": 0.7,
        "top_p": 1.0,
        "n": 1
      }'

Python

import requests
import json

url = "https://api.openai.com/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "model": "gpt-3.5-turbo",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Can you explain how photosynthesis works?"}
    ],
    "max_tokens": 150,
    "temperature": 0.7,
    "top_p": 1.0,
    "n": 1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

Sample Response

{
  "id": "chatcmpl-7B2ABC",
  "object": "chat.completion",
  "created": 1693256890,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Photosynthesis is the process by which green plants, algae, and some bacteria convert light energy into chemical energy. They use sunlight to transform carbon dioxide and water into glucose and oxygen."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 40,
    "completion_tokens": 70,
    "total_tokens": 110
  }
}

4. Embeddings Endpoint

Purpose: Return vector representations (embeddings) of input text.

Request Examples

cURL

curl -X POST "https://api.openai.com/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "model": "text-embedding-ada-002",
        "input": "The quick brown fox jumps over the lazy dog."
      }'

Python

import requests
import json

url = "https://api.openai.com/v1/embeddings"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "model": "text-embedding-ada-002",
    "input": "The quick brown fox jumps over the lazy dog."
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

Sample Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0012, -0.0034, 0.0056, /* ... more numbers ... */],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Audio Transcriptions Endpoint

Purpose: Transcribe spoken audio into text.

Request Examples

cURL

For audio endpoints, you'll need to send multipart/form-data. For example, using a file named audio.wav:

curl -X POST "https://api.openai.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.wav" \
  -F "model=whisper-1" \
  -F "prompt=Transcribe the following audio."

Python

import requests

url = "https://api.openai.com/v1/audio/transcriptions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
files = {
    "file": open("audio.wav", "rb")
}
data = {
    "model": "whisper-1",
    "prompt": "Transcribe the following audio."
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Sample Response

{
  "text": "Hello, this is a sample transcription of the audio file."
}

6. Audio Translations Endpoint

Purpose: Transcribe and translate spoken audio into English text.

Request Examples

cURL

curl -X POST "https://api.openai.com/v1/audio/translations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.wav" \
  -F "model=whisper-1" \
  -F "prompt=Translate the following audio to English."

Python

import requests

url = "https://api.openai.com/v1/audio/translations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
files = {
    "file": open("audio.wav", "rb")
}
data = {
    "model": "whisper-1",
    "prompt": "Translate the following audio to English."
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Sample Response

{
  "text": "This is the translated English text from the audio file."
}

7. Image Generation Endpoint

Purpose: Generate images from a text prompt using a DALL·E–like model.

Request Examples

cURL

curl -X POST "https://api.openai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "prompt": "A surreal landscape with melting clocks, in the style of Salvador Dalí",
        "n": 1,
        "size": "1024x1024"
      }'

Python

import requests
import json

url = "https://api.openai.com/v1/images/generations"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "prompt": "A surreal landscape with melting clocks, in the style of Salvador Dalí",
    "n": 1,
    "size": "1024x1024"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

Sample Response

{
  "created": 1693257100,
  "data": [
    {
      "url": "https://openai-images.s3.amazonaws.com/abcd1234.png"
    }
  ]
}

Final Thoughts

Many GPT providers (including DeepSeek, Open-WebUI, and others) standardize OpenAI's API design, making it easier for developers to switch between services or integrate multiple models with minimal code changes. Whether you're generating text completions, handling multi-turn conversations, computing embeddings, or even transcribing audio and generating images, the example payloads above provide a complete reference to get you started.

Feel free to adapt these examples for your projects, and remember to always refer to the latest official documentation since APIs are evolving rapidly.

Happy coding!