Convert a file. Follow the job.

1. Key. Create an API key in the dashboard.
2. Presign. Sign a GET for the source, a PUT for the output and a verify URL.
3. POST. Send POST /v1/jobs with a profile and the three URLs.
4. Verify the webhook. Check the signature on the completion event, as shown under Signed webhooks.
5. Read the result. GET /v1/jobs/{id} reports the job; the file is in your storage.

Before you start key, origin, storage URLs

1. Key. Create an API key in the dashboard and export it as SILKEN_API_KEY. It is shown once.
2. API origin. https://silken.io is the canonical public API origin. Native routes use /v1; MediaConvert clients use that origin as their endpoint override.
3. Two presigned URLs for objects in your own bucket: a GET for the source and a PUT for the output. With AWS S3 the CLI signs the GET (add --endpoint-url for R2 or another S3-compatible store); a PUT is signed with an SDK.

aws s3 presign s3://my-bucket/in.mp4 --expires-in 7200

python3 -c "import boto3; print(boto3.client('s3').generate_presigned_url('put_object', Params={'Bucket':'my-bucket','Key':'out.mp4'}, ExpiresIn=7200))"

Use aws s3 presign s3://my-bucket/out.mp4 for verify_url once the object exists, or sign a HEAD for the same key. Run these on a machine that has credentials for the bucket.

curl -X POST "https://silken.io/v1/jobs" \
  -H "Authorization: Bearer $SILKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile":     "hdr_to_sdr_1080p",
    "input_url":   "https://acct.r2.cloudflarestorage.com/in.mp4?X-Amz-Signature=…",
    "output_url":  "https://acct.r2.cloudflarestorage.com/out.mp4?X-Amz-Signature=…",
    "verify_url":  "https://acct.r2.cloudflarestorage.com/out.mp4?X-Amz-Signature=…",
    "webhook_url": "https://you.example.com/hooks/silken"
  }'

verify_url — read this before your first job the usual trap

When your storage answers the upload with success, silken records that response as a successful delivery and does not read the object back. If an upload’s outcome is uncertain — the connection drops, or no answer arrives — silken checks that the object is present and has the expected size before it completes or bills the job. A presigned PUT is often write-only, and cannot be read back — so that check needs somewhere to look.

• Send verify_url: a presigned GET or HEAD for the same object. This is the path to prefer, and it is what the samples above do.
• Omit it only if your output_url is itself readable. We probe it, and if it is, we use it for that check.
• If neither is readable, a job asking for the default durability: "verified" is rejected up front with 400 verification_unavailable rather than failing later. Send durability: "best_effort" to accept an unverifiable delivery.

Both URLs must also outlive the job. If the output URL expires before delivery, the job waits in awaiting_destination — see the lifecycle section.

A created job comes back as the job resource — id, profile, status, billable_seconds, output_bytes, attempt, timestamps, and your tuning echoed back when you sent any.

# Same job, steered: a filmic curve, local contrast restored,
# and the delivery grade disabled.
curl -X POST "https://silken.io/v1/jobs" \
  -H "Authorization: Bearer $SILKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile":    "hdr_to_sdr_1080p",
    "input_url":  "…",
    "output_url": "…",
    "tuning": {
      "tone": {
        "method":          "hable",
        "gamut":           "perceptual",
        "local_contrast":  0.6,
        "chroma_recovery": "capped",
        "chroma_strength": 0.35
      },
      "grade":  false,
      "dither": "tpdf",
      "crf":    20
    }
  }'

tuning.tone.highlight_detail: true enables optional Highlight detail for HDR-to-SDR outputs. It keeps more texture in bright highlights and adds 10% of the base output-minute rate, before speed and volume discounts. Omit it for the unchanged default. Standard and Fast only. It requires the reference look and auto or luma_hermite method; other looks, local contrast, chroma recovery, grade references, SDR profiles and the metadata/supplied-SDR grade routes reject it. Sources must be PQ/HLG YUV at 10 bits or above; RGB and dynamic-metadata profile 5 inputs are refused after source inspection. With the enhancement enabled, HLG uses reference method 11 rather than default method 12. For ladders, set it under each rendition’s tuning; native ladders require matching values. Jobs echo the setting and itemise highlight_detail in quotes and usage. Enhanced jobs wait for a worker whose engine qualified the option.

