Render MV scene

POST/api/v1/mv/{mvId}/scenes/{sceneIndex}/render

Authentication · x-api-key

Render one MV scene. Studio creates a candidate scene video from the current scene image and requires MVView.version as expectedVersion. Fast edits the currently selected generated scene and accepts prompt, optional referenceImages replacement, expectedVersion, config, and prompt compatibility aliases; a Fast edit needs at least one of prompt, referenceImages or (Omn shot-engine MVs) shotType. Omitting referenceImages preserves the source scene images. Omn V1 shot-engine MVs also accept shotType to re-render the scene as another shot type the MV's plan supports (never bridge); sent alone it re-renders the scene with its current prompt and reference images. The edit stays on the MV's pinned routes and is priced per shot second at the MV's render-tier price (no economy discount). Fast rejects durationSec/resolution/render controls; scene-edit billing uses saved Fast scene metadata.

Request

mvIdpath · Required

string

MV identifier returned by create or read operations.

sceneIndexpath · Required

string

Zero-based scene index from the MV storyboard.

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.

Unknown fields are not accepted.

Request · aspectRatioOptional

"16:9" | "9:16" | "1:1" | "4:3" | "3:4"

Requested output aspect ratio.
Request · configOptional

object

Standard task configuration: priority, tags, metadata, and webhookUrl.
4 fields
- Request · config.metadataOptional
  
  object
  
  Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
- Request · config.priorityOptional
  
  number
  
  Task priority 1-10 (higher = sooner). Default 5.
  
  Minimum: 1. Maximum: 10. Default: 5.
- Request · config.tagsOptional
  
  array<string>
  
  Free-form labels for filtering. Up to 20, 100 chars each.
  
  Maximum items: 20.
  1 field
  - Request · config.tags[]Each item
    
    string
    
    Maximum characters: 100.
- Request · config.webhookUrlOptional
  
  string
  
  URL to receive task.* lifecycle events via the central webhook service.
  
  Format: uri.
Request · draftOptional

boolean

Whether to use the supported draft rendering policy.
Request · durationSecOptional

number

Studio-only render control. Fast scene edit rejects client-supplied durationSec; Fast scene-edit billing uses saved scene metadata.

Minimum: 1. Maximum: 16.
Request · expectedVersionOptional

number

Optimistic-concurrency guard. Fast may omit it for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio requires it and rejects stale values with 409.

Minimum: 0.
Request · fpsOptional

24 | 48

Requested numeric output frame rate.
Request · maxCreditsOptional

number

Maximum OmnAPI credits authorized for this paid request.

Minimum: 0.
Request · promptOptional

string

Cross-mode prompt. Fast scene edit uses this as the official instruction field; Studio treats it as a one-shot video prompt override.

Maximum characters: 3000.
Request · quoteIdOptional

string

Short-lived quote identifier for the matching paid operation.

Minimum characters: 1. Maximum characters: 100.
Request · referenceImagesOptional

array<string>

Public reference image URLs.

Minimum items: 1. Maximum items: 7.
1 field
- Request · referenceImages[]Each item
  
  string
  
  Minimum characters: 1.
Request · resolutionOptional

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

Studio-only render control. Fast scene edit rejects client-supplied resolution; Fast scene-edit billing uses saved scene metadata.
Request · shotTypeOptional

"narrative" | "lipsync" | "performance" | "dance"

Fast Omn V1 shot-engine MVs only: render the edited scene as this shot type. May be sent alone (without prompt or referenceImages) to re-render the scene with its current prompt and reference images, at the same price as any edit. It must be a shot type the MV's pinned plan serves with the scene's reference images, within the scene's length; bridge (first/last-frame continuity) is not an edit shot type, because a bridge shot continues the previous shot of its sequence, which an edit does not re-render. Unsupported values and other MVs are rejected with 400 VALIDATION_ERROR (details.field, details.availableShotTypes) before any charge.
Request · videoModelOptional

string

