Fine-tuning reference
Purpose and Scope
This page is a reference-oriented map for fine-tuning support in the OpenAI TypeScript and JavaScript SDK. It focuses on the generated fine-tuning namespace, the jobs API used to create and monitor training work, the checkpoint-related types exposed through the jobs namespace, and the alpha and method exports that represent newer fine-tuning capabilities. The SDK is generated from OpenAI’s OpenAPI specification, so this reference should be read as the client-side surface for the platform API rather than a hand-written training framework. The most important reader task is knowing which client namespace to call, what request shapes are visible in the generated tests, and where to look for the exhaustive type list.
Sources: src/resources/fine-tuning/index.ts, src/resources/fine-tuning/jobs/index.ts, tests/api-resources/fine-tuning/jobs/jobs.test.ts
Fine-tuning itself is a model customization workflow. In supervised fine-tuning, you provide examples of desired behavior; in reinforcement fine-tuning, you provide a grader that scores candidate responses and guides training toward higher-scoring outputs. The official platform documentation also notes that the fine-tuning platform is being wound down for new users while existing users retain access for a transition period, and fine-tuned models remain available for inference until their base models are deprecated. In the SDK, that product lifecycle context does not remove the generated APIs, but it does affect whether a given account can create new jobs. Treat authorization and product availability errors as platform responses, not as missing SDK functionality.
Relevant Source Files
- api.md — Generated API reference for the SDK. Use it for the complete fine-tuning method and type signatures, including subresources not expanded in the selected TypeScript excerpts.
- src/resources/fine-tuning/index.ts — Barrel module for the fine-tuning namespace. It exports Alpha, Checkpoints, FineTuning, Jobs, Methods, job types, job parameter types, page types, and method-specific hyperparameter types.
- src/resources/fine-tuning/jobs/index.ts — Barrel module for fine-tuning jobs. It exports the Jobs class and job-related types, plus the nested job checkpoint resource and checkpoint listing parameter and page types.
- tests/api-resources/fine-tuning/jobs/jobs.test.ts — Generated resource tests showing how the client constructs job create, retrieve, list, cancel, and event-listing calls, how request options are passed, and how response helper wrappers behave.
System-to-Code Mapping
The fine-tuning namespace is exposed from the SDK as a generated resource family. The top-level barrel exports Alpha, Checkpoints, FineTuning, Jobs, and Methods, which tells you that the public surface is broader than a single job creation endpoint. Jobs are the operational center: they create training runs, retrieve status, list runs, cancel work, and expose events. Checkpoints represent intermediate or final model artifacts created by training. Methods collect typed configuration for supervised, reinforcement, and direct preference optimization style fine-tuning. Alpha is a separate namespace for experimental fine-tuning capabilities, including grader-related workflows referenced by reinforcement fine-tuning guidance.
Sources: src/resources/fine-tuning/index.ts, src/resources/fine-tuning/jobs/index.ts
The jobs barrel is intentionally narrower. It re-exports Checkpoints from the jobs subdirectory, together with FineTuningJobCheckpoint, CheckpointListParams, and FineTuningJobCheckpointsPage. It also re-exports Jobs, FineTuningJob, FineTuningJobEvent, integration types, job create parameters, list parameters, event-list parameters, and page types. That split matters when reading imports. If application code needs only job or checkpoint types, importing from the jobs resource path can keep the dependency focused. If it needs the broader fine-tuning surface, the top-level fine-tuning resource barrel is the better conceptual entry point.
The generated tests show the runtime entry point as client dot fineTuning dot jobs. A job create call accepts at least a model and a training file identifier. The required-parameter test uses a model value and a file identifier, then verifies the returned request promise can be consumed in three ways: as the raw Response object, as parsed data, and as a combined data-with-response object. Those helpers are common across generated SDK resources and are useful when debugging status codes, headers, or request tracing while still keeping the normal typed response path available.
Sources: tests/api-resources/fine-tuning/jobs/jobs.test.ts
Jobs API Reference
Use client.fineTuning.jobs.create to start a training job. The required shape demonstrated by the generated test contains model and training_file. Optional fields in the same test include hyperparameters, integrations, metadata, method, seed, suffix, and validation_file. Hyperparameters may use automatic values for batch size, learning rate multiplier, and epoch count. Integrations include a Weights and Biases style object with project, entity, name, and tags. Metadata is a string-keyed object. The suffix value lets callers influence the resulting model name, while validation_file provides held-out examples for evaluation during training.
Sources: tests/api-resources/fine-tuning/jobs/jobs.test.ts
The method object is the most detailed part of the create request in the test. It includes a type field and nested configurations for supervised, reinforcement, and direct preference optimization. The supervised configuration has hyperparameters for batch size, learning rate multiplier, and epochs. The direct preference optimization configuration adds beta to the hyperparameters. The reinforcement configuration includes both hyperparameters and a grader. The grader example uses a string check with an input, name, equality operation, and reference. Reinforcement hyperparameters add compute multiplier, evaluation interval, evaluation samples, and reasoning effort, reflecting the official description of reinforcement fine-tuning as a process driven by a programmable scoring signal.
The remaining jobs methods cover lifecycle inspection and control. retrieve accepts a fine-tuning job identifier and returns the current job record. list returns a paginated collection of jobs, and the generated test shows that list parameters can include after, limit, and metadata filters. cancel stops an existing job when the API permits cancellation. listEvents returns event records for a job and accepts event-listing parameters such as limits in the generated type exports. These methods are enough to build a polling loop, an administrative dashboard, or a job audit workflow without dropping down to raw HTTP calls.
Compact jobs reference
| SDK call | Primary purpose | Evidence-backed inputs | Notes |
|---|---|---|---|
| client.fineTuning.jobs.create(params) | Create a fine-tuning job | model, training_file, hyperparameters, integrations, metadata, method, seed, suffix, validation_file | Required and optional request shapes are exercised by generated tests. |
| client.fineTuning.jobs.retrieve(id) | Retrieve one job | fine-tuning job identifier | Tests verify parsed, raw, and combined response access. |
| client.fineTuning.jobs.list(params?, options?) | List jobs | after, limit, metadata | Tests verify request options are forwarded by passing a custom path. |
| client.fineTuning.jobs.cancel(id) | Cancel a job | fine-tuning job identifier | Covered by the generated jobs resource test suite. |
| client.fineTuning.jobs.listEvents(id, params?) | List job events | fine-tuning job identifier, event list parameters | Event page types are exported from the jobs module. |
Checkpoints, Permissions, and Alpha Graders
Checkpoints appear in two places in the generated surface. The top-level fine-tuning barrel exports Checkpoints, and the jobs barrel exports a jobs Checkpoints resource along with FineTuningJobCheckpoint, CheckpointListParams, and FineTuningJobCheckpointsPage. Conceptually, checkpoints are model artifacts produced during a fine-tuning run. They are useful for monitoring quality over time, selecting a candidate model, and applying permission controls when an organization or project boundary matters. For exact checkpoint and checkpoint-permission call signatures, use api.md because it is the generated reference file for the complete SDK surface.
Sources: api.md, src/resources/fine-tuning/index.ts, src/resources/fine-tuning/jobs/index.ts
Checkpoint permissions belong to the administrative side of fine-tuned model use rather than the act of training itself. A typical reader question is not only whether a job succeeded, but also who can use the resulting checkpoint or model. The generated SDK keeps those controls under the fine-tuning resource family, so permission operations should be treated as part of the same lifecycle as listing checkpoints and choosing an artifact. When writing internal tooling, separate the job operator role from the deployment operator role: the former starts and monitors work, while the latter reviews artifacts, grants access, and coordinates inference use.
Alpha grader resources support the reinforcement fine-tuning story. The top-level fine-tuning module exports Alpha, and the create-job test includes a reinforcement method with a grader object. Official platform guidance describes reinforcement fine-tuning as a workflow where a grader assigns a numeric reward to model responses, and training reinforces higher-scoring behavior. In SDK terms, that means grader definitions and validation belong near fine-tuning, while the actual training run is still created through the jobs resource. Because alpha surfaces can change faster than stable resources, prefer the generated types and api.md signatures over copied request shapes in long-lived application code.
Sources: api.md, src/resources/fine-tuning/index.ts, tests/api-resources/fine-tuning/jobs/jobs.test.ts
Request Options, Responses, and Pagination Behavior
The generated jobs tests demonstrate standard SDK request behavior that applies to fine-tuning resources. A resource call returns a promise-like object that can be awaited for parsed data, converted to a raw Response with asResponse, or resolved with both parsed data and the raw response through withResponse. This is useful when fine-tuning automation needs more than the job object itself. For example, operations teams may log response headers for request identifiers, inspect status codes during incident triage, or preserve raw response metadata while still handing typed job data to business logic.
The list test also demonstrates request-level options. It intentionally passes an invalid path in the options object and expects a NotFoundError, proving that options are forwarded to the underlying request. For normal code, this pattern maps to per-request overrides such as custom timeout, headers, query behavior, or other base request options supported by the SDK. The important reference point is that list parameters and request options are separate arguments. Keep filters such as after, limit, and metadata in the parameter object, and keep transport-level overrides in the request options object.
Sources: tests/api-resources/fine-tuning/jobs/jobs.test.ts
Pagination is represented by page types exported from the fine-tuning barrels. FineTuningJobsPage describes job list results, FineTuningJobEventsPage describes event list results, and FineTuningJobCheckpointsPage describes checkpoint list results. The tests do not expand iteration helpers in the selected excerpt, but the exported page types tell you that these list endpoints are not plain arrays. Application code should account for pagination when building dashboards or reconciliation jobs. Avoid assuming one list call contains every job, event, or checkpoint in a busy organization; instead, use the SDK’s generated pagination mechanisms documented in api.md.
Implementation Notes and Edge Cases
Fine-tuning workflows often span multiple resources. A training file must already exist before a create call can reference training_file, and a validation file is optional but important for measuring whether training is improving behavior. The SDK jobs API does not validate the semantic quality of a dataset; it sends typed parameters to the API. Dataset preparation guidance therefore lives in platform docs: build representative examples, check consistency, avoid training examples that teach hallucinated behavior, and establish evals before investing in fine-tuning. In code review, treat the SDK call as the final orchestration step after data and evaluation readiness are satisfied.
The generated create test is also a useful catalog of fine-tuning configuration edge cases. Automatic hyperparameter values appear as strings, not omitted numbers, which lets the server choose defaults while keeping the request explicit. Multiple method families can be represented in the type surface, but real API validation determines which combinations are accepted for a chosen model and account. Reinforcement fine-tuning adds grader and reasoning-related options, while supervised fine-tuning is closer to a demonstration dataset workflow. Keep model eligibility, account access, and platform deprecation timelines in operational documentation so SDK errors are interpreted correctly.
Testing Signals
The jobs resource test suite is generated, but it still provides practical confidence signals. It confirms that create, retrieve, and list calls return SDK response wrappers with consistent raw and parsed access. It confirms optional create parameters serialize through the generated client. It confirms list filters and request options are passed to the request layer rather than ignored. It also imports OpenAI from the package root and constructs a client with apiKey, adminAPIKey, and a base URL pointed at a test server, which mirrors how generated resource tests isolate SDK behavior from live platform state.
Sources: tests/api-resources/fine-tuning/jobs/jobs.test.ts
For developers adding fine-tuning-related code, these tests imply a few maintenance rules. Preserve method names and argument ordering when regenerating resources, because downstream users call client.fineTuning.jobs directly. Keep exported type names stable unless the OpenAPI specification intentionally changes them. When adding examples or wrappers, do not bypass the generated response helpers; many users rely on raw response access for observability. When debugging a failing fine-tuning request, first reduce it to the generated create, retrieve, list, cancel, or listEvents shape, then add application-specific abstractions only after the base SDK call behaves as expected.
Next Steps
Start with api.md when you need exact signatures for checkpoint permissions, alpha graders, or generated page helpers. Use the top-level fine-tuning barrel to understand the resource families and the jobs barrel to understand job, event, integration, and checkpoint types. Then model your own job creation code after the generated tests: provide the required model and training file, add method-specific configuration deliberately, and keep request options separate from request parameters. For adjacent SDK topics, read the files and uploads reference before preparing datasets, and read the evals reference before deciding whether a fine-tuned model is better than the base model.