Chat Completions API for Beginners

This is the moment your app actually speaks with AI. One clean API call can turn raw user input into useful, human-friendly output.

This is Lesson 4 — Beginner in our Azure Openai Basics series. By the end, you will understand this topic well enough to explain it to a friend — no jargon overload, we promise.

Understand the Request Shape First

A chat completion request has a few essential parts: endpoint, API key, deployment (model alias), and message array. Most integration bugs are missing one of these fields or using an unsupported API version.

The message array is ordered conversation history. The model reads it top to bottom and predicts the next assistant response. If context is weak, output quality drops. Good requests are clear, scoped, and role-driven.

Think of messages like theater script pages. The system message sets scene rules, user messages provide intent, and assistant messages preserve continuity.

REST API Example (Great for Understanding)

REST calls reveal every wire-level detail, which is useful for debugging and API literacy.

curl -X POST "$AZURE_OPENAI_ENDPOINT/openai/deployments/$AZURE_OPENAI_DEPLOYMENT/chat/completions?api-version=2024-10-21"   -H "api-key: $AZURE_OPENAI_KEY"   -H "Content-Type: application/json"   -d '{
    "messages": [
      {"role": "system", "content": "You explain tech for first-year students."},
      {"role": "user", "content": "Explain API rate limiting in plain English."}
    ],
    "temperature": 0.4
  }'

Look at choices[0].message.content in the JSON response. That is the assistant text your app will display.

SDK Example for Cleaner Application Code

SDKs reduce boilerplate and make code safer to maintain. You still send the same data model, just with typed objects and friendlier methods.

using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT");

var client = new Azure.AI.OpenAI.AzureOpenAIClient(new Uri(endpoint), new Azure.AzureKeyCredential(apiKey));
var chatClient = client.GetChatClient(deployment);

var response = chatClient.CompleteChat(new[]
{
    new SystemChatMessage("You are concise and practical."),
    new UserChatMessage("Give me 3 cloud security best practices.")
});

Keep credential loading outside business logic to respect clean architecture boundaries.

Parse Response and Handle Errors

Never assume success. Network hiccups, quota limits, and content filters can interrupt calls. Wrap requests in retry-aware error handling and log meaningful diagnostics.

At minimum, log timestamp, deployment, latency, token usage, and request ID (if available). Observability turns random failure into solvable engineering work.

Also sanitize user output display. If your UI accepts markdown, ensure scripts cannot execute unexpectedly. Safety includes both model output and frontend rendering discipline.

Debugging Checklist You Will Reuse

When calls fail, check this exact order:

1. Endpoint format correct and reachable?
2. API key valid and unexpired?
3. Deployment name exists in this resource?
4. API version supported?
5. Payload JSON valid and role fields correct?

This checklist saves hours. Keep it in your project wiki. Lesson 5 builds on this by improving message design and system prompt strategy.

Walk Through a Real Failure Like an Engineer

Imagine your app returns 401 Unauthorized. Many beginners immediately change random code. A better approach is structured debugging. First, confirm the key loaded by your runtime is the same key visible in Azure portal. Print only the last four characters for safety, never full key. Second, verify endpoint does not accidentally contain double slashes or missing protocol.

Now imagine request succeeds but response quality is strange. Check payload shape next. Are role names valid? Is the system instruction clear? Are you accidentally passing stale conversation history from another user session? In multi-user apps, context mixing is a common source of confusing output.

Latency spikes are another common issue. Start by logging request start/end timestamps and token usage. If token counts rise over time, conversation history is likely bloated. Add summarization or context window trimming. If token count is stable but latency still spikes, inspect regional service health and concurrent request load.

For production readiness, map each error class to a user-facing fallback. Example: auth/config errors return "service temporarily unavailable," rate limits return "please retry in a few seconds," and unsafe content returns a policy-safe response. Users should never see raw stack traces.

This is where clean architecture helps. Keep API client, retry policy, and error translation in service layer so controllers stay thin. Then all interfaces, whether web UI or CLI, benefit from the same robust behavior.

Improve Request Quality Before Blaming the Model

A surprising number of bad outputs come from vague requests. Add structure to every call: clear role, explicit user goal, desired output format, and boundaries such as "use only five bullet points." This gives model a stable frame and reduces randomness.

Use correlation IDs in logs so each request can be traced across controller, service, and API client. When a student reports a weird answer, correlation IDs let you inspect exact payload and response path without guessing.

Normalize user input before sending it upstream. Trim accidental whitespace, reject empty prompts, and set reasonable character limits. Input hygiene improves response quality and protects costs.

For multi-turn chat, store only necessary recent turns plus a concise summary. This keeps context meaningful and prevents hidden prompt drift where old irrelevant messages influence current answers.

Great API integrations are predictable. You get predictability by designing request contracts and observability, not by hoping the model behaves the same under noisy inputs.

Common Misconceptions

"SDK and REST are different products." They are two interfaces to the same service.

"If output looks weird, model is bad." Often the prompt context or message ordering is the issue.

"Retries always fix everything." Retries help transient failures, not bad configuration.

"Error handling can wait until later." AI integrations need resilient handling from the beginning.

Quick Recap

• A chat request needs endpoint, key, deployment, and messages.
• REST helps understand protocol details.
• SDK improves maintainability in application code.
• Parse responses carefully and log diagnostics.
• Use a fixed troubleshooting checklist.

Summary

Lesson 4 delivers practical API fluency. You now know how to call chat completions via REST and SDK, parse outputs, and debug failures with a repeatable process.

Ready for the next step? Continue with the suggested reads below — each lesson builds on the last.