Skip to main content
This lesson walks through the three primary Azure OpenAI REST API endpoints — completions, embeddings, and chat completions — showing typical request/response formats, key parameters, and practical tips for calling the APIs from curl or Postman. Quick overview:
  • Completion endpoint: generate text continuations from a prompt.
  • Embeddings endpoint: convert text into numeric vectors for semantic tasks (search, clustering, similarity).
  • Chat completion endpoint: structured multi-turn conversational interface using role-based messages.
Endpoint summary

​
Completion endpoint

Use the completions endpoint to generate text continuations from a prompt. Replace <your-endpoint> and <deployment-name> with values from your Azure AI Foundry deployment. URL:
Request body example:
Response example:
Key notes:
  • The generated text is in choices[0].text.
  • max_tokens caps the response length. Tokens are the billing and length units used by the models.
  • You can control generation randomness and style with parameters like temperature and top_p.

​
Embeddings endpoint

Use embeddings to convert text into numeric vectors. Store and compare these vectors (e.g., cosine similarity) for semantic search, recommendation, or clustering. URL:
Request body example:
Response example:
Key notes:
  • data[0].embedding is the numeric vector representation.
  • Embeddings are commonly stored in vector databases (e.g., Pinecone, FAISS, Azure Cognitive Search) for fast similarity search.

​
Chat completion endpoint

Chat completions support multi-turn conversational flows using role-based messages (system, user, assistant). URL:
Request body example:
Response example:
Key notes:
  • Assistant replies appear in choices[0].message.content.
  • The usage object shows token counts for prompt, completion, and total (useful for cost tracking).
  • Chat completions are optimized for multi-turn interactions; maintain the messages array to preserve conversation context.
Not all models support every API type (completions, embeddings, chat). Check the model catalog in your Azure AI Foundry portal to confirm which models support which inference tasks before calling an endpoint.

​
Inspecting models and deployments in Azure AI Foundry

Review the model catalog in Azure AI Foundry to pick the right model for your task (for example, embeddings vs chat). Filter by inference task to narrow the available models.
A web dashboard for choosing AI models, showing announcement cards at the top and a grid of model tiles (e.g., o4-mini, gpt-4.1, gpt-4o-mini). A filter menu for inference tasks is open on the left with "Audio generation" checked.
After deploying a model, open the deployment to view its REST target URI and configuration details (deployment name, model version, and state).
A screenshot of a "Model deployments" admin page showing a single deployed model entry for "gpt-4o" (model version 2024-11-20) with state "Succeeded" and a retirement date of Dec 20, 2025. A cursor hand is hovering over the model name and the UI shows options like "Deploy model", "Refresh" and "Reset view."
Notes:
  • The deployment page displays the REST endpoint you will call from applications or tools like Postman and curl.
  • Use a clear, consistent deployment name — this name appears in the request URL path.

​
Example: calling the chat completion endpoint with curl / Postman

Set your API key in your shell or PowerShell environment. Bash (Linux/macOS):
PowerShell (Windows):
Example curl request (replace <your-endpoint>, <deployment-name>, and choose the correct api-version):
Tips for Postman:
  • Add the Content-Type: application/json header (Postman will do this automatically for JSON bodies).
  • Add an api-key header with your Azure API key.
  • All inference requests (completions, embeddings, chat/completions) require POST.
Sample (abridged) response for the Paris query:
Keep your API key secure. Never commit keys to source control or expose them in client-side code. Rotate keys regularly and restrict usage with appropriate IAM policies.

​
Final notes and best practices

  • Confirm the model you plan to use supports the required API type (completion, embedding, or chat).
  • Use max_tokens, temperature, and top_p to control response length and randomness.
  • Track token usage via the response usage object to monitor costs.
  • For streaming responses, advanced control, or SDK usage, consult the official docs and your Foundry deployment settings.
Links and references This lesson covered REST endpoints, example request/response payloads, deployment inspection, and practical tips for invoking Azure OpenAI with curl and Postman.

Watch Video