Changelog

2026-10

Verified trials and MV source availability

• New website accounts claim an available trial after email verification; credits are no longer issued merely by signing in. Trial-only task limits are listed in Rate limits. Existing accounts and purchased-credit behavior are unchanged.
• Omn V1 scene edits, recompositions and upgrades reject unavailable source media before charging. See Source media recovery.
• Default-engine selection preserves quoted engines and saved preflights, including older Vidu preflights. Implicit Omn selection uses a gradual account rollout that defaults to zero; explicit engine selections remain unchanged.

Account-wide monthly resource storage

Administrators can explicitly enable long-term storage for final files including Suno WAV and MV results. Original free periods and historical permanent rights remain unchanged. Usage across products is combined into monthly credit bills. Existing accounts remain disabled; no integration change is needed unless your account enrolls. Enrolled accounts can use the new asset and charge endpoints in the storage guide.

2026-10-01 — Omn V1 upgrade availability, price card and neutral output

• MVView.capabilities adds upgrade (available, reason, renderTiers) and editShotTypes on Omn V1 MVs rendered as shots; other MVs do not have them. upgrade.reason is not_shot_engine, subtitles, motion_transfer or highest_tier when the MV can never be upgraded (the upgrade endpoints return 422 MV_ENGINE_UNSUPPORTED), and mv_not_complete or operation_in_progress while it temporarily cannot (409 MV_PRECONDITION_FAILED with the same details.reason). Upgrade preflight remains authoritative. editShotTypes matches the details.availableShotTypes of a rejected edit; each edit is still checked for its scene. Edit and upgrade admission are unchanged.
• GET /api/v1/pricing/catalog adds the required mvOmnV1 price card: credits per output second by render tier and resolution, minimum billed seconds, the economy schedule (0.75 ×, 00:00–08:00 Beijing time, last shot start 07:40) and the shot-edit, upgrade and recomposition rules. The catalog’s updatedAt is now 2026-10-01 and its version changes; clients that validate the catalog strictly must accept the new section. Prices are unchanged.
• Omn V1 Task pricing.components[].label reads Omn V1 video, Omn V1 scene edit or Omn V1 render-tier upgrade, also for earlier Tasks; component key values are unchanged opaque codes. Itemized quote and preflight components identify the Omn V1 video as providerFamily: "omn", provider: "omnapi-native" and model: "omn-v1", replacing earlier identity values. Failure details that cannot be shown are replaced with a generic message, with an unchanged errorCode, and the earlier prompt-compilation warning is reported as MV_NATIVE_PROMPT_COMPILATION_FALLBACK. Match on key, errorCode and warning codes rather than labels or message text.
• This is a development contract preview; check deployment availability. See upgrade availability, the Omn V1 price card, Omn V1 price items, generic failure messages and warning codes.

2026-10-01 — Omn V1 render tiers, economy scheduling and upgrades

• Omn V1 (generation.engineVersion:"omn-v1") renders each MV as typed shots and adds the optional generation.renderTier (draft, standard, hd, ultra), generation.schedule (standard, economy) and, for OneClick V2 dance, generation.motionReferenceVideo with generation.motionRightsConfirmed: true. Other engines and Studio reject these fields with 400 VALIDATION_ERROR; resolution:"1440p" is Omn V1 only.
• New Omn V1 purchases use a render-tier price card in credits per output second: draft 540p 6; standard 540p 12, 720p 16; hd 1080p 20; ultra 720p 48, 1080p 58, 1440p 68, with no singing, performance or dance surcharge. economy starts shots only between 00:00 and 07:40 Beijing time at 0.75 × the video price, with a 48-hour delivery deadline. Purchased Tasks keep their price.
• Where capabilities list them, Omn V1 accepts OneClick V1 lip-sync (including 540p), characterImage, the four OneClick V2 performance modes, quality:"high", 1080p, 1440p and 4:3 or 3:4. A requested singing, performance or dance shot type that cannot be rendered, including for a text-only request, returns 422 MV_ENGINE_UNSUPPORTED before any charge instead of becoming a story shot. Motion reference problems return 400 VALIDATION_ERROR with details.field; motion transfer applies at 16:9 and 9:16, and other aspect ratios are planned as ordinary dance.
• POST /api/v1/mv/{mvId}/upgrade/preflight and POST /api/v1/mv/{mvId}/upgrade re-render a finished Omn V1 MV at a higher tier for the target tier price of the whole MV. The upgrade requires an Idempotency-Key. Unknown MVs return 404 MV_NOT_FOUND, ineligible MVs (including OneClick V2 MVs, shots too long for the target tier and scenes needing an unavailable extra-image rate) 422 MV_ENGINE_UNSUPPORTED, and busy or incomplete MVs 409 MV_PRECONDITION_FAILED, all before any charge. Failed or cancelled upgrades are refunded.
• Omn V1 scene edits accept shotType, also on its own, except bridge, and are priced per shot second at the MV’s tier price. Edits that cannot run with their reference images return 400 VALIDATION_ERROR with details.field before any charge. MVView adds generation.renderTier, schedule and scheduleWindow, plus shotType and renderTier on renderings; renderings from before an upgrade are no longer selectable. Active operations report progress, deliveryDeadlineAt and, for economy, estimatedStartAt.
• Capabilities add render tier, schedule, shot type, singing, singer-count, dance, motion and characterImage hints, and native.defaultEngine. When a deployment enables the default engine, a Fast request without engineVersion may run on Omn V1 at its price; set engineVersion explicitly to keep the existing engine. Existing engines, their prices and purchased Tasks are unchanged. This is a development contract preview; check deployment availability. See the Omn V1 engine guide and Omn V1 edits and upgrades.

