openai-api

OpenAI platform API expert: the Responses API (`POST /v1/responses`) as the primary surface, Chat Completions migration posture and the Assistants API sunset, current model IDs and per-MTok pricing (G

SKILL.md

GitHub

OpenAI Platform API

One endpoint carries almost everything: POST /v1/responses. Tools, structured outputs, streaming, caching, state, and background execution are all parameters on that request. Chat Completions is the older, still-supported shape; Batch, Files, Vector Stores, and Realtime are the surrounding infrastructure.

Volatility rule — verify before you quote

Model IDs, prices, context windows, tier thresholds, deprecation dates, and cache-pricing rules move faster than this skill. Every fact here is a snapshot of OpenAI's docs as of 2026-08-05, with the exact source URL at the bottom of each file.

Re-check the cited URL before putting a price into a budget, a model ID into production config, or a deprecation date into a migration plan. Never quote a number for a model this skill does not list — say it is unverified and point at the pricing page.

Two dates are close enough to act on now:

  • Assistants API full sunset: 2026-08-26. A different, older product than Chat Completions. If a codebase still calls Assistants/Threads/Runs, migration is urgent, not optional.
  • Evals platform: read-only 2026-10-31, full shutdown 2026-11-30. Do not build new tooling on /v1/evals.

Chat Completions itself is not deprecated and has no announced sunset date. Do not tell a user otherwise.

Routing

Request Load
Create params, response object, conversation state, background mode, SDK setup references/responses-api.md
Model IDs, context windows, pricing across every family references/models-and-pricing.md
Moving off chat.completions — field-by-field mapping and order of operations references/migrate-from-chat-completions.md
Function tool schemas, strict mode, tool_choice, round trip references/function-calling.md
Web search, file search, code interpreter, computer use, image generation references/built-in-tools.md
text.format, JSON Schema subset, refusals references/structured-outputs.md
SSE event names and the consumption loop references/streaming.md
Batch JSONL format, limits, statuses references/batch.md
Cache thresholds, TTLs, breakpoints, the 1.25x write fee references/prompt-caching.md
Tiers, limit dimensions, response headers references/rate-limits.md
Files API, Vector Stores API, chunking, search references/files-and-vector-stores.md
WebRTC/WebSocket/SIP, session types, realtime models references/realtime.md

Request essentials

Base host api.openai.com, versioned path prefix /v1. Authenticate with an API key supplied via the OPENAI_API_KEY environment variable — both official SDKs read it automatically, so OpenAI() / new OpenAI() needs no arguments.

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    instructions="You are a helpful assistant.",
    input="Write a one-sentence bedtime story about a unicorn.",
)
print(response.output_text)

Three input surfaces replace the single messages array: instructions for system/developer guidance, input for the turn (a plain string, or an array of items with role in developer/user/assistant), and output for typed result items. output_text is an SDK convenience accessor that concatenates text items — reach for the typed output array whenever tool calls or reasoning items are in play.

Beware a naming inconsistency in OpenAI's own docs: guide examples use the bare model: "gpt-5.6" while the models page enumerates gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna. Confirm which exact string your account accepts before shipping config, and pin it explicitly — never build on an assumed evergreen alias.

Responses vs Chat Completions

Use Responses for all new work. OpenAI's position: "While Chat Completions remains supported, Responses is recommended for all new projects."

The structural differences that break a naive port:

Aspect Chat Completions Responses
Input messages array input + instructions
Output choices[0].message.content output_text or typed output[]
Item types messages only messages, reasoning, function calls, tool outputs
State you replay the transcript previous_response_id, Conversations API, or manual replay
Tools you implement everything built-in web search, file search, code interpreter, computer use, MCP
Structured outputs response_format text.format
Function definitions externally tagged internally tagged

OpenAI's claimed gains from migrating: ~3% on SWE-bench and 40–80% better cache utilization, because reasoning and tool context persist across turns instead of being rebuilt. Treat both as vendor claims, not measured facts for your workload.

Migrate in this order — simple text flows, then endpoint/output handling, then a state-management decision, then function definitions, then Structured Outputs schemas, then streaming handlers, then rollout. Details in references/migrate-from-chat-completions.md.

Conversation state

Three strategies, and the choice is a cost decision as much as an architecture one.

  • previous_response_id — chain each call to the prior response id. Simple, but every previous input token in the chain is re-billed as input on every subsequent call. Long chains get expensive quickly; prompt caching is what makes them tolerable, so structure prompts for cache hits (below) before reaching for chaining.
  • Conversations API — conversations.create(), then pass conversation=<id>. Durable across sessions and devices, stores messages, tool calls, and tool outputs, and is exempt from the 30-day TTL that applies to plain stored responses.
  • Manual replay — you own the transcript. Required when store: false is mandated.

store defaults to true with 30-day retention. Set store: false for data-minimization; you then cannot chain by id and must replay context yourself.

Context window counts input + output + reasoning tokens against one ceiling. Reasoning tokens are invisible in your prompt but consume the same budget — size max_output_tokens with that in mind on reasoning models.

