@j-o-r/hello-dave 0.1.1 → 0.1.4

package/lib/API/openai.com/video.js

@@ -0,0 +1,784 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * @file lib/API/openai.com/video.js
+ * @module openai.com/video
+ * @description Thin HTTP wrapper around OpenAI video endpoints.
+ *
+ * Video job calls submit a request and then poll until the video reaches a
+ * terminal state. Successful jobs can optionally download the generated asset
+ * to `.cache/openai/`.
+ *
+ * Documentation source files:
+ * - video.create.md
+ * - video.retrieve.md
+ * - video.download.md
+ * - video.edit.md
+ * - video.extend.md
+ * - video.remix.md
+ * - video.list.md
+ * - video.delete.md
+ * - video.create.character.md
+ * - video.fetch.character.md
+ */
+
+const API_URL = 'https://api.openai.com/v1';
+const TMP_DIR = path.join(process.cwd(), '.cache', 'openai');
+
+/** Terminal video statuses returned by OpenAI. */
+const TERMINAL_STATUSES = new Set(['completed', 'failed']);
+
+/** Non-terminal video statuses returned by OpenAI. */
+const PENDING_STATUSES = new Set(['queued', 'in_progress']);
+
+
+/**
+ * JSON-compatible primitive value.
+ * @typedef {string|number|boolean|null} JsonPrimitive
+ */
+
+/**
+ * JSON-compatible value accepted in OpenAI JSON request bodies.
+ * @typedef {JsonPrimitive|JsonObject|JsonArray} JsonValue
+ */
+
+/**
+ * JSON-compatible object accepted in OpenAI JSON request bodies.
+ * @typedef {{[key: string]: JsonValue|undefined}} JsonObject
+ */
+
+/**
+ * JSON-compatible array accepted in OpenAI JSON request bodies.
+ * @typedef {Array<JsonValue|undefined>} JsonArray
+ */
+
+/**
+ * HTTP header map used for OpenAI requests.
+ * @typedef {Object} OpenAIHeaders
+ * @property {string} ['User-Agent'] - User-Agent header value.
+ * @property {string} ['Content-Type'] - Content type for JSON requests. Omitted for multipart and raw downloads.
+ * @property {string} Authorization - Bearer token authorization header.
+ */
+
+/**
+ * Common wrapper request options.
+ * @typedef {Object} RequestOptions
+ * @property {string} [userAgent='@j-o-r/agents'] - User-Agent header value.
+ */
+
+/**
+ * Query parameters serialized onto an OpenAI request URL.
+ * Undefined and null values are skipped.
+ * @typedef {{[key: string]: string|number|boolean|null|undefined}} QueryParams
+ */
+
+/**
+ * Parsed response body returned by fetch helpers.
+ * @typedef {JsonValue|string|ArrayBuffer|Blob|undefined} ParsedResponseBody
+ */
+
+/**
+ * Downloadable video content variant.
+ * @typedef {'video'|'thumbnail'|'spritesheet'} VideoAssetVariant
+ */
+
+/**
+ * Supported OpenAI video model identifier.
+ * @typedef {'sora-2'|'sora-2-pro'|'sora-2-2025-10-06'|'sora-2-pro-2025-10-06'|'sora-2-2025-12-08'|string} VideoModel
+ */
+
+/**
+ * Supported base clip duration for video creation.
+ * @typedef {'4'|'8'|'12'|4|8|12|number} VideoSeconds
+ */
+
+/**
+ * Supported generated segment duration for video extensions.
+ * @typedef {'4'|'8'|'12'|'16'|'20'|4|8|12|16|20|number} VideoExtensionSeconds
+ */
+
+/**
+ * Supported generated video output resolution.
+ * @typedef {'720x1280'|'1280x720'|'1024x1792'|'1792x1024'} VideoSize
+ */
+
+/**
+ * Lifecycle status of an OpenAI video job.
+ * @typedef {'queued'|'in_progress'|'completed'|'failed'|string} VideoStatus
+ */
+
+/**
+ * Error payload returned for a failed video generation job.
+ * @typedef {Object} VideoCreateError
+ * @property {string} code - Machine-readable error code.
+ * @property {string} message - Human-readable error description.
+ */
+
+/**
+ * Optional image reference object used to guide video creation.
+ * Exactly one of `image_url` or `file_id` should be provided.
+ * @typedef {Object} VideoInputReference
+ * @property {string} [image_url] - Fully-qualified image URL or base64 data URL.
+ * @property {string} [file_id] - OpenAI file identifier for an uploaded image reference.
+ */
+
+/**
+ * Reference to an existing generated video.
+ * @typedef {Object} VideoReference
+ * @property {string} id - Identifier of the completed source video.
+ */
+
+/**
+ * Structured metadata for an OpenAI video generation job.
+ * @typedef {Object} VideoObject
+ * @property {string} id - Unique identifier for the video job.
+ * @property {number|null} [completed_at] - Unix timestamp in seconds for completion, when finished.
+ * @property {number} [created_at] - Unix timestamp in seconds when the job was created.
+ * @property {VideoCreateError|null} [error] - Error payload when generation failed.
+ * @property {number|null} [expires_at] - Unix timestamp in seconds when downloadable assets expire.
+ * @property {VideoModel} [model] - Video generation model that produced the job.
+ * @property {'video'} [object] - Object type marker for video job responses.
+ * @property {number} [progress] - Approximate completion percentage from 0 to 100.
+ * @property {string} [prompt] - Prompt used to generate, edit, extend, or remix the video.
+ * @property {string|null} [remixed_from_video_id] - Source video id when this video is a remix.
+ * @property {string} [seconds] - Duration of the generated clip, or stitched total duration for extensions.
+ * @property {VideoSize} [size] - Output resolution.
+ * @property {VideoStatus} status - Current lifecycle status of the video job.
+ * @property {VideoDownloadResult} [content] - Downloaded media data when a wrapper is called with download enabled.
+ */
+
+/**
+ * Response returned after deleting a video.
+ * @typedef {Object} VideoDeleteResponse
+ * @property {string} id - Identifier of the deleted video.
+ * @property {boolean} deleted - Whether the resource was deleted.
+ * @property {'video.deleted'} object - Object type marker for delete responses.
+ */
+
+/**
+ * Query parameters for listing generated videos.
+ * @typedef {Object} VideoListQuery
+ * @property {string} [after] - Pagination cursor from the previous response.
+ * @property {number} [limit] - Maximum number of videos to retrieve.
+ * @property {'asc'|'desc'} [order] - Sort order by timestamp.
+ */
+
+/**
+ * Paginated list response for generated videos.
+ * @typedef {Object} VideoListResponse
+ * @property {VideoObject[]} data - Page of video jobs.
+ * @property {string} [first_id] - Identifier of the first item in the page.
+ * @property {boolean} [has_more] - Whether more items are available.
+ * @property {string} [last_id] - Identifier of the last item in the page.
+ * @property {'list'} object - Object type marker for list responses.
+ */
+
+/**
+ * Response returned for character creation and retrieval.
+ * @typedef {Object} VideoCharacter
+ * @property {string} id - Identifier for the character cameo.
+ * @property {number} created_at - Unix timestamp in seconds when the character was created.
+ * @property {string} name - Display name for the character.
+ */
+
+/**
+ * Result returned by authenticated media download helpers.
+ * @typedef {Object} VideoDownloadResult
+ * @property {Buffer} buffer - Downloaded media bytes.
+ * @property {string} contentType - Response content type.
+ * @property {number} bytes - Number of downloaded bytes.
+ * @property {string} [local_path] - Absolute local path when media was saved to disk.
+ */
+
+/**
+ * Options for polling a video job until it reaches a terminal state.
+ * @typedef {RequestOptions & Object} PollOptions
+ * @property {number} [maxWaitMs=600000] - Maximum total polling time in milliseconds.
+ * @property {number} [pollIntervalMs=5000] - Delay between poll requests in milliseconds.
+ */
+
+/**
+ * Options for submitting a create-video request.
+ * @typedef {RequestOptions & PollOptions & Object} SubmitVideoOptions
+ * @property {VideoModel} [model='sora-2'] - Video generation model.
+ * @property {VideoSeconds} [seconds='4'] - Clip duration in seconds.
+ * @property {VideoSize} [size='720x1280'] - Output resolution.
+ * @property {string|VideoInputReference} [input_reference] - Optional image reference URL/data URL/file reference.
+ * @property {JsonObject} [extra] - Additional request fields merged into the JSON body.
+ */
+
+/**
+ * Options for creating a video and optionally downloading the completed result.
+ * @typedef {SubmitVideoOptions & Object} CreateVideoOptions
+ * @property {boolean} [download=false] - Download final video after completion.
+ * @property {VideoAssetVariant} [variant='video'] - Asset variant to download when download is enabled.
+ * @property {string} [filenamePrefix='openai-video'] - Local filename prefix used when saving downloaded media.
+ */
+
+/**
+ * Options for emergency polling after a previous create/edit/extend/remix timeout.
+ * @typedef {PollOptions & Object} EmergencyPollVideoOptions
+ * @property {number} [maxWaitMs=3600000] - Maximum total polling time in milliseconds.
+ * @property {number} [pollIntervalMs=30000] - Delay between poll requests in milliseconds.
+ * @property {boolean} [download=false] - Download final media when completed.
+ * @property {VideoAssetVariant} [variant='video'] - Asset variant to download.
+ * @property {string} [filenamePrefix='openai-video'] - Local filename prefix used when saving downloaded media.
+ */
+
+/**
+ * Options for downloading generated video media or preview assets.
+ * @typedef {RequestOptions & Object} DownloadVideoOptions
+ * @property {VideoAssetVariant} [variant='video'] - Asset variant to download.
+ * @property {boolean} [save=false] - Save bytes to `.cache/openai/`.
+ * @property {string} [filenamePrefix='openai-video'] - Local filename prefix.
+ */
+
+/**
+ * Options for edit, extension, and remix requests.
+ * @typedef {RequestOptions & PollOptions & Object} VideoMutationOptions
+ * @property {JsonObject} [extra] - Additional request fields merged into the JSON body.
+ */
+
+/**
+ * Local or in-memory video input accepted by createCharacter().
+ * @typedef {string|Buffer|Blob|ArrayBuffer} CharacterVideoInput
+ */
+
+/**
+ * Blob conversion result used for multipart character upload.
+ * @typedef {Object} VideoBlobResult
+ * @property {Blob} blob - Blob ready to append to FormData.
+ * @property {string} filename - Filename sent with the multipart upload.
+ */
+
+/**
+ * Get the default JSON headers.
+ * @param {string} [USER_AGENT='@j-o-r/agents'] - User-Agent header value.
+ * @returns {OpenAIHeaders} Headers object.
+ * @throws {Error} If OPENAIKEY is missing.
+ */
+const getHeaders = (USER_AGENT = '@j-o-r/agents') => {
+  if (!process.env['OPENAIKEY']) {
+    throw new Error('Missing OPENAIKEY!export OPENAIKEY=<OPENAI_API_KEY>');
+  }
+  const KEY = process.env['OPENAIKEY'];
+  return {
+    'User-Agent': USER_AGENT,
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${KEY}`
+  };
+};
+
+/**
+ * Get auth headers for multipart/form-data requests.
+ * Do not set Content-Type; fetch/FormData must set the boundary.
+ * @param {string} [USER_AGENT='@j-o-r/agents'] - User-Agent header value.
+ * @returns {OpenAIHeaders} Headers object.
+ * @throws {Error} If OPENAIKEY is missing.
+ */
+const getMultipartHeaders = (USER_AGENT = '@j-o-r/agents') => {
+  const headers = getHeaders(USER_AGENT);
+  delete headers['Content-Type'];
+  return headers;
+};
+
+/**
+ * Wait for a number of milliseconds.
+ * @param {number} ms - Milliseconds to sleep.
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Ensure the local cache directory exists.
+ * @returns {Promise<void>}
+ */
+async function ensureTmpDir() {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+}
+
+/**
+ * Convert a plain object to a URL query string.
+ * Undefined/null values are skipped.
+ * @param {QueryParams} [query={}] - Query parameters.
+ * @returns {string} Query string, including leading `?` when non-empty.
+ */
+function toQueryString(query = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    params.set(key, String(value));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : '';
+}
+
+/**
+ * Parse a fetch Response as JSON when possible, otherwise text.
+ * @param {Response} response - Fetch response.
+ * @returns {Promise<ParsedResponseBody>} Parsed body.
+ */
+async function parseResponseBody(response) {
+  const contentType = response.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) return response.json();
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Make a JSON API request to OpenAI.
+ * @param {string} endpoint - Endpoint path, e.g. `/videos`.
+ * @param {'GET'|'POST'|'DELETE'} [method='GET'] - HTTP method.
+ * @param {JsonObject|null} [body=null] - JSON body.
+ * @param {QueryParams} [query={}] - Query parameters.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @param {string} [options.userAgent='@j-o-r/agents'] - User-Agent header value.
+ * @returns {Promise<ParsedResponseBody>} Parsed API response.
+ * @throws {Error} On non-2xx responses.
+ */
+async function apiRequest(endpoint, method = 'GET', body = null, query = {}, options = {}) {
+  const url = `${API_URL}${endpoint}${toQueryString(query)}`;
+  const response = await fetch(url, {
+    method,
+    headers: getHeaders(options.userAgent),
+    body: body === null || body === undefined ? undefined : JSON.stringify(body)
+  });
+  const parsed = await parseResponseBody(response);
+
+  if (!response.ok) {
+    throw new Error(`OpenAI video API error ${response.status}: ${JSON.stringify(parsed)}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Download bytes from an authenticated OpenAI endpoint.
+ * @param {string} endpoint - Endpoint path.
+ * @param {QueryParams} [query={}] - Query parameters.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @param {string} [options.userAgent='@j-o-r/agents'] - User-Agent header value.
+ * @returns {Promise<VideoDownloadResult>}
+ * @throws {Error} On non-2xx responses.
+ */
+async function apiDownload(endpoint, query = {}, options = {}) {
+  const url = `${API_URL}${endpoint}${toQueryString(query)}`;
+  const headers = getHeaders(options.userAgent);
+  delete headers['Content-Type'];
+
+  const response = await fetch(url, { method: 'GET', headers });
+  if (!response.ok) {
+    const parsed = await parseResponseBody(response);
+    throw new Error(`OpenAI video download error ${response.status}: ${JSON.stringify(parsed)}`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  return {
+    buffer,
+    contentType: response.headers.get('content-type') || 'application/octet-stream',
+    bytes: buffer.length
+  };
+}
+
+/**
+ * Return a useful file extension for a content variant / content type.
+ * @param {VideoAssetVariant} variant - Asset variant.
+ * @param {string} contentType - Response content type.
+ * @returns {string} File extension without a dot.
+ */
+function getVariantExtension(variant = 'video', contentType = '') {
+  if (variant === 'thumbnail') return contentType.includes('png') ? 'png' : 'jpg';
+  if (variant === 'spritesheet') return contentType.includes('png') ? 'png' : 'jpg';
+  return 'mp4';
+}
+
+/**
+ * Save downloaded media bytes to `.cache/openai/`.
+ * @param {Buffer} buffer - Media bytes.
+ * @param {string} [filenamePrefix='openai-video'] - Filename prefix.
+ * @param {string} [ext='mp4'] - File extension.
+ * @returns {Promise<string>} Absolute local path.
+ */
+async function saveMediaToLocal(buffer, filenamePrefix = 'openai-video', ext = 'mp4') {
+  await ensureTmpDir();
+  const filename = `${filenamePrefix}-${Date.now()}.${ext}`;
+  const localPath = path.join(TMP_DIR, filename);
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/**
+ * Normalize an image reference for video creation.
+ * @param {string|VideoInputReference} inputReference - URL/data URL/file reference.
+ * @returns {VideoInputReference|undefined} OpenAI input_reference object.
+ */
+function normalizeInputReference(inputReference) {
+  if (!inputReference) return undefined;
+  if (typeof inputReference === 'string') return { image_url: inputReference };
+  return inputReference;
+}
+
+/**
+ * Validate a completed/failed video response and throw on failed jobs.
+ * @param {VideoObject} video - Video object.
+ * @returns {VideoObject} Video object.
+ * @throws {Error} If the video job failed.
+ */
+function assertTerminalVideo(video) {
+  if (video?.status === 'failed') {
+    throw new Error(`OpenAI video generation failed: ${JSON.stringify(video.error || video)}`);
+  }
+  return video;
+}
+
+/**
+ * Poll a video until it reaches a terminal state.
+ *
+ * This is the normal polling helper used by create/edit/extend/remix wrappers.
+ * Use `emergencyPollVideo()` for edge cases after a caller-side timeout.
+ *
+ * @param {string} videoId - OpenAI video id.
+ * @param {PollOptions} [options={}] - Polling options.
+ * @param {number} [options.maxWaitMs=600000] - Maximum wait time in ms.
+ * @param {number} [options.pollIntervalMs=5000] - Delay between polls in ms.
+ * @param {string} [options.userAgent='@j-o-r/agents'] - User-Agent header value.
+ * @returns {Promise<VideoObject>} Completed video object.
+ * @throws {Error} On failed job or timeout.
+ */
+async function pollVideo(videoId, options = {}) {
+  if (!videoId) throw new Error('pollVideo() requires a videoId');
+
+  const maxWaitMs = options.maxWaitMs ?? 600000;
+  const pollIntervalMs = options.pollIntervalMs ?? 5000;
+  const start = Date.now();
+  let lastVideo = null;
+
+  while (Date.now() - start <= maxWaitMs) {
+    lastVideo = await retrieveVideo(videoId, options);
+    const status = lastVideo?.status;
+
+    if (TERMINAL_STATUSES.has(status)) return assertTerminalVideo(lastVideo);
+    if (status && !PENDING_STATUSES.has(status)) return lastVideo;
+
+    await sleep(pollIntervalMs);
+  }
+
+  const timeout = new Error(
+    `OpenAI video polling timed out after ${maxWaitMs}ms for ${videoId}. ` +
+    `Use emergencyPollVideo('${videoId}') to continue polling. Last response: ${JSON.stringify(lastVideo)}`
+  );
+  timeout.videoId = videoId;
+  timeout.lastResponse = lastVideo;
+  throw timeout;
+}
+
+/**
+ * Emergency polling call for jobs that outlive a previous request timeout.
+ *
+ * Call this with the video id from a timed-out create/edit/extend/remix response
+ * or from the thrown timeout error's `videoId` property. Defaults are longer and
+ * less aggressive than normal polling.
+ *
+ * @param {string} videoId - OpenAI video id.
+ * @param {PollOptions} [options={}] - Polling options.
+ * @param {number} [options.maxWaitMs=3600000] - Maximum wait time in ms.
+ * @param {number} [options.pollIntervalMs=30000] - Delay between polls in ms.
+ * @param {boolean} [options.download=false] - Download final media when completed.
+ * @param {VideoAssetVariant} [options.variant='video'] - Asset variant to download.
+ * @param {string} [options.userAgent='@j-o-r/agents'] - User-Agent header value.
+ * @returns {Promise<VideoObject>} Completed video response, optionally with download data.
+ */
+async function emergencyPollVideo(videoId, options = {}) {
+  const video = await pollVideo(videoId, {
+    ...options,
+    maxWaitMs: options.maxWaitMs ?? 3600000,
+    pollIntervalMs: options.pollIntervalMs ?? 30000
+  });
+
+  if (!options.download) return video;
+
+  const content = await downloadVideoContent(videoId, {
+    ...options,
+    variant: options.variant ?? 'video',
+    save: true
+  });
+
+  return { ...video, content };
+}
+
+/**
+ * Submit a video create job without waiting.
+ * @param {string} prompt - Prompt describing the video.
+ * @param {SubmitVideoOptions} [options={}] - Create options.
+ * @param {VideoModel} [options.model='sora-2'] - Video model.
+ * @param {VideoSeconds} [options.seconds='4'] - Duration in seconds.
+ * @param {VideoSize} [options.size='720x1280'] - Output size.
+ * @param {string|VideoInputReference} [options.input_reference] - Optional image reference.
+ * @param {JsonObject} [options.extra] - Extra request fields.
+ * @returns {Promise<VideoObject>} Created video job response.
+ */
+async function submitVideo(prompt, options = {}) {
+  if (!prompt || typeof prompt !== 'string') throw new Error('submitVideo() requires a prompt string');
+
+  const body = {
+    model: options.model ?? 'sora-2',
+    prompt,
+    seconds: String(options.seconds ?? '4'),
+    size: options.size ?? '720x1280',
+    ...options.extra
+  };
+
+  const inputReference = normalizeInputReference(options.input_reference);
+  if (inputReference) body.input_reference = inputReference;
+
+  return apiRequest('/videos', 'POST', body, {}, options);
+}
+
+/**
+ * Create a video and wait until the job completes.
+ * @param {string} prompt - Prompt describing the video.
+ * @param {CreateVideoOptions} [options={}] - Create and polling options.
+ * @param {boolean} [options.download=false] - Download final video after completion.
+ * @returns {Promise<VideoObject>} Completed video response, optionally with `content`.
+ */
+async function createVideo(prompt, options = {}) {
+  const created = await submitVideo(prompt, options);
+  const video = await pollVideo(created.id, options);
+
+  if (!options.download) return video;
+
+  const content = await downloadVideoContent(video.id, {
+    ...options,
+    variant: options.variant ?? 'video',
+    save: true
+  });
+  return { ...video, content };
+}
+
+/**
+ * Retrieve the latest metadata for a generated video.
+ * @param {string} videoId - OpenAI video id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoObject>} Video object.
+ */
+async function retrieveVideo(videoId, options = {}) {
+  if (!videoId) throw new Error('retrieveVideo() requires a videoId');
+  return apiRequest(`/videos/${encodeURIComponent(videoId)}`, 'GET', null, {}, options);
+}
+
+/**
+ * List recently generated videos for the current project.
+ * @param {VideoListQuery} [query={}] - List query parameters.
+ * @param {string} [query.after] - Pagination cursor.
+ * @param {number} [query.limit] - Number of items to retrieve.
+ * @param {'asc'|'desc'} [query.order] - Sort order.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoListResponse>} List response.
+ */
+async function listVideos(query = {}, options = {}) {
+  return apiRequest('/videos', 'GET', null, query, options);
+}
+
+/**
+ * Delete a completed or failed video and its stored assets.
+ * @param {string} videoId - OpenAI video id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoDeleteResponse>} Delete response.
+ */
+async function deleteVideo(videoId, options = {}) {
+  if (!videoId) throw new Error('deleteVideo() requires a videoId');
+  return apiRequest(`/videos/${encodeURIComponent(videoId)}`, 'DELETE', null, {}, options);
+}
+
+/**
+ * Download generated video bytes or a preview asset.
+ * @param {string} videoId - OpenAI video id.
+ * @param {DownloadVideoOptions} [options={}] - Download options.
+ * @param {VideoAssetVariant} [options.variant='video'] - Asset variant.
+ * @param {boolean} [options.save=false] - Save bytes to `.cache/openai/`.
+ * @param {string} [options.filenamePrefix='openai-video'] - Local filename prefix.
+ * @returns {Promise<VideoDownloadResult>}
+ */
+async function downloadVideoContent(videoId, options = {}) {
+  if (!videoId) throw new Error('downloadVideoContent() requires a videoId');
+
+  const variant = options.variant ?? 'video';
+  const result = await apiDownload(`/videos/${encodeURIComponent(videoId)}/content`, { variant }, options);
+
+  if (options.save) {
+    const ext = getVariantExtension(variant, result.contentType);
+    result.local_path = await saveMediaToLocal(result.buffer, options.filenamePrefix ?? 'openai-video', ext);
+  }
+
+  return result;
+}
+
+/**
+ * Submit a video edit job without waiting.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Edit prompt.
+ * @param {VideoMutationOptions} [options={}] - Request options.
+ * @returns {Promise<VideoObject>} Created video job response.
+ */
+async function submitVideoEdit(videoId, prompt, options = {}) {
+  if (!videoId) throw new Error('submitVideoEdit() requires a videoId');
+  if (!prompt || typeof prompt !== 'string') throw new Error('submitVideoEdit() requires a prompt string');
+
+  return apiRequest('/videos/edits', 'POST', {
+    prompt,
+    video: { id: videoId },
+    ...options.extra
+  }, {}, options);
+}
+
+/**
+ * Edit a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Edit prompt.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+async function editVideo(videoId, prompt, options = {}) {
+  const created = await submitVideoEdit(videoId, prompt, options);
+  return pollVideo(created.id, options);
+}
+
+/**
+ * Submit a video extension job without waiting.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Extension prompt.
+ * @param {VideoExtensionSeconds} [seconds='4'] - New segment length.
+ * @param {VideoMutationOptions} [options={}] - Request options.
+ * @returns {Promise<VideoObject>} Created video job response.
+ */
+async function submitVideoExtension(videoId, prompt, seconds = '4', options = {}) {
+  if (!videoId) throw new Error('submitVideoExtension() requires a videoId');
+  if (!prompt || typeof prompt !== 'string') throw new Error('submitVideoExtension() requires a prompt string');
+
+  return apiRequest('/videos/extensions', 'POST', {
+    prompt,
+    seconds: String(seconds),
+    video: { id: videoId },
+    ...options.extra
+  }, {}, options);
+}
+
+/**
+ * Extend a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Extension prompt.
+ * @param {VideoExtensionSeconds} [seconds='4'] - New segment length.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+async function extendVideo(videoId, prompt, seconds = '4', options = {}) {
+  const created = await submitVideoExtension(videoId, prompt, seconds, options);
+  return pollVideo(created.id, options);
+}
+
+/**
+ * Submit a video remix job without waiting.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Remix prompt.
+ * @param {VideoMutationOptions} [options={}] - Request options.
+ * @returns {Promise<VideoObject>} Created video job response.
+ */
+async function submitVideoRemix(videoId, prompt, options = {}) {
+  if (!videoId) throw new Error('submitVideoRemix() requires a videoId');
+  if (!prompt || typeof prompt !== 'string') throw new Error('submitVideoRemix() requires a prompt string');
+
+  return apiRequest(`/videos/${encodeURIComponent(videoId)}/remix`, 'POST', {
+    prompt,
+    ...options.extra
+  }, {}, options);
+}
+
+/**
+ * Remix a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Remix prompt.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+async function remixVideo(videoId, prompt, options = {}) {
+  const created = await submitVideoRemix(videoId, prompt, options);
+  return pollVideo(created.id, options);
+}
+
+/**
+ * Create a Blob from a local file path, Buffer, Blob, or ArrayBuffer.
+ * @param {CharacterVideoInput} video - Video input.
+ * @returns {Promise<VideoBlobResult>} Blob and filename.
+ */
+async function toVideoBlob(video) {
+  if (typeof video === 'string') {
+    const buffer = await fs.readFile(video);
+    return { blob: new Blob([buffer], { type: 'video/mp4' }), filename: path.basename(video) };
+  }
+  if (Buffer.isBuffer(video)) return { blob: new Blob([video], { type: 'video/mp4' }), filename: 'video.mp4' };
+  if (video instanceof ArrayBuffer) return { blob: new Blob([video], { type: 'video/mp4' }), filename: 'video.mp4' };
+  if (video instanceof Blob) return { blob: video, filename: 'video.mp4' };
+  throw new Error('Unsupported video input for createCharacter()');
+}
+
+/**
+ * Create a character from an uploaded video.
+ * @param {string} name - Display name for the character.
+ * @param {CharacterVideoInput} video - Local file path or video bytes.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoCharacter>} Character response.
+ */
+async function createCharacter(name, video, options = {}) {
+  if (!name || typeof name !== 'string') throw new Error('createCharacter() requires a name string');
+  if (!video) throw new Error('createCharacter() requires a video input');
+
+  const { blob, filename } = await toVideoBlob(video);
+  const form = new FormData();
+  form.append('name', name);
+  form.append('video', blob, filename);
+
+  const response = await fetch(`${API_URL}/videos/characters`, {
+    method: 'POST',
+    headers: getMultipartHeaders(options.userAgent),
+    body: form
+  });
+  const parsed = await parseResponseBody(response);
+
+  if (!response.ok) {
+    throw new Error(`OpenAI character API error ${response.status}: ${JSON.stringify(parsed)}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Fetch a character by id.
+ * @param {string} characterId - Character id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoCharacter>} Character response.
+ */
+async function fetchCharacter(characterId, options = {}) {
+  if (!characterId) throw new Error('fetchCharacter() requires a characterId');
+  return apiRequest(`/videos/characters/${encodeURIComponent(characterId)}`, 'GET', null, {}, options);
+}
+
+export {
+  createVideo,
+  retrieveVideo,
+  listVideos,
+  deleteVideo,
+  downloadVideoContent,
+  emergencyPollVideo,
+  editVideo,
+  extendVideo,
+  remixVideo,
+  createCharacter,
+  fetchCharacter
+};