Meet MediaRuntime: An Async Media Runtime for Developers

Media features look simple from the outside. A user uploads a video, your product shows a playable version, and the work appears finished. Behind that interaction are uploads, format conversion, codec choices, adaptive streaming, thumbnails, audio extraction, transcripts, retries, storage, delivery, and cost tracking. MediaRuntime brings that work into one asynchronous media pipeline built for developers. Your application uploads a source, submits the outputs it needs, and moves on. MediaRuntime executes the job outside your request-response cycle and tells your backend when the result is ready.

Media work does not belong in a request-response cycle

A media job can take seconds or minutes. Its runtime depends on the source, selected outputs, codecs, machine-learning features, and the number of artifacts being generated. Keeping an HTTP request open for that work creates fragile timeouts and forces application servers to manage infrastructure they were never meant to own. MediaRuntime accepts the job quickly and returns a job ID with a QUEUED status. Your application persists that ID, continues serving the user, and handles a signed terminal webhook when processing reaches COMPLETED or FAILED. That boundary keeps the integration predictable even when the media workload is not.

Your application submits intent. MediaRuntime handles execution.

The pipeline in four steps

1. Request a short-lived upload target with your server-side API key. 2. Upload the source bytes using the exact URL and headers returned by MediaRuntime. 3. Submit a transcode job using the returned file_uri and one or more output recipes. 4. Verify the signed terminal webhook, update your application record, and use the returned delivery URLs. The file_uri is deliberately opaque. Applications never need to know or construct MediaRuntime storage paths.

const baseUrl = "https://mediaruntime.com";
const apiKey = process.env.MEDIARUNTIME_API_KEY;

async function mediaRuntime(path, body) {
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const result = await response.json();
  if (!response.ok) throw new Error(JSON.stringify(result));
  return result;
}

const target = await mediaRuntime("/v1/upload-url", {
  filename: "launch-trailer.mp4",
  content_type: "video/mp4",
});

const upload = await fetch(target.upload_url, {
  method: "PUT",
  headers: target.upload_headers,
  body: sourceBytes,
});
if (!upload.ok) throw new Error(`Upload failed: ${upload.status}`);

const job = await mediaRuntime("/v1/transcode", {
  file_url: target.file_uri,
  metadata: { asset_id: "asset_0426", media_type: "video" },
  outputs: [
    { type: "mp4", preset: "mp4_720p_h264_aac" },
  ],
});

console.log(job.job_id, job.status); // job_... QUEUED

One input can become every artifact your product needs

MediaRuntime is not limited to changing one video extension into another. A single video upload can produce a browser-ready MP4, an adaptive HLS streaming package, a poster image, an animated GIF preview, an audio-only file, and SRT or WebVTT transcripts. Audio jobs can normalize loudness, trim silence, copy compatible streams, or prepare 16 kHz mono WAV for speech systems. Image jobs can generate multiple JPG, PNG, WebP, or AVIF derivatives with fit, cover, contain, or fill behavior. Each output is an explicit recipe, so your backend describes the product result instead of orchestrating individual media commands.

{
  "file_url": "gs://value-returned-by-upload-url",
  "metadata": {
    "asset_id": "episode_0426",
    "media_type": "video"
  },
  "outputs": [
    {
      "type": "mp4",
      "preset": "mp4_720p_h264_aac",
      "path_suffix": "playback",
      "poster_time_sec": 5,
      "poster_format": "jpg",
      "gif_preview": {
        "enabled": true,
        "width": 480,
        "fps": 10,
        "start_time": 5,
        "duration": 3
      }
    },
    {
      "type": "hls",
      "preset": "hls_ladder_v1",
      "path_suffix": "stream"
    },
    {
      "type": "audio",
      "preset": "audio_aac_128k",
      "path_suffix": "listen",
      "subtitles": {
        "enabled": true,
        "languages": ["auto"],
        "format": "both",
        "model": "ggml-base.bin",
        "translate_to_english": false
      }
    }
  ]
}

Presets provide a stable contract

Instead of asking every developer to become a codec expert, MediaRuntime exposes named presets for common delivery goals: H.264 playback, HLS ladders, fast remuxing, HEVC, AV1, ProRes masters, social 9:16 video, GIFs, frame sequences, audio formats, speech preparation, and multi-size images. A preset defines a dependable starting point. You add only the options your product needs, such as a poster timestamp, GIF duration, image dimensions, transcript format, or output suffix. This makes job payloads easier to review, reproduce, and evolve.

Delivery is part of the runtime

Completed jobs include their generated artifacts and a short-lived, job-scoped bundle URL under the MediaRuntime domain. Your application reads those URLs from the terminal job payload instead of constructing bucket names or filenames. Terminal webhooks are signed. Verify the raw request body before trusting the event, use the event ID for idempotency, and return a successful response only after your application has safely recorded the result. That gives retries a clear contract without duplicating downstream work.

Usage-aware from estimate to settlement

Before execution, MediaRuntime estimates the requested work and reserves the projected amount from the account wallet. After the engine finishes, the job settles against actual usage and releases any unused reservation. That model makes the cost lifecycle visible: projected usage before processing, final usage after processing, and one account-level view of available, reserved, and pending funds. Different codecs, output counts, and premium features can change the required tier and usage, so the job estimate remains the source of truth for a specific request.

Safety and brand controls travel with the job

Premium jobs can request moderation for sexual content, violence or gore, and dangerous content. Moderation currently produces a report and sampled-frame evidence; it does not block the transcode. That lets application teams decide how a result should affect review queues, publishing, or user access. Watermarking is just as direct. Configure an account logo once, then add watermark.enabled to the job. The execution engine applies the configured logo to supported outputs without requiring a separate worker or client-side image operation.

{
  "moderation": {
    "enabled": true,
    "mode": "report",
    "checks": ["sexual", "violence", "dangerous"]
  },
  "watermark": { "enabled": true }
}

A runtime, not a pile of media scripts

The goal of MediaRuntime is not to hide media capabilities. It is to give them a clean application boundary. Your product owns the user experience, business rules, and the decision about what to create. MediaRuntime owns the asynchronous execution path needed to create it reliably. That separation works for a creator tool generating social clips, a marketplace preparing product media, a learning platform producing streams and transcripts, a podcast service extracting normalized audio, or any application that should not have to build a media platform before shipping a media feature.

Start with one job

Create an API key and webhook secret from your MediaRuntime account, choose the first output your product needs, and submit it asynchronously. From there, the same pipeline can grow from one MP4 into HLS, previews, audio, transcripts, image derivatives, moderation reports, and branded delivery. Read the complete integration guide at https://mediaruntime.com/docs. If you want help shaping a production workflow, contact the team at https://mediaruntime.com/contact.