Repository Public Research preview
1---2name: openai-api-toolkit3description: Write, review, debug and migrate code that calls the OpenAI API (Responses API, Chat Completions, function calling, structured outputs, hosted tools, embeddings, batches, Agents SDK). Use when choosing an OpenAI model, building a request or an agent, fixing a 400 or 404 error, converting Chat Completions to Responses, estimating cost, or moving code to a newer GPT model. Ships a linter and model tables built from live API probes.4license: MIT5compatibility: Scripts need Node.js 20+. No network access and no API key are required by the scripts.6metadata:7 version: "1.0.2"8 observed: "2026-11-10"9---1011# OpenAI API toolkit1213OpenAI parameter rules differ per model and per API. The same request can be valid on one model14and a 400 on the next: reasoning effort levels vary, `temperature` is only accepted in specific15conditions, several models are not served on Chat Completions at all. **Do not write OpenAI API16code from memory.** Use the tables and the linter in this skill: they were produced by sending real17requests to 29 models and recording the answers.1819## The loop to follow20211. **Pick the model** from `references/models.md` (or `node scripts/openai-api.mjs models`).22 Default to `gpt-6.1-sol`; `gpt-6-astra` for the hardest work, `gpt-6.1-terra` for speed,23 `gpt-6-luna` for high-volume simple work. Use the model the user names if they name one. Never24 invent an id.252. **Use the Responses API** (`client.responses.create`) for new code. Chat Completions still26 works for most models but not for the `-pro` models or `gpt-5.3-codex`, and it restricts tools27 on the newest reasoning models.283. **Build the request, then lint it before running anything**:29 ```bash30 node scripts/openai-api.mjs lint request.json # exit 2 = the API would reject it31 node scripts/openai-api.mjs fix request.json # corrected request + what changed32 node scripts/openai-api.mjs convert chat.json # Chat Completions → Responses33 ```34 The API (Responses or Chat) is detected from the body. Lint again after every change of model.354. **Start from a scaffold** rather than a blank file:36 ```bash37 node scripts/openai-api.mjs scaffold function_loop --language python --model gpt-6.1-sol38 ```39 Approaches: `single_call`, `streaming`, `structured_output`, `function_loop`, `conversation`,40 `web_search`, `agents_sdk`, `embeddings`, `batch`. Every template has been executed against the41 live API in TypeScript and Python.425. **Use the official SDK** (`openai`), read the key from `OPENAI_API_KEY`, never put a key in43 source, logs or prompts.446. **Check `response.status` before reading output** — every time. See "Status" below.457. **Estimate cost** when volume matters: `node scripts/openai-api.mjs cost <model> <in> <out>`.4647## Rules that cause most failures4849Per-model tables and exact error texts: `references/request-rules.md`.5051- **Parameter names differ by API.** Responses: `input`, `instructions`, `max_output_tokens`,52 `reasoning: {effort}`, `text: {format, verbosity}`. Chat Completions: `messages`,53 `max_completion_tokens`, `reasoning_effort`, `response_format`. The legacy `max_tokens` is54 rejected by every reasoning model.55- **Reasoning effort levels are model-specific.** `minimal` exists only on `gpt-5`, `gpt-5-mini`,56 `gpt-5-nano`. `none` does not exist on `gpt-6.1-sol`, `gpt-6-astra`, `gpt-5`, `o3` or the `-pro`57 models. `max` exists only on the gpt-6 / gpt-5.6 line. `gpt-4.1` and `gpt-4o` reject58 `reasoning.effort` entirely.59- **`temperature` and `top_p`** work on non-reasoning models, and on reasoning models **only while60 the effective effort is `none`**. `gpt-5.4`, `gpt-5.2` and `gpt-5.1` default to `none`, so they61 accept it until you raise the effort; the gpt-6 / gpt-5.6 / gpt-5.5 line needs62 `reasoning: {effort: "none"}` explicitly; `gpt-6.1-sol`, `gpt-6-astra`, `gpt-5`, `o3` and the63 `-pro` models never accept it.64- **`max_output_tokens` includes reasoning tokens** and has a minimum of 16. Too small a cap ends65 the response as `incomplete` with no visible text. Leave thousands of tokens on reasoning models.66- **Structured outputs** must be strict-clean: `additionalProperties: false` on every object and67 every property listed in `required` (optional fields become a union with `null`). Responses puts68 `name`, `schema`, `strict` directly under `text.format`; Chat nests them under69 `response_format.json_schema`.70- **Tool shapes differ.** Responses: `{type: "function", name, description, parameters, strict}`.71 Chat: `{type: "function", function: {…}}`. Tool results on Responses are72 `{type: "function_call_output", call_id, output}` items, not a `tool` role message.73- **Hosted tools** (`web_search`, `code_interpreter`, `file_search`, `image_generation`, `mcp`)74 exist only on the Responses API and are billed per call.75- **Function tools on Chat Completions** for the gpt-6 / gpt-5.6 line require76 `reasoning_effort: "none"`; on `gpt-6.1-sol` and `gpt-6-astra` they are not available there at77 all. Use Responses.7879## Status8081| `response.status` | Meaning | What to do |82|---|---|---|83| `completed` | Finished | Read `output_text` / walk `output` |84| `incomplete` | Stopped early; see `incomplete_details.reason` | Usually `max_output_tokens`: raise the cap. Truncated JSON is invalid |85| `in_progress` / `queued` | Background response still running | Poll `responses.retrieve(id)` |86| `failed` / `cancelled` | Did not produce output | Read `error`; retry if transient |8788`output` is a list of typed items: `message` (with `output_text` or `refusal` parts), `reasoning`,89`function_call`, `web_search_call`, and others. When you continue a conversation yourself, append90**every** output item to your input, reasoning items included.9192## Choosing how to build9394| Need | Use | Reference |95|---|---|---|96| One answer, classification, extraction | Single Responses call (+ structured output) | `references/requests.md` |97| Live text in a UI | Streaming events | `references/requests.md` |98| Your own tools, full control | Function-calling loop | `references/tools-and-agents.md` |99| Loop, handoffs and tracing handled for you | Agents SDK | `references/tools-and-agents.md` |100| Search, code execution, retrieval run by OpenAI | Hosted tools | `references/tools-and-agents.md` |101| Multi-turn memory | `previous_response_id`, or your own history | `references/state-caching-cost.md` |102| Thousands of non-urgent requests | Batch API (half price) | `references/requests.md` |103| Semantic search, clustering | Embeddings / vector stores | `references/requests.md` |104| A 4xx or odd behaviour | Error table | `references/errors.md` |105106Prefer the simplest tier that works. Most tasks need one call or a fixed workflow, not an agent.107108## Migrating code109110```bash111node scripts/openai-api.mjs migrate request.json gpt-6.1-sol112```113114A Chat Completions request aimed at a Responses-only model is converted automatically. Then, by115hand: choose a reasoning effort (a non-reasoning model had none), raise the output cap to leave116room for reasoning, loosen prompts written for older models, re-run your evaluation. Ask the user117which files are in scope before editing a codebase.118119## Honesty about this skill's limits120121- The tables are a **snapshot** (see `metadata.observed`). If the API disagrees with a table, the122 API is right: trust the error, and tell the user the skill is stale.123- Only text models visible to the probing key were probed. Audio, image, realtime, embedding and124 moderation models are not rule-probed; dated snapshots are assumed to behave like their alias.125- Not probed: computer use, the Realtime API, fine-tuning, the Assistants API, Azure OpenAI126 differences, organisation-level settings. Read `https://developers.openai.com/api/docs`.127- Two probed models have no price on the official pricing page (`gpt-5.3-codex`, `chat-latest`);128 the scripts say so instead of guessing.129- Cost output is an estimate from list prices; hosted-tool charges are not included.130131The companion MCP server `@spboucher/openai-api-mcp` exposes the same linter plus live tools132(responses, token counting, embeddings, batches, files, vector stores, speech, images).133