Openai Sora 2 Text To Video API Documentation

Openai Sora 2 Text To Video API Documentation

Playground

OpenAI Sora 2 is a state-of-the-art text-to-video model with realistic visuals, accurate physics, synchronized audio, and strong steerability. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

> Notice — Service Stability > > The Sora 2 family is currently unstable. Generations may fall back to alternative models without notice and the service can be temporarily unavailable. OpenAI is also expected to discontinue this model in the future. > > If you need an equally capable, stable alternative, we recommend Seedance 2: bytedance/seedance-2.0/text-to-video.

Sora 2 Text-to-Video

Describe the scene in natural language, reference your pre-defined character IDs, and the model renders a cohesive, temporally consistent video where every character looks and moves exactly as intended — no manual compositing required.

Why Choose This?

• True multi-character consistency Reference two or more character IDs in a single generation. Each character retains its unique appearance, proportions, and style throughout every frame.

• Natural-language scene control Describe interactions, environments, and actions in plain text. The model understands spatial relationships and character dynamics to produce believable compositions.

• Flexible aspect ratio support Choose between portrait (720×1280) and landscape (1280×720) orientations to match your target platform.

• Scalable duration Generate clips from 4 seconds up to 20 seconds in fixed steps, giving you full control over pacing and output cost.

• Production-ready output Delivers smooth, artifact-free motion suitable for marketing content, storytelling, game cinematics, and social media video.

Parameters

How to Use

1.2. Select size — portrait (720×1280) for mobile/social, landscape (1280×720) for widescreen. 3. Set duration — choose 4, 8, 12, 16, or 20 seconds based on your scene length. 4.5. Submit — generate, preview, and download your video.

Pricing

Billing Rules

• Rate: $0.10 per second
• Duration options: 4, 8, 12, 16, or 20 seconds
• Billing is based on the selected duration, not actual playback length

Best Use Cases

• Social Media Content — Produce portrait-format multi-character clips optimized for Reels, TikTok, and Shorts.
• Advertising & Campaigns — Generate diverse cast scenarios rapidly for A/B testing creative variations.

Pro Tips

• Be specific about character positions and actions in your prompt for better spatial composition.
• Use portrait mode (720×1280) for mobile-first platforms and landscape (1280×720) for cinematic or desktop use.
• Start with a 4-second generation to validate composition and character rendering before committing to a longer duration.
• Ensure all referenced character IDs are valid and accessible in your account before submitting.

Notes

• Character IDs must be created and saved in advance — this model references existing character profiles and does not create new definitions.
• Complex multi-character scenes benefit from concise, clearly structured prompts.

Related Models

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "size": "720*1280",
  "duration": 4
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/openai/sora-2/text-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters