Sora 2 Image to Video API

openai/sora-2/image-to-video

Sora 2 (Image to Video) animates a single static reference image into 720p HD video with synchronized audio, supporting fixed durations from 4 to 20 seconds in 16:9 or 9:16 aspect ratios. It preserves subject appearance, textural details, and spatial composition while injecting realistic physical dynamics and atmospheric acoustics.

Input

Prompt

291

Reference image

Add image

Upload one reference image before running this task.

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 Text to Video Sora 2 Pro Text to Video Sora 2 Pro Image to Video

Examples

The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.

Steam rises and swirls from the ceramic coffee cup on the wooden table, warm cafe light flickering subtly, gentle macro stillness. Natural sound: quiet cafe ambience, a faint cup clink, soft murmur. Realistic motion, no text, no logos.

The white sailboat drifts slowly across the calm alpine lake, its sail rippling gently, mountain reflections shimmering on the water. Natural sound: water lapping against the hull, soft wind, a distant bird call. Realistic motion, no text, no logos.

REST API

Quick Start

Authenticate, pass reference image and motion prompt, then retrieve 720p animated video.

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 image-to-video task

Send POST request to /api/generate/submit with model openai/sora-2/image-to-video, prompt, and image_urls.

Submit request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "openai/sora-2/image-to-video",
  "input": {
    "prompt": "The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.",
    "duration": 4,
    "aspect_ratio": "16:9",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/openai/sora-2/image-to-video/v1/01/input.png"
    ]
  }
}
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-i2v-918230",
    "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/image-to-video",
  "input": {
    "prompt": "The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.",
    "duration": 4,
    "aspect_ratio": "16:9",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/openai/sora-2/image-to-video/v1/01/input.png"
    ]
  }
}
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	—	Action and camera motion prompt, at least 1 character.
image_urls	array	Yes	—	Array containing exactly one public image URL. Supported formats: JPEG, PNG, WebP (≤10MB).
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 animating reference image frames and synthesizing audio.
finished
Generation completed; read video URL from data.files[0].file_url.
failed
Task stopped due to invalid image or safety filter; inspect data.error_message.

Polling and Errors

AuthenticationVerify Bearer API key in request header if 401 is received.
Image validationEnsure image_urls contains exactly 1 valid public image URL under 10MB in supported format.
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 + One Image	A prompt guides motion, and image_urls provides exactly one required reference image.
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.
Image requirements	JPEG / PNG / WebP, ≤ 10MB	Must provide exactly one publicly accessible URL.
Billing basis	Per video duration tier	4s=48, 8s=96, 12s=144, 16s=192, 20s=240 credits.

View Sora 2 API documentation

Sora 2 Image to Video

Sora 2 Image to Video is an OpenAI model for generating video from images. It uses a single reference image as the initial visual anchor, animating camera paths and subject movements according to text prompts to deliver continuous 720p video clips with native synchronized sound. With fixed tiers of 4, 8, 12, 16, and 20 seconds, it serves as a workhorse for product animation, character awakening, and commercial visual previews.

Why Choose This Endpoint?

High-Fidelity First-Frame AwakeningUses a single reference image as an unambiguous visual baseline, locking subject appearance, spatial layout, and lighting style.
Image-Guided Native SoundscapesSynthesizes synchronized ambient acoustics and motion foley directly aligned with the visual scene, eliminating separate audio post-production.
Motion Stability & Authentic PhysicsSimulates natural cloth dynamics, fluid physics, and human momentum without morphing artifacts or anatomical distortions.
Predictable Tier-Based BudgetingOffers structured 4s, 8s, 12s, 16s, and 20s tiers with upfront credit calculation, ideal for high-volume automated asset generation.
Standard Framing AdaptabilityOutputs 16:9 landscape (1280x720) and 9:16 portrait (720x1280) formats, fitting desktop displays and mobile short-form video feeds.
Clean Developer-Friendly ContractAccepts public image URLs directly inside the input payload with standard asynchronous polling and optional webhooks for pipeline automation.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Describe action choreography, camera trajectory, environmental changes, and sound cues. Minimum 1 character after trimming.
image_urls	Required	Array of strings. Exactly one public URL pointing to a JPEG, PNG, or WebP image, up to 10MB.
duration	Optional	Integer. Sets clip duration in seconds: 4, 8, 12, 16, or 20. The playground defaults to 4 seconds. Default`48121620`
aspect_ratio	Optional	String. Output framing format: 16:9 (default, 1280x720) or 9:16 (720x1280). Default`16:99:16`

How to Use

