Your First LLM API Call

A key, an account, and a model name are all you need to get text back. The first call matters because it teaches the contract you will reuse in every later integration: what you send, what comes back, and what each piece costs you. Send it over raw HTTP before reaching for an SDK so nothing hides the payload.

The request

import httpx, os

response = httpx.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": "Bearer " + os.environ["OPENAI_API_KEY"]},
    json={
        "model": "gpt-4o-mini",
        "messages": [
            {"role": "user", "content": "Explain idempotency in one sentence."}
        ],
    },
    timeout=30.0,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Input: Explain idempotency in one sentence.

Output: Idempotency means retrying a request produces the same server-side effect as sending it once, so a duplicate charge or booking cannot happen.

Two fields carry the whole request. model selects the weights that answer. messages is the conversation so far, and every entry is the same pair: a role string and a content string. Nothing else is required on this endpoint — no system prompt, no temperature, no token cap. The rules that decide who may speak when live in Messages, Roles, and Turn Structure.

timeout=30.0 is not decoration. Generation is slow, and without an explicit budget a stalled connection parks your worker indefinitely. Set it too low and you abort mid-generation, paying for output you never read.

Shape of the exchange

POST /v1/chat/completions
 |
 |-- request
 |     model          "gpt-4o-mini"
 |     messages       [ {role, content}, ... ]
 |
 +-- response
       choices[0].message.content    the text you wanted
       choices[0].finish_reason      why generation stopped
       usage.prompt_tokens           what you sent
       usage.completion_tokens       what you paid for

You will use choices[0] in almost every call you write. The array exists because some requests ask for multiple candidate completions; a normal chat call fills index 0 and leaves the rest empty.

The generated string is the part users see. The two fields next to it are the parts that keep the system healthy, and skipping them is how truncated answers quietly reach production.

finish_reason tells you why the model stopped. Four values cover nearly every case:

A length result is the dangerous one. The text looks finished — sentences read cleanly right up to the cut — so a service that only reads content[0].message.content will ship half an answer. Check the field before you trust the string:

choice = response.json()["choices"][0]
text = choice["message"]["content"]
if choice["finish_reason"] == "length":
    raise RuntimeError("Answer truncated at the token limit: " + text[-80:])

usage reports prompt_tokens (your instructions and history, sent in) and completion_tokens (what the model generated). They are billed at different rates and they come from the same tokenizer, so counting characters instead of tokens will misprice your feature — How Tokenizers Work explains why the ratio varies by language and punctuation. In production these two numbers become an invoice line, which is what Token Usage Metering builds on top of this response.

Every integration meets the same early failures. They arrive as HTTP status codes, and each one demands a different reaction — retrying all of them identically is the most common first bug.

Failure modes, worst to most confusing:

• 401 Unauthorized — the key is missing, mistyped, or revoked. A configuration problem. Retrying cannot fix it; fail fast and alert, or your logs fill with the same error every request.
• 429 Too Many Requests — you exceeded a per-minute rate limit or your prepaid quota ran out. Transient. Wait for the interval the response indicates, then retry with jittered backoff.
• 400 Bad Request — the payload is malformed: an empty messages array, a role that does not exist, a model name that was never real. The response body carries a human-readable message; print it instead of guessing.
• 5xx — the provider is having a bad minute. Retry with backoff, and cap total attempts so a long outage surfaces as an error rather than a hung queue.

import httpx, os, time

payload = {
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Ping"}],
}

for attempt in range(4):
    response = httpx.post(
        "https://api.openai.com/v1/chat/completions",
        headers={"Authorization": "Bearer " + os.environ["OPENAI_API_KEY"]},
        json=payload,
        timeout=30.0,
    )
    if response.status_code == 200:
        print(response.json()["choices"][0]["message"]["content"])
        break
    if response.status_code == 429:
        wait = float(response.headers.get("retry-after", 2 ** attempt))
        time.sleep(wait)          # provider tells you how long to back off
        continue
    if response.status_code == 400:
        raise ValueError(response.json()["error"]["message"])  # your bug, not theirs
    if response.status_code == 401:
        raise SystemExit("API key rejected; check OPENAI_API_KEY")
    time.sleep(2 ** attempt)      # 5xx and anything else: exponential backoff

Retrying is only half the story. The key itself must live in an environment variable or a secret manager, injected at runtime. It does not go in source control, in a client-side bundle where anyone can read the DOM, in a Docker image layer, or in a log line. Treat a leaked key as an incident: revoke it first, then investigate, then rotate. Rate Limiting and Retries covers the backoff policy in depth, and the SDK in OpenAI SDK Essentials automates most of the loop you just wrote by hand.