Sora 2 Text to Video API

openai/sora-2/text-to-video

Sora 2 (Text to Video) generates 720p HD videos with synchronized stereo audio from text prompts, supporting fixed durations from 4 to 20 seconds in 16:9 or 9:16 aspect ratios. It adheres to real-world physics and camera trajectories while delivering coherent motion dynamics and ambient soundscapes.

Input

Prompt

291

Duration

Aspect ratio

Output

Idle

Your generated video will appear here

Add your prompt and required media, review the settings, then click Run.

Continue with

Sora 2 Image to Video Sora 2 Pro Text to Video Sora 2 Pro Image to Video

Examples

A hummingbird hovers at a red trumpet flower in slow motion, wings beating in a blur as it sips nectar, soft morning garden light, macro detail. Natural sound: rapid wingbeat hum, gentle garden breeze, distant birdsong. Realistic wildlife documentary motion, no text, no logos.

A skateboarder launches out of an empty concrete pool at golden hour, board catching air at the coping, dust motes in warm side light, dynamic low-angle follow shot. Natural sound: wheels rolling on concrete, the pop of the tail, wind rush. Realistic athletic motion, no text, no logos.

Macro shot of a single raindrop striking the glass-still surface of a lake, concentric ripples expanding outward, overcast soft light, mist over distant pines. Natural sound: gentle rain patter, a soft droplet plink, muted wind. Realistic fluid motion, no text, no logos.

REST API

Quick Start

Authenticate, submit generation request, and poll task status for 720p video result.

Step 1: Set up authentication

Include Authorization: Bearer VIDGO_API_KEY in all HTTP request headers.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Step 2: Submit generation task

Send POST request to /api/generate/submit with model openai/sora-2/text-to-video and input payload.

Submit request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "openai/sora-2/text-to-video",
  "input": {
    "prompt": "An astronaut riding a horse across the surface of Mars, red dust blowing in the wind, dramatic sunset on the horizon, cinematic wide shot, slow motion, detailed space suit reflections, epic atmosphere, volumetric lighting, smooth camera tracking. Audio: howling Martian wind, horse hooves crunching gravel, rhythmic radio breathing.",
    "duration": 4,
    "aspect_ratio": "16:9"
  }
}
JSON
)

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Step 3: Poll for video result

Poll with task_id while status is not_started or running, and stop at finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll with task_id while status is not_started or running, and stop at finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-sora2-t2v-849120",
    "status": "running",
    "created_time": "2026-09-17T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete script example

Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a 600-second polling timeout.

