OpenAI API

What it covers

The OpenAI API groups model inference and platform capabilities behind authenticated HTTP APIs. The Responses API is the general entry point for model responses and tool use, while specialized APIs cover embeddings, images, audio, files, batches, and real-time interactions.

Request shape

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL","input":"Summarize this release note."}'

Select a current model from the official model catalog instead of copying a model name from an old article. Handle 429 responses with bounded exponential backoff and respect the returned rate-limit metadata.

Key endpoints

Endpoint	Description
POST /v1/chat/completions	Chat completions
GET /v1/models	List models
GET /v1/models/{model_id}	Model details
POST /v1/embeddings	Create embeddings
POST /v1/images/generations	Generate images
POST /v1/audio/transcriptions	Speech to text
POST /v1/audio/speech	Text to speech
GET /v1/assistants	List assistants

Decision notes

Evaluate models using your own representative inputs, latency target, and output-quality rubric. Price comparisons should include input, cached input where applicable, output, and tool-specific charges rather than a single headline token price.

Python example: chat completion with error handling

import httpx

API_KEY = "your_openai_api_key"
BASE = "https://api.openai.com/v1"

def chat(messages: list[dict], model: str = "gpt-4o-mini", **kwargs) -> str:
    """Send a chat completion request. Raises on API errors."""
    resp = httpx.post(
        f"{BASE}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"model": model, "messages": messages, **kwargs},
        timeout=60,
    )
    if resp.status_code == 429:
        raise RuntimeError("Rate limited — back off and retry")
    if resp.status_code == 401:
        raise RuntimeError("Invalid API key")
    resp.raise_for_status()
    return resp.json()["choices"][0]["message"]["content"]

def list_models() -> list[str]:
    resp = httpx.get(f"{BASE}/models", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
    resp.raise_for_status()
    return [m["id"] for m in resp.json()["data"]]

print(chat([{"role": "user", "content": "What is 2+2? Answer in one word."}]))

Notes:

• Auth is Authorization: Bearer <key>; never expose keys client-side
• 429 means rate limit — respect retry-after headers and back off
• Model names change frequently; call /models or check docs for current IDs
• Use the official openai Python SDK for streaming, retries, and type safety in production