Lesson 27 — Beginner

First API Calls & Conversation State

Pehli API call ka scene simple hai — messages bhejo, model jawab deta hai. Lekin asli cheezein response object, usage metadata aur conversation state hain. Is lesson mein hum SDK se call lagana, roles samajhna, response inspect karna aur history khud sambhalna seekhenge.

Pehla chat completion call

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Tum ek madadgar assistant ho — Hinglish mein jawab do."},
        {"role": "user", "content": "Barish ke baare mein chhoti si poem likho."},
    ],
    temperature=0.7,
)

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

Call ka skeleton hamesha same rehta hai: client → messages → response. System message app ka behavior set karta hai, user message is waqt ka sawaal hai. Jawab resp.choices[0].message ke andar milta hai — string seedhi nahi milti.

Response object ko inspect karo

resp = client.chat.completions.create(model="gpt-4o-mini", messages=messages)

print(resp.id)                        # request ka unique id
print(resp.model)                     # kaunsa model actually chala
print(resp.choices[0].finish_reason)   # stop | length | tool_calls
print(resp.usage.prompt_tokens)        # input tokens
print(resp.usage.completion_tokens)    # output tokens
print(resp.usage.total_tokens)         # dono ka total — bill yahin se banti hai

• finish_reason batata hai jawab kyun ruka — "stop" matlab model ne khud khatam kiya, "length" matlab token limit aayi, "tool_calls" matlab model tool chaahta hai (M2.5 mein).
• usage har call par aata hai — input aur output tokens alag-alag. Cost estimate isi se banti hai.
• model field check karo — kabhi kabhi tumne jo maanga aur jo serve hua wo alag hote hain (aliases, versioning).
• Request id aur timestamps bhi response mein hote hain — debugging aur logs mein yahi sabse pehle kaam aata hai.

Bahut se log API ko prompt → string function samajh kar sirf content padh lete hain. Production mein yeh enough nahi — finish_reason, usage aur id batate hain ki request poori hui ya beech mein kahin atak gayi.

API stateless hai — history tum sambhalo

history = [
    {"role": "system", "content": "Tum ek booking assistant ho."},
]

def ask(user_text):
    history.append({"role": "user", "content": user_text})
    resp = client.chat.completions.create(model="gpt-4o-mini", messages=history)
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})  # yaad rakhna TUMHARA kaam hai
    return reply

print(ask("Mera naam Rahul hai."))
print(ask("Mujhe yaad hai kya?"))   # "Haan, Rahul" — kyunki history bheji thi

• Model server par kuch yaad nahi rakhta. Agli call woh zero se shuru hoti hai — jo history tum bhejoge wahi uska poora context hai.
• Application state (database, user profile, session store) aur model context (is waqt messages array mein kya hai) alag cheezein hain — confuse mat karo.
• History badhti rehti hai — kabhi trim karo, summarize karo, warna context window bharega (L1 ke context window lesson).
• Messages ka order matter karta hai: system pehle, phir user/assistant alternating. Order bigadne se model confuse hota hai.

API keys safely manage karo

# GALAT — key code mein hardcode, git pe chali jaayegi
client = OpenAI(api_key="sk-proj-xxxxxxxx")

# SAHI — environment variable / .env file
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()          # .env padh lo
client = OpenAI()      # key khud env se utha lega

# .env file (gitignored):
# OPENAI_API_KEY=sk-...

# shell se direct chalana ho
export OPENAI_API_KEY="sk-..."
python app.py

• Key ko kabhi frontend, browser bundle ya public repo mein mat daalo — wahan se koi bhi utha kar tumhara bill bhaega.
• Production mein secret manager (Azure Key Vault, AWS Secrets Manager), local dev mein env var — dono kaam ke hain.
• Key leak ho jaye toh pehle revoke/rotate karo, investigation baad mein.
• .env ko .gitignore mein daalo — yeh naye project ka pehla kaam hai.

Exercise

Common mistakes

• API ko stateless samajh kar history chhod dena: — doosri call mein model ko pehli baat yaad nahi hogi, bot pagal lagne lagega. Har request ke saath poora messages array bhejo ya apna history store banao.
• Sirf content padh kar khush ho jaana: — finish_reason "length" aaya toh jawab adhoora kata hua hai, aur usage na dekha toh andar-andar cost badhti rehti hai. Har call par teeno check karo.
• Key frontend ya git commit mein daal dena: — leak hote hi koi bhi tumhare account se API chala sakta hai. Env var/secret manager use karo, aur leak ho toh fauran rotate karo.
• History ko bina trim kiye hamesha bhejte rehna: — har turn purana sab bhejne se tokens badhte hain aur context window ek din phat jaati hai. Purane turns ko summarize ya drop karo.

usage = resp.usage
# wazan (input)  : tumhara prompt + poora history
# wazan (output) : model ka jawab
bill = usage["prompt_tokens"] * rate_in + usage["completion_tokens"] * rate_out
# rate tumhare account ke rate table se aata hai (config mein rakho)