VORQ Docs
Reference

Units and media inputs

The exact rules the client uses to count an order's units, with frame sizes, defaults and reference asset limits.

The client declares units_in and units_out on every order from the input's shape. Why, and how they turn into cost, is in Units and cost. All violations below raise ValidationError before anything is sealed.

Shape

ShapeThe input names
textmax_output_tokens, max_tokens or max_completion_tokens (checked first)
videootherwise duration or duration_secs
imageotherwise num_images, width, resolution or any reference asset
textotherwise

Counts

Shapeunits_inunits_out
textmax(1, len(canonical JSON of the input) // 4)the first ceiling present, in the order above, or 4096
imagereference pixel-seconds, or 0frame pixels × num_images (default 1)
videoreference pixel-seconds, or 0frame pixels × duration seconds

submit(..., units_out=N) replaces the output count; it doesn't change units_in.

Frame pixels

  • Explicit width / height always win. Each defaults to 1024 when only the other is given.
  • Otherwise a resolution tier (480p, 720p, 1080p, 4k), resolved against aspect_ratio, from the table below.
  • Otherwise 1024 × 1024.
aspect_ratio480p720p1080p4k
21:9976×4161472×6322200×9444400×1888
16:9854×4801280×7201920×10803840×2160
4:3736×5521112×8321664×12483328×2496
1:1640×640960×9601440×14402880×2880
3:4552×736832×11121248×16642496×3328
9:16480×854720×12801080×19202160×3840

A tier is a pixel budget: every ratio in a tier has about the same area.

  • aspect_ratio: "auto", or no aspect_ratio, picks the row closest to the first pixel-bearing reference's declared shape, or 16:9 when there is no reference.
  • aspect_ratio: "adaptive" is priced at the tier's largest frame.
  • Any other aspect_ratio, or an unknown resolution, is refused.

Duration

  • duration_secs wins over duration.
  • A whole number, or a string of ASCII digits (5 or "5"). A fractional number is cut to whole seconds. Anything else, such as "7.5" or "+5", is refused.
  • Missing, empty or not positive: 5 seconds.
  • "auto": priced at 15 seconds, a cap the delivered clip settles under.

Reference assets

Reference assets travel as base64 inside the sealed payload, never as URLs.

KeyHoldsKind
image, end_imageone assetstill
videoone assetclip
reference_imagesa list, up to 9still
reference_videosa list, up to 3clip
reference_audiosa list, up to 3audio

A singular key holding something other than an object, or a list key holding something other than a list, is not treated as a reference.

Every asset:

  • needs b64 (non-empty) and media_type;
  • if a still or a clip, needs integer width and height of at least 1;
  • if a clip, needs duration_secs, a positive integer rounded up to whole seconds.

units_in is the sum over stills and clips of width × height × seconds, where a still counts as one second (or its own duration_secs if given). Audio counts zero.

LimitValue
Pixel-bearing assets per request12
Pixels per asset8,294,400 (3840×2160)
Seconds per clip60
Decoded bytes per audio asset15,728,640 (15 MiB)

The provider decodes each asset after opening the payload and fails the job if it is larger or longer than declared.

Batches

Reference for client.batches, BatchHandle and JobError.

OpenAI transport

Reference for vorq.sealing_http_client and SealingTransport, the sealed path for the stock openai package.

On this page

ShapeCountsFrame pixelsDurationReference assets