Learning the OpenAI GPT API: Responses API & structured output

OpenAI’s GPT is the most widely used LLM API in the industry — understanding it matters even if (like me) you reach for Claude or Gemini more often, because many client codebases already use it. This tutorial uses the official openai SDK with the Responses API (the newer, recommended interface).

1. Setup

1. Create an account at platform.openai.com, create an API key, and add billing (without credit, requests are rejected).
2. Store it as an environment variable:

export OPENAI_API_KEY="sk-..."

3. Install the SDK:

npm install openai

2. Your first call (Responses API)

import OpenAI from "openai";

const client = new OpenAI(); // reads OPENAI_API_KEY automatically

const response = await client.responses.create({
  model: "gpt-5.1",
  input: "Explain conversion rate to an online store owner in 3 sentences.",
});

console.log(response.output_text);

output_text is the combined-text shortcut. If you find older code using client.chat.completions.create({ messages: [...] }) — that’s the Chat Completions API; it still works, but the Responses API is the new direction.

3. Instructions & conversations

const response = await client.responses.create({
  model: "gpt-5.1",
  instructions: "You are an online store's support assistant. Answer concisely; never invent policies.",
  input: [
    { role: "user", content: "Hi, I'm Budi." },
    { role: "assistant", content: "Hi Budi! How can I help?" },
    { role: "user", content: "How many days do I have to return an item?" },
  ],
});

instructions = the Responses API’s system prompt; input accepts a single string or a conversation array.

4. Streaming

const stream = await client.responses.create({
  model: "gpt-5.1",
  input: "Write a product description for a handmade rattan bag.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

5. Structured output (JSON)

For pipelines (data extraction, classification), force output to follow a schema:

const response = await client.responses.create({
  model: "gpt-5.1",
  input: "Extract: 'Budi ordered 2x Gayo coffee 250g, ship to Bandung'",
  text: {
    format: {
      type: "json_schema",
      name: "order",
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          product: { type: "string" },
          quantity: { type: "integer" },
          city: { type: "string" },
        },
        required: ["name", "product", "quantity", "city"],
        additionalProperties: false,
      },
    },
  },
});

const order = JSON.parse(response.output_text); // guaranteed to match the schema

Tips from experience

• Model names change fast (gpt-5.x, the o-series for reasoning, mini/nano for budget) — always check the official models page before choosing; don’t memorize them from tutorials.
• Set a usage limit in the billing dashboard on day one — an accidental infinite loop in development becomes a real invoice.
• All three providers (Claude, Gemini, GPT) share the same concepts: system prompts, stateless history, streaming, and per-token pricing. Master the concepts once — switching providers is just a syntax change.