MV API migration notes — July 2026

This page is for integrations that used /api/v1/mv/* before July 10, 2026. Existing endpoint paths and request payloads remain accepted, but this release adds response fields and enum values and changes Fast availability and media URL behavior.

Compatibility summary

Area	Compatibility	Required customer action
Existing /api/v1/mv/* paths and methods	Compatible	None. No existing public MV endpoint was removed or renamed.
Existing request bodies	Compatible	None. quoteId and maxCredits remain optional.
Create response	Compatible type narrowing	Treat the new non-null mvId as resource identity, not as a readiness signal.
Response objects	Additive	Allow unknown JSON properties or update strict response schemas.
Status enums	Expanded	Handle ACTION_REQUIRED, DELETED, incomplete, and Fast availability unknown.
Fast paid create	Operator-controlled	Read availability gateEnabled; retryable 503 MV_PROVIDER_UNAVAILABLE occurs only when the gate is enabled.
Customer media URLs	Behavior change	Do not persist returned URLs as permanent asset identifiers; refresh them when needed.
Historical MV operation totals	Cutover-limited	Use the existing task billing or usage ledger for spend that predates operation-ledger coverage.
Hidden Suno /v1/* migration routes	Unchanged	No action is required for this MV release.

Existing requests remain valid

Existing MV create and paid-write request bodies continue to work. quoteId and maxCredits are optional controls: use them when you want a short-lived price confirmation and a hard spend ceiling, but older request bodies do not need to add them to remain valid.

Quote responses keep the existing credits, breakdown, and warningCodes fields and add quoteId, operation, expiresAt, pricingVersion, and assumptions. Clients that reject unknown JSON properties must update their response schemas before upgrading.

Stable mvId is not a readiness signal

New create responses always return a non-null mvId; for newly created resources, it equals taskId. This gives the integration a stable resource identity immediately, but does not mean that generation is complete or that the product view has already been materialized.

Use this sequence:

1. Persist both taskId and mvId from the create response.
2. Poll GET /api/v1/tasks/{taskId} until the task reaches a terminal state.
3. Read GET /api/v1/mv/{mvId} for product state.
4. When ready, call GET /api/v1/mv/{mvId}/final for a fresh final URL.

Handle expanded status vocabulary

Existing clients should recognize these additions:

Field	New value	Meaning
MVView.status	ACTION_REQUIRED	Usable partial Studio work remains, but customer action is required. Do not treat it as a total failure.
MVView.status	DELETED	The MV has been deleted and is no longer available for normal product reads.
deliveryStatus	incomplete	The workflow has usable output but has not completed every requested component.
Fast availability status	unknown	Delivery health has not been verified; check gateEnabled to determine whether paid Fast create is blocked.

Use an explicit fallback when switching on public enum values:

switch (mv.status) {
  case "READY":
    showReady(mv);
    break;
  case "ACTION_REQUIRED":
    showRecoveryActions(mv);
    break;
  case "DELETED":
    showDeleted();
    break;
  default:
    showPendingOrUnknown(mv);
}

Regenerate typed clients from the current OpenAPI document, or update local enum definitions before enabling the new workflow in a strictly typed client.

Fast availability has an independent paid-create gate

Availability now includes additive gateEnabled. It defaults to false, so health remains visible without blocking paid creates. When an operator enables the gate, Fast delivery health unknown or unavailable returns 503 MV_PROVIDER_UNAVAILABLE before charging credits. Quote and preflight remain available in either policy.

{
  "success": false,
  "error": {
    "code": "MV_PROVIDER_UNAVAILABLE",
    "message": "MV Fast is temporarily unavailable",
    "retryable": true,
    "retryAfterSec": 30
  }
}

Respect retryAfterSec, apply normal backoff, and reuse your idempotency key for the same logical create attempt. Do not record a charge for this response.

Returned media URLs are temporary

Customer-facing MV media URLs are short-lived signed URLs. Store resource and asset identifiers instead of the URL itself, and refresh MVView or GET /api/v1/mv/{mvId}/final when a URL expires. Upload helpers expose their own expiresInSec value where applicable.

Previously returned public URLs are not revoked merely because this release was deployed, but that is not a retention guarantee. Deletion or normal asset expiry can still make an older URL unavailable, and refreshing a URL does not extend the asset’s retention window.

Deletion removes the MV from normal customer reads and best-effort deletes its known media assets. Task, operation, pricing, and billing rows needed for financial reconciliation remain subject to the platform audit-retention policy. After the configured Task retention window, retained MV operation Tasks are compacted: financial identity, ownership, status, amount, settlement, pricing, and timing evidence remains, while request, provider, result, step, webhook, and detailed-error payloads are removed. This is a retention implementation change and does not alter existing MV API request or response contracts.

Historical operation totals have a cutover boundary

GET /api/v1/mv/{mvId}/operations and MVView.costSummary aggregate recorded MV operation rows. Projects created after operation-ledger coverage was enabled have complete project totals. Older projects may omit work completed before the cutover.

For pre-cutover spend, continue to use task billing fields and the authenticated usage export as the financial source of record. A zero or partial costSummary on an older MV does not prove that the project had no historical spend.

Delivery outcomes may become stricter

Newly finalized or recomposed outputs must pass deterministic media checks for usable video and audio streams, expected duration, purchased resolution tier, and viable frame rate. An invalid output can therefore fail and be refunded where an older workflow might have exposed the asset. Existing READY assets are not reprocessed merely because this release was deployed.

Upgrade checklist

• Keep existing request bodies, or adopt optional quoteId and maxCredits.
• Update strict response schemas for additive fields.
• Add a fallback for future enum values and handle the new values above.
• Treat mvId as identity and taskId as the execution-readiness source.
• Read availability gateEnabled; when enabled, handle retryable 503 MV_PROVIDER_UNAVAILABLE as a no-charge result.
• Store asset identifiers, not temporary signed URLs.
• Reconcile pre-cutover projects with task billing or the usage export.
• Download assets that must be retained beyond the documented retention window.

Continue with the MV API guide, follow the MV Fast quickstart, and review the public changelog.