Skip to content
OmnAPI Docs

OmnAPI API endpoint directory

Use https://api.omnapi.com as the base URL. Authenticated operations use the x-api-key header on your server. The public pricing catalog can be read without a key. Generation requests return task receipts; acceptance is separate from completion.

This directory contains 60 operations from the published API contract (version 2.0.0). Read exact request fields, required inputs, response schemas, and operation-specific authentication in the interactive reference or downloadable OpenAPI JSON.

Start with the Suno quickstart, Producer quickstart, MV quote-to-download flow, or Python and TypeScript examples. For recovery, read task states, webhooks, and request limits.

60 operations

Permissions, billable reads and recovery rules

Account

Read the Account guide

Method and pathOperation
GET /api/v1/account/credits Get Account Credits
Description and searchable fields

Returns the caller's exact OmnAPI credit balance from the billing source of truth. Suitable for low-balance monitoring and alerts.

  • response.balanceCredits — Exact currently available OmnAPI credit balance.
  • response.balanceUnits — Exact balance in credit units as a decimal string (1 credit = 10000 units).
  • response.billingStatus
  • response.tier
  • response.updatedAt

Lyrics

Read the Lyrics guide

Method and pathOperation
POST /api/v1/lyrics/generate Generate Lyrics Package
Description and searchable fields

Create a GPT lyrics-generation task, persist it through the unified task pipeline, and wait briefly for the completed result.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.durationSec — Target duration in seconds.
  • body.explicit — Whether explicit language is acceptable.
  • body.extraGuidance — Additional creative guidance or constraints.
  • body.genre — Requested musical genre direction.
  • body.language — Primary lyric language. Use 'auto' to let the model decide.
  • body.languages — Additional languages to include or consider.
  • body.mode — Lyrics generation mode. GPT is the supported mode.
  • body.mood — Requested musical or visual mood.
  • body.multilingualMode — How multiple lyric languages should be arranged.
  • body.negativeConstraints — Topics, styles, or tropes the output should avoid.
  • body.perspective — Requested lyric narrative perspective.
  • body.prompt — Core song brief, story, scene, or hook idea.
  • body.structure — Requested lyric section order.
  • body.themeKeywords — Short theme keywords to anchor the lyrics.
  • body.vocalStyle — Requested vocal performance direction.
  • response.creditsCharged
  • response.hook
  • response.languagePlan
  • response.languagePlan.mixStrategy
  • response.languagePlan.primaryLanguage
  • response.languagePlan.secondaryLanguages
  • response.languagePlan.transliteration
  • response.lyrics
  • response.model
  • response.modelPath
  • response.notes
  • response.producer
  • response.producer.lyrics
  • response.producer.soundPrompt
  • response.producer.title
  • response.sectionOrder
  • response.status
  • response.suno
  • response.suno.negativeTags
  • response.suno.prompt
  • response.suno.tags
  • response.suno.title
  • response.taskId
  • response.title
  • response.usage
  • response.usage.completionTokens
  • response.usage.promptTokens
  • response.usage.totalTokens

MV

Read the MV guide

Method and pathOperation
GET /api/v1/mv/ List MVs
Description and searchable fields

Cursor-paginated Fast and Studio MV project history. Archived projects are excluded.

  • query.limit —
  • query.cursor — Opaque pagination cursor returned as nextCursor; omit it on the first page.
  • response.hasMore
  • response.items
  • response.items[].createdAt
  • response.items[].generatedSceneVideoCount
  • response.items[].generatedVideoCount
  • response.items[].hasFinalVideo
  • response.items[].mode
  • response.items[].mvId
  • response.items[].sceneCount
  • response.items[].status
  • response.items[].title
  • response.items[].updatedAt
  • response.nextCursor
POST /api/v1/mv/ Create MV
Description and searchable fields

Create a Fast finished MV or Studio storyboard. The accepted response returns `taskId` and the same value as an immediately stable `mvId` alias, addressable through `viewUrl`; the resolved MVView may later expose the canonical project/storyboard id. Send an `Idempotency-Key` header to make retries safe — a duplicate key replays the original response without charging again. If maxCredits is present, the final create-time quote must not exceed it.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.aspectRatio — Requested output aspect ratio.
  • body.characterImage — Public character reference image URL.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.generation — Product-specific generation controls.
  • body.generation.creativeMode — Creative intent used by Fast MV prompt and reference planning.
  • body.generation.lipReferenceImages — Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.
  • body.generation.managedVersion — Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.
  • body.generation.motionPreset — Fast MV motion prompt policy.
  • body.generation.performanceMode — Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.
  • body.generation.promptMode — Whether Fast MV preserves or compiles the caller prompt.
  • body.generation.quality — Requested public quality tier.
  • body.generation.referenceStrategy — Fast MV policy for direct or synthesized references.
  • body.generation.style — Requested creative style direction.
  • body.generation.subtitleMode — Fast MV subtitle rendering mode.
  • body.generation.visualBoard — Fast MV Visual Board configuration.
  • body.generation.visualBoard.imageProvider — Public image-generation option code.
  • body.generation.visualBoard.preset — Visual Board speed/detail policy.
  • body.language — Requested or known language code/name.
  • body.lipSync — Whether the MV should use the supported lip-sync workflow.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.mode — Operation or product mode discriminator for this schema variant.
  • body.preflightId — Reusable MV preflight snapshot identifier.
  • body.prompt — Primary creative or operation instruction.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.referenceImages — Public reference image URLs.
  • body.resolution — Requested output resolution.
  • body.source — Public source media or product reference.
  • body.source.clipId — Source clip identifier.
  • body.source.lyrics — Lyrics or lyric context supplied to the operation.
  • body.source.range — Optional source-media range.
  • body.source.range.endSec — Scene or source-range end time in seconds.
  • body.source.range.startSec — Scene or source-range start time in seconds.
  • body.source.type — Source or product type discriminator.
  • body.source.audioUrl — Public HTTP(S) audio URL.
  • body.source.durationSec — Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.
  • body.srtUrl — Public URL of caller-supplied SRT subtitles.
  • body.subtitle — MV subtitle generation and fallback policy.
  • body.subtitle.fallback — Behavior when the preferred subtitle path cannot complete.
  • body.subtitle.language — Requested or known language code/name.
  • body.subtitle.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.subtitle.mode — Operation or product mode discriminator for this schema variant.
  • body.subtitle.quality — Requested public quality tier.
  • body.subtitle.required — Whether the selected subtitle policy must succeed.
  • body.subtitleColor — Requested subtitle foreground color.
  • body.subtitles — Whether subtitles are enabled for the MV.
  • body.title — Optional customer-facing title.
  • body.generation.imageProvider — Public image-generation option code.
  • body.generation.videoModel — Public scene-video model code.
  • body.generation.videoProvider — Public scene-video option code.
  • response.autoFinalize
  • response.creditsRequired
  • response.deliveryStatus
  • response.estimatedCompletionTime
  • response.finalUrl
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.mode
  • response.mvId
  • response.pollUrl
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId
  • response.viewUrl
  • response.warningCodes
GET /api/v1/mv/fast/availability Get Fast MV availability
Description and searchable fields

Check whether Fast MV creation is currently available. Use the requested managedVersion and honor retryAfterSec before trying again. `gateEnabled` remains in the public contract and is fixed to true; `unknown` and `unavailable` block paid creates before direct debit.

  • query.managedVersion —
  • response.admissionState
  • response.checkedAt
  • response.checks
  • response.checks[].message
  • response.checks[].name
  • response.checks[].status
  • response.gateEnabled — Paid-create availability gate; fixed to true in the current public contract.
  • response.guidance
  • response.managedVersion
  • response.message
  • response.metrics
  • response.metrics.avgTerminalDurationSec
  • response.metrics.failedCount
  • response.metrics.failureRate
  • response.metrics.predictedDeliveryWaitSec
  • response.metrics.predictedQueueWaitSec
  • response.metrics.processingCount
  • response.metrics.projectCount
  • response.metrics.readyCount
  • response.metrics.readyRate
  • response.metrics.recentServiceRatePerMinute
  • response.metrics.staleProcessingCount
  • response.metrics.terminalCount
  • response.retryAfterSec
  • response.status
  • response.windowMinutes
POST /api/v1/mv/preflight Preflight MV create
Description and searchable fields

Validate MV create resources and return a reusable create-time estimate without creating a task or charging credits. The returned preflightId may be supplied to POST /api/v1/mv with the same media and generation body to reuse the validated snapshot. Create-time quoteId and maxCredits may be added or changed without invalidating media validation; final credits are determined immediately before task creation and maxCredits caps the authorized charge.

  • body.aspectRatio — Requested output aspect ratio.
  • body.characterImage — Public character reference image URL.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.generation — Product-specific generation controls.
  • body.generation.creativeMode — Creative intent used by Fast MV prompt and reference planning.
  • body.generation.lipReferenceImages — Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.
  • body.generation.managedVersion — Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.
  • body.generation.motionPreset — Fast MV motion prompt policy.
  • body.generation.performanceMode — Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.
  • body.generation.promptMode — Whether Fast MV preserves or compiles the caller prompt.
  • body.generation.quality — Requested public quality tier.
  • body.generation.referenceStrategy — Fast MV policy for direct or synthesized references.
  • body.generation.style — Requested creative style direction.
  • body.generation.subtitleMode — Fast MV subtitle rendering mode.
  • body.generation.visualBoard — Fast MV Visual Board configuration.
  • body.generation.visualBoard.imageProvider — Public image-generation option code.
  • body.generation.visualBoard.preset — Visual Board speed/detail policy.
  • body.language — Requested or known language code/name.
  • body.lipSync — Whether the MV should use the supported lip-sync workflow.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.mode — Operation or product mode discriminator for this schema variant.
  • body.prompt — Primary creative or operation instruction.
  • body.referenceImages — Public reference image URLs.
  • body.resolution — Requested output resolution.
  • body.source — Public source media or product reference.
  • body.source.clipId — Source clip identifier.
  • body.source.lyrics — Lyrics or lyric context supplied to the operation.
  • body.source.range — Optional source-media range.
  • body.source.range.endSec — Scene or source-range end time in seconds.
  • body.source.range.startSec — Scene or source-range start time in seconds.
  • body.source.type — Source or product type discriminator.
  • body.source.audioUrl — Public HTTP(S) audio URL.
  • body.source.durationSec — Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.
  • body.srtUrl — Public URL of caller-supplied SRT subtitles.
  • body.subtitle — MV subtitle generation and fallback policy.
  • body.subtitle.fallback — Behavior when the preferred subtitle path cannot complete.
  • body.subtitle.language — Requested or known language code/name.
  • body.subtitle.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.subtitle.mode — Operation or product mode discriminator for this schema variant.
  • body.subtitle.quality — Requested public quality tier.
  • body.subtitle.required — Whether the selected subtitle policy must succeed.
  • body.subtitleColor — Requested subtitle foreground color.
  • body.subtitles — Whether subtitles are enabled for the MV.
  • body.title — Optional customer-facing title.
  • body.generation.imageProvider — Public image-generation option code.
  • body.generation.videoModel — Public scene-video model code.
  • body.generation.videoProvider — Public scene-video option code.
  • response.checks
  • response.checks.characterImage
  • response.checks.characterImage.clipId
  • response.checks.characterImage.durationSec
  • response.checks.characterImage.kind
  • response.checks.characterImage.processingMode
  • response.checks.characterImage.range
  • response.checks.characterImage.range.endSec
  • response.checks.characterImage.range.startSec
  • response.checks.characterImage.sourceDurationSec
  • response.checks.characterImage.status
  • response.checks.characterImage.url
  • response.checks.referenceImages
  • response.checks.referenceImages[].clipId
  • response.checks.referenceImages[].durationSec
  • response.checks.referenceImages[].kind
  • response.checks.referenceImages[].processingMode
  • response.checks.referenceImages[].range
  • response.checks.referenceImages[].range.endSec
  • response.checks.referenceImages[].range.startSec
  • response.checks.referenceImages[].sourceDurationSec
  • response.checks.referenceImages[].status
  • response.checks.referenceImages[].url
  • response.checks.source
  • response.checks.source.clipId
  • response.checks.source.durationSec
  • response.checks.source.kind
  • response.checks.source.processingMode
  • response.checks.source.range
  • response.checks.source.range.endSec
  • response.checks.source.range.startSec
  • response.checks.source.sourceDurationSec
  • response.checks.source.status
  • response.checks.source.url
  • response.checks.srtUrl
  • response.checks.srtUrl.clipId
  • response.checks.srtUrl.durationSec
  • response.checks.srtUrl.kind
  • response.checks.srtUrl.processingMode
  • response.checks.srtUrl.range
  • response.checks.srtUrl.range.endSec
  • response.checks.srtUrl.range.startSec
  • response.checks.srtUrl.sourceDurationSec
  • response.checks.srtUrl.status
  • response.checks.srtUrl.url
  • response.checks.visualBoard
  • response.checks.visualBoard.clipId
  • response.checks.visualBoard.durationSec
  • response.checks.visualBoard.kind
  • response.checks.visualBoard.processingMode
  • response.checks.visualBoard.range
  • response.checks.visualBoard.range.endSec
  • response.checks.visualBoard.range.startSec
  • response.checks.visualBoard.sourceDurationSec
  • response.checks.visualBoard.status
  • response.checks.visualBoard.url
  • response.creditsRequired
  • response.expiresAt
  • response.mode
  • response.preflightId
  • response.quote
  • response.quote.assumptions
  • response.quote.baseCredits
  • response.quote.billingIncrementCredits
  • response.quote.breakdown
  • response.quote.breakdown.base
  • response.quote.breakdown.composeOperations
  • response.quote.breakdown.duration
  • response.quote.breakdown.estimatedSceneCount
  • response.quote.breakdown.finalize
  • response.quote.breakdown.lipSync
  • response.quote.breakdown.renderPerScene
  • response.quote.breakdown.scenes
  • response.quote.breakdown.visualBoard
  • response.quote.calculatedSubtotalCredits
  • response.quote.credits
  • response.quote.discountCredits
  • response.quote.expiresAt
  • response.quote.operation
  • response.quote.pricingVersion
  • response.quote.quoteId
  • response.quote.settlementPolicyVersion
  • response.quote.settlementRoundingCredits
  • response.quote.warningCodes
  • response.quoteType
  • response.warningCodes
