# Openai Sdk

> Official guide for developing with the OpenAI SDK (openai npm package v7+ in Node.js/TypeScript and openai Python package v1+) and OpenAI APIs. Use when implementing, upgrading, or debugging OpenAI API calls, Responses API, Chat Completions, reasoning models (o1, o3, o4-mini), structured outputs, function calling/tools, streaming, vision, audio, or embeddings.

- Skill: `matthewtaormina/openai-sdk` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add matthewtaormina/openai-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matthewtaormina/openai-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: MatthewTaormina (https://skillmd.com/u/matthewtaormina)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/matthewtaormina/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](./references/models.md).**
> 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

```bash
# Node.js / TypeScript
npm install openai

# Python
pip install openai
```

### Client Initialization

#### TypeScript / JavaScript
```typescript
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
```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](./references/models.md) for details, token pricing, and deprecations.*

| Model ID | Generation | Max Context | Features |
| :--- | :--- | :--- | :--- |
| `gpt-6-astra` | Flagship Frontier | 256,000 tokens | Deep reasoning, autonomous agents, computer use, cybersecurity |
| `gpt-5.6-sol` | Professional Flagship | 128,000 tokens | Enterprise architecture, advanced code generation, multimodal |
| `gpt-5.6-terra` | Balanced Workhorse | 128,000 tokens | High intelligence, cost-effective, low latency for production |
| `gpt-5.6-luna` | High Throughput | 128,000 tokens | Cost-optimized for high-volume customer-facing agents |
| `o3` / `o3-pro` | Frontier Reasoning | 200,000 tokens | Deep mathematical proofs, algorithm design, competitive coding |
| `o4-mini` | Fast Reasoning | 200,000 tokens | Real-time agent verification, logic auditing, high-speed reasoning |
| `text-embedding-3-large` | Embeddings | 8,191 tokens | 3,072 dimensions, high-accuracy semantic search |
| `text-embedding-3-small` | Embeddings | 8,191 tokens | 1,536 dimensions, fast vector search |

---

## 3. Core Implementation Patterns

### 3.1 Responses API (`client.responses.create`)

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

```typescript
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
```typescript
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`)

```typescript
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

```typescript
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)

```typescript
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'`.

```typescript
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

```typescript
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

```typescript
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**](./references/models.md)
* [Full API Reference Cheatsheet](./references/api-reference.md)
* [TypeScript Reference Implementation](./examples/typescript-examples.ts)
* [Python Reference Implementation](./examples/python-examples.py)