Public scene-video model code.

Maximum characters: 100.
Request · videoPromptOptional

string

Alias of videoPromptOverride for Studio. Fast accepts this only as a compatibility alias for prompt.

Maximum characters: 1500.
Request · videoPromptOverrideOptional

string

Studio one-shot video prompt override. Fast accepts this only as a compatibility alias for prompt.

Maximum characters: 1500.
Request · videoProviderOptional

"p-video" | "hailuo" | "minimax-h3" | "vidu"

Public scene-video option code.

Responses

200 OK

application/json

Response 200 · creditsRequiredRequired

number

Minimum: 0.
Response 200 · linksRequired

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 · pricingRequired

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 · productRequired

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 · requestIdRequired

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 · taskIdRequired

string
Response 200 · warningCodesRequired

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.
Response 200 · chargedOptional

boolean
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 · renderingIdOptional

string
Response 200 · sceneIndexOptional

number
Response 200 · versionOptional

number

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

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

import { readFile } from "node:fs/promises";
const response = await fetch("https://api.omnapi.com/api/v1/mv/{mvId}/scenes/{sceneIndex}/render", {
  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());

import os, json
import requests

response = requests.request(
    "POST", "https://api.omnapi.com/api/v1/mv/{mvId}/scenes/{sceneIndex}/render",
    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

Render MV scene

Request

Request · aspectRatioOptional

Request · configOptional

Request · config.metadataOptional

Request · config.priorityOptional

Request · config.tagsOptional

Request · config.tags[]Each item

Request · config.webhookUrlOptional

Request · draftOptional

Request · durationSecOptional

Request · expectedVersionOptional

Request · fpsOptional

Request · maxCreditsOptional

Request · promptOptional

Request · quoteIdOptional

Request · referenceImagesOptional

Request · referenceImages[]Each item

Request · resolutionOptional

Request · shotTypeOptional

Request · videoModelOptional

Request · videoPromptOptional

Request · videoPromptOverrideOptional

Request · videoProviderOptional

Responses

Response 200 · creditsRequiredRequired

Response 200 · linksRequired

Response 200 · links.finalRequired

Response 200 · links.final · anyOf 1Alternative

Response 200 · links.final · anyOf 2Alternative

Response 200 · links.resourceRequired

Response 200 · links.resource · anyOf 1Alternative

Response 200 · links.resource · anyOf 2Alternative

Response 200 · links.streamRequired

Response 200 · links.taskRequired

Response 200 · pricingRequired

Response 200 · pricing.adjustmentCreditsRequired

Response 200 · pricing.baseCreditsRequired

Response 200 · pricing.chargedCreditsRequired

Response 200 · pricing.quoteVersionRequired

Response 200 · pricing.sourceRequired

Response 200 · pricing.billingIncrementCreditsOptional

Response 200 · pricing.calculatedCreditsOptional

Response 200 · pricing.settlementPolicyVersionOptional

Response 200 · pricing.settlementRoundingCreditsOptional

Response 200 · productRequired

Response 200 · product.featureCodeRequired

Response 200 · product.modelCodeRequired

Response 200 · product.providerCodeRequired

Response 200 · product.resourceIdRequired

Response 200 · product.resourceId · anyOf 1Alternative

Response 200 · product.resourceId · anyOf 2Alternative

Response 200 · product.typeRequired

Response 200 · product.autoFinalizeOptional

Response 200 · product.deliveryStatusOptional

Response 200 · product.deliveryStatus · anyOf 1Alternative

Response 200 · product.deliveryStatus · anyOf 2Alternative

Response 200 · requestIdRequired

Response 200 · requestId · anyOf 1Alternative

Response 200 · requestId · anyOf 2Alternative

Response 200 · taskIdRequired

Response 200 · warningCodesRequired

Response 200 · warningCodes[]Each item

Response 200 · chargedOptional

Response 200 · estimatedCompletionTimeOptional

Response 200 · estimatedCompletionTime · anyOf 1Alternative

Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 1Alternative

Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 2Alternative

Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 3Alternative

Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 4Alternative

Response 200 · estimatedCompletionTime · anyOf 2Alternative

Response 200 · renderingIdOptional

Response 200 · sceneIndexOptional

Response 200 · versionOptional

Response 400 · errorRequired

Response 400 · error.codeRequired

Response 400 · error.messageRequired

Response 400 · error.detailsOptional

Response 400 · successRequired

Response 401 · errorRequired

Request · `aspectRatio`Optional

Request · `config`Optional

Request · `config.metadata`Optional

Request · `config.priority`Optional

Request · `config.tags`Optional

Request · `config.tags[]`Each item

Request · `config.webhookUrl`Optional

Request · `draft`Optional

Request · `durationSec`Optional

Request · `expectedVersion`Optional

Request · `fps`Optional

Request · `maxCredits`Optional

Request · `prompt`Optional

Request · `quoteId`Optional

Request · `referenceImages`Optional

Request · `referenceImages[]`Each item

Request · `resolution`Optional

Request · `shotType`Optional

Request · `videoModel`Optional

Request · `videoPrompt`Optional

Request · `videoPromptOverride`Optional

Request · `videoProvider`Optional

Response 200 · `creditsRequired`Required

Response 200 · `links`Required

Response 200 · `links.final`Required

Response 200 · `links.final · anyOf 1`Alternative

Response 200 · `links.final · anyOf 2`Alternative

Response 200 · `links.resource`Required

Response 200 · `links.resource · anyOf 1`Alternative

Response 200 · `links.resource · anyOf 2`Alternative

Response 200 · `links.stream`Required

Response 200 · `links.task`Required

Response 200 · `pricing`Required

Response 200 · `pricing.adjustmentCredits`Required

Response 200 · `pricing.baseCredits`Required

Response 200 · `pricing.chargedCredits`Required

Response 200 · `pricing.quoteVersion`Required

Response 200 · `pricing.source`Required

Response 200 · `pricing.billingIncrementCredits`Optional

Response 200 · `pricing.calculatedCredits`Optional

Response 200 · `pricing.settlementPolicyVersion`Optional

Response 200 · `pricing.settlementRoundingCredits`Optional

Response 200 · `product`Required

Response 200 · `product.featureCode`Required

Response 200 · `product.modelCode`Required

Response 200 · `product.providerCode`Required

Response 200 · `product.resourceId`Required

Response 200 · `product.resourceId · anyOf 1`Alternative

Response 200 · `product.resourceId · anyOf 2`Alternative

Response 200 · `product.type`Required

Response 200 · `product.autoFinalize`Optional

Response 200 · `product.deliveryStatus`Optional

Response 200 · `product.deliveryStatus · anyOf 1`Alternative

Response 200 · `product.deliveryStatus · anyOf 2`Alternative

Response 200 · `requestId`Required

Response 200 · `requestId · anyOf 1`Alternative

Response 200 · `requestId · anyOf 2`Alternative

Response 200 · `taskId`Required

Response 200 · `warningCodes`Required

Response 200 · `warningCodes[]`Each item

Response 200 · `charged`Optional

Response 200 · `estimatedCompletionTime`Optional

Response 200 · `estimatedCompletionTime · anyOf 1`Alternative

Response 200 · `estimatedCompletionTime · anyOf 1 · anyOf 1`Alternative

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

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

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

Response 200 · `estimatedCompletionTime · anyOf 2`Alternative

Response 200 · `renderingId`Optional

Response 200 · `sceneIndex`Optional

Response 200 · `version`Optional

Response 400 · `error`Required

Response 400 · `error.code`Required

Response 400 · `error.message`Required

Response 400 · `error.details`Optional

Response 400 · `success`Required

Response 401 · `error`Required

Response 401 · `error.code`Required

Response 401 · `error.message`Required

Response 401 · `error.details`Optional