POST /api/v1/mv/quote Quote MV credits
Description and searchable fields

Customer-facing pricing preview for Fast and Studio MV generation and paid follow-up operations. The response includes a short-lived quoteId that can be supplied with the operation; execution reprices and rejects before direct debit if the current price exceeds the quoted/maxCredits ceiling. Create quotes are lightweight and do not validate remote media resources.

  • body.durationSec — Requested or known media duration in seconds.
  • body.lipSync — Whether the MV should use the supported lip-sync workflow.
  • body.managedVersion — Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.
  • body.mode — Operation or product mode discriminator for this schema variant.
  • body.performanceMode — Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.
  • body.quality — Requested public quality tier.
  • body.resolution — Requested output resolution.
  • body.step — Quoted operation step discriminator.
  • body.subtitleMode — Fast MV subtitle rendering mode.
  • body.visualBoardImageCount — Number of generated Visual Board images to price.
  • body.visualBoardImageProvider — Public Visual Board image option code.
  • body.visualBoardReferenceImageCount — Number of billed Visual Board reference images.
  • body.visualBoardStrategy — Public Visual Board pricing strategy.
  • body.mvId — MV identifier targeted by this operation.
  • body.sceneIndex — Zero-based scene index.
  • body.draft — Whether to use the supported draft rendering policy.
  • body.fps — Requested numeric output frame rate.
  • body.videoModel — Public scene-video model code.
  • body.videoProvider — Public scene-video option code.
  • body.sceneIndexes — Unique zero-based scene indexes included in the operation.
  • body.estimatedSceneCount — Estimated number of Studio scenes for total pricing.
  • body.perSceneDurationSec — Estimated duration of each Studio scene in seconds.
  • response.assumptions
  • response.baseCredits
  • response.billingIncrementCredits
  • response.breakdown
  • response.breakdown.base
  • response.breakdown.composeOperations
  • response.breakdown.duration
  • response.breakdown.estimatedSceneCount
  • response.breakdown.finalize
  • response.breakdown.lipSync
  • response.breakdown.renderPerScene
  • response.breakdown.scenes
  • response.breakdown.visualBoard
  • response.calculatedSubtotalCredits
  • response.credits
  • response.discountCredits
  • response.expiresAt
  • response.operation
  • response.pricingVersion
  • response.quoteId
  • response.settlementPolicyVersion
  • response.settlementRoundingCredits
  • response.warningCodes
DELETE /api/v1/mv/{mvId} Delete MV
Description and searchable fields

Idempotently marks an MV deleted, removes it from list/read results, blocks new operations, and deletes known source, scene, rendering, and final assets with bounded concurrency. Task, operation, pricing, and billing records required for financial reconciliation remain subject to the platform audit-retention policy.

  • path.mvId — MV identifier returned by create or read operations.
  • response.assetsDeleted
  • response.assetsFailed
  • response.id
  • response.status
GET /api/v1/mv/{mvId} Get MV
Description and searchable fields

Returns the public MVView shape for Fast or Studio: source, prompt, scene timing, generated assets, finalMv, version, and capability flags. Some asset URLs may be short-lived; refresh by reading the MV again. Existing clients may omit historyLimit to retain the original complete renderingHistory response; new interactive clients can request 1-50 recent entries per scene. Selected entries and the latest playable Fast fallback are additionally retained when they fall outside that recent window.

  • path.mvId — MV identifier returned by create or read operations.
  • query.historyLimit —
  • response.billing
  • response.billing.creditsCharged
  • response.billing.creditsReserved
  • response.billing.refundReason
  • response.billing.refundedCredits
  • response.billing.settlementStatus
  • response.capabilities
  • response.capabilities.canEditManagedScene
  • response.capabilities.canEditSceneFraming
  • response.capabilities.canEditSceneImage
  • response.capabilities.canEditScenePrompt
  • response.capabilities.canFinalize
  • response.capabilities.canLockCharacter
  • response.capabilities.canPatchStageOutput
  • response.capabilities.canRecompose
  • response.capabilities.canRefreshFinalUrl
  • response.capabilities.canRegenerateSceneImage
  • response.capabilities.canRenderScene
  • response.capabilities.canRerenderSceneWithImages
  • response.capabilities.canRerenderSceneWithPrompt
  • response.capabilities.canRetryFinalize
  • response.capabilities.canSelectRendering
  • response.capabilities.canTriggerRender
  • response.capabilities.canUseCurrentFinal
  • response.capabilities.finalizeAction
  • response.capabilities.requiresFinalize
  • response.characterAnchor
  • response.characterAnchor.url
  • response.costSummary
  • response.costSummary.authorizedCredits
  • response.costSummary.chargedCredits
  • response.costSummary.netSpentCredits
  • response.costSummary.operationCount
  • response.costSummary.refundedCredits
  • response.createdAt
  • response.customerAction
  • response.deliveryStatus
  • response.failedAt
  • response.failureCategory
  • response.failureReason
  • response.failureReason.code
  • response.failureReason.message
  • response.finalMv
  • response.finalMv.assetId
  • response.finalMv.assetStatus
  • response.finalMv.durationSec
  • response.finalMv.expiresAt
  • response.finalMv.finalizationRequired
  • response.finalMv.finalizedVersion
  • response.finalMv.id
  • response.finalMv.isCurrent
  • response.finalMv.resolution
  • response.finalMv.retainedUntil
  • response.finalMv.sourceVersion
  • response.finalMv.staleReason
  • response.finalMv.status
  • response.finalMv.urlExpiresAt
  • response.finalMv.videoUrl
  • response.finalUrl
  • response.finalizationRequired
  • response.finalizedVersion
  • response.generation
  • response.generation.aspectRatio
  • response.generation.draft
  • response.generation.language
  • response.generation.lipSync
  • response.generation.managedVersion
  • response.generation.performanceMode
  • response.generation.resolution
  • response.generation.subtitleColor
  • response.generation.subtitles
  • response.generation.videoProvider
  • response.generationTaskId
  • response.lastErrorCode
  • response.lastErrorMessage
  • response.mode
  • response.mvId
  • response.progress
  • response.prompt
  • response.referenceImages
  • response.referenceImages[].source
  • response.referenceImages[].url
  • response.refundable
  • response.retryable
  • response.scenes
  • response.scenes[].endSec
  • response.scenes[].framing
  • response.scenes[].imageAssetId
  • response.scenes[].imagePrompt
  • response.scenes[].imageRetainedUntil
  • response.scenes[].imageUrl
  • response.scenes[].imageUrlExpiresAt
  • response.scenes[].index
  • response.scenes[].lyricsWindow
  • response.scenes[].prompt
  • response.scenes[].renderingHistory
  • response.scenes[].renderingHistory[].assetId
  • response.scenes[].renderingHistory[].assetStatus
  • response.scenes[].renderingHistory[].createdAt
  • response.scenes[].renderingHistory[].durationSec
  • response.scenes[].renderingHistory[].id
  • response.scenes[].renderingHistory[].isSelectable
  • response.scenes[].renderingHistory[].isSelected
  • response.scenes[].renderingHistory[].prompt
  • response.scenes[].renderingHistory[].referenceImages
  • response.scenes[].renderingHistory[].retainedUntil
  • response.scenes[].renderingHistory[].urlExpiresAt
  • response.scenes[].renderingHistory[].videoUrl
  • response.scenes[].sourceJob
  • response.scenes[].sourceJob.createdAt
  • response.scenes[].sourceJob.errorCode
  • response.scenes[].sourceJob.errorMessage
  • response.scenes[].sourceJob.id
  • response.scenes[].sourceJob.isComposable
  • response.scenes[].sourceJob.status
  • response.scenes[].startSec
  • response.scenes[].status
  • response.scenes[].videoPrompt
  • response.scenes[].videoUrl
  • response.source
  • response.source.audioUrl
  • response.source.clipId
  • response.source.durationSec
  • response.source.lyrics
  • response.source.range
  • response.source.range.endSec
  • response.source.range.startSec
  • response.source.sourceDurationSec
  • response.source.type
  • response.sourceVersion
  • response.stages
  • response.stages.creativeConcept
  • response.stages.emotionMap
  • response.stages.narrativeArc
  • response.staleReason
  • response.status
  • response.title
  • response.updatedAt
  • response.version
  • response.warningCodes
GET /api/v1/mv/{mvId}/final Get final MV download URL
Description and searchable fields

