Document Utilities

OpenAI API Reference

OpenAI's /v1/chat/completions endpoint is designed for conversational generation where you pass ordered messages and receive a model-generated assistant reply. It is one of the most common interfaces used to build chat assistants, coding copilots, and automation agents.

Endpoint Summary

  • Method: POST
  • URL: https://api.openai.com/v1/chat/completions
  • Auth: Authorization: Bearer OPENAI_API_KEY
  • Body Type: JSON

Core Request Fields

Field Type Purpose
model string Target model name for inference.
messages array Conversation turns using role + content.
temperature number Controls randomness and creativity.
max_tokens integer Caps generated output length.

VS Code Style cURL Example

# Chat Completions request
curl -X POST "https://api.openai.com/v1/chat/completions" \
  -H "Authorization: Bearer OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain vector databases in 3 bullet points."}
    ],
    "temperature": 0.4,
    "max_tokens": 220
  }'

VS Code Style Python Example

import requests

url = "https://api.openai.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer OPENAI_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "gpt-4.1-mini",
    "messages": [
        {"role": "system", "content": "You are an API explainer."},
        {"role": "user", "content": "Compare REST and GraphQL."},
    ],
    "temperature": 0.5,
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Response Anatomy

The response typically includes id, created, model, and a choices array. The first generated text is usually read from choices[0].message.content. Token usage metadata is provided for monitoring cost and throughput.

Implementation tip: Always validate status codes and parse errors before trusting model output.