Background mode

Set background: true for long-running work, then poll responses.retrieve(id) until a terminal status (completed, failed, cancelled, incomplete). Only background responses can be cancelled — POST /v1/responses/{id}/cancel, idempotent.

Combine background: true with stream: true to get events immediately while execution continues server-side. Track each event's sequence_number as a resume cursor and reconnect with starting_after after a dropped connection — this is the only reliable recovery path for a long background stream.

Zero Data Retention projects force store=false on background responses; data lives ~10 minutes on disk purely to support polling. Do not design a ZDR background flow that assumes retrievability later.

Tools

Function tools are internally tagged — type, name, description, parameters, strict sit at the top level of the tool object, not nested under a function key as in Chat Completions. This is the single most common port error.

Round-trip rules that break requests when violated:

  • Append the model's output items to your input array unchanged, then push a function_call_output item carrying the matching call_id — not the item id. Those are two different fields on the same object.
  • arguments arrives as a JSON-encoded string; parse it. It is never a dict.
  • Set "strict": true and satisfy its schema rules (additionalProperties: false everywhere, every property in required, optional fields typed as ["string", "null"]). Cheaper than a retry loop.
  • tool_choice is "auto" (default), "required", "none", a forced {"type": "function", "name": ...}, or an allowed_tools object restricting the callable set without forcing one.
  • Parallel calls are on by default on GPT-5 and later; parallel_tool_calls: false caps a turn at zero or one call.

Keep the active toolset under ~20 functions. Every definition consumes input tokens on every request — defer rarely-used tools via tool search rather than trimming descriptions into uselessness.

Built-in tools

Tool type What it does Sharpest constraint
web_search OpenAI-run search with url_citation annotations Inline citations must be visible and clickable in your UI
file_search Retrieval over vector stores Files must reach completed status before they are searchable
code_interpreter Sandboxed Python container Container dies after 20 minutes idle; data is unrecoverable
computer Screenshot → batched actions loop Requires gpt-5.6 (or gpt-5.4); send screenshots at detail: "original"
image_generation In-conversation image generation/editing gpt-image-2 does not support transparent backgrounds

Prefer web_search over the legacy web_search_preview type — the old string still works but misses newer options (filters, search_content_types, external_web_access, return_token_budget).

Code interpreter memory tiers are 1g (default), 4g, 16g, 64g; above-default tiers bill at built-in-tool rates, so do not raise the tier speculatively. Persist anything you need out of the container before it expires.

Full option tables in references/built-in-tools.md.

Structured outputs

Prefer text: { format: { type: "json_schema", strict: true, schema: ... } } over prompt-and-parse. Better still, use the SDK helpers — client.responses.parse(text_format=YourPydanticModel) in Python, zodTextFormat(schema, "name") in JS — so the schema and your types cannot drift.

Design to the supported subset. allOf, not, dependentRequired, and if/then/else are unsupported and will not silently degrade. The root must be an object, not an anyOf. Hard caps: 5,000 total properties, 10 nesting levels, 120,000 schema characters, 1,000 enum values across all properties.

Handle three distinct terminal cases, not one: a schema-valid payload, a refusal item (safety), and incomplete_details.reason of max_output_tokens or content_filter. Code that assumes only the first will crash in production.

Not available on gpt-3.5-turbo or gpt-4-turbo — those need legacy JSON mode.

Streaming

Set stream: true and iterate events. Handle unknown event types gracefully; OpenAI adds them.

The events that carry the actual work: response.output_text.delta for text, response.function_call_arguments.delta/.done for tool arguments, response.refusal.delta, plus lifecycle (response.created, response.completed, response.failed) and per-tool progress events for file search and code interpreter. Never parse accumulated function_call_arguments fragments before the matching .done event — partial JSON is not JSON. Full event list in references/streaming.md.

Batch

Use Batch for anything latency-tolerant: 50% off, and it draws from a separate, much higher rate-limit pool so it does not compete with your synchronous traffic.

Caps: 50,000 requests and 200 MB per batch, .jsonl only, 2,000 batch creations per hour, and "24h" is the only completion window offered. Each line needs custom_id, method, url, body.

Always map results by custom_id — output order does not match input order. Output files auto-delete 30 days after completion; video outputs only stay downloadable 24 hours.

Prompt caching

Caching is automatic on prefix match — the first ~256 tokens select the routing bucket — but it only engages above a 1,024-token minimum on GPT-5.6+ (1,024–2,048 and less consistent on earlier models). Short prompts are simply never cached; there is no error.

The cost model changed at GPT-5.6 and this catches people: cache writes now bill at 1.25x the uncached input rate. On earlier models writes were free. A high-churn prefix that used to be merely useless is now actively more expensive than not caching. Set prompt_cache_options.mode: "explicit" with prompt_cache_breakpoint markers after stable blocks to stop paying for automatic write attempts you never read back.