Read or refresh the current final MP4 URL. Returns a fresh short-lived presigned URL (60 minutes by default) only when ready=true and the final asset matches the current source composition. Stale or missing finals return ready=false with sourceVersion/finalizedVersion/staleReason/actionHint diagnostics. The response includes `videoUrl`; fetch it directly. `id` identifies the final asset and differs from `mvId`.

  • path.mvId — MV identifier returned by create or read operations.
  • response.actionHint
  • response.expiresInSec
  • response.failureCode
  • response.failureMessage
  • response.finalizationRequired
  • response.finalizedVersion
  • response.id
  • response.isCurrent
  • response.pollAfterSec
  • response.ready
  • response.retainedUntil
  • response.retryable
  • response.sourceVersion
  • response.staleReason
  • response.status
  • response.urlExpiresAt
  • response.videoUrl
POST /api/v1/mv/{mvId}/finalize Finalize MV
Description and searchable fields

Create or refresh the final MP4 asset. Fast create normally auto-finalizes; explicit Fast finalize is used to recover a missing/failed final or recompose after successful Fast scene edits. For Fast, expectedVersion is recommended; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio finalize stitches selected scene renderings and requires MVView.version as expectedVersion.

  • path.mvId — MV identifier returned by create or read operations.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.expectedVersion — Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.retry — Whether to retry a supported failed operation.
  • body.expectedVersion — Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.
  • body.scenes — Explicit Studio scene/rendering selections.
  • body.scenes[].renderingId — Scene rendering-history identifier to select.
  • body.scenes[].sceneIndex — Zero-based scene index.
  • body.selectLatest — Whether Studio should select the latest ready rendering per scene.
  • body.title — Optional customer-facing title.
  • response.compositionHash
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.finalMvId
  • response.idempotent
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.message
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.retryable
  • response.status
  • response.taskId
  • response.warningCodes
POST /api/v1/mv/{mvId}/lock-character Lock Studio character anchor
Description and searchable fields

Attach a public character portrait URL as the Studio character anchor. Requires the MVView.version as expectedVersion and supports quoteId/maxCredits spend confirmation.

  • path.mvId — MV identifier returned by create or read operations.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.characterImage — Public character reference image URL.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.description — Optional customer-facing resource description.
  • body.expectedVersion — Required Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.taskId
  • response.warningCodes
GET /api/v1/mv/{mvId}/operations List MV operations and costs
Description and searchable fields

Returns quote/task linkage and charged, refunded, and net credits for this MV.

  • path.mvId — MV identifier returned by create or read operations.
  • query.limit —
  • response.costSummary
  • response.costSummary.authorizedCredits
  • response.costSummary.chargedCredits
  • response.costSummary.netSpentCredits
  • response.costSummary.operationCount
  • response.costSummary.refundedCredits
  • response.items
  • response.items[].authorizedCredits
  • response.items[].chargedCredits
  • response.items[].createdAt
  • response.items[].expectedVersion
  • response.items[].netCredits
  • response.items[].operation
  • response.items[].operationId
  • response.items[].quoteId
  • response.items[].refundedCredits
  • response.items[].settlementStatus
  • response.items[].taskId
  • response.items[].taskStatus
POST /api/v1/mv/{mvId}/operations/{taskId}/cancel Cancel MV operation
Description and searchable fields

Cancels and refunds an active MV task before Provider submission. After submission, cancellation succeeds only when the Provider confirms remote cancellation; otherwise the operation remains active and this endpoint returns 409.

  • path.mvId — MV identifier returned by create or read operations.
  • path.taskId — OmnAPI task identifier.
  • response.message
  • response.providerCancellationSupported
  • response.refundedCredits
  • response.status
  • response.success
  • response.taskId
POST /api/v1/mv/{mvId}/scenes/render-batch Render multiple Studio scenes
Description and searchable fields

Creates one parent task and one direct-debit charge for 1-30 Studio scenes. Use a render-batch quoteId and maxCredits to confirm the total before execution. Per-scene failures remain individually visible and component usage drives settlement.

  • path.mvId — MV identifier returned by create or read operations.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.aspectRatio — Requested output aspect ratio.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.draft — Whether to use the supported draft rendering policy.
  • body.expectedVersion — Optimistic-concurrency guard using the current resource version.
  • body.fps — Requested numeric output frame rate.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.resolution — Requested output resolution.
  • body.sceneIndexes — Unique zero-based scene indexes included in the operation.
  • body.videoModel — Public scene-video model code.
  • body.videoProvider — Public scene-video option code.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.sceneIndexes
  • response.taskId
  • response.warningCodes
PATCH /api/v1/mv/{mvId}/scenes/{sceneIndex} Edit Studio scene
Description and searchable fields

Persistently edits Studio prompts, framing, mood, lyrics window, or timing. The backend invalidates dependent image/video/final assets and increments both scene and MV versions.

  • path.mvId — MV identifier returned by create or read operations.
  • path.sceneIndex — Zero-based scene index from the MV storyboard.
  • body.endSec — Scene or source-range end time in seconds.
  • body.expectedVersion — Optimistic-concurrency guard using the current resource version.
  • body.framing — Persistent scene framing direction.
  • body.imagePrompt — Image-generation or persistent scene-image instruction.
  • body.lighting — Persistent scene lighting direction.
  • body.lyricsWindow — Lyric context associated with this scene.
  • body.mood — Requested musical or visual mood.
  • body.startSec — Scene or source-range start time in seconds.
  • body.videoPrompt — Persistent or one-shot scene-video instruction.
  • response.finalizationRequired
  • response.invalidated
  • response.mvId
  • response.requiresImageRegeneration
  • response.sceneIndex
  • response.sceneVersion
  • response.version
POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/regenerate-image Regenerate Studio scene image
Description and searchable fields

Regenerate one Studio scene still image without changing the rest of the storyboard. Requires the MVView.version as expectedVersion.

  • path.mvId — MV identifier returned by create or read operations.
  • path.sceneIndex — Zero-based scene index from the MV storyboard.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.expectedVersion — Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.
  • body.imagePrompt — Image-generation or persistent scene-image instruction.
  • body.imagePromptOverride — One-shot scene-image prompt override.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.taskId
  • response.warningCodes
POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/render Render MV scene
Description and searchable fields

Render one MV scene. Studio creates a candidate scene video from the current scene image and requires MVView.version as expectedVersion. Fast edits the currently selected generated scene and accepts prompt, optional referenceImages replacement, expectedVersion, config, and prompt compatibility aliases. Omitting referenceImages preserves the source scene images. Fast rejects durationSec/resolution/render controls; scene-edit billing uses saved Fast scene metadata.

  • path.mvId — MV identifier returned by create or read operations.
  • path.sceneIndex — Zero-based scene index from the MV storyboard.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.aspectRatio — Requested output aspect ratio.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.draft — Whether to use the supported draft rendering policy.
  • body.durationSec — Studio-only render control. Fast scene edit rejects client-supplied durationSec; Fast scene-edit billing uses saved scene metadata.
  • body.expectedVersion — Optimistic-concurrency guard. Fast may omit it for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio requires it and rejects stale values with 409.
  • body.fps — Requested numeric output frame rate.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.prompt — Cross-mode prompt. Fast scene edit uses this as the official instruction field; Studio treats it as a one-shot video prompt override.
  • body.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.referenceImages — Public reference image URLs.
  • body.resolution — Requested output resolution.
  • body.videoModel — Public scene-video model code.
  • body.videoPrompt — Alias of videoPromptOverride for Studio. Fast accepts this only as a compatibility alias for prompt.
  • body.videoPromptOverride — Studio one-shot video prompt override. Fast accepts this only as a compatibility alias for prompt.
  • body.videoProvider — Public scene-video option code.
  • response.charged
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.renderingId
  • response.requestId
  • response.sceneIndex
  • response.taskId
  • response.version
  • response.warningCodes
PATCH /api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering Select scene rendering
Description and searchable fields

Choose which completed scene rendering should be used by finalization. Fast uses MVView.scenes[].renderingHistory[].id and recomposes selected Vidu jobs; Studio selects the storyboard rendering. Requires the MVView.version as expectedVersion.

  • path.mvId — MV identifier returned by create or read operations.
  • path.sceneIndex — Zero-based scene index from the MV storyboard.
  • body.expectedVersion — MV optimistic-concurrency guard: the MVView.version this selection is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.
  • body.renderingId — Scene rendering-history identifier to select.
  • response.finalizationRequired
  • response.finalizeAction
  • response.mvId
  • response.sceneIndex
  • response.selectedRenderingId
  • response.staleReason
  • response.storyboardId
  • response.version

Pricing

Read the Pricing guide

Method and pathOperation
GET /api/v1/pricing/catalog Get public pricing catalog — no API key required
Description and searchable fields

Returns the public pricing catalog used by omnapi.com and docs. The catalog is generated from the same runtime pricing functions used for task credit deduction.

  • response.apiPricingDetails
  • response.apiPricingDetails[].allowedValues
  • response.apiPricingDetails[].apiName
  • response.apiPricingDetails[].billingUnit
  • response.apiPricingDetails[].costLabel
  • response.apiPricingDetails[].credits
  • response.apiPricingDetails[].creditsLabel
  • response.apiPricingDetails[].endpoint
  • response.apiPricingDetails[].exampleLabel
  • response.apiPricingDetails[].id
  • response.apiPricingDetails[].model
  • response.apiPricingDetails[].notes
  • response.apiPricingDetails[].operation
  • response.apiPricingDetails[].parameters
  • response.apiPricingDetails[].pricingFormula
  • response.apiPricingDetails[].pricingFormula.creditsPerUnit
  • response.apiPricingDetails[].pricingFormula.defaultCostGuardUsdPerUnit
  • response.apiPricingDetails[].pricingFormula.kind
  • response.apiPricingDetails[].pricingFormula.minimumCredits
  • response.apiPricingDetails[].pricingFormula.referenceUsdPerUnit
  • response.apiPricingDetails[].pricingFormula.unitSeconds
  • response.apiPricingDetails[].productLine
  • response.apiPricingDetails[].sourceBasis
  • response.apiProducts
  • response.apiProducts[].category
  • response.apiProducts[].costLabel
  • response.apiProducts[].creditsLabel
  • response.apiProducts[].creditsPerRequest
  • response.apiProducts[].description
  • response.apiProducts[].docsPath
  • response.apiProducts[].icon
  • response.apiProducts[].id
  • response.apiProducts[].includeInUsageExamples
  • response.apiProducts[].name
  • response.apiProducts[].usageUnitLabel
  • response.checkoutFeeBps
  • response.creditPackages
  • response.creditPackages[].credits
  • response.creditPackages[].description
  • response.creditPackages[].id
  • response.creditPackages[].name
  • response.creditPackages[].price — Package price in USD.
  • response.creditsExpirationYears
  • response.updatedAt — Catalog effective date in YYYY-MM-DD format.
  • response.version — Immutable pricing-catalog version.
  • response.welcomeCredits

Producer

Read the Producer guide

Method and pathOperation
POST /api/v1/producer/generate/image Generate Image
Description and searchable fields

Create an image generation task using Producer service.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.prompt — Image generation prompt
  • response.creditsRequired — Exact credits deducted to start the task
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId — Task unique identifier
  • response.warningCodes
POST /api/v1/producer/generate/lyrics Generate Lyrics
Description and searchable fields

Create a lyrics generation task using Producer service.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.prompt — Text prompt for lyrics generation
  • response.creditsRequired — Exact credits deducted to start the task
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId — Task unique identifier
  • response.warningCodes
