Select scene rendering

PATCH/api/v1/mv/{mvId}/scenes/{sceneIndex}/select-renderingCopy URL

Authentication · x-api-key

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.

All endpointsRequestResponsesCode

Request

mvIdpath · Required

string

MV identifier returned by create or read operations.

sceneIndexpath · Required

string

Zero-based scene index from the MV storyboard.

Unknown fields are not accepted.

• Request · expectedVersionRequired

  number

  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.

  Minimum: 0.

• Request · renderingIdRequired

  string

  Scene rendering-history identifier to select.

  Minimum characters: 1.

Responses

200 OK

application/json

• Response 200 · mvIdRequired

  string

• Response 200 · sceneIndexRequired

  number

• Response 200 · selectedRenderingIdRequired

  string

• Response 200 · versionRequired

  number

• Response 200 · finalizationRequiredOptional

  boolean

• Response 200 · finalizeActionOptional

  "recompose" | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · finalizeAction · anyOf 1Alternative

    "recompose"

  • Response 200 · finalizeAction · anyOf 2Alternative

    null

• Response 200 · staleReasonOptional

  "missing_final" | "final_processing" | "final_expired" | "source_rendering" | "source_failed" | "source_changed" | "composition_unknown" | "url_unavailable" | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · staleReason · anyOf 1Alternative

    "missing_final" | "final_processing" | "final_expired" | "source_rendering" | "source_failed" | "source_changed" | "composition_unknown" | "url_unavailable"

    Must match at least one alternative.

    8 fields / alternatives

    • Response 200 · staleReason · anyOf 1 · anyOf 1Alternative

      "missing_final"

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

      "final_processing"

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

      "final_expired"

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

      "source_rendering"

    • Response 200 · staleReason · anyOf 1 · anyOf 5Alternative

      "source_failed"

    • Response 200 · staleReason · anyOf 1 · anyOf 6Alternative

      "source_changed"

    • Response 200 · staleReason · anyOf 1 · anyOf 7Alternative

      "composition_unknown"

    • Response 200 · staleReason · anyOf 1 · anyOf 8Alternative

      "url_unavailable"

  • Response 200 · staleReason · anyOf 2Alternative

    null

• Response 200 · storyboardIdOptional

  string

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

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 PATCH \
  --url 'https://api.omnapi.com/api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering' \
  --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}/scenes/{sceneIndex}/select-rendering", {
  method: "PATCH",
  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(
    "PATCH", "https://api.omnapi.com/api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering",
    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