#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-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.