POST /api/v1/producer/generate/music/compose Generate Music (Compose)
Description and searchable fields

Queue a Producer compose task: supports lyrics/instrumental, sound prompt, seed/bpm/length, title, and optional cover image.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.advancedMode — Deprecated compatibility field; Producer compose ignores this value.
  • body.bpm — Optional BPM hint
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.conversationId — Existing Producer conversation identifier to continue.
  • body.currentSongId — Optional current song id used for queue/context continuity
  • body.imageId — Optional cover image id
  • body.imagePrompt — Optional prompt for generating a cover image
  • body.instrumental — Whether to force instrumental generation
  • body.length — Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.
  • body.lyrics — Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.
  • body.lyricsId — Optional existing lyrics id
  • body.model — Model identifier accepted by this schema variant.
  • body.seed — Optional seed value
  • body.soundPrompt — Sound prompt for music generation
  • body.title — Optional customer-facing title.
  • response.creditsRequired — Exact credits deducted to start the task
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId — Task unique identifier
  • response.warningCodes
POST /api/v1/producer/generate/music/modify Generate Music (Modify)
Description and searchable fields

Queue a Producer edit. Current deterministic modes (extend, cover, replace) use Recipe + audio__render_edit; legacy swap modes use conversation interpretation.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.clipId — Source clip id to modify
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.conversationId — Optional existing conversation id to reuse
  • body.cropEndAt — Deprecated alias for extendFromSeconds
  • body.currentSongId — Optional current song id for client_context; defaults to clipId
  • body.extendFromSeconds — Source timestamp where extension begins
  • body.extendSeconds — Seconds generated by ExtendSection
  • body.imageId — Optional output cover image id
  • body.lyrics — New lyrics (useful for cover / swap_vocals)
  • body.lyricsId — Optional lyrics id paired with lyrics when using conversation-based modify flows
  • body.modifyMode — Producer modification transport mode.
  • body.prompt — Additional modification instructions
  • body.regions — Ordered, non-overlapping regions for ReplaceSection
  • body.regions[].end — Region end timestamp in seconds
  • body.regions[].start — Region start timestamp in seconds
  • body.replaceEndAt — Deprecated single-region alias for regions[].end
  • body.replaceStartAt — Deprecated single-region alias for regions[].start
  • body.seed — Optional deterministic seed for the modification
  • body.soundPrompt — New sound prompt (useful for swap_sound)
  • body.strength — Cover similarity strength (0-1)
  • body.tags — Style tags for the modified clip
  • body.title — Optional customer-facing title.
  • body.transform — Producer music modification operation.
  • response.creditsRequired — Exact credits deducted to start the task
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId — Task unique identifier
  • response.warningCodes

Subtitles

Read the Subtitles guide

Method and pathOperation
POST /api/v1/subtitles/ Create subtitle extraction task
Description and searchable fields

Extract lyrics and aligned subtitle artifacts from a public audio URL.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.budget — Public price guard for this request.
  • body.budget.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.language — Requested or known language code/name.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.mode — Operation or product mode discriminator for this schema variant.
  • body.outputs — Requested subtitle artifact formats.
  • body.source — Public source media or product reference.
  • body.source.audioUrl — Public HTTP(S) audio URL.
  • body.source.durationSec — Requested or known media duration in seconds.
  • body.source.type — Source or product type discriminator.
  • response.creditsRequired
  • response.pollUrl
  • response.status
  • response.taskId
POST /api/v1/subtitles/quote Quote subtitle extraction
Description and searchable fields

Estimate credits and public price for audio-to-lyrics subtitle extraction.

  • body.budget — Public price guard for this request.
  • body.budget.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.language — Requested or known language code/name.
  • body.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.mode — Operation or product mode discriminator for this schema variant.
  • body.outputs — Requested subtitle artifact formats.
  • body.source — Public source media or product reference.
  • body.source.audioUrl — Public HTTP(S) audio URL.
  • body.source.durationSec — Requested or known media duration in seconds.
  • body.source.type — Source or product type discriminator.
  • response.credits
  • response.durationSec
  • response.estimatedUsd
  • response.maxCostUsdPerMin
  • response.publicUsdPerMin
GET /api/v1/subtitles/{id} Get subtitle task
Description and searchable fields

Get subtitle extraction task status and artifacts.

  • path.id — Resource identifier returned by the corresponding create operation.
  • response.artifacts
  • response.artifacts.json
  • response.artifacts.json.expiresAt
  • response.artifacts.json.retentionDays
  • response.artifacts.json.url
  • response.artifacts.jsonUrl
  • response.artifacts.lrc
  • response.artifacts.lrc.expiresAt
  • response.artifacts.lrc.retentionDays
  • response.artifacts.lrc.url
  • response.artifacts.lrcUrl
  • response.artifacts.srt
  • response.artifacts.srt.expiresAt
  • response.artifacts.srt.retentionDays
  • response.artifacts.srt.url
  • response.artifacts.srtUrl
  • response.artifacts.vtt
  • response.artifacts.vtt.expiresAt
  • response.artifacts.vtt.retentionDays
  • response.artifacts.vtt.url
  • response.artifacts.vttUrl
  • response.errorCode
  • response.errorMessage
  • response.lyrics
  • response.progress
  • response.status
  • response.taskId
  • response.timeline
  • response.timeline.lines
  • response.timeline.lines[].endSec
  • response.timeline.lines[].section
  • response.timeline.lines[].startSec
  • response.timeline.lines[].text
  • response.timeline.words
  • response.timeline.words[].endSec
  • response.timeline.words[].startSec
  • response.timeline.words[].text
  • response.warnings

Suno

Read the Suno guide

Method and pathOperation
GET /api/v1/suno/assets List retained Suno assets
Description and searchable fields

Tenant-owned new-policy deliveries remain discoverable independently of Task history. Historical permanent assets remain on their original access paths.

  • query.cursor — Opaque pagination cursor returned as nextCursor; omit it on the first page.
  • query.limit — Maximum number of items to return.
  • response.items
  • response.items[].byteLength
  • response.items[].clipId
  • response.items[].deliveredAt
  • response.items[].format
  • response.items[].id
  • response.items[].policy
  • response.items[].retainedUntil
  • response.items[].status
  • response.nextCursor
GET /api/v1/suno/assets/{id}/download Get a retained Suno asset download
Description and searchable fields

Returns a private URL valid for at most one hour and never beyond retention. Expired deliveries return 410; other users' assets return 404. Lyrics downloads are gzip-compressed JSON snapshots.

  • path.id — Resource identifier returned by the corresponding create operation.
  • response.byteLength
  • response.clipId
  • response.deliveredAt
  • response.format
  • response.id
  • response.policy
  • response.retainedUntil
  • response.status
  • response.url
  • response.urlExpiresAt
GET /api/v1/suno/availability Get Suno availability
Description and searchable fields

Advisory delivery health for Suno operations, including whether advanced operations are currently available.

  • response.checkedAt
  • response.checks
  • response.checks[].message
  • response.checks[].name
  • response.checks[].status
  • response.guidance
  • response.message
  • response.retryAfterSec
  • response.status
  • response.subscriptionOperationsAvailable — Whether advanced Suno operations are currently available.
GET /api/v1/suno/clips Query multiple clips
Description and searchable fields

Free direct batch read with the same per-clip access projection as the detail endpoint. Preserves request order, reports definitively absent IDs in missingClipIds, and reserves errors for transient per-ID read failures. No Task is created and no credits are charged.

  • query.clipIds —
  • response.errors
  • response.errors[].clipId
  • response.errors[].code
  • response.errors[].message
  • response.errors[].retryable
  • response.items
  • response.items[].accessLevel
  • response.items[].audioUrl
  • response.items[].clipId — Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.
  • response.items[].createdAt
  • response.items[].deliveryStatus
  • response.items[].duration
  • response.items[].errorCode
  • response.items[].errorMessage
  • response.items[].imageUrl
  • response.items[].index
  • response.items[].instrumental
  • response.items[].majorModelVersion
  • response.items[].model
  • response.items[].modelCode
  • response.items[].playable
  • response.items[].playback
  • response.items[].playback.delivery
  • response.items[].playback.expiresAt
  • response.items[].playback.mimeType
  • response.items[].playback.retryAfterMs
  • response.items[].playback.seekable
  • response.items[].playback.sessionCreateUrl
  • response.items[].playback.state
  • response.items[].playback.url
  • response.items[].prompt
  • response.items[].providerModelName
  • response.items[].role
  • response.items[].tags
  • response.items[].title
  • response.items[].updatedAt
  • response.items[].videoUrl
  • response.missingClipIds
GET /api/v1/suno/clips/{clipId} Get clip detail
Description and searchable fields

Free direct resource read. `clipId` is the external Suno ID (legacy `mid`), never a TaskResult database ID. `accessLevel` controls field projection only: owned clips return the full contract, shared clips are public or remixable, and other readable external clips return minimal media fields. It does not grant derive or export permission. No Task is created or charged.

  • path.clipId — Suno clip identifier returned by a Generation or clip read.
  • response.accessLevel
  • response.audioUrl
  • response.clipId — Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.
  • response.createdAt
  • response.deliveryStatus
  • response.duration
  • response.errorCode
  • response.errorMessage
  • response.imageUrl
  • response.index
  • response.instrumental
  • response.majorModelVersion
  • response.model
  • response.modelCode
  • response.playable
  • response.playback
  • response.playback.delivery
  • response.playback.expiresAt
  • response.playback.mimeType
  • response.playback.retryAfterMs
  • response.playback.seekable
  • response.playback.sessionCreateUrl
  • response.playback.state
  • response.playback.url
  • response.prompt
  • response.providerModelName
  • response.role
  • response.tags
  • response.title
  • response.updatedAt
  • response.videoUrl
GET /api/v1/suno/clips/{clipId}/audio-analysis Get clip audio analysis
Description and searchable fields

Aggregates Suno downbeats, musical-key and waveform-mipmap analysis. Short sync-wait; returns 202 with taskId on timeout.

  • path.clipId — Suno clip identifier returned by a Generation or clip read.
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.outputResults.clipId
  • response.outputResults.downbeats
  • response.outputResults.key
  • response.outputResults.waveform
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier
POST /api/v1/suno/clips/{clipId}/derive Derive a clip
Description and searchable fields

Extend or cover an existing Suno clip. Extend includes automatic Concat finalization in the same task and charge; use the resource with role=final as the complete song. There is no public Concat endpoint.

  • path.clipId —
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • header.Prefer — Set to respond-async to skip the acknowledgement wait and return the generation receipt immediately.
  • body.action — Operation action selected for this request.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.continueAt — Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.
  • body.continuedAlignedPrompt — Optional aligned continuation prompt for action=extend.
  • body.controlSliders — Optional bounded generation-control weights.
  • body.controlSliders.audio_weight — Source-audio adherence weight from 0 to 1.
  • body.controlSliders.style_weight — Style adherence weight from 0 to 1.
  • body.controlSliders.weirdness_constraint — Creative-variation constraint from 0 to 1.
  • body.isInstrumental — Optional instrumental intent for the derived result.
  • body.isRemix — Optional remix intent for the derived result.
  • body.model — Model identifier accepted by this schema variant.
  • body.negativeTags — Negative music-style tags or exclusions.
  • body.prompt — Primary creative or operation instruction.
  • body.tags — Style tags or caller labels, as defined by this schema.
  • body.title — Optional customer-facing title.
  • response.autoFinalize
  • response.clipIds
  • response.creditsRequired
  • response.deliveryStatus
  • response.estimatedCompletionTime
  • response.finalUrl
  • response.generationId
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pollUrl
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize
  • response.product.deliveryStatus
  • response.product.featureCode
  • response.product.modelCode
  • response.product.providerCode
  • response.product.resourceId
  • response.product.type
  • response.requestId
  • response.status
  • response.taskId
  • response.viewUrl
  • response.warningCodes
