Preflight an Omn MV render-tier upgrade

POST/api/v1/mv/{mvId}/upgrade/preflightCopy URL

Authentication · x-api-key

Validate that a completed Omn V1 shot-engine MV can be re-rendered at a higher render tier and return the whole-MV price (target tier credits per output second), the delivery resolution, the shot count and a rough completion estimate. A fresh admission pins the target routes and accounts. Creates no Task and charges nothing. Rejections are returned before any charge: 404 MV_NOT_FOUND when the MV does not exist for this account. 422 MV_ENGINE_UNSUPPORTED with reason not_eligible when the MV cannot be upgraded: it is not an Omn V1 shot-engine MV, it has burned-in subtitles, it was created for motion transfer (a Premium V2 dance MV with generation.motionReferenceVideo on a 16:9 or 9:16 canvas, even if some or all of its dance shots fell back to dancing without the video; on other aspect ratios the video is not used and does not block an upgrade), its shots are longer than the target tier's routes accept, or the target tier is not higher than the current one. reason reference_images_unsupported when a scene (for example one edited with more reference images) would send more reference images than the target tier's route includes without an approved per-image rate. reason output_profile_unsupported when the target renderTier/resolution/quality combination cannot be delivered; Premium V2 MVs are never upgradable because that contract is standard-tier only. Other admission reasons are the same as for a new omn-v1 purchase (422 MV_ENGINE_UNSUPPORTED or 503 MV_PROVIDER_UNAVAILABLE). 409 MV_PRECONDITION_FAILED with reason mv_not_complete (no delivered final, or not every shot is complete) or operation_in_progress (another operation on this MV is running).

All endpointsRequestResponsesCode

Request

mvIdpath · Required

string

MV identifier returned by create or read operations.

Unknown fields are not accepted.

• Request · renderTierRequired

  "standard" | "hd" | "ultra"

  Target Omn render tier. It must be higher than the MV's current tier (draft → standard/hd/ultra, standard → hd/ultra, hd → ultra).

• Request · qualityOptional

  "standard" | "high"

  Omn quality; "high" requires renderTier="ultra". Defaults to standard.

• Request · resolutionOptional

  "540p" | "720p" | "1080p" | "1440p"

  Delivery resolution at the target tier. Defaults to the MV's current resolution when the tier delivers it, otherwise the tier default (hd 1080p, ultra 720p).

Responses

200 OK

application/json

Unknown fields are not accepted.

• Response 200 · creditsRequiredRequired

  number

  Minimum: 0.

• Response 200 · deliveryResolutionRequired

  "540p" | "720p" | "1080p" | "1440p"

• Response 200 · mvIdRequired

  string

• Response 200 · renderTierRequired

  "standard" | "hd" | "ultra"

  Target Omn render tier. It must be higher than the MV's current tier (draft → standard/hd/ultra, standard → hd/ultra, hd → ultra).

• Response 200 · shotCountRequired

  string | integer

  Minimum: 1. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · shotCount · anyOf 1Alternative

    string

    Format: integer. Default: 0.

  • Response 200 · shotCount · anyOf 2Alternative

    integer

    Minimum: 1.

• Response 200 · estimatedCompletionSecOptional

  string | integer

  Minimum: 0. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · estimatedCompletionSec · anyOf 1Alternative

    string

    Format: integer. Default: 0.

  • Response 200 · estimatedCompletionSec · anyOf 2Alternative

    integer

    Minimum: 0.

400 Bad Request

application/json

• Response 400 · errorRequired

  object
  3 fields

  • Response 400 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 400 · error.messageRequired

    string

    Human readable error message

  • Response 400 · error.detailsOptional

    object

    Additional error details (optional)

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

• Response 401 · errorRequired

  object
  3 fields

  • Response 401 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 401 · error.messageRequired

    string

    Human readable error message

  • Response 401 · error.detailsOptional

    object

    Additional error details (optional)

• Response 401 · successRequired

  false

  Always false for error responses

402 Payment Required

application/json

• Response 402 · errorRequired

  object
  3 fields

  • Response 402 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 402 · error.messageRequired

    string

    Human readable error message

  • Response 402 · error.detailsOptional

    object

    Additional error details (optional)

