openai-api — скилл для Claude Code: что делает и как установить
Скилл помогает интегрировать OpenAI API в проекты: настраивает вызовы моделей GPT-5 и GPT-4o, стриминг, вызов функций, эмбеддинги и обработку ошибок.
MIT ★ 328 обновлён 2026-10-29
npx skills add coco-research/coco --skill openai-api -a claude-codeЧто делает openai-api
Скилл содержит готовые шаблоны интеграции для библиотеки [email protected] и прямых запросов через fetch в средах вроде Cloudflare Workers. Внутри описана работа с моделями GPT-5, GPT-5.1, GPT-5.2 и сериями O (o3, o4-mini), генерация картинок, аудио через Whisper и TTS, модерация и структурированный JSON-вывод.
Справочник учитывает особенности конфигурации свежих моделей: для GPT-5 параметр temperature не поддерживается, а глубина рассуждений задаётся через reasoning_effort. Поскольку Chat Completions API работает без сохранения состояния, агент помогает корректно прокидывать историю сообщений или переключаться на связанный скилл openai-responses.
Какие задачи решает
- настроить потоковую передачу ответов через SSE
- исправить ошибки типизации TypeScript и лимиты 429
- подключить вызов функций и валидацию схем JSON
- реализовать генерацию эмбеддингов для RAG
Примеры запросов агенту
- Напиши вызов чата на GPT-5 через официальный SDK с параметром reasoning_effort
- Сделай стриминг ответов OpenAI через fetch для Cloudflare Workers
- Как обработать ошибку 429 rate limit в клиенте [email protected]?
Как установить openai-api
1Через Skills CLI (Vercel)
npx skills add coco-research/coco --skill openai-api -a claude-code2Вручную: положить файлы
~/.claude/skills/openai-api/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/openai-api/
1Через Skills CLI (Vercel)
npx skills add coco-research/coco --skill openai-api -a codex2Вручную: положить файлы
.agents/skills/openai-api/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add coco-research/coco --skill openai-api -a cursor2Вручную: положить файлы
.cursor/skills/openai-api/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install coco-research/coco skills/openai-api2Вручную: положить файлы
.github/skills/openai-api/SKILL.md1Через Skills CLI (Vercel)
npx skills add coco-research/coco --skill openai-api -a gemini-cli2Командой платформы
gemini skills install https://github.com/coco-research/coco --path skills/openai-apiВручную: положить файлы
.devin/skills/openai-api/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об openai-api
Как установить openai-api в Claude Code?
Выполните в терминале команду npx skills add coco-research/coco --skill openai-api -a claude-code.
Что делает скилл openai-api?
Он даёт агенту шаблоны кода для работы с чатом, эмбеддингами, аудио, изображениями и инструментами OpenAI, предотвращая частые ошибки интеграции.
Поддерживает ли скилл линейку моделей GPT-5?
Да, руководство описывает работу с GPT-5, 5.1 и 5.2, включая управление рассуждениями через reasoning_effort вместо неподдерживаемого параметра temperature.
Исходный текст
SKILL.md · MIT
--- name: openai-api description: "Use when implementing GPT chat, streaming, function calling, embeddings for RAG, images, audio or batch jobs, or troubleshooting 429 rate limits and API or TypeScript errors. Stateless OpenAI patterns that prevent 16 documented errors." user-invocable: true domain: engineering --- # OpenAI API - Complete Guide **Version**: Production Ready ✅ **Package**: [email protected] **Last Updated**: 2026-01-20 --- ## Status **✅ Production Ready**: - ✅ Chat Completions API (GPT-5, GPT-4o, GPT-4 Turbo) - ✅ Embeddings API (text-embedding-3-small, text-embedding-3-large) - ✅ Images API (DALL-E 3 generation + GPT-Image-1 editing) - ✅ Audio API (Whisper transcription + TTS with 11 voices) - ✅ Moderation API (11 safety categories) - ✅ Streaming patterns (SSE) - ✅ Function calling / Tools - ✅ Structured outputs (JSON schemas) - ✅ Vision (GPT-4o) - ✅ Both Node.js SDK and fetch approaches --- ## Table of Contents 1. [Quick Start](#quick-start) 2. [Chat Completions API](#chat-completions-api) 3. [GPT-5 Series Models](#gpt-5-series-models) 4. [Streaming Patterns](#streaming-patterns) 5. [Function Calling](#function-calling) 6. [Structured Outputs](#structured-outputs) 7. [Vision (GPT-4o)](#vision-gpt-4o) 8. [Embeddings API](#embeddings-api) 9. [Images API](#images-api) 10. [Audio API](#audio-api) 11. [Moderation API](#moderation-api) 12. [Error Handling](#error-handling) 13. [Rate Limits](#rate-limits) 14. [Common Mistakes & Gotchas](#common-mistakes--gotchas) 15. [TypeScript Gotchas](#typescript-gotchas) 16. [Production Best Practices](#production-best-practices) 17. [Relationship to openai-responses](#relationship-to-openai-responses) --- ## Quick Start ### Installation ```bash npm install [email protected] ``` ### Environment Setup ```bash export OPENAI_API_KEY="sk-..." ``` Or create `.env` file: ``` OPENAI_API_KEY=sk-... ``` ### First Chat Completion (Node.js SDK) ```typescript import OpenAI from 'openai'; const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); const completion = await openai.chat.completions.create({ model: 'gpt-5', messages: [ { role: 'user', content: 'What are the three laws of robotics?' } ], }); console.log(completion.choices[0].message.content); ``` ### First Chat Completion (Fetch - Cloudflare Workers) ```typescript const response = await fetch('https://api.openai.com/v1/chat/completions', { method: 'POST', headers: { 'Authorization': `Bearer ${env.OPENAI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'gpt-5', messages: [ { role: 'user', content: 'What are the three laws of robotics?' } ], }), }); const data = await response.json(); console.log(data.choices[0].message.content); ``` --- ## Chat Completions API **Endpoint**: `POST /v1/chat/completions` The Chat Completions API is the core interface for interacting with OpenAI's language models. It supports conversational AI, text generation, function calling, structured outputs, and vision capabilities. ### Supported Models #### GPT-5 Series (Released August 2025) - **gpt-5**: Full-featured reasoning model with advanced capabilities - **gpt-5-mini**: Cost-effective alternative with good performance - **gpt-5-nano**: Smallest/fastest variant for simple tasks #### GPT-4o Series - **gpt-4o**: Multimodal model with vision capabilities - **gpt-4-turbo**: Fast GPT-4 variant #### GPT-4 Series (Legacy) - **gpt-4**: Original GPT-4 model *(deprecated - use gpt-5 or gpt-4o)* ### Basic Request Structure ```typescript { model: string, // Model to use (e.g., "gpt-5") messages: Message[], // Conversation history reasoning_effort?: string, // GPT-5 only: "minimal" | "low" | "medium" | "high" verbosity?: string, // GPT-5 only: "low" | "medium" | "high" temperature?: number, // NOT supported by GPT-5 max_tokens?: number, // Max tokens to generate stream?: boolean, // Enable streaming tools?: Tool[], // Function calling tools } ``` ### Response Structure ```typescript { id: string, // Unique completion ID object: "chat.completion", created: number, // Unix timestamp model: string, // Model used choices: [{ index: number, message: { role: "assistant", content: string, // Generated text tool_calls?: ToolCall[] // If function calling }, finish_reason: string // "stop" | "length" | "tool_calls" }], usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number } } ``` ### Message Roles & Multi-turn Conversations Three roles: **system** (behavior), **user** (input), **assistant** (model responses). **Important**: API is **stateless** - send full conversation history each request. For stateful conversations, use `openai-responses` skill. --- ## GPT-5 Series Models GPT-5 models (released August 2025) introduce reasoning and verbosity controls. ### GPT-5.2 (Released December 11, 2025) **Latest flagship model**: - **gpt-5.2**: 400k context window, 128k output tokens - **xhigh reasoning_effort**: New level beyond "high" for complex problems - **Compaction**: Extends context for long workflows (via API endpoint) - **Pricing**: $1.75/$14 per million tokens (1.4x of GPT-5.1) ```typescript // GPT-5.2 with maximum reasoning const completion = await openai.chat.completions.create({ model: 'gpt-5.2', messages: [{ role: 'user', content: 'Solve this extremely complex problem...' }], reasoning_effort: 'xhigh', // NEW: Beyond "high" }); ``` ### GPT-5.1 (Released November 13, 2025) **Warmer, more intelligent model**: - **gpt-5.1**: Adaptive reasoning that varies thinking time dynamically - **24-hour extended prompt caching**: Faster follow-up queries at lower cost - **New developer tools**: apply_patch (code editing), shell (command execution) **BREAKING CHANGE**: GPT-5.1/5.2 default to `reasoning_effort: 'none'` (vs GPT-5 defaulting to `'medium'`). ### O-Series Reasoning Models Dedicated reasoning models (separate from GPT-5): | Model | Released | Purpose | |-------|----------|---------| | **o3** | Apr 16, 2025 | Successor to o1, advanced reasoning | | **o3-pro** | Jun 10, 2025 | Extended compute version of o3 | | **o3-mini** | Jan 31, 2025 | Smaller, faster o3 variant | | **o4-mini** | Apr 16, 2025 | Fast, cost-efficient reasoning | ```typescript // O-series models const completion = await openai.chat.completions.create({ model: 'o3', // or 'o3-mini', 'o4-mini' messages: [{ role: 'user', content: 'Complex reasoning task...' }], }); ``` **Note**: O-series may be deprecated in favor of GPT-5 with `reasoning_effort` parameter. ### reasoning_effort Parameter Controls thinking depth (GPT-5/5.1/5.2): - **"none"**: No reasoning (fastest) - GPT-5.1/5.2 default - **"minimal"**: Quick responses *(Note: May not be available - [Issue #1690](https://github.com/openai/openai-node/issues/1690))* - **"low"**: Basic reasoning - **"medium"**: Balanced - GPT-5 default - **"high"**: Deep reasoning - **"xhigh"**: Maximum reasoning (GPT-5.2 only) ### verbosity Parameter Controls output detail (GPT-5 series): - **"low"**: Concise - **"medium"**: Balanced (default) - **"high"**: Verbose ### GPT-5 Limitations **NOT Supported**: - ❌ `temperature`, `top_p`, `logprobs` parameters - ❌ Stateful Chain of Thought between turns **Alternatives**: Use GPT-4o for temperature/top_p, or `openai-responses` skill for stateful reasoning --- ## Streaming Patterns Enable with `stream: true` for token-by-token delivery. ### Node.js SDK ```typescript const stream = await openai.chat.completions.create({ model: 'gpt-5.1', messages: [{ role: 'user', content: 'Write a poem' }], stream: true, }); for await (const chunk of stream) { const content = chunk.choices[0]?.delta?.content || ''; process.stdout.write(content); } ``` ### Fetch (Cloudflare Workers) ```typescript const response = await fetch('https://api.openai.com/v1/chat/completions', { method: 'POST', headers: { 'Authorization': `Bearer ${env.OPENAI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'gpt-5.1', messages: [{ role: 'user', content: 'Write a poem' }], stream: true, }), }); const reader = response.body?.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader!.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\n').filter(line => line.trim() !== ''); for (const line of lines) { if (line.startsWith('data: ')) { const data = line.slice(6); if (data === '[DONE]') break; try { const json = JSON.parse(data); const content = json.choices[0]?.delta?.content || ''; console.log(content); } catch (e) { // Skip invalid JSON } } } } ``` **Server-Sent Events (SSE) format**: ``` data: {"id":"chatcmpl-xyz","choices":[{"delta":{"content":"Hello"}}]} data: [DONE] ``` **Key Points**: Handle incomplete chunks, `[DONE]` signal, and invalid JSON gracefully. --- ## Function Calling Define tools with JSON schema, model invokes them based on context. ### Tool Definition & Request ```typescript const tools = [{ type: 'function', function: { name: 'get_weather', description: 'Get current weather for a location', parameters: { type: 'object', properties: { location: { type: 'string', description: 'City name' }, unit: { type: 'string', enum: ['celsius', 'fahrenheit'] } }, required: ['location'] } } }]; const completion = await openai.chat.completions.create({ model: 'gpt-5.1', messages: [{ role: 'user', content: 'What is the weather in SF?' }], tools: tools, }); ``` ### Handle Tool Calls ```typescript const message = completion.choices[0].message; if (message.tool_calls) { for (const toolCall of message.tool_calls) { const args = JSON.parse(toolCall.function.arguments); const result = await executeFunction(toolCall.function.name, args); // Send result back to model await openai.chat.completions.create({ model: 'gpt-5.1', messages: [ ...messages, message, { role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(result) } ], tools: tools, }); } } ``` **Loop pattern**: Continue calling API until no tool_calls in response. --- ## Structured Outputs Structured outputs allow you to enforce JSON schema validation on model responses. ### Using JSON Schema ```typescript const completion = await openai.chat.completions.create({ model: 'gpt-4o', // Note: Structured outputs best supported on GPT-4o messages: [ { role: 'user', content: 'Generate a person profile' } ], response_format: { type: 'json_schema', json_schema: { name: 'person_profile', strict: true, schema: { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' }, skills: { type: 'array', items: { type: 'string' } } }, required: ['name', 'age', 'skills'], additionalProperties: false } } } }); const person = JSON.parse(completion.choices[0].message.content); // { name: "Alice", age: 28, skills: ["TypeScript", "React"] } ``` ### JSON Mode (Simple) For simpler use cases without strict schema validation: ```typescript const completion = await openai.chat.completions.create({ model: 'gpt-5', messages: [ { role: 'user', content: 'List 3 programming languages as JSON' } ], response_format: { type: 'json_object' } }); const data = JSON.parse(completion.choices[0].message.content); ``` **Important**: When using `response_format`, include "JSON" in your prompt to guide the model. --- ## Vision (GPT-4o) GPT-4o supports image understanding alongside text. ### Image via URL ```typescript const completion = await openai.chat.completions.create({ model: 'gpt-4o', messages: [ { role: 'user', content: [ { type: 'text', text: 'What is in this image?' }, { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } } ] } ] }); ``` ### Image via Base64 ```typescript import fs from 'fs'; const imageBuffer = fs.readFileSync('./image.jpg'); const base64Image = imageBuffer.toString('base64'); const completion = await openai.chat.completions.create({ model: 'gpt-4o', messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe this image in detail' }, { type: 'image_url', image_url: { url: `data:image/jpeg;base64,${base64Image}` } } ] } ] }); ``` ### Multiple Images ```typescript const completion = await openai.chat.completions.create({ model: 'gpt-4o', messages: [ { role: 'user', content: [ { type: 'text', text: 'Compare these two images' }, { type: 'image_url', image_url: { url: 'https://example.com/image1.jpg' } }, { type: 'image_url', image_url: { url: 'https://example.com/image2.jpg' } } ] } ] }); ``` --- ## Embeddings API **Endpoint**: `POST /v1/embeddings` Convert text to vectors for semantic search and RAG. ### Models - **text-embedding-3-large**: 3072 dims (custom: 256-3072), highest quality - **text-embedding-3-small**: 1536 dims (custom: 256-1536), cost-effective, recommended ### Basic Request ```typescript const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'The food was delicious.', }); // Returns: { data: [{ embedding: [0.002, -0.009, ...] }] } ``` ### Custom Dimensions (OpenAI-Specific) ```typescript const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'Sample text', dimensions: 256, // Reduced from 1536 default }); ``` **Benefits**: 4x-12x storage reduction, faster search, minimal quality loss. ### Batch Processing ```typescript const embeddings = await openai.embeddings.create({ model: 'text-embedding-3-small', input: ['First doc', 'Second doc', 'Third doc'], }); ``` **Limits**: 8192 tokens/input, 300k tokens total across batch, 2048 max array size. **Key Points**: Use custom dimensions for efficiency, batch up to 2048 docs, cache embeddings (deterministic). --- ## Images API ### Image Generation (DALL-E 3) **Endpoint**: `POST /v1/images/generations` ```typescript const image = await openai.images.generate({ model: 'dall-e-3', prompt: 'A white siamese cat with striking blue eyes', size: '1024x1024', // Also: 1024x1536, 1536x1024, 1024x1792, 1792x1024 quality: 'standard', // or 'hd' style: 'vivid', // or 'natural' }); console.log(image.data[0].url); console.log(image.data[0].revised_prompt); // DALL-E 3 may revise for safety ``` **DALL-E 3 Specifics**: - Only supports `n: 1` (one image per request) - May revise prompts for safety/quality (check `revised_prompt`) - URLs expire in 1 hour (use `response_format: 'b64_json'` for persistence) ### Image Editing (GPT-Image-1) **Endpoint**: `POST /v1/images/edits` **Important**: Uses `multipart/form-data`, not JSON. ```typescript import FormData from 'form-data'; const formData = new FormData(); formData.append('model', 'gpt-image-1'); formData.append('image', fs.createReadStream('./woman.jpg')); formData.append('image_2', fs.createReadStream('./logo.png')); // Optional composite formData.append('prompt', 'Add the logo to the fabric.'); formData.append('input_fidelity', 'high'); // low|medium|high formData.append('format', 'png'); // Supports transparency formData.append('background', 'transparent'); // transparent|white|black const response = await fetch('https://api.openai.com/v1/images/edits', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`, ...formData.getHeaders(), }, body: formData, }); ``` **GPT-Image-1 Features**: Supports transparency (PNG/WebP), compositing with image_2, output compression control. --- ## Audio API ### Whisper Transcription **Endpoint**: `POST /v1/audio/transcriptions` ```typescript const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream('./audio.mp3'), model: 'whisper-1', }); // Returns: { text: "Transcribed text..." } ``` **Formats**: mp3, mp4, mpeg, mpga, m4a, wav, webm ### Text-to-Speech (TTS) **Endpoint**: `POST /v1/audio/speech` **Models**: - **tts-1**: Standard quality, lowest latency - **tts-1-hd**: High definition audio - **gpt-4o-mini-tts**: Supports voice instructions (November 2024), streaming **11 Voices**: alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse ```typescript const mp3 = await openai.audio.speech.create({ model: 'tts-1', voice: 'alloy', input: 'Text to speak (max 4096 chars)', speed: 1.0, // 0.25-4.0 response_format: 'mp3', // mp3|opus|aac|flac|wav|pcm }); ``` ### Voice Instructions (gpt-4o-mini-tts Only) ```typescript const speech = await openai.audio.speech.create({ model: 'gpt-4o-mini-tts', voice: 'nova', input: 'Welcome to support.', instructions: 'Speak in a calm, professional tone.', // Custom voice control }); ``` ### Streaming TTS (gpt-4o-mini-tts Only) ```typescript const response = await fetch('https://api.openai.com/v1/audio/speech', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'gpt-4o-mini-tts', voice: 'nova', input: 'Long text...', stream_format: 'sse', // Server-Sent Events }), }); ``` **Note**: `instructions` and `stream_format: "sse"` only work with gpt-4o-mini-tts. --- ## Moderation API **Endpoint**: `POST /v1/moderations` Check content across 11 safety categories. ```typescript const moderation = await openai.moderations.create({ model: 'omni-moderation-latest', input: 'Text to moderate', }); console.log(moderation.results[0].flagged); console.log(moderation.results[0].categories); console.log(moderation.results[0].category_scores); // 0.0-1.0 ``` ### 11 Safety Categories 1. **sexual**: Sexual content 2. **hate**: Hateful content based on identity 3. **harassment**: Bullying, intimidation 4. **self-harm**: Promoting self-harm 5. **sexual/minors**: Child sexualization (CSAM) 6. **hate/threatening**: Violent threats based on identity 7. **violence/graphic**: Extreme gore 8. **self-harm/intent**: Suicidal ideation 9. **self-harm/instructions**: Self-harm how-to guides 10. **harassment/threatening**: Violent personal threats 11. **violence**: Violence threats/glorification **Scores**: 0.0 (low confidence) to 1.0 (high confidence) ### Batch Moderation ```typescript const moderation = await openai.moderations.create({ model: 'omni-moderation-latest', input: ['Text 1', 'Text 2', 'Text 3'], }); ``` **Best Practices**: Use lower thresholds for severe categories (sexual/minors: 0.1, self-harm/intent: 0.2), batch requests, fail closed on errors. --- ## Realtime API (Voice/Audio) Low-latency voice and audio interactions via WebSocket/WebRTC. GA August 28, 2025. **Update (Feb 2025)**: Concurrent session limit removed - unlimited simultaneous connections now supported. ### WebSocket Connection ```typescript const ws = new WebSocket('wss://api.openai.com/v1/realtime', { headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}`, 'OpenAI-Beta': 'realtime=v1', }, }); ws.onopen = () => { ws.send(JSON.stringify({ type: 'session.update', session: { voice: 'alloy', // or: echo, fable, onyx, nova, shimmer, marin, cedar instructions: 'You are a helpful assistant', input_audio_transcription: { model: 'whisper-1' }, }, })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); switch (data.type) { case 'response.audio.delta': // Handle audio chunk (base64 encoded) playAudioChunk(data.delta); break; case 'response.text.delta': // Handle text transcript console.log(data.delta); break; } }; // Send user audio ws.send(JSON.stringify({ type: 'input_audio_buffer.append', audio: base64AudioData, })); ``` ### Model - **gpt-realtime**: Production model ($32/1M input, $64/1M output) - **gpt-realtime-mini**: Smaller, faster variant ### Features - Voice activity detection - Interruption handling - Function calling while speaking - 13 voices (including new: marin, cedar) - WebRTC, WebSocket, SIP connections --- ## Batch API (50% Cost Savings) Process large volumes with 24-hour maximum turnaround at 50% lower cost. **Note**: While the completion window is 24 hours maximum, jobs often complete much faster (reports show completion in under 1 hour for tasks estimated at 10+ hours). ### Create Batch ```typescript // 1. Create JSONL file with requests const requests = [ { custom_id: 'req-1', method: 'POST', url: '/v1/chat/completions', body: { model: 'gpt-5.1', messages: [{ role: 'user', content: 'Hello 1' }] } }, { custom_id: 'req-2', method: 'POST', url: '/v1/chat/completions', body: { model: 'gpt-5.1', messages: [{ role: 'user', content: 'Hello 2' }] } }, ]; // 2. Upload file const file = await openai.files.create({ file: new File([requests.map(r => JSON.stringify(r)).join('\n')], 'batch.jsonl'), purpose: 'batch', }); // 3. Create batch const batch = await openai.batches.create({ input_file_id: file.id, endpoint: '/v1/chat/completions', completion_window: '24h', }); console.log(batch.id); // batch_abc123 ``` ### Check Status ```typescript const batch = await openai.batches.retrieve('batch_abc123'); console.log(batch.status); // validating, in_progress, completed, failed console.log(batch.request_counts); // { total, completed, failed } if (batch.status === 'completed') { const results = await openai.files.content(batch.output_file_id); // Parse JSONL results } ``` ### When to Use Batch API | Use Case | Batch API? | |----------|------------| | Content moderation at scale | ✅ | | Document processing (embeddings) | ✅ | | Bulk summarization | ✅ | | Real-time chat | ❌ Use Chat API | | Streaming responses | ❌ Use Chat API | --- ## Error Handling & Rate Limits ### Common Errors - **401**: Invalid API key - **429**: Rate limit exceeded (implement exponential backoff) - **500/503**: Server errors (retry with backoff) ```typescript async function completionWithRetry(params, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await openai.chat.completions.create(params); } catch (error) { if (error.status === 429 && i < maxRetries - 1) { await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000)); continue; } throw error; } } } ``` ### Rate Limit Headers (OpenAI-Specific) ```typescript response.headers.get('x-ratelimit-limit-requests'); response.headers.get('x-ratelimit-remaining-requests'); response.headers.get('x-ratelimit-reset-requests'); ``` **Limits**: Based on RPM (Requests/Min), TPM (Tokens/Min), IPM (Images/Min). Varies by tier and model. --- ## Common Mistakes & Gotchas ### Mistake #1: Using Wrong Model Name "gpt-5.1-mini" **Error**: `400 The requested model 'gpt-5.1-mini' does not exist` **Source**: [GitHub Issue #1706](https://github.com/openai/openai-node/issues/1706) **Wrong**: ```typescript model: 'gpt-5.1-mini' // Does not exist ``` **Correct**: ```typescript model: 'gpt-5-mini' // Correct (no .1 suffix) ``` Available GPT-5 series models: - `gpt-5`, `gpt-5-mini`, `gpt-5-nano` - `gpt-5.1`, `gpt-5.2` - Note: No `gpt-5.1-mini` or `gpt-5.2-mini` - mini variant doesn't have .1/.2 versions ### Mistake #2: Embeddings Dimension Mismatch **Error**: `ValueError: shapes (0,256) and (1536,) not aligned` Ensure vector database dimensions match embeddings API `dimensions` parameter: ```typescript // ❌ Wrong - missing dimensions, returns 1536 default const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'text', }); // ✅ Correct - specify dimensions to match database const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'text', dimensions: 256, // Match your vector database config }); ``` ### Mistake #3: Forgetting reasoning_effort When Upgrading to GPT-5.1/5.2 **Issue**: GPT-5.1 and GPT-5.2 default to `reasoning_effort: 'none'` (breaking change from GPT-5) ```typescript // GPT-5 (defaults to 'medium') model: 'gpt-5' // Automatic reasoning // GPT-5.1 (defaults to 'none') model: 'gpt-5.1' // NO reasoning unless specified! reasoning_effort: 'medium' // Must add explicitly ``` --- ## TypeScript Gotchas ### Gotcha #1: usage Field May Be Null **Issue**: [GitHub Issue #1402](https://github.com/openai/openai-node/issues/1402) With `strictNullChecks: true`, the `usage` field may cause type errors: ```typescript // ❌ TypeScript error with strictNullChecks const tokens = completion.usage.total_tokens; // ✅ Use optional chaining or null check const tokens = completion.usage?.total_tokens ?? 0; // Or explicit check if (completion.usage) { const tokens = completion.usage.total_tokens; } ``` ### Gotcha #2: text_tokens and image_tokens Not Typed **Issue**: [GitHub Issue #1718](https://github.com/openai/openai-node/issues/1718) Multimodal requests include `text_tokens` and `image_tokens` fields not in TypeScript types: ```typescript // These fields exist but aren't typed const usage = completion.usage as any; console.log(usage.text_tokens); console.log(usage.image_tokens); ``` ### Gotcha #3: Zod Unions Broken in v4.1.13+ **Issue**: [GitHub Issue #1709](https://github.com/openai/openai-node/issues/1709) Using `zodResponseFormat()` with Zod 4.1.13+ breaks union type conversion: ```typescript // ❌ Broken with Zod 4.1.13+ const schema = z.object({ status: z.union([z.literal('success'), z.literal('error')]), }); // ✅ Workaround: Use enum instead const schema = z.object({ status: z.enum(['success', 'error']), }); ``` **Alternatives**: 1. Downgrade to Zod 4.1.12 2. Use enum instead of union 3. Manually construct JSON schema --- ## Production Best Practices **Security**: Never expose API keys client-side, use server-side proxy, store keys in environment variables. **Performance**: Stream responses >100 tokens, set max_tokens appropriately, cache deterministic responses. **Cost**: Use gpt-5.1 with reasoning_effort: 'none' for simple tasks, gpt-5.1 with 'high' for complex reasoning. --- ## Relationship to openai-responses ### openai-api (This Skill) **Traditional/stateless API** for: - ✅ Simple chat completions - ✅ Embeddings for RAG/search - ✅ Images (DALL-E 3) - ✅ Audio (Whisper/TTS) - ✅ Content moderation - ✅ One-off text generation - ✅ Cloudflare Workers / edge deployment **Characteristics**: - Stateless (you manage conversation history) - No built-in tools - Maximum flexibility - Works everywhere (Node.js, browsers, Workers, etc.) ### openai-responses Skill **Stateful/agentic API** for: - ✅ Automatic conversation state management - ✅ Preserved reasoning (Chain of Thought) across turns - ✅ Built-in tools (Code Interpreter, File Search, Web Search, Image Generation) - ✅ MCP server integration - ✅ Background mode for long tasks - ✅ Polymorphic outputs **Characteristics**: - Stateful (OpenAI manages conversation) - Built-in tools included - Better for agentic workflows - Higher-level abstraction ### When to Use Which? | Use Case | Use openai-api | Use openai-responses | |----------|----------------|---------------------| | Simple chat | ✅ | ❌ | | RAG/embeddings | ✅ | ❌ | | Image generation | ✅ | ✅ | | Audio processing | ✅ | ❌ | | Agentic workflows | ❌ | ✅ | | Multi-turn reasoning | ❌ | ✅ | | Background tasks | ❌ | ✅ | | Custom tools only | ✅ | ❌ | | Built-in + custom tools | ❌ | ✅ | **Use both**: Many apps use openai-api for embeddings/images/audio and openai-responses for conversational agents. --- ## Dependencies ```bash npm install [email protected] ``` **Environment**: `OPENAI_API_KEY=sk-...` **TypeScript**: Fully typed with included definitions. --- ## Official Documentation ### Core APIs - **Chat Completions**: https://platform.openai.com/docs/api-reference/chat/create - **Embeddings**: https://platform.openai.com/docs/api-reference/embeddings - **Images**: https://platform.openai.com/docs/api-reference/images - **Audio**: https://platform.openai.com/docs/api-reference/audio - **Moderation**: https://platform.openai.com/docs/api-reference/moderations ### Guides - **GPT-5 Guide**: https://platform.openai.com/docs/guides/latest-model - **Function Calling**: https://platform.openai.com/docs/guides/function-calling - **Structured Outputs**: https://platform.openai.com/docs/guides/structured-outputs - **Vision**: https://platform.openai.com/docs/guides/vision - **Rate Limits**: https://platform.openai.com/docs/guides/rate-limits - **Error Codes**: https://platform.openai.com/docs/guides/error-codes ### SDKs - **Node.js SDK**: https://github.com/openai/openai-node - **Python SDK**: https://github.com/openai/openai-python --- ## What's Next? **✅ Skill Complete - Production Ready** All API sections documented: - ✅ Chat Completions API (GPT-5, GPT-4o, streaming, function calling) - ✅ Embeddings API (text-embedding-3-small, text-embedding-3-large, RAG patterns) - ✅ Images API (DALL-E 3 generation, GPT-Image-1 editing) - ✅ Audio API (Whisper transcription, TTS with 11 voices) - ✅ Moderation API (11 safety categories) **Remaining Tasks**: 1. Create 9 additional templates 2. Create 7 reference documentation files 3. Test skill installat...
© coco-research · MIT · coco-research/coco