POST /api/v1/suno/clips/{clipId}/export Export clip audio
Description and searchable fields

Export M4A (1 standard credit), MP3 (2), WAV (3), or separated tracks. WAV delivers the requested original clip. Twelve stems cost 140; Extract costs 56. Customer pricing applies to every operation. When managed storage is available, new ordinary audio has a 14-day retention period, extendable through explicitly enabled paid storage; WAV has fixed 180-day retention. Read retainedUntil and urlExpiresAt on returned resources. Refresh private URLs through task or asset reads; signed URLs last at most one hour and never outlive retention. Existing permanent delivery rights remain valid for the same customer. Never construct or assume permanent download URLs.

  • path.clipId — Suno clip identifier returned by a Generation or clip read.
  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.format — Requested output format discriminator.
  • body.format — Export an M4A audio file. New managed deliveries have a 14-day retention period and renewable signed URLs; existing permanent delivery rights are preserved. Your account pricing applies to separately requested exports. Automatic audio delivery for a Suno creation task has no additional charge.
  • body.format — 2-standard-credit MP3 export. Use the returned URL; do not construct download URLs. For managed assets, inspect retainedUntil and refresh expiring URLs through asset reads.
  • body.format — Separated audio tracks.
  • body.stemName — Required for stemsMode=extract. Use one exact canonical value from this enum.
  • body.stemsMode — twelve = full split (140 standard credits, default); extract = isolate/remove one named stem (56 standard credits). Suno no longer supports two.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId
  • response.warningCodes
GET /api/v1/suno/clips/{clipId}/timeline Get aligned lyrics timeline
Description and searchable fields

Word/line-level timestamps for a clip. Short sync-wait; returns 202 with taskId on timeout.

  • path.clipId — Suno clip identifier returned by a Generation or clip read.
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.outputResults.clipId
  • response.outputResults.lines
  • response.outputResults.lines[].end
  • response.outputResults.lines[].section
  • response.outputResults.lines[].start
  • response.outputResults.lines[].text
  • response.outputResults.lines[].words
  • response.outputResults.waveform_data
  • response.outputResults.words
  • response.outputResults.words[].confidence
  • response.outputResults.words[].end
  • response.outputResults.words[].start
  • response.outputResults.words[].success
  • response.outputResults.words[].word
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier
GET /api/v1/suno/generations List Suno generations
Description and searchable fields

Cursor-paginated product history. The cursor is opaque; do not construct it client-side.

  • query.limit — Maximum number of items to return.
  • query.cursor — Opaque pagination cursor returned as nextCursor; omit it on the first page.
  • response.hasMore
  • response.items
  • response.items[].autoFinalize
  • response.items[].billing
  • response.items[].billing.creditsCharged
  • response.items[].billing.creditsRequired
  • response.items[].billing.pricing
  • response.items[].billing.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.items[].billing.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.items[].billing.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.items[].billing.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.items[].billing.pricing.chargedCredits — Frozen task charge. New whole-credit quotes are integers; historical fractional quotes retain up to four decimal places.
  • response.items[].billing.pricing.quoteVersion — Pricing quote version stored with the task
  • response.items[].billing.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.items[].billing.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.items[].billing.pricing.source — Public pricing source category
  • response.items[].billing.refunded
  • response.items[].billing.settlementStatus
  • response.items[].clips
  • response.items[].clips[].accessLevel
  • response.items[].clips[].audioUrl
  • response.items[].clips[].clipId — Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.
  • response.items[].clips[].createdAt
  • response.items[].clips[].deliveryStatus
  • response.items[].clips[].duration
  • response.items[].clips[].errorCode
  • response.items[].clips[].errorMessage
  • response.items[].clips[].imageUrl
  • response.items[].clips[].index
  • response.items[].clips[].instrumental
  • response.items[].clips[].majorModelVersion
  • response.items[].clips[].model
  • response.items[].clips[].modelCode
  • response.items[].clips[].playable
  • response.items[].clips[].playback
  • response.items[].clips[].playback.delivery
  • response.items[].clips[].playback.expiresAt
  • response.items[].clips[].playback.mimeType
  • response.items[].clips[].playback.retryAfterMs
  • response.items[].clips[].playback.seekable
  • response.items[].clips[].playback.sessionCreateUrl
  • response.items[].clips[].playback.state
  • response.items[].clips[].playback.url
  • response.items[].clips[].prompt
  • response.items[].clips[].providerModelName
  • response.items[].clips[].role
  • response.items[].clips[].tags
  • response.items[].clips[].title
  • response.items[].clips[].updatedAt
  • response.items[].clips[].videoUrl
  • response.items[].createdAt
  • response.items[].deliveryStatus
  • response.items[].failureReason
  • response.items[].finalClipId
  • response.items[].finalUrl
  • response.items[].generationId — Canonical OmnAPI Suno product ID. It equals the originating taskId.
  • response.items[].partialFailure — True when the generation completed with at least one successful clip and at least one failed clip.
  • response.items[].phase
  • response.items[].progress
  • response.items[].refundable
  • response.items[].retryable
  • response.items[].status
  • response.items[].taskId
  • response.items[].updatedAt
  • response.items[].version
  • response.items[].warningCodes
  • response.nextCursor
GET /api/v1/suno/generations/{generationId} Get a Suno generation
Description and searchable fields

Canonical product view for one Suno generation. It exposes every candidate's submitted/queued/streaming/complete/error lifecycle independently. Use GET /api/v1/tasks/{taskId} for execution and billing diagnostics.

  • path.generationId — Suno Generation identifier returned by song creation.
  • response.autoFinalize
  • response.billing
  • response.billing.creditsCharged
  • response.billing.creditsRequired
  • response.billing.pricing
  • response.billing.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.billing.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.billing.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.billing.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.billing.pricing.chargedCredits — Frozen task charge. New whole-credit quotes are integers; historical fractional quotes retain up to four decimal places.
  • response.billing.pricing.quoteVersion — Pricing quote version stored with the task
  • response.billing.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.billing.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.billing.pricing.source — Public pricing source category
  • response.billing.refunded
  • response.billing.settlementStatus
  • response.clips
  • response.clips[].accessLevel
  • response.clips[].audioUrl
  • response.clips[].clipId — Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.
  • response.clips[].createdAt
  • response.clips[].deliveryStatus
  • response.clips[].duration
  • response.clips[].errorCode
  • response.clips[].errorMessage
  • response.clips[].imageUrl
  • response.clips[].index
  • response.clips[].instrumental
  • response.clips[].majorModelVersion
  • response.clips[].model
  • response.clips[].modelCode
  • response.clips[].playable
  • response.clips[].playback
  • response.clips[].playback.delivery
  • response.clips[].playback.expiresAt
  • response.clips[].playback.mimeType
  • response.clips[].playback.retryAfterMs
  • response.clips[].playback.seekable
  • response.clips[].playback.sessionCreateUrl
  • response.clips[].playback.state
  • response.clips[].playback.url
  • response.clips[].prompt
  • response.clips[].providerModelName
  • response.clips[].role
  • response.clips[].tags
  • response.clips[].title
  • response.clips[].updatedAt
  • response.clips[].videoUrl
  • response.createdAt
  • response.deliveryStatus
  • response.failureReason
  • response.finalClipId
  • response.finalUrl
  • response.generationId — Canonical OmnAPI Suno product ID. It equals the originating taskId.
  • response.partialFailure — True when the generation completed with at least one successful clip and at least one failed clip.
  • response.phase
  • response.progress
  • response.refundable
  • response.retryable
  • response.status
  • response.taskId
  • response.updatedAt
  • response.version
  • response.warningCodes
POST /api/v1/suno/lyrics Generate Lyrics
Description and searchable fields

Create lyrics without changing the established request contract. `candidates=2` succeeds only after both ordered A/B candidates complete. Each completed text resource may include `metadata.stylePrompt` and compatibility `metadata.tags: [stylePrompt]`; style expansion is best-effort and never turns completed lyrics into a failed Task. The optional `lyricsModel` currently accepts only `default`. Returns a task id — poll `GET /api/v1/tasks/{taskId}` for the result. `Idempotency-Key` is optional but recommended for safe client retries. For a synchronous lyrics call, use `POST /api/v1/lyrics/generate`.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.candidates — Number of independent candidates to generate.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.lyricsModel — Only the stable "default" lyrics model is supported for candidates=2.
  • body.prompt — Primary creative or operation instruction.
  • body.source — Optional caller label retained in Task audit input for candidates=2.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId
  • response.warningCodes
POST /api/v1/suno/songs Generate Song
Description and searchable fields

Create a song from text, a confirmed public Voice, or a managed upload + Extend/Cover workflow.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • header.Prefer — Set to respond-async to skip the acknowledgement wait and return the generation receipt immediately.
  • body.audio — Public audio source and format information.
  • body.audio.extensionType — Audio filename or media extension hint.
  • body.audio.url — Publicly retrievable audio URL used only by upload-extend or upload-cover.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.continueAt — Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.
  • body.continuedAlignedPrompt — Aligned continuation prompt used for an Extend operation.
  • body.controlSliders — Optional bounded generation-control weights.
  • body.controlSliders.audio_weight — Source-audio adherence weight from 0 to 1.
  • body.controlSliders.style_weight — Style adherence weight from 0 to 1.
  • body.controlSliders.weirdness_constraint — Creative-variation constraint from 0 to 1.
  • body.instrumental — Whether to generate an instrumental result.
  • body.lyrics — Lyrics or lyric context supplied to the operation.
  • body.mode — Generation mode. Vox accepts the three v6 generation models with account-specific permission checks; unsupported model combinations are rejected before task creation. Upload modes atomically import the supplied audio and then Extend or Cover it; standalone upload is not exposed.
  • body.model — Model identifier accepted by this schema variant.
  • body.negativeTags — Negative music-style tags or exclusions.
  • body.prompt — Primary creative or operation instruction.
  • body.tags — Style tags or caller labels, as defined by this schema.
  • body.title — Optional customer-facing title.
  • body.voiceId — Reusable public Suno Voice identifier.
  • response.autoFinalize
  • response.clipIds
  • response.creditsRequired
  • response.deliveryStatus
  • response.estimatedCompletionTime
  • response.finalUrl
  • response.generationId
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pollUrl
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize
  • response.product.deliveryStatus
  • response.product.featureCode
  • response.product.modelCode
  • response.product.providerCode
  • response.product.resourceId
  • response.product.type
  • response.requestId
  • response.status
  • response.taskId
  • response.viewUrl
  • response.warningCodes
GET /api/v1/suno/storage Inspect Suno storage policy, rate and subscription
Description and searchable fields

