Sora-2 Video Generation Guide

A complete guide to creating, iterating on, and managing videos with Sora-2.

Overview

Sora-2 is Apifree’s advanced video generation model, capable of creating high-quality video content from natural language prompts or images. The model is built on multimodal diffusion technology with deep understanding of 3D space, motion, and scene continuity. The Video Generation API provides five main endpoints, each with distinct capabilities:

Create video: Start a new render job from a prompt, with optional reference inputs or a remix ID
Get video status: Retrieve the current state of a render job and monitor its progress
Download video: Fetch the finished MP4 once the job is completed
List videos: Enumerate your videos with pagination for history, dashboards, or housekeeping
Delete videos: Remove an individual video ID from storage

Models

The Sora-2 model comes in two variants, each tailored for different use cases.

Sora-2

sora-2 is designed for speed and flexibility. It’s ideal for the exploration phase, when you’re experimenting with tone, structure, or visual style and need quick feedback rather than perfect fidelity. It generates good quality results quickly, making it well suited for rapid iteration, concepting, and rough cuts. sora-2 is often more than sufficient for social media content, prototypes, and scenarios where turnaround time matters more than ultra-high fidelity.

Sora-2 Pro

sora-2-pro produces higher quality results. It’s the better choice when you need production-quality output. sora-2-pro takes longer to render and is more expensive to run, but it produces more polished, stable results. It’s best for high-resolution cinematic footage, marketing assets, and any situation where visual precision is critical.

Generate a video

Generating a video is an asynchronous process:

When you call the POST /videos endpoint, the API returns a job object with a job id and an initial status
You can either poll the GET /videos/{video_id} endpoint until the status transitions to completed, or – for a more efficient approach – use webhooks (see the webhooks section below) to be notified automatically when the job finishes
Once the job has reached the completed state you can fetch the final MP4 file with GET /videos/{video_id}/content

Start a render job

Start by calling POST /videos with a text prompt and the required parameters. The prompt defines the creative look and feel – subjects, camera, lighting, and motion – while parameters like size and seconds control the video’s resolution and length.

cURL
Python (requests)
Python (OpenAI)

curl https://api.apifree.ai/v1/openai/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A video of the words 'Thank you' in sparkling letters",
    "size": "1280x720",
    "seconds": 8
  }'

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"

response = requests.post(
    f"{BASE_URL}/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "sora-2",
        "prompt": "A video of the words 'Thank you' in sparkling letters",
        "size": "1280x720",
        "seconds": 8
    }
)

video = response.json()
print("Video generation started: ", video)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

video = client.videos.create(
    model="sora-2",
    prompt="A video of the words 'Thank you' in sparkling letters",
    size="1280x720",
    seconds=8
)

print("Video generation started: ", video)

The response is a JSON object with a unique id and an initial status such as queued or in_progress. This means the render job has started.

{
  "id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
  "object": "video",
  "created_at": 1758941485,
  "status": "queued",
  "model": "sora-2",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720"
}

Guardrails and restrictions

The API enforces several content restrictions:

Only content suitable for audiences under 18 (a setting to bypass this restriction will be available in the future)
Copyrighted characters and copyrighted music will be rejected
Real people—including public figures—cannot be generated
Input images with faces of humans are currently rejected

Make sure prompts, reference images, and transcripts respect these rules to avoid failed generations.

Effective prompting

For best results, describe shot type, subject, action, setting, and lighting. For example:

“Wide shot of a child flying a red kite in a grassy park, golden hour sunlight, camera slowly pans upward.”
“Close-up of a steaming coffee cup on a wooden table, morning light through blinds, soft depth of field.”

This level of specificity helps the model produce consistent results without inventing unwanted details.

Monitor progress

Video generation takes time. Depending on model, API load and resolution, a single render may take several minutes. You can poll the API to request status updates or you can get notified via a webhook.

Poll the status endpoint

Call GET /videos/{video_id} with the id returned from the create call. The response shows the job’s current status, progress percentage (if available), and any errors. Typical states are queued, in_progress, completed, and failed. Poll at a reasonable interval (for example, every 10–20 seconds), use exponential backoff if necessary, and provide feedback to users that the job is still in progress.

cURL
Python (requests)
Python (OpenAI)

curl https://api.apifree.ai/v1/openai/videos/video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5 \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"
VIDEO_ID = "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5"

