Implement a solution that generates videos from text prompts and reference media

Video generation is asynchronous, which changes the shape of the whole solution: you create a job, poll a status, then download an MP4. Around that loop sit a set of hard numbers — resolutions, durations, variant limits, concurrency, job lifetime — and a content policy stricter than anything else on the platform.

Why This Matters

It is a job, not a call. Create → poll → download. An implementation written as a synchronous request is wrong before any parameter is considered, and generation typically takes 1 to 5 minutes.

Variants fall as resolution rises. n_variants is disabled at 1080p, capped at two at 720p, and up to four at other resolutions. This is the direction people guess wrong.

The content policy is unusually strict. Real people, including public figures, cannot be generated, and input images with faces of humans are currently rejected. That last one invalidates whole solution designs.

Prerequisites

• Asynchronous job patterns: submit, poll, retrieve.
• That content filtering applies to prompts and generated output.
• Aspect ratio and resolution basics.
• The idea of a reference image anchoring a generation.

Learning Objectives

By the end of this lesson you will be able to:

1. Implement the create → poll → download loop and handle its states.
2. Set size, seconds, and n_variants within the documented limits.
3. Use input_reference correctly, including its matching rule.
4. Apply the content restrictions when assessing a design.
5. Plan around concurrency, job lifetime, and the five endpoints.

Building Blocks

Modalities. text → video, image → video, and video (generated) → video. The last is worth reading carefully: the input video must be one the service generated.

Audio. Sora 2 supports audio generation in output videos.

The five endpoints. Create Video (a new render job from a prompt, with optional reference inputs or a remix ID), Get Video Status, Download Video (the finished MP4), List Videos, and Delete Videos.

Parameters.

Supported output resolutions. 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080.

Limits. Videos between 1 and 20 seconds. Variants: disabled at 1080p, max 2 at 720p, max 4 at other resolutions. Two video creation jobs running at the same time — one must finish before another starts. Jobs are available for up to 24 hours after creation. Inputs: up to two images (the video interpolates between them) or one video up to five seconds.

Job states. Progress runs through queued, preprocessing, running, processing, and finally succeeded; the SDK surfaces queued, in_progress, completed, and failed. Poll until a terminal state. On failed, check failure_reason.

Content restrictions. Only content suitable for audiences under 18; copyrighted characters and copyrighted music are rejected; real people — including public figures — cannot be generated; input images with faces of humans are currently rejected. Sora 2 blocks all IP and photorealistic content.

Deep Dive

The asynchronous shape

Video generation is a background process, and the solution must be built for it.

Create the job with a prompt and format specifications. Poll the status. Download the MP4 when it finishes. Generation typically takes 1 to 5 minutes depending on resolution and duration, which rules out a synchronous request-response design entirely — the application needs a job record, a polling or notification path, and a way to present pending work to the user.

The state sequence is worth knowing: queued, preprocessing, running, processing, then succeeded. Poll until a terminal state, and on failed read failure_reason, which distinguishes a content-policy rejection from an internal error. That distinction matters operationally — a policy rejection should surface to the user with an explanation, while an internal error may be worth retrying.

Two constraints shape the queueing design. Only two creation jobs can run at once, so a system serving many users needs its own queue rather than submitting on demand. And jobs are available for up to 24 hours, after which the video must be regenerated — so anything to be kept must be downloaded and stored within that window.

Resolution, duration, and the variant ceiling

Three numbers interact, and the variant rule is the counterintuitive one.

Resolution comes from a fixed list — 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080 — covering square, portrait, and landscape at three tiers. The size parameter documents portrait 720×1280 and landscape 1280×720 with portrait as the default, which is a sensible default for social formats and a surprise if you expected landscape.

Duration is 4, 8, or 12 seconds through the seconds parameter, defaulting to 4, while the model overall can produce videos between 1 and 20 seconds.

Variants invert with resolution: disabled at 1080p, at most two at 720p, at most four at other resolutions. The reasoning is capacity, and the design implication is a natural workflow — explore at low resolution with four variants, then render the chosen direction at 1080p as a single video. A scenario asking for several 1080p options in one job is describing something the platform does not do.

Reference media and its matching rule

input_reference supplies a single image that acts as a visual anchor for the first frame, accepting image/jpeg, image/png, and image/webp.