Read availability, the current published storage rate, active subscription, billable bytes and unpaid usage. Check available before offering paid storage enrollment. All amounts are integer credit units represented as strings.

  • response.audioFreeDays
  • response.available
  • response.billableBytes
  • response.billingUnit
  • response.cancellationGraceDays
  • response.fixedRetentionDays
  • response.publishedRateUnitsPerGbMonth
  • response.subscription
  • response.subscription.graceUntil
  • response.subscription.meteredThrough
  • response.subscription.rateUnitsPerGbMonth
  • response.subscription.status
  • response.subscription.stoppedAt
  • response.unpaidUnits
PUT /api/v1/suno/storage Opt in to or cancel paid long-term audio storage
Description and searchable fields

Explicitly accepts the published unit rate and includes currently live ordinary audio and future deliveries. WAV and timestamp lyrics stay fixed at 180 days. Billing starts after the first 14 days and settles daily. Cancellation stops accrual and grants a 7-day download grace period. Expired assets are not revived.

  • body.acceptedRateUnits — Current publishedRateUnitsPerGbMonth accepted by the customer. Required to enable a new subscription; obtain it from GET /api/v1/suno/storage.
  • body.enabled — True explicitly enables paid long-term ordinary audio storage; false cancels accrual and starts the download grace period.
  • response.graceUntil
  • response.meteredThrough
  • response.rateUnitsPerGbMonth
  • response.status
  • response.stoppedAt
GET /api/v1/suno/storage/charges List Suno storage charges
Description and searchable fields

Exact usage, captured rate and debit state; amounts are integer credit units.

  • query.cursor — Opaque pagination cursor returned as nextCursor; omit it on the first page.
  • query.limit — Maximum number of items to return.
  • response.items
  • response.items[].amountUnits
  • response.items[].byteMilliseconds
  • response.items[].from
  • response.items[].id
  • response.items[].rateUnitsPerGbMonth
  • response.items[].status
  • response.items[].until
  • response.nextCursor
GET /api/v1/suno/styles/recommend Recommend Styles
Description and searchable fields

Style suggestions. Short sync-wait; returns 202 with taskId on timeout.

  • query.exclude —
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.outputResults.recommendStyles
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier
GET /api/v1/suno/voices List Voices
Description and searchable fields

Lists only fully completed public Voices created by the current OmnAPI user. Private, test, intermediate, and partially completed Voices are excluded.

  • query.page —
  • query.pageSize —
  • response.currentPage
  • response.pageSize
  • response.totalResults
  • response.voices
  • response.voices[].createdAt
  • response.voices[].description
  • response.voices[].imageUrl
  • response.voices[].name
  • response.voices[].sourceClipId
  • response.voices[].voiceId
  • response.voices[].voiceType
POST /api/v1/suno/voices Create Voice
Description and searchable fields

Creates a public Voice from verified recordings. First obtain a verification phrase, record it, then submit `verificationPhraseTaskId`, the verification recording URL, and the clean singing URL. Only the final public Voice is returned.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.description — Optional customer-facing resource description.
  • body.imageUrl — Optional public image URL for the resulting Voice.
  • body.name — Customer-facing resource name.
  • body.verificationAudioUrl — Recording of the requested verification phrase from the same speaker.
  • body.verificationExtensionType — Verification recording extension hint.
  • body.verificationPhraseTaskId — Completed verification-phrase Task identifier.
  • body.voiceAudioUrl — Clean singing recording URL used to create the public Voice.
  • body.voiceExtensionType — Voice recording extension hint.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId
  • response.warningCodes
POST /api/v1/suno/voices/from-clip Create Voice from Clip
Description and searchable fields

Creates a reusable public Voice from a completed clip owned by the caller. This clip-derived workflow does not require a verification phrase or real-person recordings.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.clipId — Completed Suno clip owned by the current OmnAPI user.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.description — Optional customer-facing resource description.
  • body.imageUrl — Optional public image URL for the Voice.
  • body.name — Customer-facing resource name.
  • body.vocalRange — Optional source-clip vocal range. When omitted, OmnAPI selects a continuous singing segment from the effective clip's final lyrics timeline. If a reliable timeline is unavailable, provide this range manually.
  • body.vocalRange.endSeconds — End of the selected vocal range in seconds.
  • body.vocalRange.startSeconds — Start of the selected vocal range in seconds.
  • response.creditsRequired
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId
  • response.warningCodes
GET /api/v1/suno/voices/verification-phrase Get Voice verification phrase
Description and searchable fields

Returns a verification phrase and taskId for subsequent verified Voice creation. Use that taskId as verificationPhraseTaskId when creating the Voice.

  • query.language —
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.outputResults.expiresAt
  • response.outputResults.phraseText
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier
GET /api/v1/suno/voices/{voiceId} Get Voice
Description and searchable fields

Voice detail by ID. There is no OmnAPI ownership restriction: any readable public Voice ID may be queried and then used for generation.

  • path.voiceId — Reusable public Suno Voice identifier.
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.outputResults.voice
  • response.outputResults.voice.createdAt
  • response.outputResults.voice.description
  • response.outputResults.voice.imageUrl
  • response.outputResults.voice.isPublic
  • response.outputResults.voice.name
  • response.outputResults.voice.voiceId
  • response.outputResults.voice.voiceType
  • response.outputResults.voiceId
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier

Tasks

Read the Tasks guide

Method and pathOperation
GET /api/v1/tasks List Tasks
Description and searchable fields

List the current user's tasks, optionally filtered by status / providerCode / appSlug. Keyset pagination is the default; pass `nextCursor` back as `cursor`. Legacy offset pagination requires `cursorMode=false` and is capped at offset 10000.

  • query.status —
  • query.providerCode —
  • query.modelCode —
  • query.featureCode —
  • query.dateFrom —
  • query.dateTo —
  • query.appSlug —
  • query.tag —
  • query.limit — Maximum number of items to return.
  • query.offset — Zero-based pagination offset.
  • query.cursorMode —
  • query.cursor —
  • response.hasMore — Whether there are more tasks (cursor mode)
  • response.items
  • response.items[].createdAt — Task creation timestamp
  • response.items[].creditsCharged
  • response.items[].creditsRequired — Credits deducted to start the task
  • response.items[].errorMessage
  • response.items[].feature
  • response.items[].feature.code — Feature code
  • response.items[].feature.name — Feature name
  • response.items[].featureCode — Feature code
  • response.items[].inputParameters — Task input parameters
  • response.items[].metadata
  • response.items[].model
  • response.items[].model.code — Model code
  • response.items[].model.name — Model display name
  • response.items[].model.version — Model version
  • response.items[].modelCode — Model code
  • response.items[].pricing
  • response.items[].pricing.components
  • response.items[].pricing.quoteVersion — Pricing quote version stored with the task.
  • response.items[].processingCompletedAt
  • response.items[].processingDuration
  • response.items[].processingDurationText
  • response.items[].processingStartedAt
  • response.items[].progress
  • response.items[].provider
  • response.items[].provider.code — Provider code
  • response.items[].provider.name — Provider display name
  • response.items[].providerCode — Provider code
  • response.items[].status
  • response.items[].tags
  • response.items[].taskId — Task unique identifier
  • response.items[].updatedAt — Last update timestamp
  • response.limit — Page size
  • response.nextCursor
  • response.offset — Offset
  • response.total — Total number of tasks (offset mode only)
POST /api/v1/tasks Create Task
Description and searchable fields