while True:
    response = requests.get(
        f"{BASE_URL}/videos/{VIDEO_ID}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    video = response.json()
    
    print(f"Status: {video['status']}, Progress: {video.get('progress', 0)}%")
    
    if video['status'] == 'completed':
        print("Video generation completed!")
        break
    elif video['status'] == 'failed':
        print("Video generation failed!")
        break
    
    time.sleep(10)  # Wait 10 seconds before checking again

from openai import OpenAI
import time

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

video = client.videos.create(
    model="sora-2",
    prompt="A video of the words 'Thank you' in sparkling letters"
)

while video.status in ['queued', 'in_progress']:
    video = client.videos.retrieve(video.id)
    print(f"Status: {video.status}, Progress: {getattr(video, 'progress', 0)}%")
    time.sleep(10)

if video.status == 'completed':
    print("Video generation completed!")
else:
    print(f"Video generation failed with status: {video.status}")

Response example:

{
  "id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
  "object": "video",
  "created_at": 1758941485,
  "status": "in_progress",
  "model": "sora-2",
  "progress": 33,
  "seconds": "8",
  "size": "1280x720"
}

Use webhooks for notifications

Instead of polling job status repeatedly with GET, register a webhook to be notified automatically when a video generation completes or fails. Webhooks can be configured in your webhook settings page. When a job finishes, the API emits one of two event types: video.completed and video.failed. Each event includes the ID of the job that triggered it. Example webhook payload:

{
  "id": "evt_abc123",
  "object": "event",
  "created_at": 1758941485,
  "type": "video.completed",
  "data": {
    "id": "video_abc123"
  }
}

Retrieve results

Download the MP4

Once the job reaches status completed, fetch the MP4 with GET /videos/{video_id}/content. This endpoint streams the binary video data and returns standard content headers, so you can either save the file directly to disk or pipe it to cloud storage.

cURL
Python (requests)
Python (OpenAI)

# Download video
curl -L "https://api.apifree.ai/v1/openai/videos/video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output video.mp4

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"
VIDEO_ID = "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5"

# Download video content
response = requests.get(
    f"{BASE_URL}/videos/{VIDEO_ID}/content",
    headers={"Authorization": f"Bearer {API_KEY}"},
    stream=True
)

with open('video.mp4', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

print("Video downloaded as video.mp4")

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

# Create and wait for video to complete
video = client.videos.createAndPoll(
    model="sora-2",
    prompt="A video of the words 'Thank you' in sparkling letters"
)

if video.status == 'completed':
    # Download video content
    content = client.videos.downloadContent(video.id)
    
    # Save to file
    with open('video.mp4', 'wb') as f:
        f.write(content.read())
    
    print("Video downloaded as video.mp4")

You now have the final video file ready for playback, editing, or distribution. Download URLs are valid for a maximum of 1 hour after generation. If you need long-term storage, copy the file to your own storage system promptly.

Download supporting assets

For each completed video, you can also download a thumbnail and a spritesheet. These are lightweight assets useful for previews, scrubbers, or catalog displays. Use the variant query parameter to specify what you want to download. The default is variant=video for the MP4.

cURL
Python (requests)
Python (OpenAI)

# Download thumbnail
curl -L "https://api.apifree.ai/v1/openai/videos/video_abc123/content?variant=thumbnail" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output thumbnail.webp

# Download spritesheet
curl -L "https://api.apifree.ai/v1/openai/videos/video_abc123/content?variant=spritesheet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output spritesheet.jpg

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"
VIDEO_ID = "video_abc123"

# Download thumbnail
response = requests.get(
    f"{BASE_URL}/videos/{VIDEO_ID}/content",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"variant": "thumbnail"}
)
with open('thumbnail.webp', 'wb') as f:
    f.write(response.content)

# Download spritesheet
response = requests.get(
    f"{BASE_URL}/videos/{VIDEO_ID}/content",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"variant": "spritesheet"}
)
with open('spritesheet.jpg', 'wb') as f:
    f.write(response.content)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

VIDEO_ID = "video_abc123"

# Download thumbnail
thumbnail = client.videos.downloadContent(VIDEO_ID, variant="thumbnail")
with open('thumbnail.webp', 'wb') as f:
    f.write(thumbnail.read())

# Download spritesheet
spritesheet = client.videos.downloadContent(VIDEO_ID, variant="spritesheet")
with open('spritesheet.jpg', 'wb') as f:
    f.write(spritesheet.read())

Use image references

You can guide a generation with an input image, which acts as the first frame of your video. This is useful if you need the output video to preserve the look of a brand asset, a character, or a specific environment. Include an image file as the input_reference parameter in your POST /videos request. The image must match the target video’s resolution (size). Supported file formats are image/jpeg, image/png, and image/webp.

cURL
Python (requests)
Python (OpenAI)

curl -X POST "https://api.apifree.ai/v1/openai/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F prompt="She turns around and smiles, then slowly walks out of the frame." \
  -F model="sora-2-pro" \
  -F size="1280x720" \
  -F seconds="8" \
  -F input_reference="@sample_720p.jpeg;type=image/jpeg"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"

with open('sample_720p.jpeg', 'rb') as f:
    files = {
        'input_reference': ('sample_720p.jpeg', f, 'image/jpeg')
    }
    data = {
        'prompt': 'She turns around and smiles, then slowly walks out of the frame.',
        'model': 'sora-2-pro',
        'size': '1280x720',
        'seconds': '8'
    }
    
    response = requests.post(
        f"{BASE_URL}/videos",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files=files,
        data=data
    )
    
    video = response.json()
    print("Video generation started: ", video)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

