Models reference

Purpose and Scope

The Models resource is the SDK surface for discovering and inspecting model identifiers that can be used elsewhere in OpenAI API calls. Most application code chooses a model inside a generation, embedding, audio, image, or agent-style request, but the model catalog is useful when a service needs to display available choices, confirm metadata for a known identifier, or manage fine-tuned model cleanup. In this SDK, the catalog is intentionally small and direct: it lists models, retrieves one model by identifier, and deletes a fine-tuned model when the caller has the required organization role.

Sources: src/resources/models.ts, tests/api-resources/models.test.ts

Model selection itself is a product decision, not only an SDK call. The official guidance emphasizes choosing explicit models in production and balancing accuracy, latency, and cost. This reference therefore treats model identifiers as operational inputs used by other APIs, while the Models resource provides metadata and lifecycle operations around those identifiers. A common workflow is to list or retrieve a model during administration, then pass the chosen identifier into a Responses or Chat Completions request. Deletion is narrower: it applies to fine-tuned models and requires ownership authority in the organization.

Sources: src/resources/models.ts

Relevant Source Files

• api.md — Generated API reference for the package; use it as the public catalog companion when checking exported SDK surfaces and examples.
• src/resources/models.ts — Defines the generated Models resource, its methods, response types, pagination alias, request options, paths, and bearer authentication behavior.
• tests/api-resources/models.test.ts — Exercises retrieve, list, and delete through the public OpenAI client and verifies promise helpers for raw and paired responses.

System-to-Code Mapping

The implementation is generated from the OpenAPI specification by Stainless, which matters for readers because this file follows the same conventions as the rest of the SDK resource layer. The Models class extends the shared API resource base and delegates actual HTTP work to the client instance. Each method returns an SDK promise abstraction rather than a raw fetch promise. That promise resolves to typed data, but it can also expose the underlying HTTP response when callers need headers, status, or debugging context. The generated style keeps the method names stable and close to the platform API.

Sources: src/resources/models.ts, tests/api-resources/models.test.ts

The source maps three public operations to REST paths. Retrieving and deleting both interpolate the model identifier into the model path, while listing calls the collection path. The list method returns a page promise using the shared Page type, even though the source notes that no pagination actually occurs yet. That forward-compatible shape means code can use the same paging conventions as other SDK resources without assuming the endpoint will always remain a single response. The model objects themselves contain identifier, creation time, object type, and owning organization metadata.

Sources: src/resources/models.ts

API Reference

The concrete types are simple and important for downstream validation. A model has an identifier, a Unix timestamp in seconds, a constant object type of model, and an owner string. A deletion response has the identifier, a boolean deleted flag, and an object string. All three methods accept optional request options, so callers can use the same per-request configuration patterns available throughout the SDK. The resource attaches bearer authentication metadata to each call, which aligns these operations with standard API-key-authenticated usage rather than a separate unauthenticated discovery channel.

Sources: src/resources/models.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'],
});
 
const catalog = await client.models.list();
const model = await client.models.retrieve('gpt-4o-mini');
 
console.log(model.id, model.owned_by);

Execution Flow

A typical read-only flow begins with client construction, then a list or retrieve call. Listing is appropriate when an administration page, CLI, or setup script needs the available model catalog. Retrieval is more precise when the application already has a configured identifier and wants to confirm that it resolves to a model record before using it elsewhere. Because the response is typed, TypeScript callers can read fields such as the identifier and owning organization without hand-written response guards. If the request fails, it follows the same SDK error behavior as other API resource methods.

Sources: src/resources/models.ts, tests/api-resources/models.test.ts

Deletion should be treated as an administrative lifecycle step, not a routine inference-path operation. The generated comment states that it deletes a fine-tuned model and that the caller must have the Owner role in the organization. The test fixture uses a fine-tuned model-style identifier, which illustrates the expected input shape without implying that base model identifiers should be deleted. In production tools, confirmation prompts, audit logging, and clear separation from ordinary model lookup are sensible safeguards because successful deletion returns only a compact deletion result rather than the full prior model metadata.

Sources: src/resources/models.ts, tests/api-resources/models.test.ts

const deleted = await client.models.delete('ft:gpt-4o-mini:acemeco:suffix:abc123');
 
if (deleted.deleted) {
  console.log(`Deleted ${deleted.id}`);
}

Promise and Response Helpers

The tests show the same promise helper contract used throughout the SDK. Calling a Models method returns a response promise, and awaiting it gives typed data rather than a Response object. When a caller needs the raw platform response, the promise exposes an asResponse helper. When the caller wants both values together, the withResponse helper returns a data and response pair. The tests assert that the paired data is the same resolved object and that the paired response is the same raw response obtained earlier, which is useful for logging and header inspection.

Sources: tests/api-resources/models.test.ts

This helper behavior is especially valuable for catalog and administration tooling. A console command might list models and only print typed records in the common path, but include request identifiers, rate-limit headers, or status information when a verbose flag is enabled. The SDK design lets that command use one request promise rather than issuing duplicate calls. The tests construct the client with an API key, an admin API key, and a test base URL, confirming that the public OpenAI client namespace exposes the models resource in normal client usage.

Sources: tests/api-resources/models.test.ts

Usage Guidance and Next Steps

Use the Models resource to support configuration, validation, and fine-tuned model administration, but keep actual model selection close to the workload that uses the model. For application requests, prefer explicit model identifiers and evaluate quality before optimizing for cost or latency. If you are building a user-facing model picker, combine model listing with product guidance and organization policy rather than assuming every listed model is appropriate for every task. If you are managing fine-tuned models, keep deletion behind owner-only operational workflows and verify the identifier before calling the delete method.

Sources: src/resources/models.ts

Next, read the Responses reference for the primary generation surface where model identifiers are commonly used, the Chat Completions reference for message-based workflows, and the Fine-tuning reference for the model lifecycle that can produce deletable fine-tuned identifiers. For setup concerns such as API keys, request options, base URLs, and environment-specific client construction, see the client configuration and authentication page before wiring model catalog calls into production services.