Create a new AI task

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.
  • body.inputParameters — Input parameters for the task
  • body.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.model — Public model path in format "providerCode/modelCode/featureCode". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.
  • body.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.inputParameters — Feature-specific input matching the selected model path.
  • body.inputParameters.durationSec — Target duration in seconds.
  • body.inputParameters.explicit — Whether explicit language is allowed.
  • body.inputParameters.extraGuidance — Additional creative guidance and constraints.
  • body.inputParameters.genre — Requested musical genre direction.
  • body.inputParameters.language — Primary lyric language. Use 'auto' to let the model decide.
  • body.inputParameters.languages — Additional languages to include or consider.
  • body.inputParameters.maxTokens — Maximum completion tokens for lyrics generation.
  • body.inputParameters.model — Optional lyrics model override. Defaults to the configured lyrics model.
  • body.inputParameters.mood — Requested musical or visual mood.
  • body.inputParameters.multilingualMode — How multiple languages should be mixed.
  • body.inputParameters.negativeConstraints — Topics, styles, or tropes the output should avoid.
  • body.inputParameters.perspective — Requested lyric narrative perspective.
  • body.inputParameters.prompt — Core song brief, story, scene, or hook idea.
  • body.inputParameters.structure — Requested lyric section order.
  • body.inputParameters.temperature — Sampling temperature for lyrics generation.
  • body.inputParameters.themeKeywords — Short theme anchors for structured lyrics.
  • body.inputParameters.vocalStyle — Requested vocal performance direction.
  • body.model — Public model path in format "providerCode/modelCode/featureCode".
  • body.inputParameters.aspectRatio — Requested output aspect ratio.
  • body.inputParameters.characterImage — Public character reference image URL.
  • body.inputParameters.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.inputParameters.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.inputParameters.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.inputParameters.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.inputParameters.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.inputParameters.generation — Product-specific generation controls.
  • body.inputParameters.generation.creativeMode — Creative intent used by Fast MV prompt and reference planning.
  • body.inputParameters.generation.lipReferenceImages — Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.
  • body.inputParameters.generation.managedVersion — Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.
  • body.inputParameters.generation.motionPreset — Fast MV motion prompt policy.
  • body.inputParameters.generation.performanceMode — Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.
  • body.inputParameters.generation.promptMode — Whether Fast MV preserves or compiles the caller prompt.
  • body.inputParameters.generation.quality — Requested public quality tier.
  • body.inputParameters.generation.referenceStrategy — Fast MV policy for direct or synthesized references.
  • body.inputParameters.generation.style — Requested creative style direction.
  • body.inputParameters.generation.subtitleMode — Fast MV subtitle rendering mode.
  • body.inputParameters.generation.visualBoard — Fast MV Visual Board configuration.
  • body.inputParameters.generation.visualBoard.imageProvider — Public image-generation option code.
  • body.inputParameters.generation.visualBoard.preset — Visual Board speed/detail policy.
  • body.inputParameters.language — Requested or known language code/name.
  • body.inputParameters.lipSync — Whether the MV should use the supported lip-sync workflow.
  • body.inputParameters.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.inputParameters.mode — Operation or product mode discriminator for this schema variant.
  • body.inputParameters.preflightId — Reusable MV preflight snapshot identifier.
  • body.inputParameters.prompt — Primary creative or operation instruction.
  • body.inputParameters.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.inputParameters.referenceImages — Public reference image URLs.
  • body.inputParameters.resolution — Requested output resolution.
  • body.inputParameters.source — Public source media or product reference.
  • body.inputParameters.source.clipId — Source clip identifier.
  • body.inputParameters.source.lyrics — Lyrics or lyric context supplied to the operation.
  • body.inputParameters.source.range — Optional source-media range.
  • body.inputParameters.source.type — Source or product type discriminator.
  • body.inputParameters.source.audioUrl — Public HTTP(S) audio URL.
  • body.inputParameters.source.durationSec — Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.
  • body.inputParameters.srtUrl — Public URL of caller-supplied SRT subtitles.
  • body.inputParameters.subtitle — MV subtitle generation and fallback policy.
  • body.inputParameters.subtitle.fallback — Behavior when the preferred subtitle path cannot complete.
  • body.inputParameters.subtitle.language — Requested or known language code/name.
  • body.inputParameters.subtitle.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.inputParameters.subtitle.mode — Operation or product mode discriminator for this schema variant.
  • body.inputParameters.subtitle.quality — Requested public quality tier.
  • body.inputParameters.subtitle.required — Whether the selected subtitle policy must succeed.
  • body.inputParameters.subtitleColor — Requested subtitle foreground color.
  • body.inputParameters.subtitles — Whether subtitles are enabled for the MV.
  • body.inputParameters.title — Optional customer-facing title.
  • body.inputParameters.generation.imageProvider — Public image-generation option code.
  • body.inputParameters.generation.videoModel — Public scene-video model code.
  • body.inputParameters.generation.videoProvider — Public scene-video option code.
  • body.inputParameters.height — Requested image height in pixels for this model branch.
  • body.inputParameters.prompt — Image generation prompt
  • body.inputParameters.style — Requested creative style direction.
  • body.inputParameters.width — Requested image width in pixels for this model branch.
  • body.inputParameters.numVerses — Requested number of lyric verses.
  • body.inputParameters.prompt — Text prompt for lyrics generation
  • body.inputParameters.advancedMode — Deprecated compatibility field; Producer compose ignores this value.
  • body.inputParameters.bpm — Optional BPM hint
  • body.inputParameters.conversationId — Existing Producer conversation identifier to continue.
  • body.inputParameters.currentSongId — Optional current song id used for queue/context continuity
  • body.inputParameters.imageId — Optional cover image id
  • body.inputParameters.imagePrompt — Optional prompt for generating a cover image
  • body.inputParameters.instrumental — Whether to force instrumental generation
  • body.inputParameters.length — Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.
  • body.inputParameters.lyrics — Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.
  • body.inputParameters.lyricsId — Optional existing lyrics id
  • body.inputParameters.model — Producer music model. 'Lyria 3 preview' is accepted as a deprecated alias for Lyria 3.5.
  • body.inputParameters.seed — Optional seed value
  • body.inputParameters.soundPrompt — Sound prompt for music generation
  • body.inputParameters.clipId — Source clip id to modify
  • body.inputParameters.conversationId — Optional existing conversation id to reuse
  • body.inputParameters.cropEndAt — Deprecated alias for extendFromSeconds
  • body.inputParameters.currentSongId — Optional current song id for client_context; defaults to clipId
  • body.inputParameters.extendFromSeconds — Source timestamp where extension begins
  • body.inputParameters.extendSeconds — Seconds generated by ExtendSection
  • body.inputParameters.imageId — Optional output cover image id
  • body.inputParameters.lyrics — New lyrics (useful for cover / swap_vocals)
  • body.inputParameters.lyricsId — Optional lyrics id paired with lyrics when using conversation-based modify flows
  • body.inputParameters.modifyMode — Modify transport: 'task' uses Recipe + audio__render_edit; 'conversation' lets Producer interpret a legacy/agentic request first.
  • body.inputParameters.prompt — Additional modification instructions
  • body.inputParameters.regions — Ordered, non-overlapping regions for ReplaceSection
  • body.inputParameters.regions[].end — Region end timestamp in seconds
  • body.inputParameters.regions[].start — Region start timestamp in seconds
  • body.inputParameters.replaceEndAt — Deprecated single-region alias for regions[].end
  • body.inputParameters.replaceStartAt — Deprecated single-region alias for regions[].start
  • body.inputParameters.seed — Optional deterministic seed for the modification
  • body.inputParameters.soundPrompt — New sound prompt (useful for swap_sound)
  • body.inputParameters.strength — Cover similarity strength (0-1)
  • body.inputParameters.tags — Style tags for the modified clip
  • body.inputParameters.transform — Current deterministic edit type. inpaint is a deprecated alias for replace; swap_* use the legacy conversation path.
  • body.inputParameters.clipId — Clip ID to analyze
  • body.inputParameters.clipId — Clip ID to fetch detail for
  • body.inputParameters.clipId — Clip ID to get lyrics timeline for
  • body.inputParameters.voiceId — Voice ID to fetch
  • body.inputParameters.page — One-based result page.
  • body.inputParameters.createSessionToken — Optional create session token
  • body.inputParameters.lyricsModel — Only the stable "default" lyrics model is supported for paired candidates
  • body.inputParameters.prompt — Text prompt for generating two lyrics candidates
  • body.inputParameters.source — Caller source tag retained in Task audit input
  • body.inputParameters.mids — Clip identifiers accepted by this model branch.
  • body.inputParameters.version — Requested compatibility or resource version.
  • body.inputParameters.excludedStyles — Styles to exclude from the generated result.
  • body.inputParameters.isInstrumental — Optional instrumental intent for the derived result.
  • body.inputParameters.prompt — Text prompt for simple music generation (GPT description)
  • body.inputParameters.waitAudio — Whether this model branch waits for playable audio before completion.
  • response.creditsRequired — Exact credits deducted to start the task
  • response.estimatedCompletionTime
  • response.links
  • response.links.final
  • response.links.resource
  • response.links.stream — Task SSE stream URL for the created task
  • response.links.task — Task polling URL for the created task
  • response.pricing
  • response.pricing.adjustmentCredits — chargedCredits - baseCredits
  • response.pricing.baseCredits — Standard quoted credits before customer pricing adjustment
  • response.pricing.billingIncrementCredits — Smallest customer charge increment
  • response.pricing.calculatedCredits — Precise whole-order subtotal before settlement rounding
  • response.pricing.chargedCredits — Credits charged for this create request
  • response.pricing.quoteVersion — Pricing quote version stored with the task
  • response.pricing.settlementPolicyVersion — Versioned customer settlement policy
  • response.pricing.settlementRoundingCredits — Whole-order rounding adjustment added at settlement
  • response.pricing.source
  • response.product
  • response.product.autoFinalize — Whether the product should finalize automatically
  • response.product.deliveryStatus
  • response.product.featureCode — Resolved feature code
  • response.product.modelCode — Resolved model code
  • response.product.providerCode — Resolved provider code
  • response.product.resourceId
  • response.product.type — Product family for this task, e.g. suno, producer, mv
  • response.requestId
  • response.status
  • response.taskId — Task unique identifier
  • response.warningCodes
POST /api/v1/tasks/sync Create Task (Sync)
Description and searchable fields

Create a task and wait for result. Returns 200 on terminal status (COMPLETED/FAILED/CANCELLED) and 202 when the wait timed out — clients should poll GET /api/v1/tasks/{taskId} in that case.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.
  • body.inputParameters — Input parameters for the task
  • body.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.model — Public model path in format "providerCode/modelCode/featureCode". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.
  • body.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.inputParameters — Feature-specific input matching the selected model path.
  • body.inputParameters.durationSec — Target duration in seconds.
  • body.inputParameters.explicit — Whether explicit language is allowed.
  • body.inputParameters.extraGuidance — Additional creative guidance and constraints.
  • body.inputParameters.genre — Requested musical genre direction.
  • body.inputParameters.language — Primary lyric language. Use 'auto' to let the model decide.
  • body.inputParameters.languages — Additional languages to include or consider.
  • body.inputParameters.maxTokens — Maximum completion tokens for lyrics generation.
  • body.inputParameters.model — Optional lyrics model override. Defaults to the configured lyrics model.
  • body.inputParameters.mood — Requested musical or visual mood.
  • body.inputParameters.multilingualMode — How multiple languages should be mixed.
  • body.inputParameters.negativeConstraints — Topics, styles, or tropes the output should avoid.
  • body.inputParameters.perspective — Requested lyric narrative perspective.
  • body.inputParameters.prompt — Core song brief, story, scene, or hook idea.
  • body.inputParameters.structure — Requested lyric section order.
  • body.inputParameters.temperature — Sampling temperature for lyrics generation.
  • body.inputParameters.themeKeywords — Short theme anchors for structured lyrics.
  • body.inputParameters.vocalStyle — Requested vocal performance direction.
  • body.model — Public model path in format "providerCode/modelCode/featureCode".
  • body.inputParameters.aspectRatio — Requested output aspect ratio.
  • body.inputParameters.characterImage — Public character reference image URL.
  • body.inputParameters.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.inputParameters.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.inputParameters.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.inputParameters.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.inputParameters.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.inputParameters.generation — Product-specific generation controls.
  • body.inputParameters.generation.creativeMode — Creative intent used by Fast MV prompt and reference planning.
  • body.inputParameters.generation.lipReferenceImages — Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.
  • body.inputParameters.generation.managedVersion — Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.
  • body.inputParameters.generation.motionPreset — Fast MV motion prompt policy.
  • body.inputParameters.generation.performanceMode — Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.
  • body.inputParameters.generation.promptMode — Whether Fast MV preserves or compiles the caller prompt.
  • body.inputParameters.generation.quality — Requested public quality tier.
  • body.inputParameters.generation.referenceStrategy — Fast MV policy for direct or synthesized references.
  • body.inputParameters.generation.style — Requested creative style direction.
  • body.inputParameters.generation.subtitleMode — Fast MV subtitle rendering mode.
  • body.inputParameters.generation.visualBoard — Fast MV Visual Board configuration.
  • body.inputParameters.generation.visualBoard.imageProvider — Public image-generation option code.
  • body.inputParameters.generation.visualBoard.preset — Visual Board speed/detail policy.
  • body.inputParameters.language — Requested or known language code/name.
  • body.inputParameters.lipSync — Whether the MV should use the supported lip-sync workflow.
  • body.inputParameters.maxCredits — Maximum OmnAPI credits authorized for this paid request.
  • body.inputParameters.mode — Operation or product mode discriminator for this schema variant.
  • body.inputParameters.preflightId — Reusable MV preflight snapshot identifier.
  • body.inputParameters.prompt — Primary creative or operation instruction.
  • body.inputParameters.quoteId — Short-lived quote identifier for the matching paid operation.
  • body.inputParameters.referenceImages — Public reference image URLs.
  • body.inputParameters.resolution — Requested output resolution.
  • body.inputParameters.source — Public source media or product reference.
  • body.inputParameters.source.clipId — Source clip identifier.
  • body.inputParameters.source.lyrics — Lyrics or lyric context supplied to the operation.
  • body.inputParameters.source.range — Optional source-media range.
  • body.inputParameters.source.type — Source or product type discriminator.
  • body.inputParameters.source.audioUrl — Public HTTP(S) audio URL.
  • body.inputParameters.source.durationSec — Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.
  • body.inputParameters.srtUrl — Public URL of caller-supplied SRT subtitles.
  • body.inputParameters.subtitle — MV subtitle generation and fallback policy.
  • body.inputParameters.subtitle.fallback — Behavior when the preferred subtitle path cannot complete.
  • body.inputParameters.subtitle.language — Requested or known language code/name.
  • body.inputParameters.subtitle.maxCostUsdPerMin — Maximum accepted public subtitle price in USD per minute.
  • body.inputParameters.subtitle.mode — Operation or product mode discriminator for this schema variant.
  • body.inputParameters.subtitle.quality — Requested public quality tier.
  • body.inputParameters.subtitle.required — Whether the selected subtitle policy must succeed.
  • body.inputParameters.subtitleColor — Requested subtitle foreground color.
  • body.inputParameters.subtitles — Whether subtitles are enabled for the MV.
  • body.inputParameters.title — Optional customer-facing title.
  • body.inputParameters.generation.imageProvider — Public image-generation option code.
  • body.inputParameters.generation.videoModel — Public scene-video model code.
  • body.inputParameters.generation.videoProvider — Public scene-video option code.
  • body.inputParameters.height — Requested image height in pixels for this model branch.
  • body.inputParameters.prompt — Image generation prompt
  • body.inputParameters.style — Requested creative style direction.
  • body.inputParameters.width — Requested image width in pixels for this model branch.
  • body.inputParameters.numVerses — Requested number of lyric verses.
  • body.inputParameters.prompt — Text prompt for lyrics generation
  • body.inputParameters.advancedMode — Deprecated compatibility field; Producer compose ignores this value.
  • body.inputParameters.bpm — Optional BPM hint
  • body.inputParameters.conversationId — Existing Producer conversation identifier to continue.
  • body.inputParameters.currentSongId — Optional current song id used for queue/context continuity
  • body.inputParameters.imageId — Optional cover image id
  • body.inputParameters.imagePrompt — Optional prompt for generating a cover image
  • body.inputParameters.instrumental — Whether to force instrumental generation
  • body.inputParameters.length — Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.
  • body.inputParameters.lyrics — Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.
  • body.inputParameters.lyricsId — Optional existing lyrics id
  • body.inputParameters.model — Producer music model. 'Lyria 3 preview' is accepted as a deprecated alias for Lyria 3.5.
  • body.inputParameters.seed — Optional seed value
  • body.inputParameters.soundPrompt — Sound prompt for music generation
  • body.inputParameters.clipId — Source clip id to modify
  • body.inputParameters.conversationId — Optional existing conversation id to reuse
  • body.inputParameters.cropEndAt — Deprecated alias for extendFromSeconds
  • body.inputParameters.currentSongId — Optional current song id for client_context; defaults to clipId
  • body.inputParameters.extendFromSeconds — Source timestamp where extension begins
  • body.inputParameters.extendSeconds — Seconds generated by ExtendSection
  • body.inputParameters.imageId — Optional output cover image id
  • body.inputParameters.lyrics — New lyrics (useful for cover / swap_vocals)
  • body.inputParameters.lyricsId — Optional lyrics id paired with lyrics when using conversation-based modify flows
  • body.inputParameters.modifyMode — Modify transport: 'task' uses Recipe + audio__render_edit; 'conversation' lets Producer interpret a legacy/agentic request first.
  • body.inputParameters.prompt — Additional modification instructions
  • body.inputParameters.regions — Ordered, non-overlapping regions for ReplaceSection
  • body.inputParameters.regions[].end — Region end timestamp in seconds
  • body.inputParameters.regions[].start — Region start timestamp in seconds
  • body.inputParameters.replaceEndAt — Deprecated single-region alias for regions[].end
  • body.inputParameters.replaceStartAt — Deprecated single-region alias for regions[].start
  • body.inputParameters.seed — Optional deterministic seed for the modification
  • body.inputParameters.soundPrompt — New sound prompt (useful for swap_sound)
  • body.inputParameters.strength — Cover similarity strength (0-1)
  • body.inputParameters.tags — Style tags for the modified clip
  • body.inputParameters.transform — Current deterministic edit type. inpaint is a deprecated alias for replace; swap_* use the legacy conversation path.
  • body.inputParameters.clipId — Clip ID to analyze
  • body.inputParameters.clipId — Clip ID to fetch detail for
  • body.inputParameters.clipId — Clip ID to get lyrics timeline for
  • body.inputParameters.voiceId — Voice ID to fetch
  • body.inputParameters.page — One-based result page.
  • body.inputParameters.createSessionToken — Optional create session token
  • body.inputParameters.lyricsModel — Only the stable "default" lyrics model is supported for paired candidates
  • body.inputParameters.prompt — Text prompt for generating two lyrics candidates
  • body.inputParameters.source — Caller source tag retained in Task audit input
  • body.inputParameters.mids — Clip identifiers accepted by this model branch.
  • body.inputParameters.version — Requested compatibility or resource version.
  • body.inputParameters.excludedStyles — Styles to exclude from the generated result.
  • body.inputParameters.isInstrumental — Optional instrumental intent for the derived result.
  • body.inputParameters.prompt — Text prompt for simple music generation (GPT description)
  • body.inputParameters.waitAudio — Whether this model branch waits for playable audio before completion.
  • response.creditsCharged
  • response.creditsRequired — Exact credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.outputResults
  • response.pollUrl
  • response.processingDuration
  • response.processingDurationText
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId — Task unique identifier
GET /api/v1/tasks/{taskId} Get Task
Description and searchable fields