To keep HDR10 or HLG, request hdr_1080p_hevc or hdr_4k_hevc in a VOD ladder alongside SDR versions. The HEVC Main10 versions retain the source transfer, BT.2020 colour and static mastering/light-level metadata. Each version has its own VIDEO-RANGE and codec in the HLS master. HDR versions use the HEVC +50% output price, with no extra HDR fee. Standard and Fast only; SDR sources are refused by name. Availability follows the worker’s HDR render qualification.

Tone controls HDR→SDR profiles; applicability is validated against the source

Output controls all profiles

Sending a tone control with a profile that does not tone-map is an error rather than a no-op, so you never believe a setting took effect when it could not.

import crypto from "node:crypto"

// Header:  Silken-Signature: t=<unix-seconds>,v1=<hex>
// Signed:  HMAC-SHA256(secret, `${t}.${rawBody}`)
//
// Body, verbatim:
// { "job_id": "job_…", "status": "completed", "profile": "hdr_to_sdr_1080p",
//   "billable_minutes": 12.4, "output_bytes": 418293114, "timestamp": 1756800000 }
//
// billable_minutes is the DURATION of the output, measured before your free
// allowance — not an amount owed. A job inside the free tier still reports a
// positive number. Record it; bill from your invoice.
app.post("/hooks/silken", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Silken-Signature") || ""
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")))
  const t = Number(parts.t)

  // Reject anything older than five minutes, so a captured call can't be replayed.
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401)

  const expected = crypto
    .createHmac("sha256", process.env.SILKEN_WEBHOOK_SECRET)
    .update(`${t}.`)
    .update(req.body)
    .digest("hex")

  const got = Buffer.from(parts.v1 || "", "hex")
  const want = Buffer.from(expected, "hex")
  if (got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
    return res.sendStatus(401)
  }

  const event = JSON.parse(req.body)
  if (event.status === "completed") {
    // The output is already in your bucket, at the output_url you presigned.
    // The minutes are how long that output is, not what it cost.
    recordOutputMinutes(event.job_id, event.billable_minutes)
  }
  res.sendStatus(200)
})

billable_minutes is the duration of the output we delivered, measured before your free allowance is applied. A job covered entirely by the allowance still reports a positive number and still costs nothing, so it is a figure to record against the job — not an amount to charge anyone. What you owe is on your invoice.

What status can be delivery statuses

The status on a delivery is its own set. Three values are sent, and only two of them (completed and failed) appear in the job lifecycle table below under the same name.

Correlate on job_id, deduplicate on event_id. They are not the same key: one job can send a destination_expired for every renewal deadline it passes and then a completed, each with its own event_id, while a retry of one event repeats its event_id unchanged. The two statuses sent as the job ends carry no event_id at all.

Delivery and retries when your endpoint is down

The sender's contract, so you can size your handler against it rather than discover it in production. A slow endpoint is retried; one that answers 400 is not.

Retry timing includes the time each request takes as well as the backoff, and depends on the delivery path, so an endpoint that is down for a deploy may miss the event. Reconcile job state through GET /v1/jobs/{id}; do not rely on a single callback.

Retries

• Transient failures — download, conversion, probing — requeue up to 3 attempts with no added delay; the worker picks the job straight back up.
• Permanent failures fail on the first hit: an unknown profile, a source whose readable duration exceeds the job’s admitted maximum, an output longer than that maximum, or a destination URL the guard rejects outright. If a source’s duration cannot be read, the conversion bound still applies; validate the resulting file.
• Finalizing — metering and webhook — has its own budget of 10 attempts with backoff doubling from 1 second to a 1-hour cap. Exhausting it fails the job, and never charges for it. The error says what that means: the transcode ran and the output WAS delivered to your destination, and it is silken's own completion bookkeeping that did not finish. Check your destination before resubmitting — the file should already be there.
• A dead worker loses its lease after 5 minutes. The job is reclaimed and resumes from its last durable state rather than starting over, and every write is fenced on a lease epoch so a revived worker cannot overwrite newer state.

Width, height, CRF and preset are all overridable per job through tuning, so a profile is a starting point rather than a fixed SKU.

Authentication and endpoint discovery

Sign with AWS SigV4: service mediaconvert, region us-east-1. Use your silken API key as both the AWS access key ID and secret access key. Both are secrets. Do not use AWS IAM credentials or a session token for this client. Bucket credentials are separate. Requests must sign the host and date; keep your clock accurate. DescribeEndpoints is supported for clients that discover an endpoint first.

