Changelog

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

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-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 one-click 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 MV URL behavior: MVView asset URLs prefer stable CDN URLs and may fall back to short-lived URLs; GET /api/v1/mv/{mvId}/final remains the 15-minute final MP4 URL refresh endpoint.

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 managed one-click 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-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 personas.
• 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