Duplicate-safe retries
If your worker restarts after submitting a request, the same idempotency key can return the existing Convertrilo job.
Reliability guide
Retry-safe video encoding queue automation
Connect Convertrilo to your own queues, cron jobs, imports, and backfills without duplicating jobs when retries happen.
Most production encoding starts inside another queue. The important part is making retries boring: stable idempotency keys, clear external ids, metadata, and terminal status handling.
Queue worker patternguide
const idempotencyKey = [
upload.assetId,
upload.targetCodec,
upload.targetResolution
].join(":");
await client.onDemandEncode({
sourceUrl: upload.sourceUrl,
externalId: upload.assetId,
metadata: {
queueJobId: upload.queueJobId,
tenantId: upload.tenantId
},
codec: upload.targetCodec,
resolution: upload.targetResolution,
priority: upload.paidPriority ? "high" : "normal"
}, { idempotencyKey });A durable queue, scheduled job, or import process in your own backend.
Stable asset ids or upload ids for idempotency keys.
A policy for normal versus paid priority jobs.
A terminal-state handler for completed, failed, and canceled jobs.
Recipe
Build the workflow with stable API primitives
These guides focus on primitives that can be reused by dashboards, queue workers, scripts, CLIs, MCP tools, and agent runtimes.
- Step 1
Derive one idempotency key from your asset id and intended output recipe.
- Step 2
Attach externalId and metadata so your own records can be updated later.
- Step 3
Submit normal or high-priority jobs according to plan, billing, or customer action.
- Step 4
Handle terminal events with polling or signed webhooks instead of leaving local queue jobs open forever.
Priority without separate code paths
Paid or urgent jobs can set priority while still using the same source, metadata, output, and webhook handling flow.
Backfill friendly
Use the same pattern for one upload, a folder import, or a scheduled library cleanup pass.
Developer questions
Should my queue retry failed Convertrilo jobs automatically?
Retry network and submit failures with the same idempotency key. Treat terminal encoding failures as product events that need a policy, because the source or requested settings may be invalid.
How should I prioritize paid work?
Send priority in the job payload for paid or urgent work, then let the worker queue choose priority lanes while normal jobs continue to flow.
Can I cancel queued work?
Use the API or dashboard cancellation path for jobs that should not continue, then reconcile the terminal state in your own app.
Related developer paths
SDK quickstartInstall the Convertrilo TypeScript SDK, create an API key, submit a retry-safe encoding job, and wait for a completed output.Webhook receiverReceive signed Convertrilo job events, verify the HMAC signature, and update your own product when outputs are ready.S3 output workflowsRoute completed video encodes to S3-compatible buckets so your product keeps ownership of storage, CDN, lifecycle rules, and access control.MCP setupInstall @convertrilo/sdk, save an API key with the CLI, configure convertrilo-mcp in an MCP client, and verify the available video encoding tools.Agent workflowsDesign agent-friendly video encoding workflows with the Convertrilo MCP server, scoped API keys, deterministic job payloads, idempotency, polling, and signed webhooks.Video encoding APICreate video encoding jobs from your backend with API keys, idempotency, metadata, priority queues, webhooks, and storage destinations you control.Video encoding CLIAutomate video compression from terminals, deployment jobs, content pipelines, and scheduled scripts with a Convertrilo CLI workflow.VMAF video encodingUse VMAF-guided sample encoding to choose a better quality target before the final video encode, without manually testing bitrate settings.Two-pass video encodingUse classic two-pass H.264 and H.265 encoding when predictable bitrate allocation matters more than raw hardware speed.
Start with a real estimate
Choose your codec, resolution, FPS, bitrate, quality, and optimization settings. Convertrilo shows the NEU estimate before credits are reserved, and failed jobs release reserved credits back to your balance.