OpenAI API Python Nasıl Kullanılır? Adım Adım (2026)

OpenAI’ın Python SDK’sı, GPT-4o’dan GPT-5’e kadar tüm modellere tek tip bir arayüz üzerinden erişim sunar. ChatGPT benzeri bir chatbot, belge analiz aracı ya da harici API’lerle entegre bir asistan yazmak istiyorsanız doğru yere geldiniz. Bu rehberde kurulumdan başlayarak streaming, function calling, vision ve prodüksiyon hazırlığını çalışan kod örnekleriyle adım adım ele alıyoruz.

OpenAI Python SDK Neden Bu Kadar Popüler?

OpenAI Python SDK, yapay zeka geliştirme ekosisteminde fiili standart konumuna geldi.

API tasarımı tutarlı. client.chat.completions.create() yöntemi, GPT-3.5’ten GPT-5’e kadar değişmez; model adını güncellemek yeterli. Aynı tutarlılık Anthropic ve Google tarafından da benimsendi, bu yüzden birini öğrenmek diğerlerine geçişi kolaylaştırır. Ekosistem karşılaştırması için OpenAI vs Anthropic vs Google vs Groq API karşılaştırması yazısına bakabilirsiniz.

Topluluk da büyük. Stack Overflow’daki OpenAI API soruları Gemini ve Claude toplamından fazla; hata aldığınızda çözüm bulmak görece kolay.

İşlevsel kapsam da geniş: streaming, function calling, vision API, ses (Whisper, TTS), embeddings ve fine-tuning hepsi aynı paket altında. Proje büyüdükçe farklı kütüphane kurmak yerine aynı istemciyle ilerlenir.

Kurulum ve API Key Alma

Python 3.8 veya üzeri gerektiriyor. Sanal ortam kurmak iyi pratiktir:

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install openai python-dotenv

API anahtarını platform.openai.com adresinden alın: API keys menüsünden yeni bir anahtar oluşturun. Anahtarı bir kez görürsünüz, yedekleyin.

Anahtarı doğrudan koda yazmak tehlikelidir. .env dosyası kullanın:

# .env
OPENAI_API_KEY=sk-proj-...

.gitignore dosyanıza .env satırı ekleyin, ardından Python tarafında yükleyin:

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

İlk ChatGPT Çağrısı: Temel Yapı

SDK’nın temel çağrı yapısını anlamak her şeyin temeli. Sade bir örnek:

from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY env var'dan otomatik okunur

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Sen yardımcı bir Python uzmanısın."},
        {"role": "user", "content": "Liste comprehension ne işe yarar? Kısa açıkla."},
    ],
    max_tokens=300,
    temperature=0.7,
)

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

Yanıt nesnesinin önemli alanları:

temperature değeri 0 ile 2 arasında; düşük değer daha tutarlı, yüksek değer daha yaratıcı çıktı verir. Kod üretimi için 0.2-0.4, yaratıcı yazı için 0.8-1.2 iyi başlangıç noktasıdır.

Streaming ile Gerçek Zamanlı Yanıtlar

ChatGPT’nin web arayüzündeki karakter karakter yazma efekti streaming ile gerçekleşir. Kullanıcılar yanıtın tamamını beklemek zorunda kalmadan ilk tokenları hemen görür; bu, özellikle uzun yanıtlarda algılanan gecikmeyi önemli ölçüde düşürür.

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Python'da async/await farkını anlat."}],
    stream=True,
)

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

print()  # son satır sonu

stream=True geçildiğinde create() bir generator döndürür. Her chunk içinde choices[0].delta.content bir veya birkaç token taşır; None geldiğinde akış bitti demektir.

Async streaming: FastAPI veya başka bir async framework kullanıyorsanız:

import asyncio
from openai import AsyncOpenAI

async def stream_response():
    aclient = AsyncOpenAI()
    async with aclient.chat.completions.stream(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Fibonacci serisini hesapla."}],
    ) as stream:
        async for text in stream.text_stream:
            print(text, end="", flush=True)

asyncio.run(stream_response())

Konuşma Geçmişi ve Çok Turlu Chat

OpenAI API durumsuz (stateless) çalışır: her çağrıda tüm konuşma geçmişini messages listesinde göndermeniz gerekir. Bunu yönetmenin basit ama güvenilir bir yolu:

conversation = [
    {"role": "system", "content": "Sen deneyimli bir Python geliştiricisisin. Kısa ve net yanıt ver."}
]

def chat(user_input: str) -> str:
    conversation.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=conversation,
        max_tokens=500,
    )

    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

# Kullanım
print(chat("Decorator nedir?"))
print(chat("Gerçek dünya örneği ver."))

Geçmiş büyüdükçe token sayısı artar ve maliyet yükselir. Uzun sohbetlerde eski mesajları kırpmak ya da özetlemek pratik bir çözümdür. Prompt mühendisliği kapsamında system mesajının nasıl yapılandırılacağını da inceleyebilirsiniz.

Function Calling ile Harici API Entegrasyonu

Function calling, modelin yapılandırılmış bir JSON nesnesi üretip bunu sizin belirlediğiniz fonksiyona yönlendirdiği mekanizmadır. Modelin kendi başına yapamayacağı şeyler (anlık hava durumu, veritabanı sorgusu, e-posta gönderme) bu yolla mümkün hale gelir.

