# name: openai-api-toolkit description: 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. license: MIT compatibility: Scripts need Node.js 20+. No network access and no API key are required by the scripts. metadata: version: "1.0.2" observed: "2026-11-10"

# OpenAI API toolkit

OpenAI parameter rules differ per model and per API. The same request can be valid on one model and a 400 on the next: reasoning effort levels vary, temperature is only accepted in specific conditions, several models are not served on Chat Completions at all. Do not write OpenAI API code from memory. Use the tables and the linter in this skill: they were produced by sending real requests to 29 models and recording the answers.

# The loop to follow

Pick the model from references/models.md (or node scripts/openai-api.mjs models). Default to gpt-6.1-sol; gpt-6-astra for the hardest work, gpt-6.1-terra for speed, gpt-6-luna for high-volume simple work. Use the model the user names if they name one. Never invent an id.
Use the Responses API (client.responses.create) for new code. Chat Completions still works for most models but not for the -pro models or gpt-5.3-codex, and it restricts tools on the newest reasoning models.

Build the request, then lint it before running anything:

bash

node scripts/openai-api.mjs lint request.json      # exit 2 = the API would reject it
node scripts/openai-api.mjs fix request.json       # corrected request + what changed
node scripts/openai-api.mjs convert chat.json      # Chat Completions → Responses

The API (Responses or Chat) is detected from the body. Lint again after every change of model.

Start from a scaffold rather than a blank file:
bash
```
node scripts/openai-api.mjs scaffold function_loop --language python --model gpt-6.1-sol
```
Approaches: single_call, streaming, structured_output, function_loop, conversation, web_search, agents_sdk, embeddings, batch. Every template has been executed against the live API in TypeScript and Python.
Use the official SDK (openai), read the key from OPENAI_API_KEY, never put a key in source, logs or prompts.
Check response.status before reading output — every time. See "Status" below.
Estimate cost when volume matters: node scripts/openai-api.mjs cost <model> <in> <out>.

# Rules that cause most failures

Per-model tables and exact error texts: references/request-rules.md.

Parameter names differ by API. Responses: input, instructions, max_output_tokens, reasoning: {effort}, text: {format, verbosity}. Chat Completions: messages, max_completion_tokens, reasoning_effort, response_format. The legacy max_tokens is rejected by every reasoning model.
Reasoning effort levels are model-specific. minimal exists only on gpt-5, gpt-5-mini, gpt-5-nano. none does not exist on gpt-6.1-sol, gpt-6-astra, gpt-5, o3 or the -pro models. max exists only on the gpt-6 / gpt-5.6 line. gpt-4.1 and gpt-4o reject reasoning.effort entirely.
temperature and top_p work on non-reasoning models, and on reasoning models only while the effective effort is none. gpt-5.4, gpt-5.2 and gpt-5.1 default to none, so they accept it until you raise the effort; the gpt-6 / gpt-5.6 / gpt-5.5 line needs reasoning: {effort: "none"} explicitly; gpt-6.1-sol, gpt-6-astra, gpt-5, o3 and the -pro models never accept it.
max_output_tokens includes reasoning tokens and has a minimum of 16. Too small a cap ends the response as incomplete with no visible text. Leave thousands of tokens on reasoning models.
Structured outputs must be strict-clean: additionalProperties: false on every object and every property listed in required (optional fields become a union with null). Responses puts name, schema, strict directly under text.format; Chat nests them under response_format.json_schema.
Tool shapes differ. Responses: {type: "function", name, description, parameters, strict}. Chat: {type: "function", function: {…}}. Tool results on Responses are {type: "function_call_output", call_id, output} items, not a tool role message.
Hosted tools (web_search, code_interpreter, file_search, image_generation, mcp) exist only on the Responses API and are billed per call.
Function tools on Chat Completions for the gpt-6 / gpt-5.6 line require reasoning_effort: "none"; on gpt-6.1-sol and gpt-6-astra they are not available there at all. Use Responses.

# Status

`response.status`	Meaning	What to do
`completed`	Finished	Read `output_text` / walk `output`
`incomplete`	Stopped early; see `incomplete_details.reason`	Usually `max_output_tokens`: raise the cap. Truncated JSON is invalid
`in_progress` / `queued`	Background response still running	Poll `responses.retrieve(id)`
`failed` / `cancelled`	Did not produce output	Read `error`; retry if transient

output is a list of typed items: message (with output_text or refusal parts), reasoning, function_call, web_search_call, and others. When you continue a conversation yourself, append every output item to your input, reasoning items included.

# Choosing how to build

Need	Use	Reference
One answer, classification, extraction	Single Responses call (+ structured output)	`references/requests.md`
Live text in a UI	Streaming events	`references/requests.md`
Your own tools, full control	Function-calling loop	`references/tools-and-agents.md`
Loop, handoffs and tracing handled for you	Agents SDK	`references/tools-and-agents.md`
Search, code execution, retrieval run by OpenAI	Hosted tools	`references/tools-and-agents.md`
Multi-turn memory	`previous_response_id`, or your own history	`references/state-caching-cost.md`
Thousands of non-urgent requests	Batch API (half price)	`references/requests.md`
Semantic search, clustering	Embeddings / vector stores	`references/requests.md`
A 4xx or odd behaviour	Error table	`references/errors.md`

Prefer the simplest tier that works. Most tasks need one call or a fixed workflow, not an agent.

# Migrating code

bash

node scripts/openai-api.mjs migrate request.json gpt-6.1-sol

A Chat Completions request aimed at a Responses-only model is converted automatically. Then, by hand: choose a reasoning effort (a non-reasoning model had none), raise the output cap to leave room for reasoning, loosen prompts written for older models, re-run your evaluation. Ask the user which files are in scope before editing a codebase.

# Honesty about this skill's limits

The tables are a snapshot (see metadata.observed). If the API disagrees with a table, the API is right: trust the error, and tell the user the skill is stale.
Only text models visible to the probing key were probed. Audio, image, realtime, embedding and moderation models are not rule-probed; dated snapshots are assumed to behave like their alias.
Not probed: computer use, the Realtime API, fine-tuning, the Assistants API, Azure OpenAI differences, organisation-level settings. Read https://developers.openai.com/api/docs.
Two probed models have no price on the official pricing page (gpt-5.3-codex, chat-latest); the scripts say so instead of guessing.
Cost output is an estimate from list prices; hosted-tool charges are not included.

The companion MCP server @spboucher/openai-api-mcp exposes the same linter plus live tools (responses, token counting, embeddings, batches, files, vector stores, speech, images).

spb llm-api-toolkits