Get task details by ID

  • path.taskId —
  • response.actionRequired
  • response.createdAt — Task creation timestamp
  • response.creditsCharged
  • response.creditsRequired — Credits deducted to start the task
  • response.errorCode
  • response.errorMessage
  • response.errorReason
  • response.feature
  • response.feature.code — Feature code
  • response.feature.name — Feature name
  • response.inputParameters — Task input parameters
  • response.metadata
  • response.model
  • response.model.code — Model code
  • response.model.name — Model display name
  • response.model.version — Model version
  • response.outputResults
  • response.pricing
  • response.pricing.components
  • response.pricing.components[].credits — Final credits charged for this component.
  • response.pricing.components[].key — Stable billing component key.
  • response.pricing.components[].label — Human-readable component label.
  • response.pricing.quoteVersion — Pricing quote version stored with the task.
  • response.processingCompletedAt
  • response.processingDuration
  • response.processingDurationText
  • response.processingStartedAt
  • response.product
  • response.product.finalUrl
  • response.product.mode
  • response.product.mvId
  • response.product.type — Product family for this task, e.g. mv.
  • response.product.viewUrl
  • response.progress
  • response.provider
  • response.provider.code — Provider code
  • response.provider.name — Provider display name
  • response.refunded — Whether credits were refunded
  • response.rejectedField
  • response.resources — Standardized resources produced by the task
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.retryable — Whether a new request may succeed after the reported terminal failure.
  • response.status
  • response.tags
  • response.taskId — Task unique identifier
  • response.updatedAt — Last update timestamp
  • response.warningCodes
  • response.webhookUrl
POST /api/v1/tasks/{taskId}/cancel Cancel Task
Description and searchable fields

Cancel a task before Provider submission, or after submission only when its Provider confirms remote cancellation. Unconfirmed post-submit tasks remain active and return 409.

  • path.taskId —
  • response.message — Result message
  • response.success — Whether cancellation succeeded
  • response.taskId — Cancelled task identifier
GET /api/v1/tasks/{taskId}/stream Stream Task Status (SSE)
Description and searchable fields

Subscribe to real-time task status updates using Server-Sent Events (SSE). Receives updates without repeated status queries. Emits `connected` (initial snapshot), `update` (state change), `complete` (terminal), `reconnect` (deployment drain or bounded connection rotation), `error`, and `:ping` heartbeats every 25s.

  • path.taskId —

Usage

Read the Usage guide

Method and pathOperation
GET /api/v1/usage/export Export usage records (self-serve)
Description and searchable fields

Streams the caller's usage line items for a period as JSON (default) or CSV (?format=csv or Accept: text/csv). The range defaults to the last 30 days and may span at most 366 days. Requires the usage:read scope.

  • query.startDate —
  • query.endDate —
  • query.apiKeyId —
  • query.format —
  • header.Accept — Select JSON (default) or CSV. The format query parameter takes precedence when supplied.
  • response.items
  • response.items[].apiKeyId
  • response.items[].createdAt
  • response.items[].creditsUsed
  • response.items[].endpoint
  • response.items[].id
  • response.items[].ipAddress
  • response.items[].method
  • response.items[].responseTimeMs
  • response.items[].statusCode
  • response.items[].userAgent

Vidu Direct

Read the Vidu Direct guide

Method and pathOperation
POST /api/v1/vidu/quote Quote a Vidu Direct operation
Description and searchable fields

Returns the customer charge at 2.0 OmnAPI credits per Vidu credit. MV-specific commercial rates never apply. No media is downloaded or inspected.

  • body.input — Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.
  • body.operation — Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.
  • body.pricingContext — Additional caller-supplied inputs required to calculate price.
  • body.pricingContext.durationSec — Billing duration for URL-only media operations. OmnAPI does not download or probe the media.
  • body.pricingContext.providerCreditCap — Vidu-credit authorization reserve for operations without a deterministic published rate card.
  • response.credits
  • response.customerRate
  • response.notes
  • response.operation — Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.
  • response.pricingMode
  • response.pricingVersion
  • response.publicUsd
  • response.viduCredits
POST /api/v1/vidu/tasks Create a Vidu Direct task
Description and searchable fields

Relays an allowlisted Vidu operation through OmnAPI's Task/Credits lifecycle. Inputs and output URLs are passed through; OmnAPI does not upload, download, transcode, persist, or otherwise process media. Download outputs within one hour because finished URLs may expire sooner than standard 24-hour creation URLs.

  • header.Idempotency-Key — Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.
  • body.config — Standard task configuration: priority, tags, metadata, and webhookUrl.
  • body.config.metadata — Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
  • body.config.priority — Task priority 1-10 (higher = sooner). Default 5.
  • body.config.tags — Free-form labels for filtering. Up to 20, 100 chars each.
  • body.config.webhookUrl — URL to receive task.* lifecycle events via the central webhook service.
  • body.input — Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.
  • body.maxCredits — Optional OmnAPI-credit ceiling checked before direct debit.
  • body.operation — Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.
  • body.pricingContext — Additional caller-supplied inputs required to calculate price.
  • body.pricingContext.durationSec — Billing duration for URL-only media operations. OmnAPI does not download or probe the media.
  • body.pricingContext.providerCreditCap — Vidu-credit authorization reserve for operations without a deterministic published rate card.
  • response.creditsRequired
  • response.pollUrl
  • response.pricingMode
  • response.status
  • response.taskId
  • response.viduCredits
GET /api/v1/vidu/tasks/{id} Get a Vidu Direct task
Description and searchable fields

Returns OmnAPI task state and pass-through Vidu resource URLs. The published one-hour window is conservative: standard creation URLs may last 24 hours, while finished outputs may expire sooner.

  • path.id — Vidu task identifier returned by task creation.
  • response.errorCode
  • response.errorMessage
  • response.output
  • response.outputUrlTtlHours — Conservative download window. Some Vidu creation URLs remain valid for 24 hours, but finished outputs may expire after 1 hour.
  • response.progress
  • response.resources
  • response.resources[].assetId — Stable OmnAPI-owned asset id when available.
  • response.resources[].assetStatus
  • response.resources[].byteLength
  • response.resources[].content
  • response.resources[].contentType
  • response.resources[].duration
  • response.resources[].durationSec
  • response.resources[].height
  • response.resources[].id — Stable resource id (OmnAPI resource id).
  • response.resources[].index — Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
  • response.resources[].metadata
  • response.resources[].retainedUntil
  • response.resources[].role
  • response.resources[].thumbnailUrl
  • response.resources[].title
  • response.resources[].type
  • response.resources[].url
  • response.resources[].urlExpiresAt
  • response.resources[].width
  • response.status
  • response.taskId
POST /api/v1/vidu/tasks/{id}/cancel Cancel a Vidu Direct task
Description and searchable fields

Before submission, cancellation is local and refundable. After submission, OmnAPI calls Vidu's cancellation endpoint and refunds only when Vidu explicitly confirms cancellation.

  • path.id — Vidu task identifier returned by task creation.
  • response.message
  • response.success
  • response.taskId