Music Video quotes and operation billing
Guide
Use the Fast MV quickstart for a complete creation flow.
POST /api/v1/mv/quote is a pricing preview. It does not check whether remote
audio or image URLs are reachable. Use preflight when you need resource
validation and a reusable create-time estimate. Use maxCredits on create
when the caller needs a hard charge cap. Each quote returns a short-lived
quoteId, operation, expiresAt, and pricingVersion. Supply quoteId and
maxCredits on the corresponding paid write. The server reprices immediately
before atomic task creation and direct debit; an expired, used, mismatched, or
over-budget quote is rejected without creating another charge.
Treat quote as estimate-only and preflight as validated estimate:
quote is right for calculators and budget previews, while preflight is the
last safe check before a paid create because it validates source media,
reference images, optional characterImage, and optional srtUrl.
Fast quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "fast", "durationSec": 10, "lipSync": false, "resolution": "540p", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "gpt-image-2", "visualBoardImageCount": 1 }'Fast high-quality quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "fast", "durationSec": 10, "quality": "high", "resolution": "720p", "lipSync": false, "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "gpt-image-2", "visualBoardImageCount": 1 }'Fast scene-edit quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "fast", "step": "scene-edit", "mvId": "{mvId}", "sceneIndex": 2 }'Fast recompose quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "fast", "step": "compose", "mvId": "{mvId}" }'Fast scene-edit quote reads duration and resolution from saved Fast scene
metadata; callers do not pass durationSec or resolution for scene edits.
Fast compose quote returns credits: 0 when the current final already matches
the latest scene composition.
Studio storyboard quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "gpt-image-2", "visualBoardImageCount": 8 }'Visual Board add-on fields:
| Field | Type | Notes |
|---|---|---|
quality | "standard" | "high" | Optional Fast quality tier. standard uses regular Fast pricing. high requires 720p or 1080p. |
visualBoardStrategy | "direct_scene_images" | Optional; direct scene-image generation is the only public strategy. |
visualBoardImageProvider | "gpt-image-2", "p-image", or "viduq2" | Optional but recommended when quoting Visual Board add-ons. Pricing follows the selected image option. |
visualBoardImageCount | number | Direct-scene pricing unit, max 50. |
visualBoardReferenceImageCount | number | Reference-image input count for reference-capable Visual Board providers, max 16. Include it when your create/preflight body will use characterImage or caller references with a provider such as gpt-image-2. |
When visualBoardStrategy is direct_scene_images, include
visualBoardImageProvider for an exact quote. If omitted, the API keeps the
request compatible and returns a conservative direct-scene estimate with
warningCodes: ["MV_VISUAL_BOARD_PROVIDER_REQUIRED_FOR_DIRECT_QUOTE"].
For Fast create/preflight, this same provider choice lives at
generation.visualBoard.imageProvider; quote keeps it flat because it is a
lightweight pricing shape rather than a full create request.
For gpt-image-2 Visual Board quotes, visualBoardReferenceImageCount adds the
reference-image input cost. Image options without reference-input billing ignore
the count for pricing.
P-Image direct scene-image storyboard quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "p-image", "visualBoardImageCount": 3 }'Direct scene-image storyboard quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "viduq2", "visualBoardImageCount": 3 }'Studio render-scene quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "studio", "step": "render-scene", "durationSec": 4, "videoProvider": "p-video", "videoModel": "p-video", "resolution": "540p" }'Studio total quote:
curl -X POST https://api.omnapi.com/api/v1/mv/quote \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "mode": "studio", "step": "total", "estimatedSceneCount": 7, "perSceneDurationSec": 4, "videoProvider": "p-video", "videoModel": "p-video", "resolution": "540p" }'Quote request variants
Section titled “Quote request variants”mode and, except for Fast create pricing, step discriminate the request.
Unknown fields and unsupported combinations are rejected.
| Quote variant | Required fields | Optional fields |
|---|---|---|
| Fast OneClick V1 create | mode:"fast", durationSec | step:"create", managedVersion:"oneclick-v1", resolution, lipSync, quality, subtitleMode, and Visual Board quote fields |
| Fast Premium V2 create | mode:"fast", managedVersion:"premium-v2", performanceMode, durationSec | step:"create", resolution:"720p", subtitleMode, and Visual Board quote fields; omit lipSync and quality |
| Fast scene edit | mode:"fast", step:"scene-edit", mvId, sceneIndex | none |
| Fast compose | mode:"fast", step:"compose", mvId | none |
| Studio storyboard | mode:"studio", step:"storyboard" | visualBoardStrategy, visualBoardImageProvider, visualBoardImageCount, visualBoardReferenceImageCount |
| Studio render scene | mode:"studio", step:"render-scene", videoProvider, resolution, durationSec | videoModel, fps, draft |
| Studio render batch | mode:"studio", step:"render-batch", mvId, sceneIndexes, videoProvider, resolution | videoModel, fps, draft |
| Studio regenerate image | mode:"studio", step:"regenerate-image", mvId, sceneIndex | none |
| Studio lock character | mode:"studio", step:"lock-character", mvId | none |
| Studio finalize | mode:"studio", step:"finalize", mvId | none |
| Studio total | mode:"studio", step:"total", videoProvider, resolution, perSceneDurationSec, estimatedSceneCount | videoModel, draft, visualBoardStrategy, visualBoardImageProvider, visualBoardImageCount |
OneClick V1 Fast create durationSec is 10-600; Premium V2 is 10-300. Studio render and total durations are
1-16 seconds; estimatedSceneCount and quote sceneIndexes allow 1-30 scenes.
Quote sceneIndex values are non-negative. Visual Board counts allow 1-50
generated images and 0-16 reference images. The resolution, fps, and Provider
enums match the Studio mutation table above.
Pricing summary:
| Mode | Item | Credits |
|---|---|---|
| Fast | quote | 0 |
| Fast | 540p | Dynamic; call /api/v1/mv/quote |
| Fast | 720p | Dynamic; call /api/v1/mv/quote |
| Fast | 1080p | Dynamic; call /api/v1/mv/quote |
| Fast | high quality | Dynamic; call /api/v1/mv/quote. Requires 720p or 1080p. |
| Fast | lip-sync | Dynamic; call /api/v1/mv/quote |
| Premium V2 | perform at 720p | 21 Vidu credits/second; call /api/v1/mv/quote for OmnAPI credits |
| Premium V2 | sing, sing_perform, or dance at 720p | 24 Vidu credits/second; call /api/v1/mv/quote for OmnAPI credits |
| Fast | scene edit | Dynamic; call /api/v1/mv/quote with step:"scene-edit" |
| Fast | recompose final after scene edit | Dynamic; call /api/v1/mv/quote with step:"compose" |
| Studio | storyboard + scene stills | 250 plus optional Visual Board add-on |
| Studio | regenerate scene image | 15 |
| Studio | render scene | Dynamic by selected render option, model, resolution, fps, and duration |
| Studio | finalize | 50 |
Operation ledger, cancellation, and deletion
Section titled “Operation ledger, cancellation, and deletion”GET /api/v1/mv/{mvId}/operations returns each quote/task linkage plus
authorized, charged, refunded, and net credits. Its costSummary covers all
recorded MV operation rows even when the returned item list is limited.
MVView.costSummary provides the same recorded totals for normal product reads.
For projects that predate operation-ledger coverage, earlier work may be absent;
use task billing or the authenticated usage export for pre-cutover spend. See
the MV migration notes.
Cancel an active operation with
POST /api/v1/mv/{mvId}/operations/{taskId}/cancel. Before Provider submission,
a successful cancellation atomically stops the inactive OmnAPI job and refunds
the eligible credits deducted for that task. After Provider submission, cancellation succeeds
only if the generation service explicitly confirms remote cancellation.
Current managed MV providers do not expose a dependable confirmation contract,
so submitted or outcome-unknown operations return 409, stay active, keep
their original charge, and continue status synchronization. Keep polling the
original task; OmnAPI no longer reports a local CANCELLED state while remote
work may continue.
DELETE /api/v1/mv/{mvId} removes the resource from customer lists/reads and
best-effort deletes known source, scene, rendering, character, and final media.
Task, operation, pricing, and billing records required for financial
reconciliation remain subject to the platform audit-retention policy.
After the configured Task retention window, retained MV operation Tasks are
compacted to financial audit fields; request, provider, result, step, and
webhook payloads are removed.
Normal MV output assets are retained for 30 days by default. A successful
finalize or recompose resets the final video’s retention window; refreshing a
signed URL, opening the app, polling a Task, or playing a video does not extend
that window. Scene videos used by a successful finalize or recompose are
retained through the corresponding final delivery window. Download assets that
must be kept longer.
Final delivery is gated by deterministic media checks for a usable video stream, audio stream, expected duration, purchased resolution tier, and viable frame rate. Creative quality remains subjective and is not an automatic-refund signal.