import os, boto3
key = os.environ['SILKEN_API_KEY']
mc = boto3.client('mediaconvert',
    endpoint_url='https://silken.io', region_name='us-east-1',
    aws_access_key_id=key, aws_secret_access_key=key)
print(mc.describe_endpoints()['Endpoints'])
# Supply a supported job to mc.create_job(**job).
# Complete runnable examples: examples/python and examples/go.

# Use a dedicated profile; do not overwrite your bucket credentials.
AWS_ACCESS_KEY_ID="$SILKEN_API_KEY" \
AWS_SECRET_ACCESS_KEY="$SILKEN_API_KEY" \
AWS_SESSION_TOKEN= AWS_SECURITY_TOKEN= \
aws mediaconvert describe-endpoints \
  --region us-east-1 --endpoint-url https://silken.io

With aws-sdk-go-v2, set mediaconvert.Options.BaseEndpoint = aws.String("https://silken.io") and credentials.NewStaticCredentialsProvider(key, key, ""), with region us-east-1. Python and Go runnable samples include native and MediaConvert submissions.

Catalog lists use listBy=NAME, order=ASCENDING, maxResults and nextToken. Create uses POST on the collection; get/update/delete use GET/PUT/DELETE on the named resource. Dates use epoch seconds. silken statuses map to SUBMITTED, PROGRESSING, COMPLETE, ERROR and CANCELED. Unsupported operations return an AWS-shaped error, not an empty success.

Source and destination access

For the presigned path, FileInput is a full HTTPS GET URL. A single MP4 FILE group’s Destination is a full presigned HTTPS PUT URL for one object, not a bucket prefix. The adapter chooses durability: "best_effort"; it cannot obtain a separate verification URL from a standard MediaConvert job file. To check delivery explicitly, use the native API with durability: "verified" and verify_url.

Native HLS/CMAF ladders accept Destination: "s3://bucket/prefix/". Register your account role, then grant s3:PutObject, s3:AbortMultipartUpload, s3:GetObject and s3:GetBucketLocation for delivery and HEAD verification. silken appends the job ID to the prefix. Segments publish first, media playlists next, master last; every object is HEAD-verified. Billing stays unchanged.

Native API example: {"input_url":"s3://bucket/source.mp4","destination":"s3://bucket/vod/", "max_output_seconds":60,"renditions":[{"key":"large","profile":"sdr_1080p"},{"key":"small","profile":"sdr_720p"}]}. Returned ladder.master_url and rendition URLs name your S3 objects. Omit destination for authenticated downloads, retained seven days after completion by default. PUT /v1/settings/output-retention with {"days":7} sets account retention (1–30 days) for later completions. Expired held objects are deleted; customer bucket objects remain yours.

Registered role access for S3 sources and destinations

Initialize PUT /v1/settings/s3-input-role with an empty object to get your account’s ExternalId. Grant silken’s onboarding-supplied AWS principal access through a role trust policy requiring that exact ExternalId, then register role_arn and a probe_uri. Set the job’s Role to that registered ARN. Temporary credentials renew in memory. Large objects use multipart delivery.

For R2, Backblaze B2 and Wasabi, register endpoint (HTTPS), region, probe_uri, access_key_id and secret_access_key instead of role_arn. R2 uses region auto; B2 and Wasabi use the region matching the bucket endpoint. Grant a dedicated key read/HEAD, write and multipart-abort access to the intended bucket/prefix. Keys stay in private account storage; settings responses and workers never receive them. The same destination field and verified publication order apply.

SPEKE v2 DRM for CMAF

Production admission was unavailable on 15 October 2026. The contract below describes implemented SPEKE v2 / CENC cbcs packaging; use it only when your live GET /v1/job-options advertises DRM as available.

Register an HTTPS key server with POST /v1/drm-provider, using url and a complete Basic or Bearer authorization value. Credentials are private account data; reads return only whether authentication is configured.

Native VOD ladders accept drm: { content_id, systems, key_period }. The optional hls_system_ids and dash_system_ids select manifest signalling; by default HLS includes all requested systems and DASH excludes FairPlay. Supported systems are FairPlay, Widevine and PlayReady. Each rendition and shared AAC audio receive distinct key IDs. One immutable content-key period covers the complete VOD package. HLS uses SAMPLE-AES, key-provider SKD or data URIs and session keys; DASH carries cbcs ContentProtection and PSSH. Subtitle tracks stay clear. DRM adds 25% of the output base price to encrypted versions; source and clear versions receive no DRM charge.