Complete script example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "openai/sora-2/text-to-video",
  "input": {
    "prompt": "An astronaut riding a horse across the surface of Mars, red dust blowing in the wind, dramatic sunset on the horizon, cinematic wide shot, slow motion, detailed space suit reflections, epic atmosphere, volumetric lighting, smooth camera tracking. Audio: howling Martian wind, horse hooves crunching gravel, rhythmic radio breathing.",
    "duration": 4,
    "aspect_ratio": "16:9"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Input parameters

Parameters passed within the input object to /api/generate/submit:

Field	Type	Required	Default	Description
prompt	string	Yes	—	At least 1 character after trimming.
duration	integer	No	4	4, 8, 12, 16, or 20, in seconds.
aspect_ratio	string	No	16:9	16:9 or 9:16.

Response Fields

Task creation payload and query status response details:

Field	Type	Description
code	integer	Application result code; successful responses return 200.
message	string	Human-readable status or error message.
data.task_id	string	Unique asynchronous task identifier.
data.status	string	Current lifecycle: not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp in ISO 8601 format.
data.files[]	array	Output files generated upon completion.
data.files[].file_url	string	Public URL for downloading or playing the generated video.
data.error_message	string \| null	Detailed error explanation when task status is failed.

Task Lifecycle

Poll status until reaching finished or failed:

not_started
Task accepted and waiting in compute dispatch queue.
running
Diffusion model is generating video frames and audio track.
finished
Generation completed; read video URL from data.files[0].file_url.
failed
Task stopped due to parameter error or safety filter; inspect data.error_message.

Polling and Errors

AuthenticationVerify Bearer API key in request header if 401 is received.
ValidationCheck prompt length and duration enum choices on 400 response.
Polling intervalPoll with a 2-second base interval, extending gradually for longer jobs.
Webhook callbackProvide callback_url at request top level to receive asynchronous POST notifications.

Endpoint limits

Specification	Value	Details
Input mode	Text only	A prompt defines the scene, action, camera, and sound.
Output	MP4 video with native audio	Asynchronous video generation with downloadable MP4 URL upon completion.
Duration	4 / 8 / 12 / 16 / 20 seconds	Default is 4 seconds.
Aspect ratio	16:9 / 9:16	Default is 16:9 (1280x720).
Resolution	720p	Standard Official output is 720p.
Billing basis	Per video duration tier	4s=48, 8s=96, 12s=144, 16s=192, 20s=240 credits.

View Sora 2 API documentation

Sora 2 Text to Video

Sora 2 Text to Video is an OpenAI model for generating video from text. It creates 720p resolution videos with synchronized action and ambient audio directly from text descriptions. Supporting fixed tiers of 4, 8, 12, 16, and 20 seconds, it enables creators and developers to rapidly validate shot timing, storytelling flow, and audiovisual atmospheres.

Why Choose This Endpoint?

Text-Driven Audiovisual ProductionDirectly construct character actions, spatial settings, and camera paths through natural language without preparing initial reference assets.
Native Synchronized AudioGenerates ambient soundscapes, collision impacts, and room acoustics in tandem with visuals, removing the need for external audio alignment.
Physical Simulation & Motion RealismAdheres to authentic gravity, inertia, momentum, and 3D spatial continuity, producing natural human movement and believable physical interactions.
Predictable Fixed Tier BudgetingProvides precise 4s, 8s, 12s, 16s, and 20s tiers with transparent credit deductions, making commercial production budgeting straightforward.
Flexible Landscape & Portrait FramingSupports 16:9 landscape (1280x720) and 9:16 portrait (720x1280) framing for both cinematic editing and mobile social media distribution.
Production-Ready Async WorkflowSingle POST submission returns an immediate global task ID with resilient status polling and optional webhook callbacks for automated pipelines.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Describe subjects, actions, camera movement, lighting, atmosphere, and sound elements. Minimum 1 character after trimming.
duration	Optional	Integer. Sets clip length in seconds. Supported tiers are 4, 8, 12, 16, or 20 seconds; playground preselects 4 seconds. Default`48121620`
aspect_ratio	Optional	String. Sets framing format: 16:9 (default, 1280x720) or 9:16 (720x1280). Default`16:99:16`

How to Use

Get API KeyCreate an API key in the developer dashboard and pass Authorization: Bearer <API_KEY> in request headers.
Allocate CreditsTop up pay-as-you-go API credits. A 4-second clip uses 48 credits, scaling proportionally with selected clip duration.
Submit & Retrieve VideoSend POST request to /api/generate/submit with prompt, duration, and aspect_ratio, then poll status until finished.

Pricing Structure

Sora 2 uses fixed duration tiers: 48 credits for 4s, 96 credits for 8s, 144 credits for 12s, 192 credits for 16s, and 240 credits for 20s. All tiers produce 720p video with synchronized audio. Based on the standard $10 for 2,000 credits package (about $0.06/s), cost remains predictable with pay-as-you-go credits and no recurring plan requirement.

Usage	Rate	Details
4 seconds	48 credits (~$0.24)	Default tier, optimal for quick concept prototyping and storyboard beats.
8 seconds	96 credits (~$0.48)	Fixed tier, suitable for narrative transitions and medium-length action shots.
12 seconds	144 credits (~$0.72)	Fixed tier, ideal for continuous character performance and scene progression.
16 seconds	192 credits (~$0.96)	Fixed tier, designed for long tracking shots and complex visual sequences.
20 seconds	240 credits (~$1.20)	Maximum continuous generation tier, perfect for full social video spots.

Best Use Cases

Creative Storyboarding & PrevisRapidly generate dynamic visual boards for film and commercial productions, evaluating camera staging and scene pacing before shooting.
Social Media AdvertisingProduce punchy 9:16 short-form video ads with synchronized audio tracks tailored for high-engagement social platforms.
AI Video Platform IntegrationEmbed OpenAI video generation into SaaS products, developer pipelines, and creative studios via standard REST endpoints.
Educational & Explainer ContentDemonstrate scientific concepts and simulated physical interactions with clear audio cues and predictable generation costs.

Pro Tips

Describe subjects, physical actions, environment lighting, and soundscape elements in separate phrases for complete audiovisual alignment.
Use standard cinematography terms like slow push-in, low-angle tracking shot, or orbital camera movement to guide perspective.
Start prompt iteration on the 4-second tier to validate visual composition before generating full 12s to 20s sequences.
Explicitly include ambient sounds (e.g. wind howling, gravel footsteps, water splashes) to maximize the realism of the synchronized audio track.

Usage Notes

Sora 2 outputs 720p resolution (1280x720 in 16:9 or 720x1280 in 9:16) with embedded stereo audio.
Prompt requires at least 1 non-whitespace character and accurately interprets detailed scene directions.
You can configure callback_url for instant task completion notifications, with 2–3s baseline recommended polling intervals.

Sora 2 Pro Text to VideoGenerate a 4-second to 20-second clip with synced audio from a text prompt.

Sora 2 Pro Image to VideoGenerate a 4-second to 20-second clip with synced audio from a text prompt and one required reference image.

Sora 2 Text to Video API frequently asked questions

What is the Sora 2 Text to Video API?

Sora 2 Text to Video is an OpenAI model for video generation from text. It generates 720p resolution videos with synchronized action and ambient audio from natural language prompts, supporting multi-axis camera control and flexible framing. Built on OpenAI's multimodal diffusion architecture, it strictly adheres to real-world physics and temporal continuity while delivering expressive visual detail. You can call it programmatically or try it from the playground above.

Does Sora 2 Text to Video generate synchronized audio?

Yes. The model synthesizes native synchronized stereo audio directly during video generation without external audio models. When you include acoustic descriptions such as ambient wind, footsteps, engine hums, or dialogue cues in your prompt, the output MP4 embeds synchronized audio that matches visual actions.

What is the maximum duration for a single Sora 2 Text to Video generation?

A single call supports generating clips up to 20 seconds, with exact options of 4, 8, 12, 16, or 20 seconds (the playground defaults to 4 seconds). These fixed duration tiers allow developers and creative teams to calculate exact budgets before launching tasks.

What is the output resolution of Sora 2 Text to Video?

Sora 2 Standard outputs 720p resolution, rendering 1280x720 in landscape (16:9) and 720x1280 in portrait (9:16). This resolution provides an optimal balance between visual fidelity and generation speed for daily prototyping and social video workflows.

How can I direct camera trajectories in Sora 2 Text to Video?

We recommend using established cinematographic phrasing in separate clauses, such as slow dolly forward, low-angle tracking shot, or orbital camera movement. Pairing motion direction with specific lighting cues helps the model execute precise camera choreography.

Is Sora 2 Text to Video suitable for 9:16 vertical videos?

Yes. By specifying aspect_ratio as 9:16, the model formats outputs into 720x1280 portrait orientation. Focusing your prompt on vertical composition and character placement ensures optimal framing for mobile and short-video feeds.

When should I choose the Sora 2 Pro endpoint?

Choose Sora 2 Pro Text to Video when your project demands 1080p full HD master delivery, richer lighting complexity, or enhanced textural realism. Pro offers 720p, 1024p, and 1080p resolution tiers tailored for commercial film and broadcast assets.