# OpenAI — API Research (Phase 0)

Researched: 2026-07-30. Sources: https://developers.openai.com/api/docs/models , https://developers.openai.com/api/docs/pricing , https://developers.openai.com/api/docs/api-reference/chat/create , https://developers.openai.com/api/docs/guides/reasoning (platform.openai.com 301-redirects to developers.openai.com). Live model list verified against GET /v1/models with a real key on 2026-07-30 (/tmp/zyquo-probe/openai.json).

# 1. Base URL & endpoints

• Base URL: https://api.openai.com/v1
• Chat completions (what Zyquo Cloud uses): POST /v1/chat/completions
• Responses API (newer, stateful; NOT used by the app, but note some models are Responses-only): POST /v1/responses
• Model listing: GET /v1/models
• Embeddings/audio/images exist but are out of scope.

# 2. Authentication

• Header: Authorization: Bearer <OPENAI_API_KEY>
• Optional: OpenAI-Organization: <org_id>, OpenAI-Project: <proj_id>
• No other required headers besides Content-Type: application/json.

# 3. Chat model catalog

Verified live 2026-07-30. Aliases listed; dated snapshots (e.g. gpt-5.4-2026-03-05, gpt-5-2025-08-07, gpt-4.1-2025-04-14, …) exist for most and are omitted. Pricing = USD per 1M tokens (input / cached input / output), from the official pricing page. All models below: streaming ✅, function calling/tools ✅, JSON/structured output (response_format: json_schema) ✅ unless noted.

# Flagship (featured in current docs — the GPT-5.6 trio)

Note: there is no plain gpt-5.6 model — only the sol/terra/luna variants. ra-gpt-5.6-sol also appears in /models (created 2026-07-25) but is undocumented — flag as experimental, exclude from the default catalog.

# Current / recent GPT-5.x (still served, not featured)

Codex family (gpt-5-codex, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2-codex, gpt-5.3-codex): agentic-coding tuned, Responses API only — exclude from the chat-completions catalog. gpt-5-search-api / gpt-5-search-api-2025-10-14: chat completions with built-in web search (returns citations/annotations), priced ≈ gpt-5 + per-search fee (unverified).

# o-series reasoning (legacy but served)

o3-deep-research, o4-mini-deep-research: Responses API + background mode only — exclude.

# Legacy GPT-4.x / 3.5 (served; mark "legacy" in UI)

Skip entirely (non-chat): text-embedding-*, whisper-1, tts-1*, gpt-4o-*-transcribe*, gpt-4o-mini-tts*, gpt-audio*, gpt-realtime*, gpt-transcribe, gpt-live-transcribe, gpt-image-*, chatgpt-image-latest, sora-2*, omni-moderation*, davinci-002, babbage-002.

# 4. Request/response format

Fully OpenAI-native (this IS the reference format for the app's OpenAICompatibleClient).

POST /v1/chat/completions
{
  "model": "gpt-5.6-terra",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,....", "detail": "auto"}}
    ]}
  ],
  "max_completion_tokens": 4096,
  "stream": true,
  "stream_options": {"include_usage": true}
}

• Response: {"id", "object": "chat.completion", "created", "model", "choices": [{"index", "message": {"role": "assistant", "content", "tool_calls?", "refusal?"}, "finish_reason"}], "usage": {"prompt_tokens", "completion_tokens", "total_tokens", "completion_tokens_details": {"reasoning_tokens"}, "prompt_tokens_details": {"cached_tokens"}}}
• Vision input: content parts with {"type": "image_url", "image_url": {"url": "<https URL or data:image/…;base64,…>", "detail": "auto|low|high"}}.
• finish_reason: stop, length, tool_calls, content_filter.

# 5. Streaming (SSE)

• stream: true. Events are unnamed data: lines, each a chat.completion.chunk: {"id","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role"?,"content"?,"tool_calls"?},"finish_reason":null|...}]}
• First chunk carries delta.role; subsequent chunks delta.content fragments; final content chunk carries finish_reason.
• With stream_options: {"include_usage": true} a final extra chunk arrives with empty choices: [] and a populated usage object — use this for token/cost accounting.
• Terminator: literal data: [DONE].
• No SSE event: names — parse data: payloads only.

# 6. Special parameters

• max_completion_tokens — use this everywhere; max_tokens is deprecated and rejected by reasoning models (o-series, gpt-5.x).
• reasoning_effort — values none | minimal | low | medium | high | xhigh | max; support varies by model (gpt-5: minimal–high; none added with gpt-5.1; xhigh/max on newer 5.x; gpt-5.6 family supports the full set; default is medium on most, gpt-5.1+ default none/model-dependent). Send only on reasoning-capable models.
• verbosity — low | medium | high (gpt-5 family and later; controls answer length).
• Temperature restrictions: reasoning models (o-series, gpt-5/5.x reasoning variants) reject temperature, top_p, presence_penalty, frequency_penalty, logprobs (only default temperature=1 accepted). The *-chat-latest / chat-latest non-reasoning chat models DO accept temperature (0–2) and top_p. Zyquo Cloud must gate these sliders per model.
• Reasoning content is not returned via chat completions — only usage.completion_tokens_details.reasoning_tokens. (Reasoning summaries exist only on the Responses API via summary: auto|concise|detailed.)
• response_format: {"type": "json_schema", "json_schema": {...}} or {"type": "json_object"} for structured/JSON output.
• Tools: tools: [{"type": "function", "function": {name, description, parameters}}], tool_choice: none|auto|required|{...}.

# 7. Rate limits & errors

• Error body: {"error": {"message": "...", "type": "invalid_request_error|authentication_error|rate_limit_error|...", "param": null, "code": "model_not_found|insufficient_quota|..."}}
• HTTP codes: 400 invalid request, 401 bad key, 403 permission/region, 404 model, 429 rate limit or quota (insufficient_quota), 500/503 server. Retry 429/5xx with exponential backoff; honor retry-after.
• Rate-limit headers: x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-requests, x-ratelimit-reset-tokens. Limits are tier-based (usage tiers 1–5), per model family. Docs: https://developers.openai.com/api/docs/guides/rate-limits

# 8. /models listing

• GET /v1/models exists. Shape: {"object": "list", "data": [{"id", "object": "model", "created", "owned_by"}]} — no capability/context metadata, so the built-in catalog must supply context windows and capabilities; use /models only to detect availability/new IDs. 130 models returned on 2026-07-30 with a standard key.

# Catalog guidance for ModelCatalog

• Default model: gpt-5.6-terra (balanced) or gpt-5.6-sol (flagship).
• Exclude from picker: all *-pro, *-codex*, *deep-research* (Responses-only), plus all audio/image/video/embedding/moderation IDs.
• Mark legacy: gpt-4.1/4o/4/3.5 families, o1/o3-mini.
• Unverified items above must be re-checked in Phase 7 with real calls.