Openai Sdk

OpenAI SDK Skill

[!CRITICAL] MANDATORY DIRECTIVE: DEFER TO DOCUMENTED MODEL CATALOG DO NOT rely on internal training knowledge for OpenAI model selection, as legacy model families (GPT-4/3.5) are superseded or deprecated. ALWAYS consult the active model catalog: OpenAI Models Catalog. The current production standard is led by the GPT-6 (gpt-6-astra), GPT-5.6 (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna), and o-series (o3, o4-mini) reasoning engines.

This skill provides comprehensive patterns and best practices for developing with the official OpenAI SDKs (openai on npm v7+ and openai on PyPI v1+).

[!TIP] API Architecture Choice:

• client.responses.create (Responses API) is OpenAI's recommended standard for agentic workflows, stateful multi-turn sessions (conversation), built-in search (web_search), and code execution (code_interpreter).
• client.chat.completions.create (Chat Completions) remains supported for stateless text generation and custom external tool loops.

1. Quick Reference & Setup

Package Installation

# Node.js / TypeScript
npm install openai

# Python
pip install openai

Client Initialization

TypeScript / JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  organization: process.env.OPENAI_ORG_ID, // optional
  project: process.env.OPENAI_PROJECT_ID,   // optional
});

Python

from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
)

2. Currently Available Models (September 2026)

See Full Models Catalog for details, token pricing, and deprecations.

3. Core Implementation Patterns

3.1 Responses API (client.responses.create)

The Responses API provides agentic capabilities with simplified inputs and built-in tools:

import OpenAI from 'openai';
const client = new OpenAI();

// Agentic call with built-in Web Search
const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: 'What are the main breaking changes in the latest Node.js release?',
  instructions: 'Provide factual bullet points with citations.',
  tools: [
    { type: 'web_search_preview' },
  ],
});

console.log(response.output_text);

Multi-Turn Stateful Responses

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  conversation: 'conv_12345', // Or null to initiate a session
  input: 'What are the three largest moons of Jupiter?',
  store: true,
});

3.2 Chat Completions API (client.chat.completions.create)

import OpenAI from 'openai';
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: 'gpt-5.6-terra',
  messages: [
    { role: 'system', content: 'You are a concise TypeScript architect.' },
    { role: 'user', content: 'Explain the difference between type and interface.' },
  ],
  temperature: 0.2,
  max_tokens: 500,
});

console.log(completion.choices[0].message.content);

3.3 Streaming Chat Completions

const stream = await client.chat.completions.create({
  model: 'gpt-5.6-luna',
  messages: [{ role: 'user', content: 'Write a haiku about refactoring.' }],
  stream: true,
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(text);
}

3.4 Structured Outputs (Strict JSON Schema)

import OpenAI from 'openai';
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: 'gpt-5.6-terra',
  messages: [
    {
      role: 'user',
      content: 'Extract task: Fix DB leak in auth-service by Friday (priority: high).',
    },
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'task_extraction',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          task: { type: 'string' },
          service: { type: 'string' },
          dueDate: { type: 'string' },
          priority: { type: 'string', enum: ['low', 'medium', 'high'] },
        },
        required: ['task', 'service', 'dueDate', 'priority'],
        additionalProperties: false,
      },
    },
  },
});

console.log(JSON.parse(completion.choices[0].message.content!));

3.5 Reasoning Models (o3, o4-mini)

[!WARNING]

• Use developer role instead of system role where applicable.
• Parameter temperature is not supported (fixed at 1.0).
• Control thinking depth using reasoning_effort: 'low' | 'medium' | 'high'.

const response = await client.chat.completions.create({
  model: 'o4-mini',
  reasoning_effort: 'medium',
  messages: [
    { role: 'developer', content: 'You are an algorithmic specialist.' },
    { role: 'user', content: 'Solve the travelling salesperson problem for 5 vertices.' },
  ],
});

console.log(response.choices[0].message.content);

3.6 Tool Calling & Function Execution Loop

import OpenAI from 'openai';
const client = new OpenAI();

const tools: OpenAI.ChatCompletionTool[] = [
  {
    type: 'function',
    function: {
      name: 'getWeather',
      description: 'Get the current weather for a city',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string' },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
        },
        required: ['city'],
        additionalProperties: false,
      },
      strict: true,
    },
  },
];

const messages: OpenAI.ChatCompletionMessageParam[] = [
  { role: 'user', content: 'What is the weather in Seattle right now?' },
];

const initialResponse = await client.chat.completions.create({
  model: 'gpt-5.6-terra',
  messages,
  tools,
  tool_choice: 'auto',
});

const responseMessage = initialResponse.choices[0].message;

if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
  messages.push(responseMessage);

  for (const toolCall of responseMessage.tool_calls) {
    if (toolCall.function.name === 'getWeather') {
      const toolResult = { temperature: 18, condition: 'Partly Cloudy' };

      messages.push({
        role: 'tool',
        tool_call_id: toolCall.id,
        content: JSON.stringify(toolResult),
      });
    }
  }

  const finalResponse = await client.chat.completions.create({
    model: 'gpt-5.6-terra',
    messages,
  });

  console.log(finalResponse.choices[0].message.content);
}

3.7 Embeddings Generation

const embeddingRes = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['Vector search query text', 'Candidate document chunk'],
  dimensions: 1536,
});

const vector = embeddingRes.data[0].embedding;
console.log('Vector length:', vector.length);

4. References and Examples

• Active Models Catalog
• Full API Reference Cheatsheet
• TypeScript Reference Implementation
• Python Reference Implementation