VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/Sora 2 API

Sora 2 API

Build Sora 2 video workflows with text prompts and optional starting images. Choose between two API contracts for portrait or landscape output, with storyboard controls available on the model route.

Get API keyView API docs
Abstract illustration for Sora 2 API
PlaygroundAPIPricingGuideFAQs

Sora 2 API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

4 parameters

Text description of the video to generate.

Optional conditioning image URL (must be http/https).(Optional)

Requested duration in seconds. Defaults to 4 and is normalized to the nearest supported value: 4, 8, or 12.(Optional)

Output size for text-to-video. Image-to-video infers its orientation from the input image.(Optional)

Default: 720*1280

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/sora2/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "prompt": "A tiny service robot delivers flowers through a lively open-air market, cinematic natural motion",
  "size": "720*1280"
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/sora2/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["videoUrl"] // .data["videoUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

EndpointSora2 Video Generator ↓
Required inputs
prompt
Output
Video·videoUrl
EndpointSora 2 AI Video Generator ↓
Required inputs
prompt
Output
Video·videoUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Sora2 Video Generator

Requiredprompt
Optional inputsimageUrl
Request controls
  • duration: see parameter rules
  • size: "720*1280", "1280*720"

Sora 2 AI Video Generator

Modes: text-to-video, image-to-video

Additional inputs; requirements vary by mode

prompt imageUrl

Media limits by mode
  • Image To VideoImage: jpg, png
Request controls
  • duration: "10", "15"
  • aspectRatio: "16:9", "9:16"
  • storyboard: default false

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Sora2 Video Generator

POST /api/v1/sora2/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text description of the video to generate.

Edit the sample inputs for your own task before submitting.

Sora2 Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/sora2/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A tiny service robot delivers flowers through a lively open-air market, cinematic natural motion","size":"720*1280"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules4 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText description of the video to generate. No additional field constraint listed.
imageUrlstringNoNot specifiedOptional conditioning image URL (must be http/https). No additional field constraint listed.
durationnumberNoNot specifiedRequested duration in seconds. Defaults to 4 and is normalized to the nearest supported value: 4, 8, or 12. No additional field constraint listed.
sizestringNo"720*1280"Output size for text-to-video. Image-to-video infers its orientation from the input image. Values: "720*1280", "1280*720" · Default: "720*1280"

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/sora2/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Sora2 Video Generator query
curl -X POST "https://vidmage.ai/api/v1/sora2/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Sora 2 AI Video Generator

POST /api/v1/sora-2-ai-video-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text prompt describing the video to generate (max 4000 chars).

Edit the sample inputs for your own task before submitting.

Sora 2 AI Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/sora-2-ai-video-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"An astronaut explores a greenhouse on Mars while dust moves softly outside the glass walls","duration":"10","aspectRatio":"9:16","storyboard":false}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules5 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText prompt describing the video to generate (max 4000 chars). Minimum length: 5 · Maximum length: 4000
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image-to-video mode. No additional field constraint listed.
durationstringNo"10"Video duration in seconds. Values: "10", "15" · Default: "10"
aspectRatiostringNo"9:16"Output aspect ratio. Values: "16:9", "9:16" · Default: "9:16"
storyboardbooleanNofalseEnable storyboard-based planning for the generated video. Default: false
Mode-specific fields & media limits
Text To Video rules
ControlMode-specific rule
promptRequired; minimum 5 characters; maximum 4000 characters
durationValues: "10", "15"; mode default: "10"
aspectRatioValues: "16:9", "9:16"; mode default: "9:16"
storyboardDefault: false
Image To Video rules
ControlMode-specific rule
promptRequired; minimum 5 characters; maximum 4000 characters
durationValues: "10", "15"; mode default: "10"
aspectRatioValues: "16:9", "9:16"; mode default: "9:16"
imageUrlImage input
storyboardDefault: false

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/sora-2-ai-video-generator/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Sora 2 AI Video Generator query
curl -X POST "https://vidmage.ai/api/v1/sora-2-ai-video-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Sora2 Video Generatorvideo API1 generation request: 40 credits
How this is calculated
  • Video duration: 10 credits / second · 10 credits minimum

Duration is normalized to a supported video length before calculating the charge.

Estimate your own request ↗
10 credits / second10 credits minimum
Sora 2 AI Video Generatorvideo API10-second video: 50 credits
How this is calculated
  • Base rate: 5 credits / second

Base charge = duration × the selected resolution rate.

Estimate your own request ↗
5 credits / secondSee calculation details
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About Sora 2 API

VidMage's Sora 2 API is a video generation interface that turns scene descriptions and optional starting images into portrait or landscape clips. It provides two separate request contracts with different duration and framing fields. The model route also includes a storyboard option for scenes described in the prompt. To explore this model's browser workflow, open VidMage's Sora 2 AI Video Generator.

Sora 2 API capabilities

Start with text or an image
Describe the intended scene and optionally provide a starting image to establish its opening visual.
Compose portrait or landscape clips
Choose pixel dimensions on sora2 or aspect-ratio labels on the model route to frame the requested video.
Explore storyboard generation
Use the model route's storyboard boolean with a scene sequence described in your written prompt.

What you can build

Commercial storyboard prototypes

A product reveal followed by a user reaction and a closing shot forms a simple commercial outline. The model route's storyboard option provides a way to explore that sequence from a written brief while developing the production plan.

Animation studies for illustrations

A finished illustration already establishes the composition. Add one action, such as a paper boat drifting across a pond, to explore how the scene could move. Artists can use the resulting clip as an animation study.

Training scenario concepts

Course designers can visualize a fictional customer-service encounter before scripting the lesson around it. Describe the setting and action, choose the available framing, and use the scene concept to plan instructional text and narration.

How to use Sora 2 API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read videoUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Use the selected request contract
sora2 uses numeric duration and a size field. The model route uses string duration and aspectRatio, so switching capabilities also requires reviewing your request fields.
Keep storyboard on the model route
storyboard is a boolean on sora-2-ai-video-generator, not a scene array. That route lists "10" and "15" for duration; sora2 does not publish an accepted duration range.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/sora2/query
Completed result
videoUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Is Sora 2 API availability changing?

OpenAI has scheduled its Sora models and Videos API for removal on September 24, 2026. This does not establish a VidMage cutoff date. Confirm VidMage availability and a migration plan before a new integration.

OpenAI deprecation notice ↗
Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • Veo 3.1 API↗
  • Wan Video API↗
  • Vidu API↗
  • Midjourney Video API↗
  • HappyHorse API↗
  • Grok Video API↗
  • PixVerse API↗
  • Seedance API↗