Images and video

Purpose and Scope

This page explains the dedicated image and video surfaces in the OpenAI TypeScript and JavaScript SDK. Use these resources when your application needs media-specific endpoints rather than a general conversational model turn. The image resource covers prompt-based generation, edits or extensions from uploaded source images, and the older variation workflow for models that support it. The video resource covers Sora-style job creation, metadata retrieval, listing, deletion, binary content download, editing, extension, remixing, and reusable character assets. Sources: src/resources/images.ts, src/resources/videos.ts

The distinction between these resources and the Responses API matters when designing a product flow. The first-party guides describe the Images API as the direct path for a single image generation or edit, while the Responses API is better for conversational or multi-step image experiences. In SDK code, that difference appears as specialized request shapes: image methods accept prompts, uploadable files, masks, output controls, and optional streaming flags, while video methods expose an asynchronous media job lifecycle with identifiers and downloadable assets. Sources: src/resources/images.ts, src/resources/videos.ts

Relevant Source Files

• api.md — Generated API reference entry point for checking exported SDK members, request types, response types, and examples for image and video resources.
• src/resources/images.ts — Defines the Images resource class, generate, edit, and createVariation methods, streaming overloads, multipart upload behavior, and image response fields.
• src/resources/videos.ts — Defines the Videos resource class, job lifecycle methods, content download behavior, pagination, multipart operations, remixing, extension, and character endpoints.
• tests/api-resources/images.test.ts — Shows expected image call shapes, required and optional parameters, upload helper usage, promise wrappers, and raw response access.
• tests/api-resources/videos.test.ts — Shows expected video call shapes, pagination parameters, binary download request options, promise wrappers, and error propagation for overridden paths.

System-to-Code Mapping

The SDK implements images as a generated resource class that extends the common API resource base. All three public methods return SDK promise wrappers and set bearer authentication on outgoing requests. Generation posts to the generations endpoint with a JSON body and can return either a typed image response or a stream of image generation events depending on the request. Editing and variations use multipart form request options because they accept uploadable image inputs, and editing also supports a streaming overload when the request asks for incremental events. Sources: src/resources/images.ts

Video handling is deliberately more job-oriented. Creating a video posts a multipart request because the prompt can be accompanied by reference media. Retrieving, listing, and deleting operate on stored job identifiers, so applications can submit work, persist the returned identifier, and build a queue or dashboard around later status checks. Downloading content is special: the method requests binary data, merges an Accept header for binary content, marks the response as binary, and returns a Response so caller code can stream, buffer, or write the media bytes. Sources: src/resources/videos.ts

The generated tests demonstrate public ergonomics rather than only endpoint wiring. For both media families, the returned object can be awaited for parsed data, converted to a raw Response with asResponse, or resolved with both parsed data and transport metadata using withResponse. That behavior is important for media applications because they often need headers, status, or raw body access in addition to typed objects. The video tests also verify that request options and pagination arguments continue to compose with generated resource methods. Sources: tests/api-resources/images.test.ts, tests/api-resources/videos.test.ts

Image Resource Flow

Start with image generation when the user supplies a text prompt and expects new visual output. The minimal tested call passes only a prompt, while the fuller tested call shows controls for model, transparent background, moderation, image count, output compression, output format, partial images, quality, response format, size, style, streaming, and user attribution. The source response type can include base64 image data, a URL for older DALL·E response-format flows, and a revised prompt for DALL·E 3. Sources: src/resources/images.ts, tests/api-resources/images.test.ts

Use image editing when the user supplies visual context that should be transformed. The edit method accepts one or more source images plus a prompt, and the tests show uploadable image and mask values created with the SDK file helper. Optional edit parameters include input fidelity, transparent background, output controls, model selection, streaming, and size. The resource comments describe editing as creating an edited or extended image and list GPT Image models alongside DALL·E 2, which makes edit the dedicated endpoint for prompt-guided transformations of existing visuals. Sources: src/resources/images.ts, tests/api-resources/images.test.ts

Use variations only when a compatibility workflow explicitly needs that endpoint. The source comment states that createVariation creates a variation of a given image and only supports DALL·E 2, even though the generated parameter tests exercise the same multipart upload path and optional fields such as model, number of images, response format, size, and user. For new GPT Image products, generation and editing are the primary direct Image API operations, while variation remains useful for applications built around the older model capability. Sources: src/resources/images.ts, tests/api-resources/images.test.ts

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',
  output_format: 'png',
});
 
const edited = await client.images.edit({
  image: await toFile(Buffer.from('Example data'), 'otter.png'),
  prompt: 'Give the otter a tiny beret',
  background: 'transparent',
});

Video Resource Flow

Create a video when the application needs an asynchronous Sora generation job rather than an immediate image response. The minimal tested call passes a prompt, and the optional call adds an input reference upload, a model such as sora-2, a duration value, and an output size. The returned object represents the job metadata rather than the rendered bytes. A production workflow should store the identifier, retrieve it later for status and metadata, and download content only when the job is ready. Sources: src/resources/videos.ts, tests/api-resources/videos.test.ts

Listing and retrieval support operational workflows. The list method returns a paginated page promise over video objects and accepts cursor-style query parameters demonstrated in tests, including after, limit, and order. Retrieve addresses one video identifier, while delete permanently removes a completed or failed video and its stored assets. The request-options test intentionally overrides the path and expects an OpenAI NotFoundError, which confirms that normal generated-client error handling still applies to video resources instead of requiring custom exception handling. Sources: src/resources/videos.ts, tests/api-resources/videos.test.ts

The video resource also includes creative operations after initial generation. Edit creates a new job from a source or generated video, extend continues a completed clip, and remix posts a refreshed prompt against an existing video identifier. Character methods create a reusable character from an uploaded video and fetch that character later, supporting workflows that need repeated visual consistency across many clips. These calls share the same authenticated client pattern and use multipart form data when uploaded media may be part of the request. Sources: src/resources/videos.ts

import OpenAI, { toFile } from 'openai';
 
const client = new OpenAI();
 
const job = await client.videos.create({
  prompt: 'A cinematic otter walking through neon rain',
  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 content = await client.videos.downloadContent(job.id);

Compact API Reference

The compact table is useful for orientation, but the method families should be planned as complete workflows. For images, decide before calling whether the caller needs immediate parsed image metadata, incremental stream events, base64 payloads, older URL response formats, masks, or transparent backgrounds. For videos, design around identifiers, polling, pagination, retention, and binary download handling. Media operations can produce large payloads, so callers should keep raw response access and download streaming in mind even when the typed object is enough for simpler tests. 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 tests are good lightweight examples because they avoid live generation while still exercising the SDK contract. They show that toFile can wrap Buffer data for uploadable image, mask, reference, and character-video fields. They also show that minimal required parameters are accepted separately from richer option sets, which is helpful when building forms that progressively expose advanced controls. When debugging, reproduce a minimal call first, then add output, upload, pagination, or request options until the failing field is isolated. Sources: tests/api-resources/images.test.ts, tests/api-resources/videos.test.ts

Next, read the method-level Images and video reference for generated types and exact parameter unions. Read Files and uploads if your application accepts local files, browser File objects, or generated buffers before calling edit, variation, video create, or character creation. Read Streaming and events when enabling image stream events or consuming raw media responses. Read Responses API concepts if the product is conversational, multi-turn, or tool-driven, because image generation can also appear inside a broader Responses workflow rather than through these dedicated media resources.