OpenAI API Essentials

> The OpenAI API is one of the most widely used entry points into building LLM-powered products. This notebook covers the core endpoints, model lineup, and the practical patterns — function calling, structured output, streaming — you'll reach for in real applications.

What is the OpenAI API?

The OpenAI API gives programmatic access to OpenAI's models — GPT for text and reasoning, embeddings for retrieval, image and audio models for multimodal tasks. Rather than a chat interface, you get an HTTP API (with official SDKs for Python, JavaScript, and others) that you call from your own application code.

What it's typically used for:

Core Building Blocks

1. The Responses / Chat Completions API The main endpoint for text generation. You send a list of messages (system, user, assistant) and get a model-generated response back.

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what a vector database is in two sentences."},
    ],
)

print(response.choices[0].message.content)

2. Function (Tool) Calling The model can request that your code run a specific function, with arguments it fills in based on the conversation. You execute the function and send the result back.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in Bandung?"}],
    tools=tools,
)

tool_call = response.choices[0].message.tool_calls[0]
# tool_call.function.name == "get_weather"
# tool_call.function.arguments == '{"city": "Bandung"}'
# → run get_weather("Bandung"), then send the result back as a follow-up message

3. Structured Output Constrain the model's response to match a JSON schema exactly, useful for extraction tasks where downstream code needs guaranteed-valid JSON.

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Extract: John Doe, 34, Jakarta"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"},
                },
                "required": ["name", "age", "city"],
            },
        },
    },
)

4. Embeddings Convert text into vectors for semantic search, clustering, or retrieval pipelines (see [[rag-pipelines-essentials]]).

embedding = client.embeddings.create(
    model="text-embedding-3-small",
    input="How do I reset my password?",
).data[0].embedding

5. Streaming Receive tokens as they're generated instead of waiting for the full response — essential for responsive chat UIs.

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a short poem about the sea."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Model Selection

Always check current model names and pricing against OpenAI's documentation — the lineup changes frequently.

Common Use Cases

Best Practices

Key Takeaways

Resources