Skip to content
OmnAPI Docs

Edit and upgrade Omn V1 music videos

GuideAvailability varies by operation

These operations apply to Fast MVs rendered by the Omn V1 pilot. Use an API key with task:create for edits, upgrades and their preflight, and task:read to poll the resulting Task. Each paid operation needs its own saved Idempotency-Key. Read the MV with GET /api/v1/mv/{mvId} first and keep its version, current generation.renderTier and generation.resolution. Its capabilities.editShotTypes lists the shot types an edit can request, and capabilities.upgrade says whether an upgrade can be requested now.

New edits and upgrades also verify required source media before charging; keeping a final video alone does not guarantee that its sources remain available for these operations.

Omn V1 engine · Scene edits and final video · Quotes and billing

Edit one shot

Section titled “Edit one shot”

Omn V1 shots use the Fast scene edit, POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/render, described in Scene edits and final video. It accepts prompt, referenceImages or both. On Omn V1 it also accepts shotType to render the scene as another shot type, either with those fields or on its own:

Terminal window
# Save once for this operation; reuse the saved key and body on retries.
export MV_SHOT_EDIT_KEY="$(uuidgen)"
curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/scenes/3/render \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $MV_SHOT_EDIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":6,"shotType":"lipsync"}'
  • Sent alone, shotType re-renders the scene as that type with its current prompt and reference images. The price is the same as any other edit.
  • shotType must be one of the MV’s capabilities.editShotTypes: the shot types the MV was planned with, except bridge, in the fixed order narrative, lipsync, performance, dance. Another value returns 400 VALIDATION_ERROR with the same list in details.availableShotTypes. The list is per MV, not per scene: each edit is still checked against its scene (below), so a listed type can still be rejected for one scene.
  • bridge is not an edit shot type: a continuity shot continues the shot before it, which an edit does not re-render, so shotType: "bridge" returns 400 VALIDATION_ERROR. Editing an existing continuity shot without shotType renders it as a standalone shot.
  • Before any charge, OmnAPI also checks that the edit can run: the scene must fit the shot type’s maximum shot length; without an approved extra-image rate for the MV, the edit may send at most five reference images, the MV’s identity image included; and on a characterImage MV the images must lead with the character identity. A failed check returns 400 VALIDATION_ERROR with details.field set to referenceImages, or shotType when no referenceImages were sent. Image-count errors add details.referenceImagesSent and details.maxReferenceImagesSent; send fewer images.
  • Other engines and Studio return 400 VALIDATION_ERROR for shotType. Their MVView.capabilities, like that of an Omn V1 MV not rendered as shots, has no editShotTypes or upgrade field.
  • An edit costs the shot’s duration, rounded up with a 1-second minimum, at the MV’s current tier price. It is rendered immediately and has no economy discount (mvOmnV1.sceneEdit in the price card). Quote it with step: "scene-edit".
  • Recompose the final video with POST /api/v1/mv/{mvId}/finalize after the edit completes. Recomposition costs 2 credits (mvOmnV1.composeCreditsPerOperation); quote it with step: "compose".

Renderings made before an upgrade stay in renderingHistory with isSelectable: false. Selecting or editing one returns 409 MV_PRECONDITION_FAILED with reason: "rendering_superseded". While an upgrade runs, edits, rendering selection and finalize return 409 MV_PRECONDITION_FAILED with reason: "upgrade_in_progress" and the upgrade taskId in details; retry after it finishes.

Upgrade to a higher render tier

Section titled “Upgrade to a higher render tier”

An upgrade re-renders every shot of a finished Omn V1 MV at a higher tier and recomposes it: draft to standard, hd or ultra; standard to hd or ultra; hd to ultra. It keeps the MV’s shots, timing and each scene’s current rendering, including your edits, without planning the video again. Continuity shots are re-rendered as standalone shots.

Check availability

Section titled “Check availability”

MVView.capabilities.upgrade tells you whether to offer an upgrade. It applies the same fixed rules as the upgrade endpoints, without reading the MV’s scenes or pricing it:

{
  "mvId": "mv_01J...",
  "version": 6,
  "generation": {
    "engineVersion": "omn-v1",
    "renderTier": "draft",
    "resolution": "540p"
  },
  "capabilities": {
    "editShotTypes": ["narrative", "lipsync"],
    "upgrade": {
      "available": true,
      "reason": null,
      "renderTiers": ["standard", "hd", "ultra"]
    }
  }
}
FieldMeaning
availabletrue when the MV passes those rules now; reason is then null
reasonWhy it cannot be upgraded now: the first failing check, in the order of the table below
renderTiersTarget tiers in tier order: standard, hd and ultra from draft; hd and ultra from standard; ultra from hd. Kept while the MV is temporarily unavailable; empty when it can never be upgraded
reasonChanges later?The upgrade endpoints returnWhat to do
not_shot_engineNo422 MV_ENGINE_UNSUPPORTED, reason: "not_eligible"The MV was not rendered as Omn V1 shots; create a new MV at the tier you need
subtitlesNo422 MV_ENGINE_UNSUPPORTED, reason: "not_eligible"The MV has visible subtitles; keep it as delivered
motion_transferNo422 MV_ENGINE_UNSUPPORTED, reason: "not_eligible"The MV was created for motion transfer (OneClick V2 dance with a motion reference at 16:9 or 9:16); keep it as delivered
highest_tierNo422 MV_ENGINE_UNSUPPORTED: reason: "output_profile_unsupported" for a OneClick V2 MV, which has only the standard tier, and a higher target; otherwise "not_eligible", as for an ultra MVNo higher tier exists for this MV; keep it as delivered
mv_not_completeYes409 MV_PRECONDITION_FAILED, details.reason: "mv_not_complete"Wait for the MV and its final video to be ready, then read the MV again
operation_in_progressYes409 MV_PRECONDITION_FAILED, details.reason: "operation_in_progress"Wait for the running edit, recomposition or upgrade to finish, then read the MV again