Prepare Image & API KeyHost your reference image publicly (JPEG, PNG, or WebP, ≤10MB) and obtain an API key with Bearer authentication.
Select Duration & Aspect RatioChoose between 4s and 20s duration tiers and specify 16:9 or 9:16 framing based on distribution targets.
Submit Task & Retrieve ResultSend POST request to /api/generate/submit with prompt and image_urls, then poll status until finished to download video.

Pricing Structure

Sora 2 Image to Video shares the standard duration tier rates: 48 credits for 4s, 96 credits for 8s, 144 credits for 12s, 192 credits for 16s, and 240 credits for 20s. All clips render at 720p with native synchronized audio. Equivalent to ~$0.06/sec based on the base rate of 2,000 credits for $10, with pay-as-you-go flexibility and no mandatory subscription.

Usage	Rate	Details
4 seconds	48 credits (~$0.24)	Default tier, optimal for quick motion tests and subtle camera push-ins.
8 seconds	96 credits (~$0.48)	Fixed tier, suitable for full character gestures and camera pans.
12 seconds	144 credits (~$0.72)	Fixed tier, ideal for multi-stage character action and unfolding scenes.
16 seconds	192 credits (~$0.96)	Fixed tier, designed for slow cinematic exploration and dramatic sequences.
20 seconds	240 credits (~$1.20)	Maximum generation tier, perfect for full commercial social spots.

Best Use Cases

E-Commerce Product ShowcaseTransform static studio product photography into dynamic 720p video clips featuring realistic lighting reflections and subtle motion.
Character Art & Avatar AnimationBreathe life into 2D character designs and portraits while strictly maintaining facial identity, costume styling, and expressive movement.
Cinematography & Previs VisualizationTurn storyboard keyframes and location stills into fluid video sequences to evaluate camera blocking before shooting.
Social Video AdvertisingDerive high-converting 9:16 vertical video assets from key campaign posters with native ambient audio tailored for social channels.

Pro Tips

Ensure reference images have clear focal subjects and balanced exposure so depth cues are cleanly extracted.
Focus text prompts primarily on desired motion and camera directions rather than reiterating static attributes already clear in the image.
Choose an aspect ratio parameter that closely matches your source image dimensions to avoid unintended subject reframing.
Describe expected acoustic events (e.g. footsteps on hardwood, rustling leaves) to guide rich synchronized audio generation.

Usage Notes

image_urls accepts exactly one public URL pointing to a JPEG, PNG, or WebP image file up to 10MB.
Outputs standard MP4 video at 720p (1280x720 in 16:9, 720x1280 in 9:16) with embedded stereo sound.
Asynchronous workflow supports polling with 2s recommended intervals or specifying callback_url for webhook delivery.

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 Image to Video API frequently asked questions

What is the Sora 2 Image to Video API?

Sora 2 Image to Video is an OpenAI model for video generation from images. It animates a single static reference image based on text prompts into 720p resolution videos complete with synchronized action and ambient audio. Built on OpenAI's multimodal diffusion architecture, it preserves subject identity, color harmony, and spatial composition while injecting authentic physical dynamics. You can call it programmatically or try it from the playground above.

How does Sora 2 Image to Video maintain subject identity?

The model extracts key face landmarks, fabric textures, and environmental lighting from the input image to condition generation. For best results, use high-resolution source images with clear subjects and direct your prompt toward camera and limb motion rather than re-specifying static appearance.

How many reference images does Sora 2 Image to Video support?

Sora 2 Standard Image to Video accepts exactly 1 reference image passed in the image_urls array. The image functions as the initial start frame, and submitting arrays with more than 1 image will result in a validation error.

Can Sora 2 Image to Video generate audio for still photos?

Yes. The model incorporates joint audiovisual reasoning, automatically synthesizing realistic ambient audio and foley sound effects matching the visual scene (such as ocean waves, rustling leaves, or city traffic) without external sound tools.

What clip durations does Sora 2 Image to Video offer?

A single call supports generating clips up to 20 seconds, with exact duration options of 4, 8, 12, 16, or 20 seconds (the playground defaults to 4 seconds). Fixed durations provide full budget predictability before submitting jobs.

What image formats are accepted by Sora 2 Image to Video?

The endpoint accepts public URLs pointing to JPEG, PNG, or WebP images up to 10MB in size. Ensure the URL is directly accessible over HTTP or HTTPS without authentication blockers.

When should I choose the Sora 2 Pro Image to Video endpoint?

Choose Sora 2 Pro Image to Video when you need auto aspect ratio matching (which preserves original image dimensions without crop) or up to 1080p full HD master delivery for commercial broadcasts.