| name | openai-api |
| description | Build against the OpenAI API with current model selection, Responses API patterns, Codex model guidance, streaming, structured outputs, retries, and key management. Use when integrating OpenAI or Codex models into an app, service, CLI, or agent workflow. |
OpenAI API
Use the OpenAI API through the Responses API by default, choose models intentionally, and keep integration code explicit about validation, retries, and cost boundaries.
When to Activate
- Add OpenAI API calls to an application or service
- Choose a model for coding, agentic, or general reasoning work
- Build a Codex-like coding workflow against the API
- Implement streaming or tool-calling behavior
- Add structured outputs or schema validation
- Review API key handling, retries, or rate-limit behavior
- Refactor an older Chat Completions integration to a newer pattern
Model Selection
As of April 18, 2026, current official docs indicate:
gpt-5.4 is the flagship general model for complex reasoning and coding.gpt-5.4-mini is the lower-latency lower-cost GPT-5.4 variant.gpt-5.3-codex is the current most capable agentic coding model for Codex-like environments.codex-mini-latest is optimized for the Codex CLI; the docs recommend starting with gpt-4.1 for direct general API use of that class.
Sources:
| Need | Start With | Notes |
|---|
| General app logic, strong reasoning, coding | gpt-5.4 | Best default when quality matters most |
| Lower latency or cheaper general workloads | gpt-5.4-mini | Good cost/perf default |
| Agentic coding in Codex-like workflows | gpt-5.3-codex | Supports reasoning effort settings |
| Codex CLI tuning reference | codex-mini-latest | CLI-oriented, not the default general API pick |
API Surface
| Situation | Preferred | Avoid |
|---|
| New integrations | Responses API | Starting new work on legacy patterns by default |
| Need multimodal, tools, or stateful interaction | Responses API | Rebuilding these features manually |
| Existing stable legacy integration | Migrate deliberately | Blind rewrites with no regression plan |
Basic Integration Pattern
Python
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.4",
input="Summarize the migration risks in this schema diff.",
)
print(response.output_text)
TypeScript
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const response = await client.responses.create({
model: "gpt-5.4",
input: "Summarize the migration risks in this schema diff.",
});
console.log(response.output_text);
Structured Outputs and Validation
| Pattern | Preferred | Avoid |
|---|
| Model output consumed by code | Validate against a schema | Trusting free-form text blindly |
| App workflow branching on model output | Use explicit enums or tagged objects | Parsing ad hoc phrases |
| External input to model | Normalize before sending | Passing raw unbounded payloads |
BAD
const result = await client.responses.create({ model: "gpt-5.4", input });
const action = result.output_text;
if (action.includes("approve")) {
}
GOOD
const result = await client.responses.create({
model: "gpt-5.4",
input,
text: {
format: {
type: "json_schema",
name: "review_action",
schema: {
type: "object",
additionalProperties: false,
properties: {
action: { type: "string", enum: ["approve", "reject"] },
reason: { type: "string" }
},
required: ["action", "reason"]
}
}
}
});
Coding Workflows and Reasoning
| Use Case | Model | Reasoning |
|---|
| Deep repo analysis or multi-step coding | gpt-5.3-codex | Start with medium; raise to high only when needed |
| Small coding helpers or edits | gpt-5.4-mini or gpt-5.3-codex | low or medium |
| Non-coding product logic | gpt-5.4 | Match latency budget |
Rules:
- Increase reasoning only when correctness gains justify the latency.
- Keep prompts concrete: files, constraints, output shape, failure modes.
- For coding agents, provide repository context and clear acceptance criteria.
Keys, Retries, and Limits
| Concern | Rule |
|---|
| API key | Load from environment or secret manager |
| Retries | Retry transient 429/5xx responses with backoff and jitter |
| Idempotency | Make caller-side operations safe before automatic retries |
| Logging | Log request IDs, latency, model, and token usage; do not log secrets |
BAD
client = OpenAI(api_key="sk-live-real-key")
GOOD
client = OpenAI()
Checklist
