DocsAPI v1UI + API walkthroughs

Start in the UI. Graduate to API keys when the flow makes sense.

These docs are written for clients using MediaRuntime, not internal engineers. Pick the path that matches where you are: dashboard setup, sandbox exploration, workspace runs with your own media, or full server-to-server automation.

Example requests below use placeholder domains. Replace them with your public MediaRuntime endpoints in production.

Start with Sandbox Open Workspace

Start here

Choose the path that matches your stage.

The easiest way to avoid confusion is to follow the same progression your customers usually take: activate the account, test in sandbox, validate your own files in workspace, then automate the same flow from your server.

First-time setup

Activate the account in the dashboard

Choose a plan, add a payment method, fund your wallet, then roll your first API key from Profile.

Read this path

No upload needed

Learn the product in Sandbox

Run a known sample input first so you can see the request shape, logs, and result bundle before touching production files.

Read this path

Real media

Use Workspace for your own files

Upload media, configure outputs and moderation, then inspect timing, usage, and artifacts from the jobs UI.

Read this path

Production

Move to API-key automation

Create a signed upload target, upload bytes, queue /v1/transcode, and receive completion through webhooks.

Read this path

Account setup

1. Set up the account once in the dashboard.

Before clients can run real jobs, they need an active billing state, wallet credits, and at least one live API key. This is the cleanest operator path from the hosted UI.

Choose a plan and activate billing

Pick Standard or Premium, then complete card setup. Premium is required for moderation features.

Go to Pricing

Fund the wallet

Add credits to the account. The wallet must be funded before you can generate live API keys and run paid jobs.

Manage Wallet

Generate a server key

Roll a live API key and copy it to a secure location. This is the secret you will send in Authorization headers on /v1 requests.

Generate API Key

Register a webhook URL

Set the destination URL for async completion events. Every URL change rotates the signing secret, so copy the new one immediately.

Configure Webhooks

cURL

Alternative: raw key-creation call

curl -X POST "https://app.your-mediaruntime-domain.com/api/keys/roll" \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_xxx",
    "label": "production",
    "revokeOthers": false
  }'

What “ready” looks like

Billing status is active

Wallet has credits available

At least one live API key is copied to your server

A webhook URL is configured for async notifications

Sandbox

2. Use Sandbox to learn the shape of a job.

Sandbox is the fastest way to understand how requests, outputs, tier decisions, and live logs behave before you upload your own media.

Open Sandbox

Start with the hosted playground so you can learn the request shape before introducing your own uploads.

Open Sandbox

Pick a sample input

Use one of the preloaded samples. That lets you focus on outputs, moderation flags, and logs instead of upload plumbing.

Use a sample

Run and watch the event stream

Inspect queueing, tier decisions, probe progress, transcode updates, and bundle delivery in one place.

Watch a run

Save the request shape

Once the run makes sense, copy the same request structure into your own server integration.

Reuse the payload

What to watch in the sandbox run

Tier selection and whether the request stays standard or upgrades to premium.

Progress events for probing, transcode, subtitles, or moderation.

Final usage lines, bundle link, and any webhook status the worker records.

The exact request structure you will later reproduce from your server.

Open Sandbox

Workspace

3. Use Workspace for real media and richer inspection.

Workspace is the easiest place to run production-style jobs from the UI. It uses the same backend, but adds file upload, job history, and a much stronger post-run view.

Upload your own media

Use Workspace when you are ready to validate the platform with real image, audio, or video files from your own flow.

Open Workspace

Configure outputs and moderation

Choose presets, add image or video moderation when needed, and confirm whether the job should stay standard or go premium.

Configure the job

Run the job and watch progress

Keep the job open while timings, worker logs, moderation status, and final bundle metadata stream in.

Run a workspace job

Inspect the finished job

Open the Jobs page to review cost, usage, moderation evidence, outputs, and any webhook delivery status.

Inspect Jobs

What Workspace helps you validate

Your upload path and output presets with real customer media.

Premium moderation toggles on image and video jobs.

Job-level timing, credits spent, credits reserved, and final artifacts.