MediaConvert CMAF groups accept encryption.type=SPEKE, encryption.encryptionMethod=SAMPLE_AES and the spekeKeyProvider object (AWS type SpekeKeyProviderCmaf). Supply encryptionContractConfiguration with PRESET_VIDEO_1 and PRESET_AUDIO_1: these share one video key and use a separate audio key. HLS and DASH system ID arrays are independent: FairPlay belongs in HLS; Widevine and PlayReady can be signalled in either manifest. The provider URL must match the account registration.

Requires a pinned engine with DRM qualification and an explicit worker grant for the hls2_cbcs_v1 pipeline. Older workers cannot claim encrypted jobs. H.264/AAC VOD ladders only. SPEKE v1, wrapped keys/certificates, other encryption presets, AES-CTR, TS DRM, custom audio variants and live rotation are refused by name. Vendor license playback is configured with your provider.

Check your job file

POST /v1/mediaconvert/validate accepts the same job JSON with native bearer authentication. It returns every field/schema refusal and the first value or group refusal from the admission translator. A supported field means it is recognized; the whole job must have valid: true. Validation creates no job, reserves no funds, and fetches no media. Source inspection, permissions and account admission still run at submission.

curl https://silken.io/v1/mediaconvert/validate \
  -H "Authorization: Bearer $SILKEN_API_KEY" \
  -H "Content-Type: application/json" --data-binary @job.json

Supported settings matrix

Generated from the translator’s own schemas, including audio and caption selectors. The existing coverage test checks this page’s generated rows against code. The deployed revision’s table is also available at GET /v1/mediaconvert/settings. “Supported” remains conditional on values, output groups, engine qualification and account capabilities. No unsupported field is silently discarded.

Named rejection

This payload is asserted by the gateway test using an H.265 request. AWS SDKs read X-Amzn-Errortype and the message as a typed BadRequestException.

HTTP/1.1 400 Bad Request
X-Amzn-Errortype: BadRequestException
Content-Type: application/json

{"message":"unsupported field CreateJob.settings.outputGroups[0].outputs[0].videoDescription.codecSettings.codec: H_265","__type":"BadRequestException"}

Runnable SDK samples

Python and Go samples contain a native job and a MediaConvert job with a real endpoint override. They use SILKEN_API_KEY, default to https://silken.io, and submit only when explicitly passed --submit. Supply your own source, destination and verification URLs.

Download native.py, mediaconvert_job.py, Python requirements, Go source and Go module and Go checksums. The repository keeps the same files in examples/python and examples/go.

export SILKEN_API_KEY='your own key'
python3 native.py --input-url "$INPUT_GET_URL" --output-url "$OUTPUT_PUT_URL" --verify-url "$OUTPUT_VERIFY_URL"
python3 mediaconvert_job.py --input-url "$INPUT_GET_URL" --output-url "$OUTPUT_PUT_URL"
go run . -mode mediaconvert -input-url "$INPUT_GET_URL" -output-url "$OUTPUT_PUT_URL"

Python MediaConvert and Go MediaConvert commands validate by default. Native commands describe the request; add --submit to create billable work after reviewing it.

API changelog

Changes in the API source, with dates from commit history. A source release entry does not claim that every deployment already runs it. Download the deployed gateway’s OpenAPI contract for its current routes.

2026-10-13 — compatibility reference and validation

• Added a MediaConvert field matrix generated from the admission translator, a job-file validator, and runnable Python and Go examples.
• Added aggregate GET /v1/status and the embedded contract at GET /v1/openapi.yaml.
• Documented existing endpoint discovery, account-scoped presets/templates, Default queue operations, list/cancel and usage APIs.
• MediaConvert reads now represent a job being canceled as PROGRESSING until cancellation finishes. Embedded caption channel selection accepts the integer sent by AWS SDKs. Default queue lists accept standard SDK paging and sort arguments.

2026-10-06

d26ac735: price book v4 added marginal monthly volume pricing. Existing jobs retain their accepted pricing version.

2026-10-01

• 7241ef94: extended MediaConvert operations and official SDK compatibility coverage.
• 375d99ce: composite MediaConvert jobs use native output owners.
• 4e3e0c7c: registered customer-role S3 input access landed.
• 658a4b56 and 6fdc95d0: native audio track selection and subtitle input/publication contracts.