Skip to main content

Private assets and media jobs

Cortex stores private bytes in Convex-owned storage. The application upload and authenticated delivery limit is 20,000,000 decoded bytes. Protocol/backend/provider-input limits can be smaller; an otherwise valid file is not automatically eligible for a model input.

Service setup​

Install the authenticated HTTP routes, configure the same installation's explicit HTTP action origin and grant storage:read/storage:write as required. Image generation also needs a qualified Gateway model, fixed supported options and model budgets.

Asynchronous video generation is unavailable in Convex Gateway and cannot be enabled for an individual team or deployment. It is explicitly deferred until official platform support exists and the implementation passes compatibility qualification, real service checks and independent acceptance. The retained video kind and media.video.generate operation are reserved contracts, not functional generation capabilities.

The qualified image path accepts a text prompt without an input asset. Its observed descriptor has callbacks: false and records requested model identity only; serving identity and USD charges remain unknown. Private uploads, including existing video files, remain available independently of video generation. This release does not provide image understanding, OCR or visual embeddings.

Upload and preview​

import type { CortexRuntimeClient } from '@cortexmemory/sdk/runtime';

export async function previewUpload(client: CortexRuntimeClient, requestId: string, file: File) {
  const asset = await client.uploadAsset(file, {
    requestId,
    mimeType: file.type || 'application/octet-stream',
    filename: file.name,
  });
  const preview = await client.createAssetUrl({ assetId: asset.assetId, version: asset.assetVersion });
  return { asset, preview, close: () => preview.revoke() };
}

Use { assetId, version } to select an immutable version. Metadata includes hash, size, MIME, lineage and optional delivery expiry. The client freshly authorizes downloads through assetHttpUrl, checks size/MIME/hash and can create a local Blob preview. Revoke the preview on close/unmount. Client close and authentication changes revoke owned previews too.

There are no public storage links, external media storage or embedded base64 transcripts. Never store provider URLs, bytes or credentials in reconnect state.

Generate and recover​

import type { CortexRuntimeClient } from '@cortexmemory/sdk/runtime';

export async function generateImage(
  client: CortexRuntimeClient,
  requestId: string,
  prompt: string,
) {
  return client.submitMediaJob({ requestId, kind: 'image', prompt });
}

submitMediaJob saves a pending job and artifact before generation. The backend selects the qualified model/options; callers cannot override them. Read retained state with getMediaJob, listMediaJobs and getArtifact.

Keep the original request identity when recovering a lost submit response. reconcileMediaJob reads the retained job and can mark an expired submission lease as submission_unknown or resume eligible retained-output recovery. It does not guarantee recovery of a lost upstream image result. submission_unknown retains uncertainty; reconnect, observation or replay never blindly submits another generation.

cancelMediaJob fences local delivery. upstreamCancellation: 'not_supported' means the provider can continue and incur cost. costStatus distinguishes reserved, incurred-unknown and settled cost. A local deadline does not prove a terminal upstream outcome or justify refund/retry.

Revocation, deletion/tombstones, artifact history and retained-reference cleanup govern files and background jobs. The runtime client API lists asset, content and media methods.

Reserved video recovery contracts​

Signed callback verification/deduplication, native polling and provider-result download remain dormant video contracts. They describe how a future qualified video operation would reconcile its saved upstream identity, including a missed callback. They do not establish available video generation or callback support for the qualified image path. Video input profiles and callback setup require future qualification before use.