Images and video reference

Purpose and Scope

This page is a method-level reference for the SDK surfaces that generate, edit, retrieve, and manage media through client.images and client.videos. The Images resource is the direct Image API surface for prompt-based generation, image editing, and image variation requests. The Videos resource is the generated Sora video API surface for creating jobs, polling metadata, listing generated videos, downloading rendered bytes, and managing video-derived characters, edits, extensions, and remixes. Use this page when you already know you want the resource-level SDK methods rather than a broader multimodal workflow built through Responses tools.

Official OpenAI guidance distinguishes image analysis, image generation, and multimodal response workflows. In this SDK, the image resource methods are best suited for direct single-operation image generation or editing requests, while Responses can host image generation inside a larger conversation. The video resource is job-oriented: a request creates or transforms a video, and later calls retrieve metadata or binary content. That difference affects application design because image calls often return the generated payload immediately, while video generation generally requires lifecycle handling around jobs and downloadable assets.

Sources: src/resources/images.ts, src/resources/videos.ts

Relevant Source Files

• api.md - Generated API reference surface for the package; use it alongside the resource modules when looking for exported type names and endpoint groupings.
• src/resources/images.ts - Defines the Images API resource, routes for image generations, edits, and variations, streaming overloads, request option behavior, multipart handling, and response interfaces.
• src/resources/videos.ts - Defines the Videos API resource, routes for video creation, retrieval, listing, deletion, content download, character management, edits, extensions, remixes, pagination, multipart handling, and binary responses.
• tests/api-resources/images.test.ts - Exercises required and optional parameters for image variations, edits, and generations, including upload conversion with toFile and promise helper behavior.
• tests/api-resources/videos.test.ts - Exercises required and optional parameters for video creation, retrieval, listing, deletion, character creation, request options, pagination parameters, upload conversion, and response helper behavior.

Sources: api.md, src/resources/images.ts, src/resources/videos.ts, tests/api-resources/images.test.ts, tests/api-resources/videos.test.ts

Images API Resource

The Images class extends the shared API resource base and exposes three public methods: createVariation, edit, and generate. All three methods require bearer authentication, and the upload-oriented methods wrap request options with multipart form handling. createVariation posts to /images/variations and is documented in the source as supporting only dall-e-2. edit posts to /images/edits, accepts one or more source images plus a prompt, and supports both non-streaming and streaming overloads. generate posts to /images/generations, accepts a prompt, and also has streaming and non-streaming overloads.

The image methods intentionally model two different response shapes. If the request is non-streaming, the SDK returns an APIPromise<ImagesResponse>. If the request sets the streaming form, TypeScript can narrow the return to an APIPromise<Stream<...>> for image generation or edit stream events. Internally, the resource sets stream: body.stream ?? false, so callers that omit stream receive the normal non-streaming behavior. This is useful for codebases that want static typing around incremental image progress events without giving up the simpler response shape for ordinary requests.

Image responses contain image content in a model-dependent representation. The Image interface includes b64_json for base64-encoded generated image data, revised_prompt for the revised prompt returned by dall-e-3, and URL output for DALL·E models when URL response formatting is selected. The source comments also note that GPT image models return base64 JSON by default, while DALL·E models expose base64 only when requested. The tests reinforce common request fields such as background, quality, size, output_format, output_compression, partial_images, response_format, and user.

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

Image method reference

import OpenAI, { toFile } from 'openai';
 
const client = new OpenAI();
 
const generated = await client.images.generate({
  prompt: 'A cute baby sea otter',
  model: 'gpt-image-2',
  size: 'auto',
  quality: 'medium',
});
 
const edited = await client.images.edit({
  image: await toFile(Buffer.from('Example data'), 'source.png'),
  prompt: 'A cute baby sea otter wearing a beret',
  output_format: 'png',
});

Videos API Resource

The Videos class is a broader resource because video generation is managed as jobs and stored assets. create posts multipart data to /videos and creates a generation job from a prompt plus optional reference assets. retrieve fetches metadata for a specific video identifier, list returns a cursor-paginated page of recently generated videos for the current project, and delete permanently removes a completed or failed video and its stored assets. These methods give applications a stable loop: submit work, poll or list for state, consume output, and clean up when retention is no longer needed.

Video content retrieval is explicitly binary. downloadContent(videoID, query?, options?) calls /videos/{videoID}/content, sets an Accept: application/binary header, marks the request as a binary response, and returns an APIPromise<Response>. That design means the caller receives a web-standard Response object and decides whether to stream, buffer, or write bytes to storage. The method also accepts query parameters, which lets the API select the generated video bytes or a derived preview asset without changing the method shape.

The resource also includes higher-level production workflow methods. createCharacter uploads a video to create a reusable character asset, and getCharacter fetches a character by identifier. edit posts to /videos/edits to create a new generation by editing a source video or an existing generated video. extend posts to /videos/extensions to continue a completed video. remix(videoID, body, options?) posts a refreshed prompt against a completed video. These methods map closely to the official video-generation flow: create clips, use references, reuse character assets, extend scenes, edit results, and download final assets.

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

Video method reference

import OpenAI, { toFile } from 'openai';
 
const client = new OpenAI();
 
const job = await client.videos.create({
  prompt: 'A cinematic otter walking through a rainy city street',
  input_reference: await toFile(Buffer.from('Example data'), 'reference.png'),
  model: 'sora-2',
  seconds: '4',
  size: '720x1280',
});
 
const latest = await client.videos.retrieve(job.id);
const bytes = await client.videos.downloadContent(latest.id);

Request Options, Uploads, and Response Helpers

Both resources accept the SDK-wide RequestOptions object as the final argument, so callers can override per-request behavior without constructing a new client. The generated methods pass those options through to the internal client while adding endpoint-specific settings such as authentication, streaming, multipart form encoding, pagination handling, binary-response handling, or headers. Multipart calls accept Uploadable inputs, and the tests use the exported toFile helper to turn a Buffer into an uploadable file value. That pattern is the safest way to write examples that run consistently in Node-based test environments.

The tests also show the standard APIPromise helper contract for these generated methods. A method call can be awaited directly for parsed data, but the same promise also supports .asResponse() to access the raw Response and .withResponse() to receive both parsed data and the raw response together. This matters for media applications because you may need headers, status information, or request diagnostics while still consuming typed data. The video list test additionally proves that request options are propagated by overriding the path and expecting a generated NotFoundError.

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

Testing Signals and Next Steps

The generated resource tests are useful as executable reference examples because they cover both minimal and expanded request bodies. For images, the tests verify the required parameters for variations, edits, and generations, then exercise optional fields such as model choice, output formatting, moderation, background, mask, compression, size, style, streaming flags, and user identifiers. For videos, the tests verify the minimal prompt-only create call, optional reference upload, model, duration, size, metadata retrieval, pagination, deletion, character creation, and request-option forwarding. These tests do not prove model quality, but they do prove the SDK request shapes and promise helpers remain wired to the generated client contract.

When choosing between these methods, start from the lifecycle your application needs. Use client.images.generate or client.images.edit when a direct image operation is enough and you want typed SDK parameters for Image API options. Use client.responses.create with image tools when image generation is part of a multi-turn assistant or tool workflow. Use client.videos.create and the related video methods when you need Sora job management, reusable assets, editing, extension, remixing, or binary downloads. For exact exported type names beyond the methods summarized here, cross-check the generated api.md reference and the resource modules in this page’s source list.

Sources: api.md, src/resources/images.ts, src/resources/videos.ts, tests/api-resources/images.test.ts, tests/api-resources/videos.test.ts