OpenAI API Basics

Chat Completions, responses API, tools, embeddings, and billing gotchas.

Interview tip Know message roles (system/user/assistant), token limits, structured outputs, and function calling flow.

① What you must know (30 sec)

The OpenAI API provides programmatic access to GPT models via Chat Completions (and newer Responses API), plus Embeddings, Images, Audio, and Batch endpoints. Core concepts: message roles (system, user, assistant, tool), token limits, function/tool calling, and structured outputs for reliable JSON.

Analogy: The API is a vending machine for intelligence — you insert tokens (paid), select the model SKU, and get formatted output if you specify the slot correctly.

② How it works

Function calling flow

User message→Model→tool_calls JSON→Your function→Tool result → final reply

Authentication — Bearer API key from platform.openai.com
Chat Completions — POST /v1/chat/completions with model + messages
Streaming — stream: true yields SSE token deltas for UX
Tools — pass tools[] schema; model may return tool_calls to execute
Embeddings — separate endpoint for vector generation; Batch API for async 50% off

gpt-4o and gpt-4o-mini are default choices in 2025 — verify current model IDs in OpenAI docs before hardcoding.

③ Step-by-step (hands-on)

Step 1 — Get API key and set env

export OPENAI_API_KEY=sk-... — use secrets manager in production. Set usage limits and alerts on dashboard.

Step 2 — First chat completion

messages=[{role:"system",...},{role:"user",...}]. Parse choices[0].message.content.

Step 3 — Add streaming

stream=True; iterate chunks for choices[0].delta.content. Handle [DONE] and connection drops.

Step 4 — Implement tool calling

Define tools array; if message.tool_calls, run functions, append role:"tool" messages, call API again.

Step 5 — Structured outputs

Use response_format json_schema for guaranteed schema compliance on supported models.

Step 6 — Monitor usage

Log response.usage.prompt_tokens and completion_tokens. Aggregate daily cost per feature.

④ Code / config patterns

Endpoint	Use case	Cost note
Chat Completions	Interactive chat, agents	Per input + output token
Embeddings	RAG indexing	Cheaper per token than chat
Batch API	Offline eval, bulk jobs	~50% discount, 24h window
Images / Audio	Multimodal products	Separate pricing table
Fine-tuning	Custom model weights	Training + inference premium

from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user", "content": user_input}
    ],
    tools=TOOLS,  # optional
    response_format={"type": "json_schema", "json_schema": SCHEMA},
    max_tokens=1024,
    temperature=0.2
)
text = response.choices[0].message.content
usage = response.usage

⑤ Production & pitfalls

Pitfall	Why it hurts	Fix
Exposed API key	Account drained by bots	Backend only; rotate key if leaked
No max_tokens cap	Runaway completion cost	Set max_tokens per request type
Ignoring 429 errors	Cascading failures	Exponential backoff; request queue
Wrong message role order	Confused multi-turn context	Alternate user/assistant; tool after assistant tool_calls
Parsing JSON from free text	Fragile pipelines	Use structured outputs / json_schema mode
Not counting tokens pre-call	Context overflow errors	tiktoken estimate; trim or summarize history

Production tips:

Organization-level API keys per environment
Idempotency keys for payment-critical flows if supported
Fallback model (4o-mini) when flagship model overloaded
Redact PII before sending to API

⑥ Interview / on-the-job Q&A

Question	Answer
Message roles?	system (instructions), user, assistant (model), tool (function results).
What is max_tokens?	Cap on tokens the model generates in the response — controls cost and length.
Function calling flow?	Model returns tool_calls → you execute → send tool message → model final answer.
Batch API benefit?	~50% cheaper for non-urgent jobs completed within 24 hours.
Structured outputs?	JSON schema enforcement so output always matches your schema.
How estimate cost?	prompt_tokens + completion_tokens × price per 1M tokens for model tier.

⑦ Tools & ecosystem

SDK: openai Python/Node official library
Token counting: tiktoken
Proxies: LiteLLM, Portkey
Dashboard: platform.openai.com usage & limits

openaiapifunction-callingtokensstructured-output

⑧ Revision checklist

API key in env var, not source code
Usage limits and billing alerts set
max_tokens configured per endpoint
Streaming implemented for user-facing chat
429/5xx retry with backoff
Token usage logged per request
Structured outputs for JSON pipelines
Tool calling loop tested end-to-end
Model IDs verified against current docs