Whether the final UI explanation is clear enough before you automate the same flow in code.

Open Workspace

Server to server

4. Move to API-key automation once the flow is familiar.

This is the smallest reliable production sequence: create an upload target, upload bytes, queue /v1/transcode, then receive completion by webhook.

Use the API key from Profile

All /v1 data-plane requests use the live API key you rolled from the dashboard.

Request an upload target, then upload bytes

Ask for a signed upload target first, then PUT the file bytes to the returned upload_url.

Queue /v1/transcode

Send the gs:// file_uri, outputs, and optional moderation block in the transcode request body.

Treat completion as asynchronous

Use the immediate response as a queued job envelope, then wait for webhook delivery or redeem the final bundle token.

Minimal production sequence

1. Create upload target

curl -X POST "https://api.your-mediaruntime-domain.com/v1/upload-url" \
  -H "Authorization: Bearer mr_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "launch-trailer.mp4",
    "content_type": "video/mp4"
  }'

2. Upload bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file ./launch-trailer.mp4

3. Queue the job

curl -X POST "https://api.your-mediaruntime-domain.com/v1/transcode" \
  -H "Authorization: Bearer mr_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "gs://transcoder-486012-input/uploads/acc_xxx/launch-trailer.mp4",
    "metadata": {
      "assetId": "asset_launch_0426",
      "campaign": "spring-drop"
    },
    "moderation": {
      "enabled": true,
      "mode": "report",
      "checks": ["sexual", "violence", "dangerous"]
    },
    "outputs": [
      {
        "type": "mp4",
        "preset": "mp4_720p_h264_aac"
      },
      {
        "type": "image",
        "preset": "image_multi_v1"
      }
    ]
  }'

Immediate API response

{
  "job_id": "job_1320c28b72104811b075a26a99496cf6",
  "status": "QUEUED",
  "tier": "premium",
  "msg": "accepted"
}

How to think about it

The response is a queued job envelope, not a finished artifact.

Use the returned job id as your durable reference across logs, support, and webhooks.

For moderation-heavy or longer video jobs, explain clearly to users that completion is asynchronous.

Webhooks

5. Webhooks are the cleanest production completion signal.

You can set the webhook URL from the Profile UI or call the authenticated control-plane endpoint yourself. The platform signs every webhook so your server can verify it.

Webhook setup request

curl -X POST "https://app.your-mediaruntime-domain.com/api/webhooks/set" \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_xxx",
    "webhookUrl": "https://example.com/webhooks/mediaruntime"
  }'

Headers to verify

X-Transcoder-Id identifies the webhook event.

X-Transcoder-Timestamp gives the signing timestamp.

X-Transcoder-Signature contains the HMAC-SHA256 signature.

The webhook secret is view-once when you first set or rotate the destination URL, so copy it immediately to your server config.

Example completion payload

{
  "event": "job.completed",
  "jobId": "job_1320c28b72104811b075a26a99496cf6",
  "accountId": "acc_xxx",
  "status": "COMPLETED",
  "usage": {
    "units": 251,
    "costUsd": "5.02"
  },
  "delivery": {
    "bundle": {
      "url": "https://api.your-mediaruntime-domain.com/v1/jobs/job_1320c28b72104811b075a26a99496cf6/bundle?token=..."
    }
  }
}

Reference

Keep the reference small and practical.

Once the step-by-step flow is clear, these are the handful of endpoints clients usually need to remember.

POST/v1/upload-url

Create a signed upload target and get the gs:// URI you will pass into /v1/transcode.

POST/v1/transcode

Queue image, audio, or video processing. Premium moderation lives on this same request body.

GET/v1/jobs/{jobId}/bundle?token=...

Redeem a delivery token into a temporary signed bundle download when the job is complete.

POST/api/keys/roll

Create a live API key from an authenticated dashboard session. The secret is shown once.

POST/api/webhooks/set

Attach a webhook destination and rotate the signing secret for server-side verification.

POST/api/billing/summary

Read billing state, wallet requirements, and account readiness from the authenticated dashboard surface.