#Changelog

A record of notable changes to the Transcodely API. We follow Semantic Versioning — breaking changes will always be announced in advance and accompanied by a migration guide.

#Versioning Policy

The Transcodely API uses a single stable version (v1) at the endpoint level. Changes within v1 follow these rules:

Backward-compatible changes are shipped continuously without version bumps. Breaking changes would result in a new API version (e.g., v2).

#2026-09-16

#Changed

• HDR tone-mapping withheld at job creation — an output carrying hdr.mode = tonemap is now rejected with error code parameter_unsupported on outputs[i].video[j].hdr.mode, instead of being accepted and failing partway through the encode. The worker’s tone-mapping filter cannot run on the shipped worker image (worker#172): the pinned ffmpeg build is missing an option the filter emits, and the base image ships no Vulkan loader. HDR passthrough and force modes, and Dolby Vision, are unaffected. Nothing was ever billed for a failed tone-map job, so this is a stricter, more honest rejection rather than a pricing change. See HDR.

#2026-09-15

#Added

• Per-title encoding — content_aware.mode = per_title on an output is now accepted and acted on. The worker measures short samples of your source at several CRFs, scores each against the original with VMAF, and encodes your declared ladder at the cheapest setting that still reaches the target. Your ladder is untouched: same renditions, same resolutions, same count, so the price quoted at create still holds. vmaf_target accepts 80—97 and defaults to 93, regardless of quality tier. What the search decided comes back on report.content_aware — the target it aimed at, the score it reached on its samples, and the CRF it chose. See Content-Aware Encoding.
• Per-title pricing, charged only when a search ran — a per-title output carries the published 1.5x multiplier, applied once per output rather than once per rung. An output whose search could not run falls back to the quality tier’s own CRF and is billed at 1.0x; the corrected number is what its pricing snapshot reports.

In the release validation run against worker 1.28.1, a 1080p H.264 output asking for the default target of 93 reached a sample VMAF of 93.043 at CRF 27 and came out at 63.5% of the size of an identical untuned output from the same source. A three-rung HLS ladder asking for a non-default target of 90 reached 90.426. Those are measurements of those clips, not a promised savings figure for your library.

#New error codes

• per_title_source_too_short — a per-title output whose effective (clipped) encode window is under 120 seconds is failed at probe. The CRF search costs the same whatever the source’s length while the multiplier is proportional to it, so below two minutes the uplift does not cover the machine time.

Two per-title requests are also refused at job creation with parameter_incompatible: an output that encodes no video at all, and one whose every video rendition is pinned to an explicit bitrate (a bitrate-mode rendition ignores CRF, so the search would change nothing while still being billed). A mixed ladder is fine — one quality-driven rendition is enough.

Auto-ABR ladder generation is still not available. content_aware.mode = auto_abr remains rejected at job creation with parameter_unsupported, because it would change the number of renditions after the job was already quoted per rendition.

#Fixed

• Hosting enablement no longer fails on a retry — BunnyCDN’s pull-zone listing answers with a paginated envelope rather than a bare array, which the adoption path failed to decode. First-time enablement was unaffected; every retry, and every re-enable on an app whose pull zone still existed, failed hard until now.
• A preset carrying DRM is usable again — an output that names a preset states no type, and the request-level DRM rule read that as a non-streaming container and refused the job before the preset resolved. DRM on a preset output is now judged after the preset is applied, and the resolved output is checked too, so a progressive-MP4 preset still cannot carry DRM.

#2026-08-16

#Added

• Budgets — Set a monthly EUR figure for your organization and get emailed at 50%, 80% and 100% of it. A budget never blocks anything: it is telemetry you asked for about your own spend, measured against the same ledger your invoice is built from. Read and write it with BillingService.GetBudget / UpdateBudget (organization-scoped, owner-only). See Budgets.
• Outstanding balance and trust thresholds — Usage you have accrued that has not been invoiced yet is now visible, together with the threshold it is measured against: €50 while no statement has been paid, €100 after one or two, and no tier threshold at all after three. Reminder emails go out at 80%, 100%, 125%, 150% and 175% and restrict nothing; only at twice the threshold are new jobs refused. Read it with BillingService.GetOutstandingBalance. See Outstanding Balance.
• Paying an outstanding balance mid-cycle — BillingService.SettleOutstandingBalance closes the current period at that instant and produces a real statement for everything owed. Availability is reported per account by settlement_available on the balance; where it is off, the RPC answers settlement_unavailable rather than pretending.

#Changed

• An unpaid statement now has a published schedule — day 0 and day 3 change nothing while the payment provider retries; day 7 refuses new jobs (billing_past_due) while queued work finishes and playback keeps serving; day 14 suspends the organization with dashboard reads and job cancellation still open; day 45 warns about data deletion; day 60 writes the statements off. Paying restores service immediately — the next create is admitted, with no sweep to wait for. See Payment Failures.

#New error codes

• billing_past_due (failed_precondition) — an issued statement is unpaid and has reached day 7.
• outstanding_balance_exceeded (failed_precondition) — uninvoiced usage reached twice your threshold.
• settlement_unavailable (failed_precondition) — mid-cycle settlement is not enabled on this deployment.
• nothing_outstanding (failed_precondition) — there is nothing to settle right now.

Three of the four clear when somebody pays or an operator changes something; nothing_outstanding clears as usage accrues. None clears on a retry backoff, so do not retry them on one. See Errors.

#2026-08-08

#Changed

• Per-job pricing: processing fee replaces the minimum charge — Every job an encoder starts now carries a flat processing fee, scaled to the job’s size class (currently €0.05 for the shared classes S and M, €0.25 for L, €0.50 for XL; the pricing page always publishes the current rates). The fee is additive — it is added to what your outputs bill rather than clamping the total upward, which is what the retired per-job minimum charge did. It appears in fees with fee_type processing, unit job, quantity 1, and as its own fee line on the job’s cost_breakdown.
• Canceled jobs can now be billed — Canceling a job that is still queued costs nothing. Once an encoder has picked the job up, canceling bills the processing fee plus any outputs that completed before the cancel landed. Declining a delayed-start job after its probe has run also bills the processing fee, because the probe ran on real hardware. Previously a canceled job was billed only for completed outputs.
• Failed jobs still bill €0 — unchanged, and now explicitly including the processing fee. A failed job bills nothing at all.

#Deprecated

• minimum_charge_eur and minimum_charge_applied on Job — Historical jobs only. Both fields remain on the wire and keep their values for jobs created before this change; they are absent (or false) on every job created since. No new job is subject to a minimum charge. Jobs created under the old model keep the terms they were created under, and their minimum-charge line still renders on their cost breakdown.

#2026-07-13

#Removed

• API-key environment (breaking) — The live/test environment concept has been removed from API keys. The environment field/enum no longer exists on ApiKey, CreateApiKeyRequest, or ListApiKeysRequest, and keys are no longer scoped to a live or test environment. Remove any code that sets environment when creating keys or filters by it when listing them.
• Webhook livemode (breaking) — The livemode field has been removed from the webhook event envelope (Event). Delete any handler logic that read livemode from delivered events.

#2026-05-24

#Added

• Webhooks — WebhookService for managing webhook endpoints per app: CreateWebhookEndpoint, RetrieveWebhookEndpoint, UpdateWebhookEndpoint, DeleteWebhookEndpoint, and ListWebhookEndpoints, plus RotateWebhookSecret for signing-secret rotation.
• Event catalog — A 13-event catalog delivered as signed webhooks: job.created, job.succeeded, job.failed, job.canceled, job.progress, output.created, output.ready, output.failed, output.progress, video.uploaded, video.deleted, app.created, and app.updated. Endpoints subscribe to specific event types or *.
• Signed delivery & event log — Each delivery is signed so you can verify authenticity via signature headers. Browse and inspect the event log with ListEvents, RetrieveEvent, and ResendEvent.
• Delivery health & testing — GetEndpointHealth reports an endpoint’s recent delivery health, ListWebhookDeliveries lists individual delivery attempts, and SendTestWebhook sends a test event to validate your integration.

#2026-03-16

#Added

• Subtitles — Full subtitle processing support via subtitle_tracks on output specifications. Four operations: passthrough, convert, burn_in, and extract. Supports SRT, WebVTT, TTML, and ASS formats with configurable burn-in styling (font, color, outline, positioning). Source from embedded streams or external URLs.
• DRM & Encryption — Content protection for streaming outputs (HLS, DASH, adaptive) via the drm field on output specifications. Supports Widevine, FairPlay, and PlayReady with CENC and CBCS encryption schemes. Two key management modes: Bring Your Own Key (BYOK) and key server integration. Configurable clear lead for ad insertion.
• HDR processing — Per-variant HDR configuration via the hdr field on video variants. Supports HDR10, HDR10+, HLG, and Dolby Vision (profiles 5 and 8). Three processing modes: passthrough (preserve), tonemap (HDR to SDR conversion with Reinhard, Hable, BT.2390, or Mobius algorithms), and force (inject metadata). Compatible with H.265, VP9, and AV1 codecs.
• Content-aware encoding — Intelligent bitrate optimization via the content_aware field on output specifications. Two modes: per_title (optimizes bitrates for your existing ABR ladder to meet a VMAF target) and auto_abr (automatically generates the optimal ABR ladder based on content analysis). Default VMAF targets: economy 88, standard 93, premium 97.
• Thumbnails — Thumbnail generation via the thumbnails array on job creation (max 5 specs per job). Four extraction modes: single (poster frame), interval (periodic), sprite (sprite sheet with WebVTT for seek preview), and timestamps (specific moments). Supports JPEG, PNG, and WebP output.
• Feature-based pricing — Add-on features now carry cost multipliers: DRM (1.25x), HDR tone-mapping (1.50x), Dolby Vision (2.00x), per-title encoding (1.50x), auto ABR ladder (1.75x), and subtitle burn-in (1.10x). The feature_multiplier field in pricing snapshots reflects the combined multiplier. Multipliers stack multiplicatively, with two exceptions: Dolby Vision supersedes HDR tone-mapping (the higher 2.00x applies, not both), and per-title and auto ABR are mutually exclusive. Thumbnail generation carries no feature multiplier.
• Codec-specific options — Video variants now accept codec-specific configuration objects (h264, h265, vp9, av1) for fine-grained encoder control: presets, profiles, levels, CRF, bitrate modes, keyframe intervals, B-frames, reference frames, adaptive quantization, psychovisual optimization, tiling, film grain synthesis, and loop filters.

#2026-02-15

#Added

• Real-time job watching — JobService/Watch streams live updates as a job progresses through its lifecycle. Includes snapshot, progress, status_change, completed, and heartbeat event types.
• Execution timing — Jobs now include an execution field with detailed timing telemetry: boot, download, probe, encode, upload, and packaging durations, plus worker instance details and resource usage metrics.
• Chunk encoding telemetry — execution.chunk_count and execution.chunk_strategy fields report parallel encoding details when chunk encoding is used.

#2026-02-06

#Added

• Organization memberships — MembershipService for managing who belongs to an organization: List members, Get a single membership, UpdateRole to change a member’s role, and Remove a member. Roles are governed by the MembershipRole enum (owner, admin, member, viewer); the last remaining owner cannot be demoted or removed.

#2026-02-01

#Added

• Output path templates — 4-level template hierarchy for controlling where transcoded files are written: per-output, job-level, origin, and system default. Supports variables like {job_id}, {codec}, {resolution}, {date}.
• Collision auto-fix — Implicit path templates (origin or system default) that would produce duplicate paths are automatically fixed by appending /{output_id}.
• Custom manifest names — HLS and DASH outputs now support custom manifest file names via hls.manifest and dash.manifest fields.

#Improved

• Streaming outputs — HLS and DASH outputs now use a structured segments config with duration and gop_alignment fields, replacing the deprecated segment_duration field.

#2026-01-15

#Added

• Per-variant pricing — ABR outputs (HLS/DASH with multiple video variants) now include a variant_pricing array with per-variant cost breakdowns, status, and progress tracking.
• Delayed start — Jobs can be created with delayed_start: true to pause after input probing. The awaiting_confirmation status lets you review estimated costs before calling Confirm to proceed.
• Job confirmation — JobService/Confirm endpoint for starting delayed-start jobs after cost review.

#2026-01-10

#Added

• Adaptive output format — New adaptive output type that produces both HLS (master.m3u8) and DASH (manifest.mpd) manifests from shared CMAF segments.
• Multi-audio tracks — Streaming outputs (HLS, DASH, adaptive) now support multiple audio tracks with language codes and labels via the audio array.
• Video variants — Inline output specification using the video[] array for defining ABR ladders without presets.

#2026-01-05

#Added

• Origins — OriginService for managing storage locations (GCS, S3, HTTP) with credential validation, base paths, and path templates.
• Origin-based job input — Jobs can now reference an origin via input_origin_id and input_path instead of providing a direct input_url.
• Origin-based job output — output_origin_id specifies where transcoded files should be written.

#2025-12-20

#Added

• Preset duplication — PresetService/Duplicate clones any preset (system or custom) as a new custom preset with a new slug.
• Preset by slug — PresetService/GetBySlug looks up a preset using its slug identifier.
• Content types — Presets now support a content_type field for encoder tuning (film, animation, grain, gaming, sports, stillimage).

#2025-12-15

#Added

• Idempotency keys — CreateJobRequest now accepts an idempotency_key for safe retries. Duplicate requests with the same key return the existing job.
• Job metadata — Attach up to 20 custom key-value pairs to jobs via the metadata field.
• Cost estimation — Presets include estimated_cost_per_minute for pre-submission cost estimates.

#2025-12-01

#Added

• Initial API release — Core services: OrganizationService, AppService, APIKeyService, PresetService, JobService, HealthService.
• Multi-tenancy — Organization and App hierarchy with API key authentication.
• System presets — Built-in encoding presets for common configurations.
• Quality tiers — Economy (0.75x), Standard (1.0x), and Premium (2.0x) pricing tiers.
• Four video codecs — H.264, H.265, VP9, and AV1 support.
• Three audio codecs — AAC, Opus, and MP3 support.
• Cursor pagination — List endpoints support cursor-based and offset-based pagination via the shared limit/cursor/offset shape. (VideoService/ListVideos, added later with managed video hosting, is the exception — it paginates with page_size/page_token and has no offset.)
• Structured errors — Connect-RPC error codes with ErrorDetails and FieldViolation payloads.

#Subscribing to Changes

Stay informed about API changes:

• Changelog RSS feed — subscribe to this page for updates
• Status page — monitor API availability and incidents
• Release notes — detailed technical notes for each release

For questions about changes or migration assistance, contact admin@transcodely.com.