Managed media jobs

Managed media jobs are Amba's native-process companion to edge functions. Use an edge function for request handling and orchestration; submit work here when the job needs Linux, FFmpeg, filesystem scratch space, more memory, or a multi-hour wall-clock budget.

This surface is currently allowlisted. A project without an approved runtime profile receives 403 MEDIA_RUNTIME_NOT_ENABLED. The first supported profile is podpod-media-v1; arbitrary customer images are not accepted by this API.

Execution model

1. Your backend or Amba function creates a job with a project-scoped server credential and a stable idempotency key.
2. Amba durably hands it to a private queue and starts one isolated Cloudflare Sandbox using the approved profile image and bundle.
3. The sandbox reports idempotent lifecycle events, heartbeats, stdout/stderr, progress, and its terminal result.
4. You poll the job or logs, or request cancellation. The maximum v1 runtime is four hours.

Application state stays application-owned. For example, PodPod continues to own its jobs collection row; external_job_id is the link between that row and Amba's execution record.

Create a job

From an Amba function, use its injected project token:

const response = await fetch(
  `${env.AMBA_API_URL}/v1/admin/projects/${env.AMBA_PROJECT_ID}/media-jobs`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${env.AMBA_INTERNAL_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      profile: 'podpod-media-v1',
      external_job_id: podpodJobId,
      idempotency_key: `podpod:${podpodJobId}`,
      timeout_seconds: 14_400,
      metadata: { kind: 'episode-render' },
    }),
  },
);
 
if (!response.ok) throw new Error(await response.text());
const { data: execution } = await response.json();

idempotency_key is required. The create call returns 202 for a new job. Repeating the same profile + idempotency_key returns the original row with 200 and deduplicated: true; it does not start a second process. Never put credentials or private media URLs in metadata.

If Temporal accepts the durable handoff but its acknowledgement cannot be confirmed, create returns 503 DISPATCH_START_UNKNOWN with details.job_id. Retry the same request with the same idempotency_key; Amba preserves the row and its private callback capability and re-drives the same deterministic workflow instead of creating another execution.

{
  "data": {
    "id": "8e5f…",
    "profile": "podpod-media-v1",
    "external_job_id": "job_123",
    "status": "queued",
    "progress": 0,
    "timeout_seconds": 14400,
    "attempt": 0,
    "deduplicated": false
  }
}

The runtime callback capability is never included in a public response or log.

Read status and logs

GET /v1/admin/projects/{projectId}/media-jobs/{jobId}
GET /v1/admin/projects/{projectId}/media-jobs?status=running&profile=podpod-media-v1
GET /v1/admin/projects/{projectId}/media-jobs/{jobId}/logs?after_id=0&limit=200

Statuses are queued, starting, running, cancel_requested, succeeded, failed, and canceled. Log rows are ascending and cursor-paginated; pass the last next_after_id as the next request's after_id. Each job retains at most 10,000 log lines and 10 MiB of log text; log_lines and log_bytes on the job show the retained totals.

Do not infer liveness from status alone. A running job's heartbeat_at advances about every 30 seconds. Operator alerting should flag a running job after two missed heartbeat intervals.

Cancel

POST /v1/admin/projects/{projectId}/media-jobs/{jobId}/cancel
Authorization: Bearer <project server key or injected internal token>

Cancellation is idempotent. A live sandbox is stopped and the job converges on canceled; a job that is already terminal is returned unchanged.

Profile artifacts and secrets

Amba owns the base image and runtime supervisor. An approved profile provides a reviewed application bundle plus non-secret configuration in the private runtime artifact bucket. On each dispatch, Temporal resolves the project's scoped internal token and the profile's allowlisted project-wide secrets from the audited secret store. Those values never appear in the bundle, static profile config, or client binary. Application code receives the credentials it needs, so it must redact them from its own logs. The v1 artifact key is mutable; operators record its digest and retain the prior reviewed bundle for rollback. See the internal media-runtime runbook for artifact rotation and rollback.

This is a managed-profile product today, not a bring-your-own-Docker API. A general image registry, image scanning/signing, per-tenant quotas, egress policy, and billing contract are required before arbitrary customer images can be accepted safely.