OpenAI: Platform Overview and Developer Guide
What you’ll learn
Section titled “What you’ll learn”- How the OpenAI platform is structured across model tiers, the API, and end-user products.
- The difference between GPT chat models, o-series reasoning models, and specialized models for embeddings and audio.
- How to pick the right model for a given task based on cost, speed, and capability.
- Key platform features: structured outputs, function calling, and the Assistants API.
Summary
Section titled “Summary”OpenAI is the company behind the GPT model family, the o-series reasoning models, DALL·E image generation, and the ChatGPT products. For developers, the most relevant part of OpenAI is the platform API at platform.openai.com, which provides programmatic access to all current models.
The API uses a pay-as-you-go token pricing model. Models are accessed via REST API or through official SDKs for Python, Node.js, and other languages. The OpenAI Python SDK (openai) is the most common entry point.
The OpenAI stack
Section titled “The OpenAI stack”OpenAI is easier to reason about if you separate it into distinct layers:
| Layer | What it includes |
|---|---|
| End-user products | ChatGPT (browser and mobile), ChatGPT Team and Enterprise |
| Developer API | REST API at api.openai.com, official SDKs, usage dashboard |
| Chat and completion models | GPT-6, GPT-6.1, GPT-4o, GPT-4o mini |
| Reasoning models | o3, o4-mini — slow, deliberate chain-of-thought reasoning |
| Embedding models | text-embedding-3-large, text-embedding-3-small |
| Audio models | Whisper (transcription), TTS (text-to-speech) |
| Image models | DALL·E 3 and later image generations |
The model tiers
Section titled “The model tiers”Chat and completion models accept messages and return completions. They are optimized for speed and low cost per request:
| Model | Characteristics | Best for |
|---|---|---|
| GPT-6 (Astra, Sol) | Frontier capability, higher cost | Complex multi-step tasks, highest quality |
| GPT-6.1 (Terra) | Balanced cost and capability | General-purpose applications |
| GPT-4o | Mature, well-tested | Production workloads with proven reliability |
| GPT-4o mini | Fast and cheap | High-volume extraction, classification, routing |
Reasoning models (o3, o4-mini) operate differently — they spend extra compute on a long internal chain of thought before returning a response. This makes them significantly slower and more expensive per request, but substantially better at problems that require deductive reasoning, mathematics, and multi-step planning.
Use an o-series model when:
- The problem requires explicit logical deduction (mathematical proofs, formal verification)
- Multi-step planning where intermediate steps are consequential
- The correctness of the answer matters more than latency
Do not use reasoning models for:
- High-volume, low-latency requests (they are 5–20× slower than GPT-6)
- Simple extraction, classification, or summarization tasks (GPT-4o mini is better suited)
Making API calls
Section titled “Making API calls”Install the SDK:
pip install openaiA minimal chat completion call:
import openaiimport os
client = openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain the difference between o3 and GPT-6."}, ],)print(response.choices[0].message.content)Structured outputs
Section titled “Structured outputs”For applications that need deterministic JSON responses, OpenAI supports response_format with schema enforcement. This eliminates the need to parse or validate model outputs manually:
from pydantic import BaseModel
class OrderSummary(BaseModel): order_id: str total_amount: float status: str
response = client.beta.chat.completions.parse( model="gpt-4o", messages=[{"role": "user", "content": "Summarize order #A1234: $59.99, shipped."}], response_format=OrderSummary,)order = response.choices[0].message.parsedprint(order.order_id, order.total_amount, order.status)# A1234 59.99 shippedFunction calling
Section titled “Function calling”Function calling lets the model invoke tools you define — APIs, database queries, calculations. The model decides when to call a function and fills in the parameters:
tools = [ { "type": "function", "function": { "name": "get_order_status", "description": "Look up the current status of a customer order.", "parameters": { "type": "object", "properties": { "order_id": {"type": "string", "description": "The order ID to look up"}, }, "required": ["order_id"], }, }, }]
response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Where is my order A9876?"}], tools=tools,)
# If the model decides to call the function:tool_call = response.choices[0].message.tool_calls[0]print(tool_call.function.name) # get_order_statusprint(tool_call.function.arguments) # {"order_id": "A9876"}Your application handles the actual function call and passes the result back in the next message.
Embeddings
Section titled “Embeddings”Embeddings convert text into dense numeric vectors that capture semantic meaning. Two texts about the same concept will have vectors close together in the embedding space, even if they use different words. This is the foundation of semantic search and RAG systems:
response = client.embeddings.create( model="text-embedding-3-small", input="How do I cancel my subscription?",)vector = response.data[0].embedding # List of 1536 floatsUse text-embedding-3-large for applications where retrieval quality is the priority. Use text-embedding-3-small to reduce cost and storage for high-volume embeddings.
Choosing between OpenAI and alternatives
Section titled “Choosing between OpenAI and alternatives”| Consideration | OpenAI | Anthropic Claude | Google Gemini |
|---|---|---|---|
| Ecosystem maturity | Largest ecosystem of SDKs and integrations | Growing rapidly | Strong Google Cloud integration |
| Reasoning tasks | o3/o4 (strong) | Opus 5.5 (strong) | Gemini 2.5 Pro (competitive) |
| Context window | 128K–1M (model-dependent) | 1M | 1M |
| Code generation | Strong | Strong | Strong |
| Pricing | Competitive | Competitive | Competitive at scale |
| Data residency | US-based | US-based | US-based, GCP regions available |
For most applications the differences between frontier models from each provider are smaller than the differences between model tiers within a provider. Run a small benchmark on your specific task before committing to a provider.
Common mistakes
Section titled “Common mistakes”- Choosing a model by tier name rather than by task: GPT-6 is not always better than GPT-4o for every task. Measure on your workload.
- Using a reasoning model for simple tasks: o3 and o4-mini are expensive and slow. Use them only when deliberate multi-step reasoning is required.
- Hardcoding model names: Model IDs are versioned and change frequently. Pin to a specific snapshot (
gpt-4o-2024-11-20) or accept the latest via an alias and test after updates. - Ignoring token usage: Costs scale linearly with tokens. Log
usage.prompt_tokensandusage.completion_tokensfrom every response from day one.
Key takeaways
Section titled “Key takeaways”- OpenAI provides chat models (GPT-6, GPT-4o), reasoning models (o3, o4-mini), embeddings, and audio models through a single REST API.
- Reasoning models are slower and more expensive; use them only for tasks that require deliberate multi-step logical deduction.
- Structured outputs and function calling are the right tools for deterministic JSON responses and tool integration.
- Embeddings power semantic search and RAG systems;
text-embedding-3-largemaximizes retrieval quality.
Related pages
Section titled “Related pages”- OpenAI Models guide — full model matrix with context windows and pricing
- ChatGPT overview — ChatGPT features and use cases
- OpenAI API Key guide — creating and securing your API key
- RAG vs agentic RAG — using embeddings in retrieval pipelines
- LLM Model Selection — choosing between OpenAI, Anthropic, and Google
Official references
Section titled “Official references”- OpenAI Platform documentation — API reference and guides
- Models list — current model IDs, context windows, and pricing
- Structured outputs guide — JSON schema enforcement
- Function calling guide — tool use patterns
- Python SDK —
openaipackage on PyPI