Senaryo: kullanıcı hava durumu soruyor, siz bir API’ye bağlıyorsunuz.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Bir şehrin anlık hava durumunu döndürür.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Şehir adı, örn. 'İstanbul'",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                    },
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "İstanbul'da bugün hava nasıl?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"Çağrılacak fonksiyon: {tool_call.function.name}")
    print(f"Argümanlar: {args}")
    # Buraya gerçek API çağrınızı ekleyin, ardından sonucu modele gönderin

Model tool_choice="auto" ile kendi karar verir — fonksiyon çağırmak gerekiyorsa çağırır, gerekmiyorsa düz yanıt döner. JSON şema tanımlarının detayları için Structured Outputs rehberimize bakın.

Vision API: GPT-4o ile Görsel Analiz

GPT-4o çok modlu (multimodal) bir modeldir; metin yanında görsel de işler. Görsel URL veya base64 formatında gönderilebilir.

# URL yöntemi
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Bu grafikte ne görüyorsun?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://ornek.com/grafik.png",
                        "detail": "high",   # "low" | "high" | "auto"
                    },
                },
            ],
        }
    ],
    max_tokens=500,
)
print(response.choices[0].message.content)

Base64 yöntemi yerel dosyalar için uygundur:

import base64

def encode_image(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

b64 = encode_image("ekran_goruntusu.png")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Bu hata mesajını açıkla."},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{b64}"},
                },
            ],
        }
    ],
)

detail: "high" görsel büyük miktarda token harcar; makul boyuttaki görseller için "auto" tercih edin.

Maliyet Optimizasyonu: Token ve Model Seçimi

API maliyeti token üzerinden hesaplanır. Hangi modeli seçeceğiniz hem kaliteyi hem bütçeyi doğrudan belirler. 2026 itibarıyla öne çıkan seçenekler:

Güncel fiyatlar için OpenAI pricing sayfasını kontrol edin.

Fiyatların diğer sağlayıcılarla ayrıntılı karşılaştırması için ChatGPT, Claude ve Gemini API fiyatları rehberimize bakın.

Token tasarrufu için pratik yöntemler:

• System mesajını kısa tutun. Gereksiz uzun talimatlar her çağrıda tekrar gönderilir.
• max_tokens sınırlayın. Yanıt kısa olacaksa bu parametre maliyeti keser.
• GPT-4o mini ile prototip yapın. Yeterli mi deneyin, değilse GPT-4o’ya geçin.
• Prompt caching değerlendirin. Aynı uzun sistem mesajını tekrar eden uygulamalarda önbelleğe alınmış tokenlar çok daha ucuza gelir.

Hata Yönetimi ve Prodüksiyona Hazırlık

Üretim ortamında iki yaygın sorunla karşılaşılır: rate limit ve geçici ağ hataları. SDK bunları openai.RateLimitError ve openai.APIConnectionError olarak fırlatır.

Üstel geri çekilme (exponential backoff) ile yeniden deneme:

import time
import openai

def chat_with_retry(messages: list, retries: int = 3) -> str:
    for attempt in range(retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=messages,
            )
            return response.choices[0].message.content
        except openai.RateLimitError:
            if attempt < retries - 1:
                wait = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(wait)
            else:
                raise
        except openai.APIConnectionError as e:
            raise RuntimeError(f"Bağlantı hatası: {e}") from e

Async ve eşzamanlı istekler: yüksek hacimli uygulamalarda asyncio ile paralel çağrı yapın:

import asyncio
from openai import AsyncOpenAI

aclient = AsyncOpenAI()

async def process_batch(prompts: list[str]) -> list[str]:
    tasks = [
        aclient.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
        )
        for p in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

Ortam değişkenleri ve güvenlik:

• OPENAI_API_KEY asla kaynak koda girmemeli; CI/CD’de secret manager kullanın.
• Org ID ve proje ID’lerini de env var olarak yönetmek, anahtarın kimin kodu çalıştırdığını izlemenizi kolaylaştırır.
• Prodüksiyonda timeout parametresi ayarlayın; yanıt uzarsa bağlantıyı manuel kapatın:

client = OpenAI(timeout=30.0)  # 30 saniye

Sonraki Adım: SDK’yı Agent Mimarisine Taşımak

Tek bir chat.completions.create() çağrısı bir başlangıç noktası. İşler karmaşıklaştıkça, function calling zincirlerine ve tam bir AI agent mimarisine doğru adım adım geçiş yapabilirsiniz. Her aşama kendi başına çalışır; hepsini bir anda uygulamanız gerekmiyor.

Makul bir ilerleme sırası şöyle görünür:

1. Bu rehberdeki temel yapıyı kurun ve çalıştırın.
2. Function calling ile bir harici API bağlayın.
3. System mesajı tasarımı için prompt mühendisliği tekniklerini inceleyin.
4. Token maliyetini izleyin; yüksek hacimde GPT-4o mini ile başlayıp gerekince GPT-4o’ya geçin.
5. Async pattern’e geçin; aynı Python süreci içinde paralel çağrılar açılır.

SDK, kısa prototipten yüksek trafikli servise geçişte aynı API yüzeyini koruyor. Bu tutarlılık pratikte fark yaratıyor.