Structure every prompt static-first: instructions, examples, and tool definitions at the front, user-specific content at the end, byte-identical across requests. Set prompt_cache_key on requests that share a long prefix to improve routing. Verify with cached_tokens and cache_write_tokens in usage — never assume.

Rate limits

Six tiers by cumulative spend (Free/$5/$50/$100/$250/$1,000 paid) with monthly usage caps from $100 to $200,000. Limits apply across RPM, TPM, RPD, TPD, IPM, and audio-minutes-per-minute — whichever ceiling is hit first wins, so 20 tiny requests can exhaust a 20-RPM limit while nowhere near TPM.

Read x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens, and the matching -reset- headers rather than guessing, and honor Retry-After on a 429. Per-model numeric RPM/TPM values are not published on the rate-limits guide — read them from the account dashboard.

Files and vector stores

Upload via POST /v1/files with a purpose (assistants, batch, fine-tune, vision, user_data, plus the three output/result variants). Limits: 512 MB per file, 2.5 TB per project, 1,000 upload requests/minute.

Deleting a file removes it from every vector store that references it. There is no per-store detach-on-delete; treat file deletion as a global operation.

Vector store defaults: auto chunking at 800 max tokens with 400 overlap; static allows 100–4,096. Search supports filters, max_num_results (1–50), re-ranking, and rewrite_query. Endpoint tables in references/files-and-vector-stores.md.

Realtime

Three transports: WebRTC for browser/mobile clients capturing audio, WebSocket for server-side pipelines, SIP for telephony. Three session types on distinct paths — voice agents at /v1/realtime (full tool-calling), translation at /v1/realtime/translations, and transcription-only sessions.

Models: gpt-realtime-2.1 (voice agents), gpt-realtime-translate, gpt-live-transcribe. Start sessions at reasoning effort "low" in production. Audio tokens are expensive — $32/MTok in, $64/MTok out on gpt-realtime-2.1 — so budget realtime by audio minutes, not by text-token intuition.

Cost estimation checklist

Never quote a per-request cost from the input/output columns alone. Sum:

  1. Uncached input at the model's rate, plus cache reads at the cached-input rate.
  2. Cache writes at 1.25x input on GPT-5.6+ (free on earlier models).
  3. Output tokens including invisible reasoning tokens.
  4. Tool definition tokens, charged as input on every request that carries them.
  5. Built-in tool charges — code interpreter memory tiers above 1g, image generation output tokens by resolution/quality.
  6. For chained conversations: the entire prior input, re-billed each turn under previous_response_id.
  7. Multiplier: 0.5x for Batch.

Common failure modes

Symptom Cause Fix
Tool schema rejected after porting Chat Completions' externally-tagged {"function": {...}} shape Flatten to internally-tagged type/name/parameters
Function result ignored Submitted the item id instead of call_id Use call_id on function_call_output
arguments treated as an object It is a JSON string JSON.parse / json.loads first
Strict mode 400 Optional property omitted from required Type it ["string","null"] and keep it required
Schema rejected allOf/not/if-then-else present Rewrite within the supported subset
cached_tokens always 0 Prompt under 1,024 tokens, or prefix drift Move static content first; check byte-identity
Cache costs rose after upgrading to GPT-5.6 Writes now bill 1.25x Switch to explicit breakpoints, or stop caching churn
Batch results mismatched Assumed output order matches input Join on custom_id
Code interpreter file vanished 20-minute idle container expiry Download outputs before the container idles
429 well under TPM RPM/RPD hit first Read x-ratelimit-remaining-requests; honor Retry-After
Background stream dies mid-run No resume cursor tracked Record sequence_number, reconnect with starting_after
Conversation cost grows superlinearly Chained input re-billed every turn Cache the static prefix, or replay a trimmed transcript

Diagnostic scripts

Local, offline, read-only — none of them make network calls or need an API key.

  • scripts/validate-strict-schema.py <schema.json> — checks a Structured Outputs / strict-tool JSON Schema against the documented constraints (unsupported keywords, additionalProperties, required coverage, property/nesting/enum/size caps).
  • scripts/validate-batch-jsonl.py <input.jsonl> — validates a Batch input file: per-line fields, supported url values, custom_id uniqueness, and the 50,000-request / 200 MB caps.
  • scripts/cache-prefix-diff.py <a.json> <b.json> — reports the byte offset where two serialized request bodies diverge, so you can see exactly how much cacheable prefix two requests actually share.

Not covered here

The corpus behind this skill does not include: OpenAI's error/HTTP status reference; the canonical Responses create-parameter table (temperature, max_output_tokens, text.verbosity, truncation, include are referenced in guides but were not confirmed against one authoritative schema page); the MCP built-in tool type's dedicated guide; the container-files sub-API paths; the full Realtime event catalog; per-model numeric rate limits; context windows and knowledge cutoffs for anything outside the GPT-5.6 trio; and SDKs other than Python and Node. Treat all of those as unverified and check the docs directly rather than accepting a confident answer.

Sources

Fetched: 2026-08-05