<!--
  openai.md
  Zyquo Cloud
  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

# 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)

| Model ID | Context | Max output | $/1M in / cached / out | Vision | Reasoning | Notes |
|---|---|---|---|---|---|---|
| `gpt-5.6-sol` | 1.05M | 128K | 5.00 / 0.50 / 30.00 | ✅ | ✅ | Frontier — "complex professional work". **Recommended default.** |
| `gpt-5.6-terra` | 1.05M | 128K | 2.50 / 0.25 / 15.00 | ✅ | ✅ | Balanced intelligence/cost |
| `gpt-5.6-luna` | 1.05M | 128K | 1.00 / 0.10 / 6.00 | ✅ | ✅ | Cost-optimized, high volume |
| `chat-latest` | unverified (~128K) | unverified | 5.00 / 0.50 / 30.00 | ✅ | ⚠️ non-reasoning chat tuning | Rolling alias to the current ChatGPT model; accepts `temperature` |

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)

| Model ID | Context | Max output | $/1M in / cached / out | Vision | Reasoning | Notes |
|---|---|---|---|---|---|---|
| `gpt-5.5` | unverified (≥400K) | unverified | 5.00 / 0.50 / 30.00 | ✅ | ✅ | Previous flagship (Apr 2026) |
| `gpt-5.5-pro` | unverified | unverified | 30.00 / — / 180.00 | ✅ | ✅ | **Responses API only** — exclude from chat-completions catalog |
| `gpt-5.4` | unverified (400K) | unverified (128K) | 2.50 / 0.25 / 15.00 | ✅ | ✅ | Mar 2026 |
| `gpt-5.4-mini` | unverified | unverified | 0.75 / 0.075 / 4.50 | ✅ | ✅ | |
| `gpt-5.4-nano` | unverified | unverified | 0.20 / 0.02 / 1.25 | ✅ | ✅ | Cheapest current-gen |
| `gpt-5.4-pro` | unverified | unverified | 30.00 / — / 180.00 | ✅ | ✅ | **Responses API only** |
| `gpt-5.3-chat-latest` | unverified | unverified | unverified | ✅ | ⚠️ | Rolling chat alias; **no plain `gpt-5.3` exists** (only `gpt-5.3-codex`, Responses-oriented) |
| `gpt-5.2` | 400K | 128K | 1.75 / 0.175 / 14.00 | ✅ | ✅ | Dec 2025 |
| `gpt-5.2-pro` | 400K | unverified | 21.00 / — / 168.00 | ✅ | ✅ | **Responses API only** |
| `gpt-5.2-chat-latest` | 128K | 16K | ≈ gpt-5.2 | ✅ | ⚠️ | ChatGPT tuning; accepts temperature |
| `gpt-5.1` | 400K | 128K | 1.25 / 0.125 / 10.00 | ✅ | ✅ | Introduced `reasoning_effort: "none"` |
| `gpt-5.1-chat-latest` | 128K | 16K | ≈ gpt-5.1 | ✅ | ⚠️ | |
| `gpt-5` | 400K | 128K | 1.25 / 0.125 / 10.00 | ✅ | ✅ | |
| `gpt-5-mini` | 400K | 128K | 0.25 / 0.025 / 2.00 | ✅ | ✅ | |
| `gpt-5-nano` | 400K | 128K | 0.05 / 0.005 / 0.40 | ✅ | ✅ | |
| `gpt-5-pro` | 400K | 272K | 15.00 / — / 120.00 (unverified) | ✅ | ✅ | **Responses API only** |
| `gpt-5-chat-latest` | 128K | 16K | ≈ gpt-5 | ✅ | ⚠️ | |

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)

| Model ID | Context | Max output | $/1M in / cached / out | Vision | Reasoning | Notes |
|---|---|---|---|---|---|---|
| `o3` | 200K | 100K | 2.00 / 0.50 / 8.00 | ✅ | ✅ | |
| `o3-pro` | 200K | 100K | 20.00 / — / 80.00 | ✅ | ✅ | **Responses API only** |
| `o4-mini` | 200K | 100K | 1.10 / 0.275 / 4.40 | ✅ | ✅ | |
| `o3-mini` | 200K | 100K | 1.10 / 0.55 / 4.40 (unverified) | ❌ | ✅ | Text only |
| `o1` | 200K | 100K | 15.00 / 7.50 / 60.00 (unverified) | ✅ | ✅ | Legacy |
| `o1-pro` | 200K | 100K | 150.00 / — / 600.00 (unverified) | ✅ | ✅ | **Responses API only** |

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

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

| Model ID | Context | Max output | $/1M in / cached / out | Vision | Reasoning |
|---|---|---|---|---|---|
| `gpt-4.1` | 1,047,576 | 32,768 | 2.00 / 0.50 / 8.00 | ✅ | ❌ |
| `gpt-4.1-mini` | 1,047,576 | 32,768 | 0.40 / 0.10 / 1.60 | ✅ | ❌ |
| `gpt-4.1-nano` | 1,047,576 | 32,768 | 0.10 / 0.025 / 0.40 | ✅ | ❌ |
| `gpt-4o` | 128K | 16,384 | 2.50 / 1.25 / 10.00 | ✅ | ❌ |
| `gpt-4o-mini` | 128K | 16,384 | 0.15 / 0.075 / 0.60 | ✅ | ❌ |
| `gpt-4o-search-preview`, `gpt-4o-mini-search-preview` | 128K | 16,384 | ≈ 4o / 4o-mini + search fee | ✅ | ❌ (built-in web search, citations) |
| `gpt-4-turbo` | 128K | 4,096 | 10.00 / — / 30.00 | ✅ | ❌ |
| `gpt-4` | 8,192 | 8,192 | 30.00 / — / 60.00 | ❌ | ❌ |
| `gpt-3.5-turbo` (+ `-16k`, `-1106`, `-0125`, `-instruct`) | 16,385 | 4,096 | 0.50 / — / 1.50 | ❌ | ❌ |

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`).

```json
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.