The OpenAI API - Getting Started

Why the OpenAI API?

OpenAI's API is the most widely used AI API in the world. It provides access to models like GPT-4o, GPT-4, and GPT-3.5 Turbo through a clean, well-documented interface. Understanding the OpenAI API gives you skills that transfer directly to other providers like Anthropic (Claude) and Google (Gemini), since they all follow similar patterns.

As an AI Automation Engineer, you will likely use the OpenAI API or one of its alternatives as the core intelligence in most of the systems you build.

Setting Up Access

Step 1: Create an OpenAI account

Go to platform.openai.com and create an account. You will need to add a payment method before making API calls.

Step 2: Generate an API key

In the OpenAI dashboard, navigate to API keys and create a new secret key. Copy it immediately -- it will not be shown again.

Step 3: Set up your environment

Store your API key as an environment variable, never hardcoded in your scripts:

# On macOS or Linux (add to .bashrc or .zshrc)
export OPENAI_API_KEY="sk-your-key-here"

# On Windows Command Prompt
set OPENAI_API_KEY=sk-your-key-here

Step 4: Install the OpenAI SDK

The official Node.js SDK:

npm install openai

The official Python SDK:

pip install openai

Your First API Call (Node.js)

// Run in Node.js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function main() {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'user', content: 'What are the three laws of robotics?' }
    ],
  });

  console.log(response.choices[0].message.content);
}

main();

Understanding the Chat Completions Endpoint

The primary endpoint for conversational AI is /v1/chat/completions. It accepts a list of messages in a conversation format.

The messages array

Messages use three roles:

system -- Sets the behaviour and persona of the assistant for the entire conversation.

{ "role": "system", "content": "You are a concise technical writer who explains complex concepts simply." }

user -- Messages from the human (or your application acting as the user).

{ "role": "user", "content": "Explain what a neural network is." }

assistant -- Previous responses from the model. Include these to maintain conversation history.

{ "role": "assistant", "content": "A neural network is a system inspired by the human brain..." }

Multi-turn conversation example:

const messages = [
  { role: 'system', content: 'You are a friendly coding tutor.' },
  { role: 'user', content: 'What is a variable?' },
  { role: 'assistant', content: 'A variable is a named container that stores a value in your program.' },
  { role: 'user', content: 'Can you give me a JavaScript example?' },
];

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: messages,
});

By including the conversation history in the messages array, the model maintains context across turns. This is how chatbots remember previous parts of a conversation.

Understanding the Response Object

The API returns a structured JSON response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1719000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A neural network is a computational model..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 120,
    "total_tokens": 145
  }
}

Key fields to understand:

• choices[0].message.content: The actual text response from the model
• choices[0].finish_reason: Why the model stopped generating. "stop" means it finished naturally. "length" means it hit the token limit.
• usage.total_tokens: How many tokens were used (which determines your cost)

Available Models

OpenAI offers several models at different price and capability points:

For most production AI automation systems, gpt-4o-mini offers the best balance of capability and cost. Use gpt-4o when the task is complex enough to require it.

Error Handling

Production API calls must handle errors gracefully:

// Run in Node.js
import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function callWithRetry(messages, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await client.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: messages,
      });
      return response.choices[0].message.content;
    } catch (error) {
      if (error.status === 429) {
        // Rate limited -- wait and retry
        const waitMs = Math.pow(2, attempt) * 1000;
        console.log('Rate limited. Waiting ' + waitMs + 'ms before retry ' + attempt);
        await new Promise(resolve => setTimeout(resolve, waitMs));
      } else if (error.status === 500) {
        // Server error -- retry
        console.log('Server error. Retrying attempt ' + attempt);
      } else {
        // Non-retryable error
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Streaming Responses

For long responses, streaming sends tokens as they are generated rather than waiting for the full response. This dramatically improves the user experience in chat applications:

// Run in Node.js -- streaming example
const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a short story about AI.' }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(delta); // Print each token as it arrives
}

Tracking Costs

Every API call costs money based on tokens used. Monitor your usage:

• Set a monthly budget limit in the OpenAI dashboard
• Log token usage in your application
• Estimate costs before deployment using the OpenAI token calculator
• Optimise prompts to reduce unnecessary token usage (shorter system prompts, fewer examples)

A rough cost benchmark: with gpt-4o-mini, processing 1 million input tokens costs approximately $0.15, making it very affordable for most automation use cases.

Practice Exercise

Write a Node.js script that:

1. Accepts a topic from the command line as an argument
2. Calls the OpenAI API to generate a three-sentence summary of that topic
3. Prints the summary to the console
4. Also prints the number of tokens used

Key Takeaways

• The OpenAI API's primary endpoint is /v1/chat/completions, which accepts a messages array with system, user, and assistant roles.
• Maintaining conversation history requires including previous messages in the messages array -- the model has no memory between API calls.
• Always store API keys in environment variables, never hardcoded in source files.
• Handle errors and rate limits with retry logic and exponential backoff to build resilient production systems.
• Choose your model based on task complexity and cost requirements -- gpt-4o-mini is the best balance for most automation tasks.