Skip to content

    API documentation

    Changelog

    Historical reference

    Entries record changes at their stated dates. Later entries can supersede older request formats and prices; use the current API reference, catalog and preflight for new purchases.

    Read current API rules before implementation. Historical entries describe behavior at their date, not current prices or availability. Expand a month or search by date, product or action.

    Omn video edits, progress detail and quality grades are released on /api/v2/mv.

    • New endpoints edit a finished Omn video as a new video with its own id, charge, file and refund; the original is unchanged. POST /api/v2/mv/videos/{id}/edits/quote (free) and POST /api/v2/mv/videos/{id}/edits (paid, Idempotency-Key) buy a regenerate (shots from an instruction or attribute changes, with 1–4 candidates) or a recut (a new timeline or the lyric layer on or off). GET /api/v2/mv/videos/{id}/candidates, GET …/candidates/{fileId} and POST …/adopt let you pick candidates for free; GET …/timeline returns the editable cut in 24 fps frames. See Edit an Omn video.
    • Edit prices: regenerate = resolution rate × seconds the regenerated shots are on screen (rounded up, at least 1) × candidates; recut = resolution rate × 10. A failed or cancelled edit is refunded in full. GET /api/v1/pricing/catalog publishes these rules and candidate limits under mvOmnV1.centerEdit; the edit quote remains authoritative for a concrete request.
    • New codes, all returned before any charge: MV_CENTER_EDIT_REFUSED, MV_CENTER_EDIT_IN_PROGRESS and MV_CENTER_EDIT_NOT_PENDING (409), and MV_CENTER_EDIT_UNSUPPORTED (422) for videos bought before November 14, 2026.
    • The video resource adds optional stage, eta, waiting, quality (grade A, B or C with issues[]), parentId, edit and candidates. GET /api/v2/mv/capabilities reports operations.revisions: true. Clients that reject unknown fields must accept them.
    • On /api/v1/mv, a prompt-only scene edit of an Omn MV buys a new video; select rendering and scene edits with referenceImages or shotType return 422 MV_CENTER_EDIT_UNSUPPORTED, and finalize of a delivered Omn MV returns the existing final for free. See Omn on API v1.
    • OmnAPI can buy a share of /api/v1/mv requests that omit generation.engineVersion as Omn, priced and delivered as Omn, falling back to OneClick before any charge when Omn cannot take them. Send generation.engineVersion: "vidu-v1" to always buy OneClick.
    • Omn captions can be added as part of generation. In that mode a video whose required captions (captions.required, the default) cannot be delivered fails with MV_SUBTITLE_RENDER_FAILED and is refunded in full; partly shown lyrics are delivered with MV_SUBTITLE_TEXT_REVIEW_REQUIRED.

    Omn API v2 integration updates shipped in app-v2026.11.15.99.

    • A video’s id is now always its taskId and never changes; earlier, reads after generation started could return a different id (both ids keep working).
    • Webhooks and GET /api/v1/tasks/{taskId} for videos bought on /api/v2/mv link to /api/v2/mv/videos/{id} and /file; mv.ready / mv.failed add videoId. The Task view’s qualityReviewUrl is null for these videos.
    • GET /api/v2/mv/capabilities adds availableResolutions: 1080p and 1440p are listed only while they can be bought.
    • GET /api/v2/mv/videos/{id}/events sends video events whose data is the video resource.
    • GET /api/v2/mv/videos/{id}/file adds resolution and retainedUntil.
    • Cancelling needs the task:cancel scope; deleting a video that is still being made returns 409 (video_in_progress), and deleting a video cancelled before generation started succeeds with assetsDeleted: 0 instead of 404.
    • Quote errors carry details.reason: quote_expired (400) and quote_already_used (409). Error messages name /api/v2/mv fields and paths.
    • TypeScript and Python SDKs 0.7.1 add these fields, typed charges and delete results, and streamOmnVideo / stream_omn_video.
    • The OpenAPI reference lists application/json for JSON request bodies. Use that content type if an older generated client offers a form encoding for the same request.

    Omn adds output.resolution: "1080p" and "1440p" (2K), AI-upscaled from 768p. Whole-order prices are 20 and 48 credits per effective second. Failure to deliver the purchased HD tier returns MV_CENTER_HD_FAILED and refunds the entire charge; it never substitutes a base-resolution file. SDK 0.7.0, Postman and the MV guides describe the same quote, delivery and refund flow.

    • Omn now delivers native 480p (9 credits/s) or 768p (12 credits/s) videos in 11 aspect ratios, without upscaling. Non-singing auto, story and mood videos need no reference images; sing needs one performer image.
    • /api/v2/mv is a resource API: GET /capabilities, POST /quotes, POST /videos (a quoteId, or a spec in one step), and GET /videos/{id} with /file, /events, /shots, /charges, /cancel and DELETE. The earlier preflight, purchase, scene edit, select-rendering, recompose, upgrade, restore, creative-project, draft and workflow paths are removed, as is the mvContractVersion: "v2" option of /api/v1/tasks.
    • OneClick integrations can move to Omn by adding generation.engineVersion: "omn-v1" (540p maps to 480p, 720p to 768p, with MV_OMN_RESOLUTION_MAPPED) or by asking us to switch their API key. POST /api/v2/mv/migrations/v1-check shows the mapping and both prices.
    • Omn videos rejected by the renderer after its own repairs fail with MV_CENTER_QUALITY_FAILED and are refunded; when 30 Omn videos are already rendering, quotes and purchases return 503 capacity_unavailable (Retry-After: 60) before charging; quotes carry no completion estimate; started Omn videos can be cancelled once the renderer confirms.
    • OneClick Turbo is retired: new purchases return 422 MV_ENGINE_UNSUPPORTED (turbo_retired). Existing Turbo videos remain readable.
    • TypeScript and Python SDKs 0.6.0 replace the Omn helpers with the resource API.
    • OneClick V2 Turbo is open for production purchases with sing_turbo, sing_perform_turbo and perform_turbo on /api/v1/mv. Check capabilities, availability and media preflight before purchasing. A degraded status permits requests with elevated delivery risk; keep polling the original Task. Scene editing and recomposition retain their separate availability rules.
    • Suno remaster-music now costs 28 standard credits across supported models. Customer contract ratios still apply; existing Tasks keep their saved prices.
    • Omn schemas include 3:2, 2:3 and 21:9 output ratios for supported routes. Check the exact combination before purchase; schema support does not mean the route is enabled. OneClick and Studio do not accept these extra ratios.
    • MV image preparation and quality repairs retain accepted work through scheduled waits. Historical MV details remain readable when optional postprocess metadata is absent. Existing preparation purchases and stored subscription rates remain valid during recovery and re-enrollment.

    New OneClick V2 sing_turbo and sing_perform_turbo requests now use performance planning when generation.creativeMode is omitted or auto, including requests with lyrics. To request a story, explicitly select lyrics_story or prompt_story (the latter requires prompt), or describe the story in prompt. Existing purchased tasks, explicit creative choices, perform_turbo and OneClick V1 keep their behavior. See directing a Turbo performance.

    Development preview: new long-term storage subscriptions cost 20 credits per decimal GB-month (30 days). Existing subscriptions keep their original rate, including when re-enabled or upgraded from Suno-only storage to monthly resource storage. Included retention and historical bills are unchanged. For the original Suno API, re-enrollment accepts subscription.rateUnitsPerGbMonth; only first enrollment uses publishedRateUnitsPerGbMonth. Read the storage guide and the current account rate before enabling.

    Development preview: MV workflow responses may include quality.filmReview for sampled review of the delivered video, with scene/transition coverage and observations to check during playback. Existing scene-level review and Task settlement keep their meanings. Handle the field as optional and read the review guidance.

    OneClick V2 Turbo replaces the unlaunched Vidu modes with sing_turbo, sing_perform_turbo and perform_turbo. All three accept 720p or 1080p, for 10–300 seconds. Standard generation pricing is 24 credits/second at 720p and 32 at 1080p. Existing standard OneClick generation contracts also cover Turbo at 21/28 credits/second; custom contracts and purchased orders keep their original terms. Quote and preflight include any additional components. Existing Omn modes are unchanged. Check availability before purchasing; see the Turbo guide.

    2026-10 release history

    2026-10-25 — Omn shot repairs, intentional waits, review evidence and vocal gender

    Section titled “2026-10-25 — Omn shot repairs, intentional waits, review evidence and vocal gender”

    Product update

    • Omn V1 videos planned from this release patch a shot whose picture shrinks into a bordered window (after its one replacement also failed) instead of delivering it, within the existing 30% limit: the video reports MV_NATIVE_SHOT_FILLED instead of MV_NATIVE_FRAME_BORDERS and those seconds are refunded. A narrative or bridge shot with exactly one hard cut keeps its longer continuous part, slowed by at most 1.25x, and no longer reports MV_NATIVE_SHOT_INTERNAL_CUT. Other border and cut cases are delivered as before with their warnings. See shot repairs at composition.
    • Saving purchased images recovers better from slow storage (size-scaled timeouts, bounded retries) without buying them again. A platform-written reference image refused by the image provider’s safety review no longer fails a paid MV when you supplied no prompt or reference image; it is retried once and then skipped with MV_NATIVE_PREPARATION_DEGRADED.
    • Runs waiting for a delivery slot or for vocal separation are no longer shown as failures or retries. The workflow adds optional activity.wait. See workflow phases and recovery.
    • MV_NATIVE_CREATIVE_REVIEW_REQUIRED and human_review_required now come only from concrete defect evidence; plan notes, minor notes and partial coverage stay informational. Singers keep their lips closed in shots where they do not sing, and an unverified mouthing repair reports repair_unverified for silentMouth. See finished-video review.
    • Preflight also returns MV_VOCAL_GENDER_MISMATCH. On Omn V1 the requested cast is kept, but that singer is not lip-synced (same charge) and is not shown mouthing the vocal. See singer gender and the song’s vocal.

    Action: check preflight warnings for MV_VOCAL_GENDER_MISMATCH and treat activity.wait as progress; no request changes are required. Warning codes, prices and refund rules are unchanged.

    2026-10-24 — Omn delivery guarantee, queued delivery and playback review

    Section titled “2026-10-24 — Omn delivery guarantee, queued delivery and playback review”

    Product update

    • Omn V1 now delivers an MV for every request that does not violate content rules. New advisory warnings MV_NATIVE_PREPARATION_DEGRADED, MV_CHARACTER_REFERENCE_DEGRADED and MV_NATIVE_SHOT_FILLED report the fallback used; patched shots (at most 30% of the duration) are refunded at settlement with refundReason: "shots_filled". Unavailable specialist modes are still rejected before charging. See delivery and fallback warnings.
    • Omn V1 creates beyond the running limit are accepted, charged and queued in fair-share order; only a full queue returns 503 MV_PROVIDER_UNAVAILABLE with capacity_unavailable and Retry-After. Capabilities add deliveryCapacity. See queued delivery.
    • Workflow quality asks for playback review of lip-sync shots whose mouth timing could not be confirmed and of shots that show extra or duplicated people. See finished-video review.

    Action: handle the new warning codes and the queued state; no request changes are required.

    2026-10-24 — Omn creative-setting conflict warning

    Section titled “2026-10-24 — Omn creative-setting conflict warning”

    Product update

    Omn can return MV_CREATIVE_BRIEF_SONG_WORLD_CONFLICT when the requested setting conflicts with the period or culture suggested by the song’s lyrics, title or style tags. Explicit customer requirements remain in place; Omn adapts the remaining setting to the song. This advisory warning does not change delivery or billing. See creative direction or API v1 compatibility.

    2026-10-18 — MV API release and compatibility

    Section titled “2026-10-18 — MV API release and compatibility”

    Product update

    /api/v1/mv retains Vidu Fast/Studio and its optional omn-v1 engine, including render tiers, scheduling, motion references, drafts, capabilities and upgrades. Existing Task and webhook links retain their v1 paths. The redundant /api/v1/vidu/mv alias is not published.

    /api/v2/mv is deployed at https://api.omnapi.com and included in the public API reference. Submit creative.mode, output.resolution and media to preflight, then purchase with its preflightId, a saved Idempotency-Key and your credit limit. Check capabilities and preflight for the requested options. Existing purchases keep their saved request and response contracts.

    New Omn full-generation and upgrade purchases require at least ten effective seconds. Refresh unpurchased preflights; shorter purchased tasks retain their original charge, refund and idempotent recovery. Vidu duration limits are unchanged.

    Product update

    Omn quote checks retain creative mode, character, caption and aspect-ratio information. Dance motion references use the same request structure at all four output resolutions, subject to current availability. Explicit character counts also apply to Auto character policy. Published v1 Omn selectors remain supported.

    2026-10-17 — Independent Omn modes and resolution API

    Section titled “2026-10-17 — Independent Omn modes and resolution API”

    Product update

    • Omn V1 uses /api/v2/mv with one request structure for eight creative modes and four output resolutions. creative.mode replaces product-tier contracts; resolution no longer selects a different feature contract.
    • Submit source, creative intent, references, output and captions to preflight. Create using its preflightId, optional maxCredits, and an Idempotency-Key. The stored request is bound to the same account and API key.
    • Vidu and Studio keep /api/v1/mv, including its optional Omn engine. The independent API v2 request does not accept API v1 generation selectors; existing API v1 integrations keep their original endpoint and request structure.
    • Admin displays and filters creative modes. Singing and dance share the same resolution choices. Combined modes currently support alternating shots; simultaneous performance returns 422 MV_ENGINE_UNSUPPORTED before debit.
    • SDK 0.5.0 and the OpenAPI snapshot use the new routes and parameters. See Omn integration and mode options and limitations.

    2026-10-17 — MV cancellation reason, billed duration and lyric filtering

    Section titled “2026-10-17 — MV cancellation reason, billed duration and lyric filtering”

    Product update

    • MV resource views add an optional terminationReason (cancelled or failed) when status is FAILED, so a normal cancellation is distinguishable from a real failure. status and staleReason enums are unchanged. A cancelled Omn workflow no longer marks its interrupted phase as failed. See lifecycle states.
    • Billed MV source duration ignores a decoder padding tail shorter than 50 ms: an exact 25.000-second AAC file is billed as 25 seconds instead of 26. Historical charges are not recalculated. See Omn pricing.
    • Omn lyric recognition removes promotional outro phrases whose confidence or word timing shows they are not aligned with the singing.
    • Omn V1 new plans improve shot continuity without changing prices: continuous same-set shots open from the previous shot’s final frame, carried props stay consistent, push-ins are limited, people outside lip-sync shots do not mouth lyrics, and a lip-sync shot that fails its quality check may use its one internal replacement on a prompt-capable route.
    • MV automatic subtitles re-recognize up to four uncertain lines from their own audio and change a line only when that reading matches a same-syllable candidate from lyric correction; timing and review warnings are unchanged.
    • Existing tasks retain their saved results. Read optional result fields when present; their absence does not certify a successful quality review.

    2026-10-17 — MV quote and maxCredits enforcement on generic Tasks

    Section titled “2026-10-17 — MV quote and maxCredits enforcement on generic Tasks”

    Product update

    MV creates sent through POST /api/v1/tasks and /tasks/sync now validate and consume an optional quoteId and apply maxCredits exactly like POST /api/v1/mv: the lower of the two is the charge ceiling. An expired or already used quote returns 409, a missing or another account’s quote 404, and a total above the ceiling 402 INSUFFICIENT_CREDITS with reason: "MAX_CREDITS_EXCEEDED", all without charging. Requests without these fields are unaffected. See MV charge authorization.

    2026-10-17 — Omn lyric provenance warnings

    Section titled “2026-10-17 — Omn lyric provenance warnings”

    Product update

    Omn V1 reports which lyrics shaped the creative plan: MV_CREATIVE_PLANNING_FROM_UNVERIFIED_TRANSCRIPT (recognized words, including when a supplied SRT was unusable), MV_CREATIVE_PLANNING_WITHOUT_LYRICS (no usable lyrics) or MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED (your lyrics with machine-estimated timing). They are advisory and do not change delivery or billing. See lyric warnings.

    Product update

    New Omn V1 purchases require at least 10 seconds of effective audio, including selected ranges and paid previews through v1 and v2. Shorter inputs are rejected before charging and are never padded. Per-second prices are unchanged. Refresh an unpurchased preflight after the price-card update; already purchased short videos retain their original charge, refund and purchase recovery.

    New whole-MV upgrades use the same minimum before quoting or charging. Shorter historical videos report upgrade availability as false, reason as null and the optional minimumDurationSec: 10, preserving the existing reason enum; scene edits and recomposition keep their existing pricing rules. Apps use the 10-second floor even with older capability details.

    The price card version is omn-v1-public-2026-10-17-v9. See Omn pricing.

    2026-10-16 — Omn V1 duration bundle pricing

    Section titled “2026-10-16 — Omn V1 duration bundle pricing”

    Product update

    New Omn V1 orders (policy omn-duration-bundle-v8) are charged one duration-tier bundle: the tier’s per-second price × effective seconds, rounded up. Routine planning, reference images and automatic subtitles are included; there are no per-request add-ons, and internal repairs or retries add no charge. A valid create quote and maxCredits still cap the charge. Tasks purchased earlier keep their original items, charges and refunds, including subtitle component refunds. See Omn pricing.

    Product update

    This historical entry describes the earlier creative-preset request format, subsequently replaced by the October 17 mode/resolution format and released on October 18. Existing purchases retain their saved contract; new requests must use the current reference. Quotes and maxCredits limit the authorized charge. See v2 options and follow-up operations.

    Product update

    • Adds POST /api/v1/mv/capabilities/check for one explicit Omn output/material combination. supported and ready distinguish configured support from current operational readiness; an unreadable configuration reports unknown support. Existing GET groups remain unchanged.
    • Reports interpreted creative intent while preserving story source, mood, performance distinctions and explicit OneClick lipSync: false.
    • The check creates no quote or Task, reserves no capacity and charges no credits. Preflight, rollout selection and quote/budget authorization remain required. Premium performance duration limits and rolloutPercent are unchanged.
    • With an unreadable account configuration, valid shot-engine syntax no longer becomes a legacy validation error; create/preflight still rejects unavailable admission before purchase. Check current readiness before purchase.

    See Omn availability.

    2026-10-16 — Simpler Omn performance requests

    Section titled “2026-10-16 — Simpler Omn performance requests”

    Product update

    With explicit engineVersion: "omn-v1", quote, preflight and create accept performanceMode without managedVersion. Existing explicit premium-v2 requests remain supported; implicit/Vidu defaults, performance duration limits and conflicting-field checks are unchanged. Explicit managedVersion: "premium-v2" remains supported for performance modes. See Omn creative options.

    Default-engine rollout still uses stable user percentages and does not change explicit engine selections or existing purchases. A request moved to Omn is priced by the Omn V1 card within its valid quote and maxCredits ceilings. Default-engine selection remains subject to the configured rollout policy.

    2026-10-16 — Omn V1 pool deadlines and stalled generations

    Section titled “2026-10-16 — Omn V1 pool deadlines and stalled generations”

    Product update

    New standard Omn pool generations no longer have a 30-minute delivery limit. Their deliveryDeadlineAt is 24 hours after creation and is an upper bound, not an estimated completion time. Tasks accepted earlier keep their stored deadline. A generation that stops making progress ends with MV_NATIVE_PROGRESS_STALLED before that deadline and settles through the normal refund rules. Request parameters, prices and quotes are unchanged.

    2026-10-15 — Omn V1 automatic subtitles for M4A audio

    Section titled “2026-10-15 — Omn V1 automatic subtitles for M4A audio”

    Product update

    Automatic subtitle preparation now handles M4A audio selected with a source range without the previous format rejection. Transcription request failures are distinguished from missing speech or unusable timing. The existing rules also apply when unreliable recognition leaves no usable subtitle timing; speculative segments are excluded from automatic subtitles. The rules for required preparation, successful delivery with subtitle warnings, and refunds of omitted paid subtitle components remain unchanged. See subtitle policies and delivery checks.

    2026-10-15 — Omn V1 five-second pricing and preparation recovery

    Section titled “2026-10-15 — Omn V1 five-second pricing and preparation recovery”

    Product update

    • Omn V1 accepts an effective output of at least 5 seconds, with no minimum order credits. Shorter inputs are rejected before purchase; audio is not padded.
    • All customers use the same published tier prices. Lip-sync does not change the per-second price. Unpurchased older preflights must be refreshed; already purchased tasks keep their saved pricing.
    • Preparation reuses confirmed materials and preserves requested shot capabilities. Capability responses distinguish narrative and singing readiness.
    • Historical pricing: the October 17 update raised the minimum to ten seconds. Use current pricing, availability.

    2026-10-14 — Omn subtitle delivery warnings

    Section titled “2026-10-14 — Omn subtitle delivery warnings”

    Product update

    • Workflow responses include optional warningCodes. A successfully delivered video can report missing subtitles without failing the whole task.
    • Only paid subtitle extraction/alignment components are refunded when requested subtitles cannot be delivered; video generation remains payable. Subtitle delivery and refunds.

    Action required

    • Dedicated Producer endpoints return 503 SERVICE_UNAVAILABLE; generic Task creation rejects new Producer work before billing. Existing records and recovery for already accepted tasks are retained.
    • SDK 0.4.0 removes Producer helpers. Other products continue to work.
    • Structured lyrics retains its producer response field for compatibility. Producer availability.

    2026-10-14 — Independent Omn V1 requests

    Section titled “2026-10-14 — Independent Omn V1 requests”

    Product update

    • Omn V1 accepts singing, performance and dance through performanceMode without a OneClick managedVersion. Select engineVersion: "omn-v1" and use renderTier for quality.
    • Read native.modes in capabilities for each mode’s readiness, resolution and duration range, up to 600 seconds where supported. Preflight remains required before purchase.
    • Existing OneClick V1 requests retain their fields and configured default-engine rollout. Explicit Vidu selection, saved preflights, purchased Tasks and budget ceilings keep their previous behavior. Explicit legacy OneClick V2 profiles retain their 300-second maximum.
    • Check capabilities and preflight before offering these request options.

    Product update

    • New Omn V1 orders use Draft 540p 9, Standard 720p 12, HD 1080p 20, and Ultra 720p/1080p/1440p 28/35/48 credits per output second, rounded up. Full-generation and upgrade video minimums are 250, 350, 400 and 400 credits respectively.
    • New Standard purchases only offer 720p. Standard defaults to 720p; omitted tiers at standard-quality 540p select Draft. Existing Standard 540p orders remain editable at the current Standard rate; new Standard upgrades use 720p.
    • Omn orders no longer apply customer or economy discounts. Shot edits remain per-second without a full-MV minimum, and recomposition remains 2 credits.
    • The price card adds renderTiers[].minimumOrderCredits and customerDiscounts: false. Existing receipts, other products and recharge packages keep their pricing. See Omn V1 pricing.
    • Historical pricing: later October updates supersede these minimum charges. Read the current catalog and preflight before purchasing.

    2026-10-12 · Omn V1 private highlights and review coverage

    Section titled “2026-10-12 · Omn V1 private highlights and review coverage”

    Product update

    • Available highlights use expiring private URLs. Refresh the MV view to get a new URL; unavailable, expired or unmigrated highlights are omitted or null. See highlight handling.
    • Workflow quality includes optional per-check coverage counts. Unexpected cuts within a shot and black borders also produce needs_revision and suggested repair targets. Missing or unevaluated checks do not mean a pass. See finished-video review.
    • Review findings do not automatically purchase replacements or alter credits.

    2026-10-09–11 · Omn V1 direction, pricing and advisory warnings

    Section titled “2026-10-09–11 · Omn V1 direction, pricing and advisory warnings”

    Product update

    • The current price card is 12 credits/second for Draft 540p, 16/20 for Standard 540p/720p and 24 for HD 1080p. Upgrade examples now use the target tier’s current rate; purchased Tasks retain their saved price.
    • Direct API requests explicitly selecting Omn with omitted/auto creative mode use singer-led performance. Implicit rollout requests and creative drafts with performanceMode: "auto" retain narrative planning. A valid quote caps an implicit request’s price; it does not pin the engine. Saved preflights retain their selected engine.
    • sing_dance and sing_play select Omn V1 singing with dance or an instrument. The finished composition can report two advisory creative-review warning codes; see warning codes.
    • Check capabilities and preflight for the current options.

    2026-10-07 · Omn creative direction and render options

    Section titled “2026-10-07 · Omn creative direction and render options”

    Product update

    • Omn V1 can offer Draft, Standard, HD and Ultra for both managed versions, subject to capabilities and preflight. Vidu OneClick V2 remains at 720p.
    • Creative drafts save the Omn render tier, resolution and economy schedule. Omn Auto/Story use narrative creation; Stage performance and Singing + performance now describe their output explicitly. Review and revalidate existing unpurchased drafts; purchased Tasks and retries retain their saved requests and price.
    • Eligible Omn V1 videos using the premium-v2 profile on API v1 support render-tier upgrades. Motion-transfer and visible-subtitle exclusions remain. See render options and style examples and API v1 upgrade requirements.

    Verified trials and MV source availability

    Section titled “Verified trials and MV source availability”

    Product update

    • 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 saved preflights, including older Vidu preflights. Quoted implicit requests can move to Omn when its price fits the valid quote, as described in the 9–11 October entry. Implicit Omn selection uses a gradual account rollout that defaults to zero; explicit engine selections remain unchanged.

    Product update

    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

    Section titled “2026-10-01 — Omn V1 upgrade availability, price card and neutral output”

    Product update

    • 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.
    • Check capabilities and preflight before purchase. 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

    Section titled “2026-10-01 — Omn V1 render tiers, economy scheduling and upgrades”

    Product update

    • 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. Check capabilities and preflight before purchase. See the Omn API v1 compatibility and Omn V1 edits and upgrades.
    2026-09 release history

    2026-09-30 — Omn V1 generation reliability

    Section titled “2026-09-30 — Omn V1 generation reliability”

    Product update

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

    Product update

    • 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. Check capabilities before purchase. See Omn V1 generation.

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

    Section titled “2026-09-30 — MV song context and quality preview”

    Product update

    • 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.
    • Check the returned workflow and capability fields. See MV song context and review.

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

    Section titled “2026-09-24 — Producer recovery and Suno resource errors”

    Product update

    • 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 (paused October 14, 2026).
    • 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.

    Product update

    • 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 (paused October 14, 2026) for limits, resource permissions, idempotency, and recovery.

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

    Section titled “2026-09-19 — Audio editing and Suno export metadata”

    Product update

    • 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

    Section titled “2026-09-18 — Suno downloads and Legacy playback”

    Product update

    • 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

    Section titled “2026-09-18 — Documentation corrections and integration guides”

    Product update

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

    Product update

    • 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

    Section titled “2026-09-03 — Play Suno songs while generating”

    Product update

    • 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 release history

    Product update

    • 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

    Section titled “2026-08-09 — Suno Vox model admission fixed”

    Product update

    • 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

    Section titled “2026-08-09 — Suno lyrics continuity and atomic paired delivery”

    Product update

    • 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

    Section titled “2026-08-08 — Complete Vidu Direct catalog and pricing”

    Product update

    • 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

    Section titled “2026-08-08 — Public integration contract completeness”

    Product update

    • 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

    Section titled “2026-08-08 — Native Extract catalog and Suno pricing update”

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

    Product update

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

    Product update

    • 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

    Section titled “2026-08-07 — Complete Suno clip metadata and stable Task polling”

    Product update

    • 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

    Section titled “2026-08-05 — Clip-derived Voices and account credit balance”

    Product update

    • 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

    Section titled “2026-08-04 — Explicit Suno clip models and one Legacy prefix”

    Product update

    • 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 release history

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

    Section titled “2026-07-30 — Legacy Suno path aligned with the OmnAPI API namespace”

    Product update

    • 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

    Section titled “2026-07-30 — Modern Suno migration completeness”

    Migration · Action required

    • 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

    Section titled “2026-07-29 — Unified Suno pricing and public surface”

    Product update

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

    Product update

    • 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

    Section titled “2026-07-28 — Verified public Suno Voices”

    Product update

    • 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

    Section titled “2026-07-28 — Suno Stems delivery consistency”

    Product update

    • 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

    Section titled “2026-07-27 — Suno Stems contract follows current modes”

    Product update

    • 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

    Section titled “2026-07-27 — Resilient legacy Suno WAV delivery”

    Product update

    • 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

    Section titled “2026-07-24 — Fast MV scene image replacement”

    Product update

    • 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

    Section titled “2026-07-23 — Suno Cloud compatibility routes namespaced”

    Product update

    • 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)

    Section titled “2026-07-20 — Suno model-tier pricing (superseded)”

    Historical policy

    • 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

    Section titled “2026-07-18 — Fast MV creative planning and subtitle layout”

    Product update

    • 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

    Section titled “2026-07-16 — Durable task execution and confirmed cancellation”

    Product update

    • 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

    Section titled “2026-07-15 — Task list and Suno availability contract hardened”

    Product update

    • 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)

    Section titled “2026-07-14 — Suno commercial contract completed (superseded)”

    Historical policy

    • 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

    Section titled “2026-07-12 — MV query efficiency, delivery estimates, and SDK workflow”

    Product update

    • 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

    Section titled “2026-07-11 — MV asset durability and URL lifecycle”

    Product update

    • 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

    Section titled “2026-07-11 — MV preflight spend authorization clarified”

    Product update

    • 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

    Section titled “2026-07-10 — MV commercial operation and Studio workflow update”

    Product 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.
    • Correction: the advertised lock-character quote step is not accepted by the current public quote request contract. The write exists, but quote-confirmed integrations should keep this action disabled. See the current limitation.
    • 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

    Section titled “2026-07-09 — MV Fast delivery diagnostics”

    Product update

    • 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

    Section titled “2026-07-05 — Lyrics / Subtitle Sync API and MV auto subtitles”

    Product update

    • 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

    Section titled “2026-07-05 — MV Fast reference strategy clarified”

    Product update

    • 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

    Section titled “2026-07-02 — MV Fast scene version selection”

    Product update

    • 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

    Section titled “2026-07-01 — MV Fast scene edit and recompose pricing”

    Product update

    • 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 release history

    2026-06-30 — MV Fast public contract vNext

    Section titled “2026-06-30 — MV Fast public contract vNext”

    Product update

    • 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

    Section titled “2026-06-26 — MV generation fields made mode-aware”

    Product update

    • 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

    Section titled “2026-06-26 — MV Fast quality and lip reference controls”

    Product update

    • 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

    Section titled “2026-06-26 — MV Fast character reference priority”

    Product update

    • 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

    Section titled “2026-06-25 — MV Fast reference handling clarified”

    Product update

    • 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

    Section titled “2026-06-24 — MV pricing receipts aligned”

    Product update

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

    Product update

    • 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

    Section titled “2026-06-17 — MV Fast finalization and asset limits clarified”

    Product update

    • 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

    Section titled “2026-06-16 — MV public API is URL-only for API callers”

    Product update

    • 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

    Section titled “2026-06-15 — MV public API narrowed to Fast”

    Product update

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

    Product update

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

    Product update

    • 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)

    Section titled “2026-06-07 — Field naming unified (breaking)”

    Breaking change · Action required

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

    Product update

    • 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 release history

    2026-05-31 — Unified MV surface documented

    Section titled “2026-05-31 — Unified MV surface documented”

    Product update

    • 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

    Section titled “2026-05-25 — Suno direct surface and migration routes documented”

    Migration · Action required

    • 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

    Section titled “2026-05-24 — Launch surface trimmed to Producer + Get Task”

    Product update

    • 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

    Section titled “2026-05-23 — Legacy /v1 sunocloud compat removed from public spec”

    Breaking change · Action required

    • /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

    Section titled “2026-05 — Public OpenAPI spec + interactive playground”

    Product update

    • /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