Finalize MV

POST/api/v1/mv/{mvId}/finalizeCopy URL

Authentication · x-api-key

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.

All endpointsRequestResponsesCode

Request

mvIdpath · Required

string

MV identifier returned by create or read operations.

Idempotency-Keyheader · Optional

string

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.

Maximum characters: 255.

Must match at least one alternative.

• Request · body · anyOf 1Alternative

  object

  Unknown fields are not accepted.

  5 fields

  • Request · body · anyOf 1.configOptional

    object

    Standard task configuration: priority, tags, metadata, and webhookUrl.

    4 fields

    • Request · body · anyOf 1.config.metadataOptional

      object

      Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

    • Request · body · anyOf 1.config.priorityOptional

      number

      Task priority 1-10 (higher = sooner). Default 5.

      Minimum: 1. Maximum: 10. Default: 5.

    • Request · body · anyOf 1.config.tagsOptional

      array<string>

      Free-form labels for filtering. Up to 20, 100 chars each.

      Maximum items: 20.

      1 field

      • Request · body · anyOf 1.config.tags[]Each item

        string

        Maximum characters: 100.

    • Request · body · anyOf 1.config.webhookUrlOptional

      string

      URL to receive task.* lifecycle events via the central webhook service.

      Format: uri.

  • Request · body · anyOf 1.expectedVersionOptional

    number

    Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.

    Minimum: 0.

  • Request · body · anyOf 1.maxCreditsOptional

    number

    Maximum OmnAPI credits authorized for this paid request.

    Minimum: 0.

  • Request · body · anyOf 1.quoteIdOptional

    string

    Short-lived quote identifier for the matching paid operation.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 1.retryOptional

    boolean

    Whether to retry a supported failed operation.

• Request · body · anyOf 2Alternative

  object

  Unknown fields are not accepted.

  8 fields

  • Request · body · anyOf 2.expectedVersionRequired

    number

    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.

    Minimum: 0.

  • Request · body · anyOf 2.configOptional

    object

    Standard task configuration: priority, tags, metadata, and webhookUrl.

    4 fields

    • Request · body · anyOf 2.config.metadataOptional

      object

      Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

    • Request · body · anyOf 2.config.priorityOptional

      number

      Task priority 1-10 (higher = sooner). Default 5.

      Minimum: 1. Maximum: 10. Default: 5.

    • Request · body · anyOf 2.config.tagsOptional

      array<string>

      Free-form labels for filtering. Up to 20, 100 chars each.

      Maximum items: 20.

      1 field

      • Request · body · anyOf 2.config.tags[]Each item

        string

        Maximum characters: 100.

    • Request · body · anyOf 2.config.webhookUrlOptional

      string

      URL to receive task.* lifecycle events via the central webhook service.

      Format: uri.

  • Request · body · anyOf 2.maxCreditsOptional

    number

    Maximum OmnAPI credits authorized for this paid request.

    Minimum: 0.

  • Request · body · anyOf 2.quoteIdOptional

    string

    Short-lived quote identifier for the matching paid operation.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 2.retryOptional

    boolean

    Whether to retry a supported failed operation.

  • Request · body · anyOf 2.scenesOptional

    array<object>

    Explicit Studio scene/rendering selections.

    Minimum items: 1. Maximum items: 64.

    1 field

    • Request · body · anyOf 2.scenes[]Each item

      object
      2 fields

      • Request · body · anyOf 2.scenes[].sceneIndexRequired

        number

        Zero-based scene index.

        Minimum: 0.

      • Request · body · anyOf 2.scenes[].renderingIdOptional

        string

        Scene rendering-history identifier to select.

        Minimum characters: 1.

  • Request · body · anyOf 2.selectLatestOptional

    boolean

    Whether Studio should select the latest ready rendering per scene.

  • Request · body · anyOf 2.titleOptional

    string

    Optional customer-facing title.

    Maximum characters: 200.

Responses

200 OK

application/json

• Response 200 · creditsRequiredRequired

  number

  Minimum: 0.

• Response 200 · idempotentRequired

  boolean

• Response 200 · statusRequired

  "PENDING" | "PROCESSING" | "READY" | "FAILED" | "CANCELLED"

• Response 200 · taskIdRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · taskId · anyOf 1Alternative

    string

  • Response 200 · taskId · anyOf 2Alternative

    null

• Response 200 · compositionHashOptional

  string