with open('sample_720p.jpeg', 'rb') as f:
    video = client.videos.create(
        model="sora-2-pro",
        prompt="She turns around and smiles, then slowly walks out of the frame.",
        size="1280x720",
        seconds=8,
        input_reference=f
    )
    
    print("Video generation started: ", video)

Remix completed videos

Remix lets you take an existing video and make targeted adjustments without regenerating everything from scratch. Provide the remix_video_id of a completed job along with a new prompt that describes the change, and the system reuses the original’s structure, continuity, and composition while applying the modification. This works best when you make a single, well-defined change because smaller, focused edits preserve more of the original fidelity and reduce the risk of introducing artifacts.

cURL
Python (requests)
Python (OpenAI)

curl -X POST "https://api.apifree.ai/v1/openai/videos/video_abc123/remix" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Shift the color palette to teal, sand, and rust, with a warm backlight."
  }'

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"
ORIGINAL_VIDEO_ID = "video_abc123"

response = requests.post(
    f"{BASE_URL}/videos/{ORIGINAL_VIDEO_ID}/remix",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Shift the color palette to teal, sand, and rust, with a warm backlight."
    }
)

remix_video = response.json()
print("Remix video generation started: ", remix_video)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

ORIGINAL_VIDEO_ID = "video_abc123"

remix_video = client.videos.remix(
    ORIGINAL_VIDEO_ID,
    prompt="Shift the color palette to teal, sand, and rust, with a warm backlight."
)

print("Remix video generation started: ", remix_video)

Remix is especially valuable for iteration because it lets you refine without discarding what already works. By constraining each remix to one clear adjustment, you keep the visual style, subject consistency, and camera framing stable, while still exploring variations in mood, palette, or staging. This makes it far easier to build polished sequences through small, reliable steps.

Maintain your library

Use GET /videos to enumerate your videos. The endpoint supports optional query parameters for pagination and sorting.

cURL
Python (requests)
Python (OpenAI)

# Default list
curl "https://api.apifree.ai/v1/openai/videos" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With parameters
curl "https://api.apifree.ai/v1/openai/videos?limit=20&after=video_123&order=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"

# Default list
response = requests.get(
    f"{BASE_URL}/videos",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
videos = response.json()
print(videos)

# With parameters
response = requests.get(
    f"{BASE_URL}/videos",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 20, "after": "video_123", "order": "asc"}
)
videos = response.json()
print(videos)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

# Default list
videos = client.videos.list()
print(videos)

# With parameters
videos = client.videos.list(limit=20, after="video_123", order="asc")
print(videos)

Use DELETE /videos/{video_id} to remove videos you no longer need from storage.

cURL
Python (requests)
Python (OpenAI)

curl -X DELETE "https://api.apifree.ai/v1/openai/videos/video_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apifree.ai/v1/openai"
VIDEO_ID = "video_abc123"

response = requests.delete(
    f"{BASE_URL}/videos/{VIDEO_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

print(f"Video {VIDEO_ID} deleted")

from openai import OpenAI

client = OpenAI(
    base_url="https://api.apifree.ai/v1/openai",
    api_key="YOUR_API_KEY"
)

VIDEO_ID = "video_abc123"
client.videos.delete(VIDEO_ID)
print(f"Video {VIDEO_ID} deleted")

Errors

Like other OpenAI APIs, this endpoint returns non-2xx HTTP codes with a standard error object when something goes wrong:

{
  "error": {
    "message": "Invalid model specified.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_parameter"
  }
}

Common error types include:

invalid_request_error: The request parameters are invalid or missing
authentication_error: Authentication failed (missing or invalid API key)
rate_limit_error: You have hit a rate limit
insufficient_quota: Your billing plan or credit is insufficient
model_not_found: The specified model is not available

Production Introduction

Getting Started

Models Endpoints

Authentication

API Reference

Terms & Privacy

Sora-2 Video Generation Guide

Sora-2 Video Generation Guide

Overview

Models

Sora-2

Sora-2 Pro

Generate a video

Start a render job

Guardrails and restrictions

Effective prompting

Monitor progress

Poll the status endpoint

Use webhooks for notifications

Retrieve results

Download the MP4

Download supporting assets

Use image references

Remix completed videos

Maintain your library

Errors

Production Introduction

Getting Started

Models Endpoints

Authentication

API Reference

Terms & Privacy

​Sora-2 Video Generation Guide

​Overview

​Models

​Sora-2

​Sora-2 Pro

​Generate a video

​Start a render job

​Guardrails and restrictions

​Effective prompting

​Monitor progress

​Poll the status endpoint

​Use webhooks for notifications

​Retrieve results

​Download the MP4

​Download supporting assets

​Use image references

​Remix completed videos

​Maintain your library

​Errors

Sora-2 Video Generation Guide

Overview

Models

Sora-2

Sora-2 Pro

Generate a video

Start a render job

Guardrails and restrictions

Effective prompting

Monitor progress

Poll the status endpoint

Use webhooks for notifications

Retrieve results

Download the MP4

Download supporting assets

Use image references

Remix completed videos

Maintain your library

Errors