2026-09

2026-09-30 — Omn V1 generation reliability

• A shot that fails while rendering is regenerated once at OmnAPI’s cost; content-review rejections are not.
• A Task whose shot outcome cannot be confirmed within 1 hour, or whose shot has not finished within 3 hours, now fails and is refunded instead of waiting for the delivery deadline.
• New pre-render Task failure codes: MV_NATIVE_SHOT_PROMPT_TOO_LONG, MV_NATIVE_REFERENCE_REJECTED, and the retryable MV_NATIVE_REFERENCE_REVIEW_UNAVAILABLE. All are refunded. Shot prompts no longer include verbatim lyrics. See Omn V1 during generation.

2026-09-30 — Omn V1 pilot contract

• Fast MV documents the Omn V1 pilot (generation.engineVersion:"omn-v1"): its price card, supported options and limits. It remains an explicit choice.
• Requests that Omn V1 can never run return 422 MV_ENGINE_UNSUPPORTED with a details.reason; temporary unavailability keeps 503 MV_PROVIDER_UNAVAILABLE with details.retryable. Both happen before any charge, and quote now rejects the same unsupported options.
• GET /api/v1/mv/capabilities adds native.selectableContractDetails with readiness, duration, resolution and aspect-ratio hints; the existing boolean selectableContracts fields are unchanged.
• Omn V1 creative drafts with an audio source default subtitles off and return MV_SUBTITLE_DISABLED_NO_TIMELINE. This is a development contract preview; check deployment availability. See Omn V1 generation.

2026-09-30 — MV song context and quality preview

• Audio MV sources and creative drafts accept optional song titles and music styles. Auto remains the default for visual style and performance.
• New Omn V1 preparation checks whether song context supports the chosen concept and whether reference images are suitable before video generation. Missing context or rejected references require an updated brief or reference.
• Workflow quality distinguishes inconclusive identity observations from confirmed sampled issues. It never automatically buys replacement scenes.
• These additions are a development contract preview; check deployment availability. See MV song context and review.

2026-09-24 — Producer recovery and Suno resource errors

• Producer delivery preserves accepted work during recovery within the original deadline. Stale source versions fail with CONFLICT; duplicate song references in batch exports are rejected before charging. See Producer recovery.
• Cover source permission failures, missing Suno clips, and rejected Voice verification audio now have specific non-retryable errors with corrective actions. Temporary Cover throttling remains retryable. See Suno recovery.

2026-09-23 — Producer delivery preview

• Added contracts for lyrics editing, complete four-stem delivery, trim, private M4A/ZIP exports, an authorized song library, and platform playlists/projects. Availability is controlled per operation; this preview does not announce general availability.
• New private exports have 30-day retention and download signatures up to five minutes. Their delivery policy requires a complete result before settlement.
• Library changes are local by default; shared-song title, privacy, or deletion requires explicit scope and management permission. Existing generation routes remain supported, and soundPrompt now accepts up to 3,000 characters.
• See Producer editing and exports for limits, resource permissions, idempotency, and recovery.

2026-09-19 — Audio editing and Suno export metadata

• Added POST /api/v1/audio/renders to crop, reorder, repeat, and fade segments from a public MP3/WAV file in one asynchronous task.
• Standard pricing is 5 credits per started requested output minute, with maxCredits and idempotent request recovery. Outputs are retained for 14 days; private download URLs last at most one hour.
• Availability follows the backend rollout. Unavailable creation returns 503 AUDIO_RENDER_UNAVAILABLE. See Audio Editing.
• Newly delivered Suno M4A, MP3, and WAV files omit the made with suno comment while preserving customer titles, artists, and artwork. Historical cached files may retain it until separately updated; a fresh URL does not change the file. See Suno exports.

2026-09-18 — Suno downloads and Legacy playback

• Suno download signatures now default to seven days, superseding the earlier 24-hour default, and remain bounded by asset retention. Existing URLs keep their original expiry; read the song, task, or asset for a fresh URL.
• Legacy managed audio and retained Twelve or named-stem deliveries support stable playback URLs with GET, HEAD, byte ranges, and urlExpiresAt. Existing playback links remain valid during the signing-key rotation grace period; customer access and retention checks still apply.
• Managed media permits read-only browser access from any origin. Existing permanent assets, 14/180-day retention, and MV URL lifetimes are unchanged. See Suno storage and Legacy Suno.

2026-09-18 — Documentation corrections and integration guides

• Producer inputs and result examples now describe Lyria 3.5 / 3 Pro and the completed MUSIC/TEXT resources used by applications.
• Retry guidance distinguishes rejected requests from tasks that were created before a timeout or error. Examples retain the original idempotency key.
• Added model compatibility, permissions, SDK setup, and Suno asset-storage guides. Storage enrollment depends on the live available response; a documentation update does not itself activate storage on an account.
• Product guides separate creation, playback, exports, editing, and recovery.

Earlier entries describe changes at their stated date. Use the current product guide for active defaults and limits; model compatibility is summarized in Models and defaults.

