OpenAI API Basics (Authentication, Requests, Responses)

---

1. Introduction to OpenAI API

The OpenAI API provides programmatic access to advanced AI models such as GPT (text), DALL·E (image), Whisper (audio), and embeddings. It allows developers and researchers to integrate natural language understanding, generation, translation, summarization, and multimodal AI into their applications.

• Communication Protocol: Standard RESTful API over HTTPS.
• Data Format: JSON request and response.
• Transport Security: TLS (HTTPS) for data integrity and confidentiality.

---

2. Authentication

Authentication ensures secure access to the OpenAI services.

• API Key is the credential:
  • Generated from the OpenAI dashboard.
  • Passed in the HTTP Authorization header.
  • Must be kept secret (never expose in client-side code or GitHub repos).

🔑 Example:

Authorization: Bearer YOUR_API_KEY

• Best Practices:
  • Store keys in environment variables (.env file).
  • Use role-based access control (RBAC) in enterprise settings.
  • Rotate keys periodically to reduce exposure risk.
  • For multi-user applications, never expose your master API key — instead, build a backend layer to proxy requests securely.

---

3. Making Requests

Requests are HTTP POST calls with JSON payloads.

Example: Text Generation (Chat Completion)

POST https://api.openai.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Body:

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful research assistant."},
    {"role": "user", "content": "Explain reinforcement learning in simple terms."}
  ],
  "temperature": 0.7,
  "max_tokens": 500
}

Explanation of Parameters:

• model → Which model to query (e.g., gpt-4o, gpt-4-turbo, gpt-3.5-turbo).
• messages → Conversational input with roles (system, user, assistant).
• temperature → Controls randomness (0 = deterministic, 1 = creative).
• max_tokens → Limits response length.
• top_p, frequency_penalty, presence_penalty → Additional controls over diversity.

---

4. Handling Responses

Responses are JSON objects.

Example Response:

{
  "id": "chatcmpl-9yZqfT1234",
  "object": "chat.completion",
  "created": 1691234567,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Reinforcement learning is..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 120,
    "total_tokens": 170
  }
}

Key Fields:

• id → Unique request identifier.
• choices → Array of generated outputs.
• message.content → The actual model output.
• finish_reason → Why the response stopped (stop, length, content_filter).
• usage → Token counts for billing and optimization.

---

5. Error Handling

Errors are returned as JSON with HTTP status codes.

• 400 Bad Request → Invalid parameters.
• 401 Unauthorized → Missing/incorrect API key.
• 429 Too Many Requests → Rate limit exceeded.
• 500 Server Error → OpenAI system issue.

Example Error Response:

{
  "error": {
    "message": "You exceeded your current quota.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

---

6. Security & Governance

• Data privacy → By default, requests may be logged for abuse monitoring (depending on account type). Enterprise API usage can request no data retention.
• PII Handling → Never send sensitive personally identifiable information (PII) unless compliant with regulations (GDPR, HIPAA).
• Auditability → Keep logs of request IDs (id field) for debugging & compliance.

---

7. Advanced Topics

1. Streaming Responses
   • Instead of waiting for the whole output, responses can be streamed token by token (useful for chatbots, real-time apps).
   Example (Python): for chunk in client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Write a poem"}], stream=True ): print(chunk.choices[0].delta.content or "")
2. Batch Requests
   • Efficient for large-scale inference (multiple inputs at once).
3. Fine-Tuning
   • Train models with domain-specific data for better accuracy.
4. Embeddings & Vector Search
   • Use text-embedding-3-large for semantic search, RAG (Retrieval Augmented Generation).

---

8. Practical Example (Python SDK)

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a tutor for postgraduate students."},
        {"role": "user", "content": "Explain gradient descent with equations."}
    ]
)

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

---

✅ Summary for Postgraduates:

• Authentication = API key security.
• Requests = Structured JSON with parameters.
• Responses = Rich metadata beyond plain text (usage, tokens, finish reasons).
• Governance = Must comply with data handling and rate limits.
• Advanced usage = Streaming, embeddings, fine-tuning, and multimodal models.