openai-api

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 Code

SKILL.md

GitHub

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

  • Model choice matches the workload, latency, and cost target
  • New integrations use the Responses API by default
  • Structured outputs are validated before application logic consumes them
  • API keys come from environment or secret management
  • Retries are limited to transient failures with backoff
  • Logs capture request identifiers and usage without leaking secrets
  • Coding workflows provide files, constraints, and acceptance criteria explicitly