For current payment-review and recovery behavior, read Credits and Suno recovery.

2026-09-15 — Shared request allowances

• Request limits are shared across a customer’s API keys, with optional key sublimits. Task-status queries have a separate allowance from task creation and other operations.
• Paid tiers have no default daily or monthly hard cap. Existing customer-specific allowances may differ from defaults.
• Rate-limit documentation now covers the current IP protection, result-waiting admission exception, and destination webhook capacity. See Rate Limits and Webhook Events.

2026-09-03 — Play Suno songs while generating

• Generation queries now document clips[].playback, including temporary live URLs and completed audio URLs. audioUrl may remain null during live playback.
• Use playback.url directly in a browser or audio player without an API key on the media request. No SSE subscription or playback-session request is required.
• Playback guidance covers expiry, retry behavior, and transition to completed audio. Quickstart, API Reference, SDK examples, and Postman follow the same contract.

2026-08

2026-08-30 — Managed M4A and MP3 export

• POST /api/v1/suno/clips/{clipId}/export now documents the complete m4a, mp3, wav, and stems request union.
• Explicit M4A export costs 1 standard credit. MP3 export costs 2 standard credits and returns a managed playable resource derived from M4A delivery.
• The TypeScript SDK, Python SDK guidance, Postman collection, quickstart, and credit table now cover the same export lifecycle and Task polling contract.

2026-08-09 — Suno Vox model admission fixed

• POST /api/v1/suno/songs with mode: "vox" now accepts only chirp-crow (v5) or chirp-fenix (v5.5). Fenix remains the default.
• Turbo, V4, AUK, and Bluejay Vox combinations now return FEATURE_NOT_SUPPORTED before task creation, credit deduction, queueing, or retries instead of becoming refundable asynchronous failures.
• The legacy generate facade now defaults Vox to Fenix and applies the same exact allowlist when callers opt into a requested model.

2026-08-09 — Suno lyrics continuity and atomic paired delivery

• Existing POST /api/v1/suno/lyrics request fields, Task polling, billing, idempotency, A/B ordering, and legacy POST /api/legacy/generate/lyric response shape remain unchanged.
• Paired lyrics requests publish only when both ordered candidates contain complete lyrics.
• Completed lyrics may include a full stylePrompt and compatibility tags: [stylePrompt]. This style expansion is best-effort; its failure does not fail or erase completed lyrics.

2026-08-08 — Complete Vidu Direct catalog and pricing

• The Vidu guide now lists all 27 allowlisted operations, required and optional input fields, fixed service routes, and the quote/create/poll/cancel lifecycle.
• Complete Q3, Q2, Q1, Vidu 2.0, image, audio, speech, motion, utility, extension, film, advertising, and trending price matrices show both Vidu and OmnAPI credit quantities.
• Vidu Direct remains fixed at 2 OmnAPI credits per Vidu credit. The 1.75 rate remains exclusive to the separate MV OneClick component allowlist.

2026-08-08 — Public integration contract completeness

• Suno song and derive schemas now publish the exact six accepted generation models, and the guide maps each identifier to its generation family, price, default behavior, and public Voice compatibility.
• The API Reference now publishes all 98 exact stemName values, middleware headers such as Idempotency-Key and Prefer, production server metadata, streaming response media types, and successful pricing/usage schemas.
• Generic Task creation now exposes model-discriminated inputParameters schemas instead of an untyped object. Vidu and Subtitle model paths remain on their dedicated public workflows.
• Fast MV availability documentation now reflects the current gateEnabled: true contract, and authentication errors match the emitted INVALID_API_KEY / FORBIDDEN codes.

2026-08-08 — Native Extract catalog and Suno pricing update

• Named Extract now accepts all 98 native Suno instrument names. This operation uses Suno’s own separator and is not implemented through another AI service.
• Twelve results are documented as 12 stem groups with two separator candidates each. The Suno UI may display only eight detected rows, labels FX as Other, and uses selectors 1/2 for those candidates.
• chirp-auk-turbo generation now costs 25 standard credits. Other published models remain 28, and suno/chirp-v3-5 is retired for new requests.
• Timeline reads cost 0 only for customers on the legacy Suno 55,000 plan. All other standard and customer-specific pricing remains unchanged.

2026-08-08 — WAV delivery recovery

• WAV delivery recovery improved without changing the request body or adding a second customer charge. See the current export guide for delivery and retention rules.

2026-08-07 — Managed WAV delivery

• WAV requests use { "format": "wav" } and authorize 3 standard credits before customer pricing. Customers do not select a delivery strategy.

2026-08-07 — Complete Suno clip metadata and stable Task polling

• Owned and shared Suno Clip reads now return available public style tags; shared clips continue to redact the generation prompt, and external clips retain the minimal-media projection.
• Clip detail, batch reads, and Generation history now return tags and duration consistently as propagated metadata is repaired, including historical clips.
• Timeline, audio analysis, style recommendation, and Voice read Tasks now keep the same typed outputResults when a direct call returns 202 and the client switches to Task polling, SSE, or webhooks.
• The Lyrics candidates OpenAPI contract now accepts only the integer values 1 and 2; generated SDKs no longer model string values or a default 0.

2026-08-05 — Clip-derived Voices and account credit balance

