version: "1.0.0" name: openai title: OpenAI API category: AI APIs description: Use to build with OpenAI's Responses API for text, images, files, structured output, streaming, tools, and vector embeddings. tags: [openai, responses-api, structured-output, streaming, embeddings] official_docs: https://developers.openai.com/api/docs sources:

• https://developers.openai.com/api/docs/quickstart
• https://developers.openai.com/api/docs/guides/structured-outputs
• https://developers.openai.com/api/docs/guides/streaming-responses
• https://developers.openai.com/api/docs/guides/embeddings

last_verified: 2026-08-10

OpenAI API - Skillship

Generate and analyze text, images, and files through the Responses API, with schema-safe output,

typed streams, callable tools, and embeddings for semantic search.

🧭 When to use this skill

• Use when: adding generation, extraction, classification, vision, document analysis, or tool-calling workflows.
• Use when: you need structured output or embeddings for search and recommendations.
• Don't use for: deterministic business rules that ordinary code can implement more cheaply and reliably.

⚡ Quickstart

1. Install

npm install openai

2. Configure (server only)

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5.6

The SDK reads OPENAI_API_KEY automatically.

3. Call the Responses API

import "server-only";
import OpenAI from "openai";
const openai = new OpenAI();
const response = await openai.responses.create({
  model: process.env.OPENAI_MODEL ?? "gpt-5.6",
  instructions: "Answer accurately and say when you do not know.",
  input: "Explain vector databases in two sentences.",
});
console.log(response.output_text);

🧩 Common recipes

Recipe: Structured output with Zod

npm install zod

import OpenAI from "openai";
import { zodTextFormat } from "openai/helpers/zod";
import { z } from "zod";
const Event = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});
const response = await openai.responses.parse({
  model: process.env.OPENAI_MODEL ?? "gpt-5.6",
  input: "Alice and Bob are attending the science fair on Friday.",
  text: { format: zodTextFormat(Event, "event") },
});
if (!response.output_parsed) throw new Error("No structured output returned");
console.log(response.output_parsed);

Use Structured Outputs instead of JSON mode when possible. Handle refusals and incomplete responses as separate outcomes rather than assuming every response matches the schema.

Recipe: Stream text deltas

const stream = await openai.responses.create({
  model: process.env.OPENAI_MODEL ?? "gpt-5.6",
  input: "Write a short launch announcement.",
  stream: true,
});
for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Common lifecycle events are response.created, response.output_text.delta, response.completed, and error.

Recipe: Let the model request one of your functions

const response = await openai.responses.create({
  model: process.env.OPENAI_MODEL ?? "gpt-5.6",
  input: "What is the weather in Paris?",
  tools: [{
    type: "function",
    name: "get_weather",
    description: "Get the current weather for a city and country.",
    strict: true,
    parameters: {
      type: "object",
      properties: { location: { type: "string" } },
      required: ["location"],
      additionalProperties: false,
    },
  }],
});
const call = response.output.find((item) => item.type === "function_call");
if (call?.type === "function_call") {
  const argumentsObject = JSON.parse(call.arguments);
  // Validate argumentsObject, authorize the action, execute it, then return a function_call_output.
}

Recipe: Create an embedding

const result = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "Semantic search text",
  encoding_format: "float",
});
const vector = result.data[0].embedding; // 1,536 values by default

Use the same embedding model and dimensions for documents and queries. For large indexes, store vectors in a vector database and rank with cosine similarity.

🚀 Ship to production

• [ ] API keys stay server-side and are scoped/rotated through project settings.
• [ ] Model ID is configurable; pin a versioned model when reproducibility matters.
• [ ] Timeouts, retries with exponential backoff, and rate-limit handling are implemented.
• [ ] Token usage, latency, model errors, and request IDs are logged without sensitive prompts.
• [ ] Structured outputs handle refusal, incomplete, and error states explicitly.
• [ ] Evals cover representative inputs before prompt/model changes are released.

🔐 Security & secrets

• Never expose OPENAI_API_KEY in browser code, mobile apps, logs, or public environment variables.
• Treat model output and tool arguments as untrusted input: validate, authorize, and constrain every side effect.
• Apply moderation and human approval where user-generated or high-impact content requires it; streaming is harder to moderate before display.

🐛 Common errors & fixes

💰 Pricing gotchas

• Generation is billed by tokens and some built-in tools have separate usage charges. Embeddings are billed by input tokens; monitor both request volume and payload size.

📚 Sources

• https://developers.openai.com/api/docs/quickstart
• https://developers.openai.com/api/docs/guides/structured-outputs
• https://developers.openai.com/api/docs/guides/streaming-responses
• https://developers.openai.com/api/docs/guides/embeddings