Your First API Call | Getting Started with the OpenAI API

A junior developer at a fintech startup was asked to prototype a feature that summarizes transaction descriptions. She opened the OpenAI docs, copied a curl example, replaced the prompt, hit enter -- and got back a perfect summary in 200 milliseconds. Then her manager asked her to make it more concise, use JSON output, and stop after three sentences. She stared at the parameter list and froze. The difference between a hello-world API call and a production-quality one is knowing what every parameter does and when to use it.

The Chat Completions Endpoint

The core endpoint is POST /v1/chat/completions. Every call requires two things: a model and a messages array. Everything else is optional.

Python

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a concise technical writer."},
        {"role": "user", "content": "Explain HTTP status codes in 3 sentences."}
    ]
)

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

That is a complete, working API call. Let's break down every piece.

Message Roles: The Conversation Protocol

The messages array is how you communicate with the model. Each message has a role that tells the model who is speaking and how to treat the content.

Sets the model personality, tone, and behavioral constraints. Placed first in the messages array. The model treats system messages as persistent instructions that apply to the entire conversation. Example: You are a medical assistant. Never provide diagnoses. Always recommend consulting a doctor for serious symptoms.

Here is a multi-turn conversation showing how roles work together:

Python

messages = [
    {"role": "system", "content": "You are a Python tutor. Keep explanations beginner-friendly."},
    {"role": "user", "content": "What is a list comprehension?"},
    {"role": "assistant", "content": "A list comprehension is a compact way to create a new list by transforming each item in an existing list. Instead of writing a for loop..."},
    {"role": "user", "content": "Can you show me an example with filtering?"}
]

Notice: you are replaying the entire conversation each time. The API is stateless -- it has no memory between calls. Every request must contain the full context the model needs.

Concept Card

Essential Parameters

Beyond model and messages, these parameters give you fine-grained control:

temperature (0.0 - 2.0, default varies by model)

Controls randomness. Lower values make the model more deterministic and focused. Higher values make it more creative and varied.

Python

# Factual extraction -- low temperature
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "What is the boiling point of water in Celsius?"}],
    temperature=0.0  # deterministic
)

# Creative writing -- higher temperature
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Write a haiku about debugging."}],
    temperature=1.2  # more creative variety
)

Use temperature 0-0.3 for factual tasks, data extraction, and code generation. Use 0.7-1.0 for general conversation. Use 1.0-1.5 for creative writing and brainstorming.

Don't

Set temperature above 1.5 unless you specifically want chaotic, unpredictable output. At 2.0, the model output becomes nearly incoherent for most tasks.

max_tokens / max_completion_tokens

Limits the length of the model's response. This is a hard ceiling -- the model will stop generating once it hits this limit, even mid-sentence.

Python

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Explain quantum computing."}],
    max_tokens=150  # short, focused response
)

Token vs. Word

A token is roughly 3/4 of a word in English. "Explain quantum computing" is 3 words but 4 tokens. The word "authentication" is 3 tokens. JSON and code tend to use more tokens per character than prose. Use OpenAI's tokenizer tool to check exact counts for your specific prompts.

top_p (0.0 - 1.0, default 1.0)

Nucleus sampling -- an alternative to temperature for controlling randomness. A top_p of 0.1 means the model only considers tokens in the top 10% probability mass.

Important: OpenAI recommends adjusting either temperature or top_p, not both at the same time. They interact in unpredictable ways.

stop

A string or array of strings that cause the model to stop generating when encountered:

Python

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "List 3 programming languages:"}],
    stop=["4."]  # stop before a 4th item
)

response_format

Forces the model to output valid JSON:

Python

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Return the top 3 Python web frameworks as JSON with name and year fields."}],
    response_format={"type": "json_object"}
)

When you set json_object, the model guarantees syntactically valid JSON. For even stronger guarantees, use json_schema with a schema definition -- the model will conform to your exact structure.

The 3 AM Production Incident

Putting It All Together

Here is a production-quality call that uses all the key parameters:

Python

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "system",
            "content": "You are an API that extracts structured product data. Return JSON only."
        },
        {
            "role": "user",
            "content": "Extract: 'The Nike Air Max 90 in white/black, size 10, retails for $130'"
        }
    ],
    temperature=0.0,
    max_tokens=200,
    response_format={"type": "json_object"}
)

product = json.loads(response.choices[0].message.content)

Always Check finish_reason

The finish_reason field tells you why the model stopped. "stop" means it finished naturally. "length" means it hit your max_tokens limit and was cut off mid-response. Always check this in production -- a truncated JSON response will crash your parser.

Parameter Playground

beginner