• POST /api/v1/suno/voices/from-clip creates a reusable public Voice from a completed clip owned by the caller. The minimum request contains only clipId; no verification phrase or real-person recordings are required.
• Clip-derived Voice creation costs 5 credits, supports idempotent retries, confirms that the resulting Voice is public, and includes it in the caller’s existing Voice list.
• GET /api/v1/account/credits returns the exact current OmnAPI balance, account tier, billing status, and balance update time for low-balance monitoring. Restricted API keys require usage:read.

2026-08-04 — Explicit Suno clip models and one Legacy prefix

• Modern Suno Clip responses now distinguish the OmnAPI modelCode, the exact clip providerModelName, and its exact majorModelVersion. The existing model field remains a compatibility label.
• Legacy Music response mv now strictly mirrors the clip’s major model version, matching Suno Cloud; it no longer falls back to the request model.
• /api/legacy/* is now the only Suno Cloud compatibility prefix. /v1/suno-legacy/* and root /v1/* paths return 404.
• Native and managed-fallback WAV export both authorize and settle at 3 standard credits.

2026-07

2026-07-30 — Legacy Suno path aligned with the OmnAPI API namespace

• The ten Suno Cloud compatibility operations moved from /v1/suno-legacy/* to /api/legacy/*.
• /v1/suno-legacy/* remains a deprecated path alias during migration. Root /v1/* routes are not mounted. Request and response bodies, authentication headers, scopes, and deprecation headers are unchanged.

2026-07-30 — Modern Suno migration completeness

• Existing clips can now use public action: "extend" and action: "cover" through /api/v1/suno/clips/{clipId}/derive.
• Extend includes automatic Concat as one task and one charge. There is no standalone public Concat endpoint.
• WAV is public through /api/v1/suno/clips/{clipId}/export and uses managed managed delivery without an additional customer charge.
• Song and derive receipts expose a stable generationId, normally wait briefly for provider clipIds, and never advertise a Suno /stream route.
• GET /api/v1/suno/generations/{generationId} exposes each candidate’s submitted, queued, streaming, complete, or error state while work is still running.
• Direct clip detail and ?clipIds= batch reads create no Task and preserve partial results with missingClipIds and typed errors.
• Legacy customer Suno pricing rules now apply to every paid Suno operation, including actual-cost settlement paths.
• Legacy model selection defaults to chirp-auk-turbo unless use_requested_model: true; songs pagination applies skip; timeline responses include aligned_lyrics.

2026-07-29 — Unified Suno pricing and public surface

• Simple, custom, Voice, Upload + Extend, and Upload + Cover song generation cost 28 credits across the published model choices.
• Creating a reusable public Voice from verified recordings costs 66 credits.
• Twelve-stem export costs 140 credits and named Extract costs 56 credits. Managed storage and delivery recovery do not add a second customer charge.
• Lyrics and Lyrics Pair cost 0 credits; a lyrics timeline read costs 1 credit.
• Standalone Upload, source-bound editing, WAV/Opus/video export, visualizer, remaster, and other account-limited operations are not part of the modern public Suno API.
• Public tasks, webhooks, OpenAPI, SDKs, Postman, Apps, and documentation expose only customer-facing inputs, outputs, states, and errors. Admin task detail and workflow diagnostics retain the complete operational record.

2026-07-28 — Suno Voice naming

• The modern public feature is now named Voice throughout the API, SDKs, OpenAPI, Postman collection, pricing catalog, and guides.
• Voice management uses GET|POST /api/v1/suno/voices, GET /api/v1/suno/voices/verification-phrase, and GET /api/v1/suno/voices/{voiceId}.
• Song generation now uses voiceId as the canonical field and continues to accept personaId as a deprecated request alias. The deprecated /personas routes remain documented and callable for compatibility.
• The legacy Suno Cloud compatibility request keeps its exact persona_id field so existing /v1/suno-legacy/generate clients remain wire-compatible.

2026-07-28 — Verified public Suno Voices

• A new recording-based Voice flow first obtains a language-specific verification phrase, then submits the returned task ID with a clean vocal recording and a recording of the phrase.
• Recording-based Voices are public by default and cost 66 credits. There is no separate operation for publishing an existing private Voice.
• If a verification session expires before creation starts, request a new phrase and retry.
• Voice lists return only Voices created by the current OmnAPI user. Voice details and song creation can use a known public Voice ID without an OmnAPI account-ownership restriction.
• mode: "vox" requires only the public voiceId; source resolution remains entirely server-managed.

2026-07-28 — Suno Stems delivery consistency

• Completed Twelve and named Extract tasks return only after every required stem URL is deliverable.
• Idempotency-Key remains the mechanism for retrying one business request without a second charge.

2026-07-27 — Suno Stems contract follows current modes

• Removed stemsMode=two / stem_task=two from all new modern and legacy task creation. Existing historical Two tasks remain queryable and can finish.
• Legacy /v1/suno-legacy/stems now defaults to Twelve and accepts explicit stem_task=twelve or stem_task=extract.
• Named Extract currently accepts only Koto and Lead Vocal. Twelve costs 140 credits and Extract costs 56. Managed storage or delivery recovery does not change those public prices.

2026-07-27 — Resilient legacy Suno WAV delivery

• POST /v1/suno-legacy/generate-wav keeps its { "mid" } request and { "url" } success shape while OmnAPI manages delivery internally.
• WAV export is retained only for existing compatibility clients and is not exposed by the modern public Suno API.

2026-07-24 — Fast MV scene image replacement

• Fast MV scene edits now accept a new prompt, one to seven replacement reference images, or both through POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/render.
• Fast create, preflight, and quote flows now accept effective source durations from 10 to 600 seconds. Studio remains limited to 10 to 300 seconds.
• Omitting referenceImages preserves the scene’s current source images. A non-empty list replaces them for the new rendering; an empty list is rejected.
• MVView.capabilities now advertises prompt and image scene-edit support, and rendering history records expose the prompt and reference images used for each version.
• The MV app, TypeScript and Python SDK examples, Postman collection, and Fast MV guides now expose the image replacement workflow.

2026-07-23 — Suno Cloud compatibility routes namespaced

• The ten Suno Cloud compatibility operations moved from root-level /v1/* paths to /v1/suno-legacy/*.
• Root-level /v1/* aliases are no longer mounted. Existing clients must add /suno-legacy after /v1; request and response bodies are unchanged.
• The compatibility migration guide now documents the supported upload route alongside generation, lookup, timeline, account, stems, and WAV operations.

2026-07-20 — Suno model-tier pricing (superseded)

• This model-tier price split was replaced by the unified 28-credit price on 2026-07-29.
• Stems, upload, WAV, concat, editor, read, and Infill prices are unchanged.
• The legacy /v1/* compatibility surface temporarily normalizes all accepted model values to the standard lane. Modern API defaults remain unchanged.
• Existing and in-flight tasks keep their immutable create-time price; no historical task is repriced.

2026-07-18 — Fast MV creative planning and subtitle layout

• Fast automatic Visual Boards now generate a mixed reference pack with deterministic character, world/style, motif, and climax roles. Existing duration-based reference counts and Fast prices are unchanged.
• Synthesized Fast references preserve character identity without implicitly locking one outfit, and environmental roles may omit the character. Explicit user wardrobe requirements still take precedence.
• Omitting generation.motionPreset now lets OmnAPI select dynamic dance motion from clear dance/high-energy direction, while explicit presets keep their existing behavior.
• Fast custom subtitles now limit each event to two lines and split oversized cues across their existing timing range. The public request schema is unchanged.

2026-07-16 — Durable task execution and confirmed cancellation

• Suno polling now follows the observed submitted / queued / streaming cadence and preserves late Provider success for up to 48 hours instead of expiring accepted jobs prematurely.
• Interrupted creation requests are reconciled before retrying to reduce the risk of duplicate songs or charges.
• Task creation keeps idempotency, pricing, and credit deduction consistent.
• Cancellation now requires evidence: pre-submit jobs are cancelled and refunded atomically; post-submit jobs are cancelled only after explicit Provider confirmation. Submitted Suno, Producer, and MV tasks therefore return 409 and continue synchronization when remote cancellation cannot be confirmed. This supersedes the earlier local-only cancellation behavior.
• Task recovery and music-video status updates are more reliable during sustained Suno, Producer, and MV usage.

This page lists notable changes to the public API surface documented here.

2026-07-15 — Task list and Suno availability contract hardened

• GET /api/v1/tasks now returns the same customer-safe final pricing summary used by task details and no longer exposes internal pricing-policy or provider configuration fields.
• Suno availability now publishes customer-safe service, processing, capacity, advanced-operation, and delivery checks.
• Signed task-resource links now report an expiry no later than the backing asset’s retention deadline.

2026-07-14 — Suno commercial contract completed (superseded)

• The original model-tier pricing was later replaced by the unified 28-credit price.
• Added Vox generation modes, infill and editor derive actions, Opus and named stem export, audio analysis, and advisory availability to the documented API.
• Public task results now expose safe normalized resources, retryable, refunded, and Suno warning codes without provider-account identity fields.
• Official TypeScript/Python helpers and Postman examples now send idempotency keys on Suno and Producer writes.

2026-07-12 — MV query efficiency, delivery estimates, and SDK workflow

• GET /api/v1/mv/{mvId} now accepts the additive historyLimit=1..50 query parameter. It returns that many recent entries per scene, plus selected entries and the latest playable Fast fallback when needed. Omitting it preserves the original complete-history response.
• MV create may now return a estimatedCompletionTime. The field remains nullable and is an estimate rather than a delivery guarantee.
• Official TypeScript and Python SDK source now includes a create → Task poll → MV read → Fast final refresh helper. Existing individual methods remain unchanged.

2026-07-11 — MV asset durability and URL lifecycle

• Fast create now copies successful initial scene videos into OmnAPI-owned storage instead of relying on short-lived provider URLs. A scene that could not be secured carries a durability warning; historical successful provider jobs remain selectable for backward compatibility.
• Customer-facing MV Task resources, MVView, and final-video reads now share the same signed-URL policy, with a 60-minute default. Optional additive assetId, urlExpiresAt, retainedUntil, and assetStatus fields distinguish stable identity, link expiry, and storage retention; historical responses may omit them.
• Successful Fast recompose now resets the final asset’s retention window consistently with Studio finalize. Scene videos used by a successful finalize/recompose are retained at least as long as that final. Standard MV output retention remains 30 days by default; reading or refreshing a URL does not extend it.
• Known MV create fields placed incorrectly under source are now rejected before task creation and charging. This does not change any previously documented request shape.

2026-07-11 — MV preflight spend authorization clarified

• A reusable MV preflightId now treats maxCredits as create-time commercial authorization rather than part of the validated media/generation fingerprint. Clients may add or lower maxCredits on POST /api/v1/mv after preflight; the API enforces it before task creation and charging.
• Existing clients that send the same maxCredits on preflight and create, or omit it entirely, remain compatible. Media, source, and generation fields must still match the validated request.

2026-07-10 — MV commercial operation and Studio workflow update

Existing integrations should review the MV July 2026 migration notes for response enum additions, operator-controlled Fast availability gating, signed media URLs, stable mvId semantics, and the historical operation-ledger cutover.

• MV create now returns a stable non-null mvId immediately; newly created resources use the create taskId as their canonical MV id.
• MV quotes now return a short-lived quoteId, operation identity, expiry, and pricing version. Paid writes accept quoteId plus maxCredits, and quote consumption, task creation, and direct debit are atomic.
• Added GET /api/v1/mv/{mvId}/operations and MVView.costSummary for authorized, charged, refunded, and net project credits.
• Added MV-scoped cancellation with a full eligible direct-debit refund and an explicit continuation-risk disclosure when remote cancellation is unavailable.
• Added persistent Studio scene editing and one-task batch rendering for 1-30 current scene versions. A partially successful render batch keeps successful outputs, charges only successful scene components, and atomically refunds failed components; partial storyboard image failure now returns ACTION_REQUIRED when usable work remains.
• Added a lock-character quote step so every public paid Studio mutation can be confirmed against a short-lived spend ceiling.
• Final delivery now validates audio/video presence, expected duration, purchased resolution tier, and viable frame rate before making the asset available.
• Fast availability now reports additive gateEnabled, which defaults to false; unknown and unavailable block paid creates before charging only when the operator enables the gate, while quote and preflight remain usable.
• Customer media links are now always short-lived signed URLs. Added idempotent MV deletion with known-asset cleanup while retaining financial records required for reconciliation.
• Terminal MV operation Tasks are compacted after the configured retention window: financial settlement evidence remains while request, provider, result, step, and webhook payloads are removed. This does not change the existing MV API contract.
• Expanded the MV guide to cover the existing cursor-paginated list endpoint and clarified that cancellation refunds eligible direct-debit charges; no API behavior changed.

2026-07-09 — MV Fast delivery diagnostics

• Added GET /api/v1/mv/fast/availability so clients can check Fast MV delivery health before production batches.
• Added MVView.billing, failureCategory, retryable, refundable, and customerAction fields for customer-visible settlement and failure diagnostics.
• Added MV_FAST_PROVIDER_DEGRADED warning and MV_PROVIDER_UNAVAILABLE error. The latter is returned before charging when the operator-controlled gate is enabled for unknown / unavailable health.
• Clarified Fast commercial boundaries: technical task failures are automatically refunded; subjective output-quality issues are not automatic refunds.

2026-07-05 — Lyrics / Subtitle Sync API and MV auto subtitles

• Added the public Lyrics / Subtitle Sync API: POST /api/v1/subtitles/quote, POST /api/v1/subtitles, and GET /api/v1/subtitles/{taskId}.
• source.durationSec on Subtitle Sync is optional; OmnAPI probes public audio duration before quote/create when the hint is omitted.
• MV Fast and Studio can now generate subtitle timing automatically for audio sources when subtitles=true and srtUrl is absent. Use subtitle.mode="provided" to keep caller-supplied timing as a strict requirement.
• Added subtitle cost controls through budget.maxCostUsdPerMin on Subtitle Sync and subtitle.maxCostUsdPerMin on MV auto subtitles.
• Added MV auto-subtitle warnings: MV_AUTO_SUBTITLE_GENERATED, MV_AUTO_SUBTITLE_LOW_CONFIDENCE, and MV_AUTO_SUBTITLE_FALLBACK_SKIPPED.

2026-07-05 — MV Fast reference strategy clarified

• Added Fast generation.referenceStrategy with direct and synthesize.
• Fast requests that include referenceImages now use those caller references by default, even when characterImage is also supplied.
• Use generation.referenceStrategy="synthesize" when you want OmnAPI to generate unified Visual Board scene references from characterImage and caller references before managed generation.

2026-07-02 — MV Fast scene version selection

• Fast MVs now support PATCH /api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering. Pass a MVView.scenes[].renderingHistory[] entry where isSelectable=true to choose which scene version should be used by the next recomposition.
• Fast MVView.scenes[].videoUrl and renderingHistory[].isSelected now represent the selected playable scene version. Projects without explicit selections continue to fall back to the newest successful scene job.
• Fast finalization now composes the selected scene composition and stores a canonical composition snapshot for idempotency and stale-final detection.

2026-07-01 — MV Fast scene edit and recompose pricing

• Added Fast quote steps for post-create work: POST /api/v1/mv/quote with step: "scene-edit" quotes a saved Fast scene edit, and step: "compose" quotes final recomposition.
• Fast scene-edit pricing now reads duration and resolution from saved Fast scene metadata. Public callers only send prompt on the edit request; durationSec and resolution are not public edit parameters.
• MVView.scenes[].sourceJob now exposes the latest Fast edit/render attempt separately from the playable scene output. Existing scene.videoUrl and status continue to represent the latest successful playable scene.
• Fast capabilities include finalizeAction so clients can distinguish finalize, recompose, and retry_finalize UI actions without re-deriving stale-final rules.

2026-06

2026-06-30 — MV Fast public contract vNext

• MV finalization contract now separates read vs write semantics: GET /api/v1/mv/{mvId}/final only refreshes a current final URL and returns sourceVersion, finalizedVersion, finalizationRequired, staleReason, retryable, pollAfterSec, and actionHint; POST /api/v1/mv/{mvId}/finalize is the write path for recovery or recompose.
• MVView.finalMv and top-level MVView now expose isCurrent / source-version freshness fields. Fast explicit finalize is intended for recovery or recompose after managed-scene edits; Fast create still auto-finalizes.
• Fast scene render/edit and explicit finalize accept omitted expectedVersion for backward compatibility; new clients should still send the latest MVView.version. Studio write controls continue to require expectedVersion.
• Fast lip-sync now uses top-level characterImage as the only public identity and lip-sync anchor. OmnAPI validates it and uses it for the managed lip-sync workflow.
• Retired earlier Fast inputs that bypassed the current characterImage and nested Visual Board controls.
• Public Suno sources now accept clipId plus optional range and lyrics only. Use source.type="audio" for caller-hosted public audio URLs.
• Fast create auto-finalizes through the managed workflow. Use GET /api/v1/mv/{mvId}/final to refresh the temporary final MP4 URL.

2026-06-26 — MV generation fields made mode-aware

• Added Fast generation.subtitleMode for managed and OmnAPI-rendered subtitle modes.
• Added Fast generation.visualBoard.imageProvider for choosing the image provider used when OmnAPI generates Visual Board references.
• This field later became the only public Fast image-provider control; see the 2026-06-30 vNext entry.
• Clarified that /api/v1/mv/quote stays lightweight and flat: Fast quote visualBoardImageProvider maps to create/preflight generation.visualBoard.imageProvider.
• Clarified that /api/v1/mv/preflight uses the create body without declaring preflightId; preflightId is only added to the paid create request.

2026-06-26 — MV Fast quality and lip reference controls

• Added Fast generation.quality with standard and high tiers. High quality is available at 720p and 1080p; explicit 540p is rejected.
• Lip-sync reference handling was later consolidated around characterImage; see the 2026-06-30 vNext entry.
• Documented Fast lip-sync guardrails: lip-sync requires 720p or 1080p and is limited to effective sources of 180 seconds or less.
• Added quality to Fast MV quote helpers so callers can preview high-quality pricing before create.

2026-06-26 — MV Fast character reference priority

• Fast characterImage now has priority in Visual Board identity planning when callers also send referenceImages: OmnAPI keeps at most six additional secondary references.
• Added MV_REFERENCE_IMAGES_TRUNCATED_FOR_CHARACTER for Fast requests where extra secondary references were omitted to keep the managed reference plan within the 7-image limit.
• Clarified how caller-supplied character and scene references affect Visual Board reference-image pricing.

2026-06-25 — MV Fast reference handling clarified

• Aligned public MV duration limits to the shared 10-300s range for Fast create, preflight, and quote flows.
• Clarified that Fast characterImage is not sent as a separate lip reference. When callers omit referenceImages, OmnAPI may use characterImage as a Visual Board reference for image providers that support reference inputs.
• Added MV_CHARACTER_IMAGE_REFERENCE_IGNORED for Fast requests where characterImage was supplied but the effective Visual Board image provider did not use reference-image inputs.
• Added visualBoardReferenceImageCount to MV quote docs and SDK helpers so gpt-image-2 reference-image input cost can be estimated before create.

2026-06-24 — MV pricing receipts aligned

• Clarified that Studio MV remains public beta under /api/v1/mv/*, including scene render, scene image regeneration, rendering selection, character lock, and selected-scene finalization.
• Aligned MV quote, preflight, create, SDK, and quickstart examples with the current task receipt shape and delivery fields.
• Documented MV quote and preflight pricing as credits plus a customer-facing breakdown; breakdown.duration is billable seconds rather than a credit amount.

2026-06-18 — Studio Beta public MV API

• Promoted Studio MV Beta into the public /api/v1/mv contract while keeping models and templates outside the public contract.
• Added public Studio scene render, scene image regenerate, rendering selection, character lock, and selected-scene finalize endpoints.
• Hardened Studio writes with required expectedVersion checks and conflict refresh handling for render/regenerate/select/finalize control flow.
• Improved Studio media handling for bounded, timed public URL inputs and durable generated video outputs.

2026-06-17 — MV Fast finalization and asset limits clarified

• Hardened Fast MV finalization against duplicate completion races: while final MP4 delivery is settling, tasks may report externalStatus="finalizing" and continue polling instead of starting duplicate finalization.
• Failed MV generation states are now handled consistently, even when partial generation metadata is present.
• Documented Producer compose → MV Fast handoff through source.type="audio" and clarified that audio lyrics are visual context, not timed subtitles.
• Clarified Producer compose vocal behavior: when instrumental=false and no lyrics are supplied, OmnAPI auto-generates lyrics before compose instead of submitting an empty-lyrics song.
• Added MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED for Fast audio requests that enable subtitles without a caller-supplied srtUrl.
• Updated MV asset limits in the public docs: caller-hosted audio up to 128MB, reference/character images up to 12MB, SRT up to 4MB, and final video ingest up to 1GB.
• Clarified the then-current MV URL refresh behavior. As of 2026-07-10, all customer-facing MV asset URLs are short-lived signed URLs.

2026-06-16 — MV public API is URL-only for API callers

• Removed source.type: "audio-upload" from the public MV create and preflight contract. API callers should store audio in their own publicly reachable environment and pass source.audioUrl.
• Clarified that dashboard upload tools are outside the public MV API contract; API callers should pass public HTTPS URLs.
• Public Fast MV source variants are now suno and audio only. Both continue to support source.range.startSec / source.range.endSec.
• External source.type: "audio" URLs are now validated server-side. durationSec is an optional consistency hint instead of the authoritative duration.
• Added public MV audio guardrail errors for unavailable duration, download failures/timeouts, and oversized remote audio sources.
• Added coverage for Fast MV quote, create, Visual Board, generation, polling, and final storage flows.

2026-06-15 — MV public API narrowed to Fast

• Added MV audio range fields (source.range.startSec / source.range.endSec) to the public docs for Suno and audio URL sources.
• Public MV create/quote/preflight/finalize were documented as Fast-only finished-MV flows at that time.
• Removed public documentation and OpenAPI exposure for Studio models, templates, scene render/regenerate/select controls, character lock, and Studio quote variants.
• Kept Studio storyboard and per-scene controls outside the public API at that time.
• Removed the public generation.autoVisualBoard knob. No-reference Fast MV requests now use automatic Visual Board references by default for Suno and audio URL sources.
• Visual Board quote add-ons use visualBoardImageCount with visualBoardStrategy: "direct_scene_images"; responses expose breakdown.visualBoard.
• Refreshed MV pricing, duration, warning, and error wording to match the current Fast public range.

2026-06-11 — MV preflight added

• Added POST /api/v1/mv/preflight for create-time resource validation and reusable credit quotes without creating a task or charging credits.
• Documented preflightId on POST /api/v1/mv and the recommendation to send Idempotency-Key for paid create requests.
• Clarified that POST /api/v1/mv/quote is a fast estimate and does not validate remote resources.
• Suno MV requests with empty referenceImages now default to OmnAPI-generated MV board references. Fast and Studio both consume standardized board-derived references.

2026-06-08 — MV docs simplified

• Clarified that MV generation is an optional, mode-specific override object.
• Removed storyboard draft mode from the public MV documentation; Studio storyboard is documented as the full 250-credit flow.
• Fixed the MV guide’s #mode-configs anchor.
• Added GPT Image 2 as a selectable Studio scene-image model.
• Fast MV no longer uses Suno clip artwork as an automatic reference image.

2026-06-07 — Field naming unified (breaking)

A one-time consistency pass across public task and MV responses.

• Task id → taskId. Every task response — create, sync, GET /api/v1/tasks/{taskId}, the task list, and webhook payloads — now returns taskId instead of id. Path placeholders are documented as {taskId} throughout.
• creditsReserved → creditsRequired. The up-front task charge field is now creditsRequired on every create/sync response; creditsCharged (the final billed amount) is unchanged.
• MV id → mvId. MVView returns mvId as the canonical resource id. Create responses return a task receipt; poll the task and then read the MV with the resolved mvId. GET /api/v1/mv/{mvId}/final keeps id for the final-asset row id (distinct from mvId).

2026-06-01 — Credit pricing aligned

• Rebased public credit examples on the current top-up packages and the legacy Suno Cloud benchmark.
• Updated Suno Direct pricing: paid song/derive workflows are 28 credits, Suno-free reads and lyrics are free, and storage/export operations use small fixed charges.
• Updated Producer pricing examples to 8 credits for image, 1 for lyrics, and 28 for compose/modify.
• Updated MV pricing examples: Studio storyboard is 250 credits, scene-image regenerate is 15, finalize is 50, and Fast MV quotes use dynamic duration-based pricing.

2026-05

2026-05-31 — Unified MV surface documented

• Added the unified /api/v1/mv contract for Fast and Studio music-video generation.
• Added /api/v1/mv/quote, /api/v1/mv/{mvId}, per-scene render/edit endpoints, and finalize flow.
• Documented shared source variants, MVView, capability flags, subtitles, warnings, and webhook events.

2026-05-25 — Suno direct surface and migration routes documented

• Added the consolidated Suno API surface under /api/v1/suno/*.
• Public docs now cover song generation, derive, export, lyrics, clip reads, uploads and Voices.
• OpenAPI now includes Suno public paths.
• Reintroduced Suno Cloud /v1/* migration routes for existing clients while keeping them out of the public OpenAPI, SDK, and Postman surfaces.

2026-05-24 — Launch surface trimmed to Producer + Get Task

• Public surface narrowed to: POST /api/v1/producer/generate/{image,lyrics,music/compose,music/modify} and GET /api/v1/tasks/{taskId}.

2026-05-23 — Legacy /v1 sunocloud compat removed from public spec

• /v1/{generate,lyric,feed,songs} was removed from the launch public spec.
• Modern /api/v1/producer/* covered the initial launch use case before the Suno migration surface returned as hidden compatibility support.

2026-05 — Public OpenAPI spec + interactive playground

• /openapi.json published (filtered to user-facing routes only)
• Documentation moved to docs.omnapi.com
• Interactive playground at /api-reference/ — bring your own key, requests go straight to api.omnapi.com