• Response 200 · estimatedCompletionTimeOptional

  Date | string | number | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · estimatedCompletionTime · anyOf 1Alternative

    Date | string | number

    Estimated completion time

    Must match at least one alternative.

    4 fields / alternatives

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 1Alternative

      Date

      Estimated completion time

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 2Alternative

      string

      Format: date-time.

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 3Alternative

      string

      Format: date.

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 4Alternative

      number

  • Response 200 · estimatedCompletionTime · anyOf 2Alternative

    null

• Response 200 · finalMvIdOptional

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · finalMvId · anyOf 1Alternative

    string

  • Response 200 · finalMvId · anyOf 2Alternative

    null

• Response 200 · linksOptional

  object

  Unknown fields are not accepted.

  4 fields

  • Response 200 · links.finalRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.final · anyOf 1Alternative

      string

      Final downloadable resource URL when available

    • Response 200 · links.final · anyOf 2Alternative

      null

  • Response 200 · links.resourceRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.resource · anyOf 1Alternative

      string

      Product resource URL when the product has a dedicated view endpoint

    • Response 200 · links.resource · anyOf 2Alternative

      null

  • Response 200 · links.streamRequired

    string

    Task SSE stream URL for the created task

  • Response 200 · links.taskRequired

    string

    Task polling URL for the created task

• Response 200 · messageOptional

  string

• Response 200 · pricingOptional

  object

  Unknown fields are not accepted.

  9 fields

  • Response 200 · pricing.adjustmentCreditsRequired

    number

    chargedCredits - baseCredits

  • Response 200 · pricing.baseCreditsRequired

    number

    Standard quoted credits before customer pricing adjustment

  • Response 200 · pricing.chargedCreditsRequired

    number

    Credits charged for this create request

    Minimum: 0.

  • Response 200 · pricing.quoteVersionRequired

    number

    Pricing quote version stored with the task

  • Response 200 · pricing.sourceRequired

    "standard" | "customer_rule"

    Public pricing source category

  • Response 200 · pricing.billingIncrementCreditsOptional

    number

    Smallest customer charge increment

    Minimum: 0.0001.

  • Response 200 · pricing.calculatedCreditsOptional

    number

    Precise whole-order subtotal before settlement rounding

  • Response 200 · pricing.settlementPolicyVersionOptional

    string

    Versioned customer settlement policy

  • Response 200 · pricing.settlementRoundingCreditsOptional

    number

    Whole-order rounding adjustment added at settlement

    Minimum: 0.

• Response 200 · productOptional

  object

  Unknown fields are not accepted.

  7 fields

  • Response 200 · product.featureCodeRequired

    string

    Resolved feature code

  • Response 200 · product.modelCodeRequired

    string

    Resolved model code

  • Response 200 · product.providerCodeRequired

    string

    Resolved provider code

  • Response 200 · product.resourceIdRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.resourceId · anyOf 1Alternative

      string

      Product resource id when created synchronously

    • Response 200 · product.resourceId · anyOf 2Alternative

      null

  • Response 200 · product.typeRequired

    string

    Product family for this task, e.g. suno, producer, mv

  • Response 200 · product.autoFinalizeOptional

    boolean

    Whether the product should finalize automatically

  • Response 200 · product.deliveryStatusOptional

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.deliveryStatus · anyOf 1Alternative

      string

      Product-level delivery status when applicable

    • Response 200 · product.deliveryStatus · anyOf 2Alternative

      null

• Response 200 · requestIdOptional

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · requestId · anyOf 1Alternative

    string

    Request id echoed from X-Request-Id or generated by API

  • Response 200 · requestId · anyOf 2Alternative

    null

• Response 200 · retryableOptional

  boolean

• Response 200 · warningCodesOptional

  array<string>
  1 field

  • Response 200 · warningCodes[]Each item

    string

    MV advisory warning codes. Non-fatal: the request still succeeds; these flag degraded, adjusted, or automatically recovered inputs and are projected into public Task warningCodes. Omn review codes (MV_NATIVE_CREATIVE_*, MV_NATIVE_SHOT_INTERNAL_CUT, MV_NATIVE_FRAME_BORDERS) describe the delivered video; their observations and affected scenes are in `quality` of GET /api/v1/tasks/{taskId}/workflow.

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

Response for status 403 Forbidden: API-key scope/IP restrictions or billing hold. A positive balance does not bypass payment review. Check GET /api/v1/account/credits billingStatus before further paid requests.

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

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}/finalize' \
  --header "x-api-key: $OMNAPI_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_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}/finalize", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
    "Idempotency-Key": process.env.IDEMPOTENCY_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}/finalize",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
        "Idempotency-Key": os.environ["IDEMPOTENCY_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. Reuse the same IDEMPOTENCY_KEY and body on retries.

Interactive API Explorer → · OpenAPI JSON