The rule that catches people: the reference must match size exactly — "the resolution of the source image and final video must match". A 1024×1024 product photo cannot anchor a 1280x720 video; it must be resized to the target resolution first. This belongs in the application as a pre-processing step, not as an error surfaced to the user.

Beyond a single anchor, up to two images may be used as input, and "the generated video interpolates content between them" — a start frame and an end frame, with the model producing the motion between. One video of up to five seconds may also be used as input, and video-to-video accepts only a video the service generated.

And the restriction that overrides all of this: input images with faces of humans are currently rejected. A workflow feeding customer photos, staff portraits, or any person-containing reference into video generation does not work — this is not a quality caveat but a hard rejection.

Prompting for video

The documented guidance is specific and differs from text prompting.

Include shot type, subject, action, setting, lighting, and any desired camera motion — the elements that would appear in a shot list — because each removes an ambiguity the model would otherwise resolve arbitrarily.

Keep the prompt single-purpose: "keep it single-purpose for best adherence". A prompt describing several scenes or several actions divides the model's attention across a short clip and adheres to none of them well. Multi-scene output is a sequence of generations, not one prompt.

Known weaknesses are worth designing around: Sora 2 "might have difficulty with complex physics, causal relationships…, spatial reasoning (for example, knowing left from right), and precise time-based event sequencing such as camera movement". A design whose correctness depends on left-versus-right or on an exact beat is fighting a documented limitation.

Worked Examples

Example 1 — several 1080p options at once. A team wants four 1080p variants from one prompt to pick the best.

Not possible: n_variants is disabled at 1080p. The documented workflow is to explore at a lower resolution, where up to four variants are allowed (two at 720p), then generate the chosen direction at 1080p as a single video.

Example 2 — animating a customer photo. A campaign proposes turning submitted customer photographs into short videos.

Blocked twice over: input images with faces of humans are currently rejected, and real people — including public figures — cannot be generated. No parameter or prompt changes this. The workable alternative is generated, non-photorealistic subjects, since Sora 2 blocks all IP and photorealistic content.

Example 3 — a reference that will not attach. A 1024×1024 product image is supplied as input_reference for a 1280x720 video and the request fails.

The reference must match size exactly — "the resolution of the source image and final video must match". Resize the source to 1280x720 before submitting. Accepted MIME types are image/jpeg, image/png, and image/webp.

Visual Explanations

The job lifecycle:

Choosing resolution against variants:

Common Mistakes

Building a synchronous call. Generation is a job taking 1 to 5 minutes.

Expecting more variants at higher resolution. They fall — none at 1080p.

Submitting jobs on demand. Only two may run concurrently.

Leaving output in the service. Jobs are available for 24 hours.

Supplying a reference at the wrong resolution. It must match size exactly.

Feeding photos of people. Input images with faces are rejected.

Expecting landscape by default. The size default is portrait 720×1280.

Writing a multi-scene prompt. Keep it single-purpose.

Treating a policy rejection as a retryable error. Check failure_reason.

Practice Exercises

1. Give the n_variants limit at each resolution tier and the workflow it implies.
2. State the three input modalities and the constraint on the third.
3. What does input_reference do, and what is its hard requirement?
4. Name four content restrictions that can invalidate a design.
5. Which two operational limits force a queue and a storage step?

Summary & Concept Map

Video generation is an asynchronous job — create, poll, download — typically taking 1 to 5 minutes, with five endpoints and states running queued → preprocessing → running → processing → succeeded, and failure_reason distinguishing a policy rejection from an internal error. The numbers are the exam content: resolutions from 480x480 to 1920x1080 with portrait 720×1280 as the size default, seconds of 4 / 8 / 12 defaulting to 4 within an overall 1–20 second range, and variants that fall as resolution rises — none at 1080p, two at 720p, four elsewhere — which dictates an explore-low-then-render-high workflow. input_reference anchors the first frame and must match size exactly, up to two images interpolate between them, and video-to-video takes only a generated video of up to five seconds. Two jobs run at a time and jobs live 24 hours. And the content policy — no real people, no faces in inputs, no copyrighted characters or music, under-18-suitable only — eliminates designs outright.

Sources and freshness

Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.