Hide the upgrade action while available is false, and offer only the tiers in renderTiers. available: true is not an admission or a price: preflight also checks every scene against the target tier and the capacity and price that apply, so it can still return any of the upgrade rejections. Always run preflight before the upgrade.

Check eligibility and price

Section titled “Check eligibility and price”
Terminal window
curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/upgrade/preflight \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"renderTier":"standard","resolution":"720p"}'
FieldRequirementNotes
renderTierRequiredstandard, hd or ultra; must be higher than the MV’s current tier
resolutionOptional540p, 720p, 1080p or 1440p. When omitted, the MV keeps its resolution if the target tier delivers it; otherwise hd uses 1080p and ultra 720p
qualityOptionalstandard (default) or high; high requires ultra

A draft 540p MV upgraded to standard without resolution stays at 540p; send resolution: "720p" for 720p.

{
  "mvId": "mv_01J...",
  "renderTier": "standard",
  "deliveryResolution": "720p",
  "creditsRequired": 816,
  "shotCount": 6,
  "estimatedCompletionSec": 600
}

creditsRequired is the target tier price for the whole MV: output seconds rounded up, with a 10-second minimum, including recomposition and without an economy discount. The earlier purchase is not credited. In this example a 51-second draft (51 × 6 = 306 credits) becomes 51 × 16 = 816 credits at standard 720p. The same rule is published as mvOmnV1.upgrade in the Omn V1 price card; preflight returns the amount for your account. estimatedCompletionSec is a rough estimate. Preflight applies the same admission as a new Omn V1 purchase, so it can also return the other Omn V1 rejections.

Start the upgrade

Section titled “Start the upgrade”

Send the same body plus an optional maxCredits, and a required Idempotency-Key header; without it the request returns 400 VALIDATION_ERROR.

Terminal window
# Save once for this operation; reuse the saved key and body on retries.
export MV_UPGRADE_KEY="$(uuidgen)"
curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/upgrade \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $MV_UPGRADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"renderTier":"standard","resolution":"720p","maxCredits":816}'

The upgrade is repriced just before the charge. If it costs more than maxCredits, it returns 402 INSUFFICIENT_CREDITS without charging. A successful request returns HTTP 202 with the upgrade Task:

{
  "taskId": "task_01J...",
  "mvId": "mv_01J...",
  "operation": "upgrade",
  "creditsRequired": 816,
  "status": "PENDING"
}

Save taskId. Poll GET /api/v1/tasks/{taskId}, or read GET /api/v1/mv/{mvId}/operations, where the item has operation: "upgrade", progress and deliveryDeadlineAt. After an uncertain response, repeat the same request with the same key; it returns the original upgrade Task.

On success, the upgraded final replaces the delivered video, MVView.generation.renderTier and resolution change to the new values, and MVView.version increases; read the MV again before the next edit. An upgrade renders immediately, so an upgraded economy MV reports schedule: "standard". The earlier final and renderings stay in history. A failed or cancelled upgrade is refunded, and the MV keeps its current final. Cancellation follows the normal operation cancellation rules. A later upgrade to a still higher tier is allowed.

Upgrade rejections

Section titled “Upgrade rejections”

All of these are returned before any charge. The capabilities.upgrade.reason values predict the fixed ones; the scene, reference-image and capacity checks run only in preflight and the upgrade request:

ResponseWhenWhat to do
404 MV_NOT_FOUNDThe MV does not exist for this accountCheck the mvId
422 MV_ENGINE_UNSUPPORTED, reason: "not_eligible"The MV was not rendered as Omn V1 shots, has visible subtitles, was created for motion transfer (OneClick V2 dance with a motion reference at 16:9 or 9:16, even if its dance shots fell back), has a shot longer than the target tier allows (for example, hd singing shots are at most 10 seconds), or the target tier is not higherKeep the current video, try another target tier, or create a new MV at the tier you need
422 MV_ENGINE_UNSUPPORTED, reason: "reference_images_unsupported"A scene, for example one edited with more reference images, would send more images than the target tier includes without an approved extra-image rateEdit that scene with fewer reference images, then retry
422 MV_ENGINE_UNSUPPORTED, reason: "output_profile_unsupported"The tier, resolution and quality combination is not offered. OneClick V2 MVs, which have only the standard tier, return this reason unless they were created for motion transfer (not_eligible)Choose a combination from the price table and capabilities; OneClick V2 MVs cannot be upgraded
409 MV_PRECONDITION_FAILED, reason: "mv_not_complete"The MV has no delivered final, or a scene has no completed current renderingFinish pending edits and recompose, then retry
409 MV_PRECONDITION_FAILED, reason: "operation_in_progress"Another operation on the MV is runningWait for it to finish, then retry
Section titled “Related operations”