• Response 402 · successRequired

  false

  Always false for error responses

403 Forbidden

application/json

• Response 403 · errorRequired

  object
  3 fields

  • Response 403 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 403 · error.messageRequired

    string

    Human readable error message

  • Response 403 · error.detailsOptional

    object

    Additional error details (optional)

• Response 403 · successRequired

  false

  Always false for error responses

404 Not Found

application/json

• Response 404 · errorRequired

  object
  3 fields

  • Response 404 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 404 · error.messageRequired

    string

    Human readable error message

  • Response 404 · error.detailsOptional

    object

    Additional error details (optional)

• Response 404 · successRequired

  false

  Always false for error responses

408 Request Timeout

application/json

• Response 408 · errorRequired

  object
  3 fields

  • Response 408 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 408 · error.messageRequired

    string

    Human readable error message

  • Response 408 · error.detailsOptional

    object

    Additional error details (optional)

• Response 408 · successRequired

  false

  Always false for error responses

409 Conflict

application/json

• Response 409 · errorRequired

  object
  3 fields

  • Response 409 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 409 · error.messageRequired

    string

    Human readable error message

  • Response 409 · error.detailsOptional

    object

    Additional error details (optional)

• Response 409 · successRequired

  false

  Always false for error responses

413 Payload Too Large

application/json

• Response 413 · errorRequired

  object
  3 fields

  • Response 413 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 413 · error.messageRequired

    string

    Human readable error message

  • Response 413 · error.detailsOptional

    object

    Additional error details (optional)

• Response 413 · successRequired

  false

  Always false for error responses

422 Unprocessable Entity

application/json

• Response 422 · errorRequired

  object
  3 fields

  • Response 422 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 422 · error.messageRequired

    string

    Human readable error message

  • Response 422 · error.detailsOptional

    object

    Additional error details (optional)

• Response 422 · successRequired

  false

  Always false for error responses

429 Too Many Requests

Request allowance or task admission capacity exceeded. Follow Retry-After when present; otherwise wait for active tasks and use bounded backoff. Limits do not guarantee throughput. For SSE, this is the HTTP connection response, not an event.

application/json

• Response 429 · errorRequired

  object
  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

  • Response 429 · error.detailsOptional

    object

    Optional and scope-dependent. Request limits supply scope/policy/type/limit/current/retryAfterSec. Task admission supplies inFlight/limit/tier, plus scope=apiKey for a key cap. IP rejection can omit details. In-flight rejection does not promise Retry-After.

    8 fields

    • Response 429 · error.details.currentOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

      "user" | "api-key" | "ip" | "apiKey"

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

• Response 429 · successRequired

  false

  Default: false.

500 Internal Server Error

application/json

• Response 500 · errorRequired

  object
  3 fields

  • Response 500 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 500 · error.messageRequired

    string

    Human readable error message

  • Response 500 · error.detailsOptional

    object

    Additional error details (optional)

• Response 500 · successRequired

  false

  Always false for error responses

502 Bad Gateway

application/json

• Response 502 · errorRequired

  object
  3 fields

  • Response 502 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 502 · error.messageRequired

    string

    Human readable error message

  • Response 502 · error.detailsOptional

    object

    Additional error details (optional)

• Response 502 · successRequired

  false

  Always false for error responses

503 Service Unavailable

application/json

• Response 503 · errorRequired

  object
  3 fields

  • Response 503 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 503 · error.messageRequired

    string

    Human readable error message

  • Response 503 · error.detailsOptional

    object

    Additional error details (optional)

• Response 503 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request POST \
  --url 'https://api.omnapi.com/api/v1/mv/{mvId}/upgrade/preflight' \
  --header "x-api-key: $OMNAPI_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json

Node.js

import { readFile } from "node:fs/promises";
const response = await fetch("https://api.omnapi.com/api/v1/mv/{mvId}/upgrade/preflight", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
    "Content-Type": "application/json",
  },
  body: await readFile("request.json", "utf8"),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os, json
import requests

response = requests.request(
    "POST", "https://api.omnapi.com/api/v1/mv/{mvId}/upgrade/preflight",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    json=json.load(open("request.json")),
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables. Save your JSON body as request.json.

Interactive API Explorer → · OpenAPI JSON