Sora 2 Video Generation (Async)

Sora 2 Async Video Generation API - Complete 3-step workflow: Submit, Poll, Download

​

Overview

The Sora 2 Async API uses a standard asynchronous processing mechanism, ideal for scenarios requiring fine-grained control over the video generation workflow. Unlike the synchronous streaming API, the async API separates video generation into three independent steps, allowing more flexible task management and download timing.

The Async API is particularly suitable for batch processing, background tasks, and scenarios requiring long wait times. If you need real-time progress feedback, we recommend using the Synchronous Streaming API.

​

Key Features

Independent Task Management

Get task ID after submission, query status anytime

Flexible Polling Strategy

Customize polling intervals to avoid unnecessary requests

Reliable Video Download

Independent download after completion, supports resume

Batch Processing Support

Submit multiple tasks simultaneously for efficient concurrent processing

​

Complete Workflow

The Async API follows a 3-step workflow:

Step 1: Submit Request
POST /v1/videos
↓
Returns video_id

Step 2: Poll Status (recommended every 30 seconds)
GET /v1/videos/{video_id}
↓
submitted → in_progress → completed

Step 3: Download Video
GET /v1/videos/{video_id}/content
↓
Save MP4 file

Typical generation time: 3-5 minutes. Recommended polling interval: 30 seconds, maximum wait time: 10 minutes.

​

Model Pricing

Model Name	Description	Resolution	Price	Stability
sora_video2	Default portrait version	720 × 1280	$0.12/call	High
sora_video2-landscape	Landscape version	1280 × 720	$0.12/call	High
sora_video2-15s	Portrait 15s video	720 × 1280	$0.12/call	High
sora_video2-landscape-15s	Landscape 15s video	1280 × 720	$0.12/call	High
sora-2-pro	Pro account version	1024 × 1792, 1792 × 1024	$0.8/call	Now working properly!

• Async call recommended - various errors won’t incur charges;
• Synchronous call supports streaming output to view progress;
• Video storage valid for 1 day, download promptly;
• Sora 2 standard versions actually output 704 px (not 720 px), this is the official behavior;

​

API Endpoint

https://api.apiyi.com/v1/videos

​

Step 1: Submit Video Generation Request

​

Request Parameters

Parameter	Type	Required	Description
prompt	string	✅	Text description for video generation, detailed scene, action, and style recommended
model	string	✅	Fixed value: sora-2
size	string	✅	1280x720 (landscape) or 720x1280 (portrait)
seconds	string	✅	Video duration, options: 10 or 15
input_reference	file	❌	Reference image file (PNG/JPG/JPEG), optional, for image-to-video

​

Text-to-Video Examples

cURL

curl -X POST "https://api.apiyi.com/v1/videos" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "prompt=A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky" \
  -F "model=sora-2" \
  -F "size=1280x720" \
  -F "seconds=10"

import requests

BASE_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"

# Submit text-to-video request
files = {
    'prompt': (None, 'A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky'),
    'model': (None, 'sora-2'),
    'size': (None, '1280x720'),
    'seconds': (None, '10')
}

headers = {
    'Accept': 'application/json',
    'Authorization': API_KEY
}

response = requests.post(BASE_URL, headers=headers, files=files)
result = response.json()
video_id = result['id']

print(f"Video ID: {video_id}")
print(f"Status: {result['status']}")

const axios = require('axios');
const FormData = require('form-data');

const BASE_URL = 'https://api.apiyi.com/v1/videos';
const API_KEY = 'YOUR_API_KEY';

async function submitRequest() {
    const formData = new FormData();
    formData.append('prompt', 'A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky');
    formData.append('model', 'sora-2');
    formData.append('size', '1280x720');
    formData.append('seconds', '10');

    const response = await axios.post(BASE_URL, formData, {
        headers: {
            ...formData.getHeaders(),
            'Authorization': API_KEY
        }
    });

    const videoId = response.data.id;
    console.log(`Video ID: ${videoId}`);
    console.log(`Status: ${response.data.status}`);
    return videoId;
}

submitRequest();

​

Image-to-Video Examples

Upload a reference image to generate video based on the image.

cURL

curl -X POST "https://api.apiyi.com/v1/videos" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "prompt=Animate the animals in the reference image, making them chase around the field" \
  -F "model=sora-2" \
  -F "size=1280x720" \
  -F "seconds=10" \
  -F "input_reference=@/path/to/image.png"

import requests

BASE_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"

# Submit image-to-video request
with open('/path/to/image.png', 'rb') as f:
    files = {
        'prompt': (None, 'Animate the animals in the reference image, making them chase around the field'),
        'model': (None, 'sora-2'),
        'size': (None, '1280x720'),
        'seconds': (None, '10'),
        'input_reference': ('image.png', f, 'image/png')
    }

    headers = {
        'Accept': 'application/json',
        'Authorization': API_KEY
    }

    response = requests.post(BASE_URL, headers=headers, files=files)
    result = response.json()
    video_id = result['id']

    print(f"Video ID: {video_id}")

​

Response Format

{
  "id": "video_abc123def456",
  "status": "submitted",
  "progress": 0,
  "prompt": "A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky",
  "model": "sora-2",
  "size": "1280x720",
  "seconds": "10",
  "created_at": 1704067200,
  "url": null,
  "completed_at": null
}

​

Step 2: Poll Video Generation Status

After submitting the request, regularly poll to check video generation status.

​

Request Method

GET /v1/videos/{video_id}

​

Query Examples

cURL

curl -X GET "https://api.apiyi.com/v1/videos/video_abc123def456" \
  -H "Authorization: YOUR_API_KEY"

import requests
import time

BASE_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"
POLL_INTERVAL = 30  # Query every 30 seconds
MAX_WAIT_TIME = 600  # Maximum wait 10 minutes

def poll_status(video_id):
    headers = {'Authorization': API_KEY}
    status_url = f"{BASE_URL}/{video_id}"
    start_time = time.time()

    while True:
        elapsed_time = time.time() - start_time

        # Check timeout
        if elapsed_time > MAX_WAIT_TIME:
            print(f"Timeout: waited {MAX_WAIT_TIME} seconds")
            return False

        # Query status
        response = requests.get(status_url, headers=headers)
        result = response.json()
        status = result.get('status')
        progress = result.get('progress', 0)

        print(f"Status: {status}, Progress: {progress}%")

        if status == 'completed':
            print(f"Video generation completed! URL: {result.get('url')}")
            return True
        elif status == 'failed':
            print(f"Video generation failed")
            return False
        elif status in ['submitted', 'in_progress']:
            print(f"Generating, waiting {POLL_INTERVAL} seconds...")
            time.sleep(POLL_INTERVAL)
        else:
            print(f"Unknown status: {status}")
            time.sleep(POLL_INTERVAL)

# Usage example
poll_status("video_abc123def456")

const axios = require('axios');

const BASE_URL = 'https://api.apiyi.com/v1/videos';
const API_KEY = 'YOUR_API_KEY';
const POLL_INTERVAL = 30000; // 30 seconds
const MAX_WAIT_TIME = 600000; // 10 minutes

async function pollStatus(videoId) {
    const startTime = Date.now();

    while (true) {
        const elapsedTime = Date.now() - startTime;

        // Check timeout
        if (elapsedTime > MAX_WAIT_TIME) {
            console.log('Timeout: waited 10 minutes');
            return false;
        }

        // Query status
        const response = await axios.get(`${BASE_URL}/${videoId}`, {
            headers: { 'Authorization': API_KEY }
        });

        const { status, progress, url } = response.data;
        console.log(`Status: ${status}, Progress: ${progress}%`);

        if (status === 'completed') {
            console.log(`Video generation completed! URL: ${url}`);
            return true;
        } else if (status === 'failed') {
            console.log('Video generation failed');
            return false;
        }

        // Wait and continue
        await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
    }
}

// Usage example
pollStatus('video_abc123def456');

​

Status Descriptions

Status	Description	Next Action
submitted	Request submitted, waiting for processing	Continue polling
in_progress	Video generation in progress	Continue polling, check progress percentage
completed	Video generation completed	Can download video
failed	Video generation failed	Check error message, resubmit

​

In-Progress Response Example

{
  "id": "video_abc123def456",
  "status": "in_progress",
  "progress": 45,
  "prompt": "A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky",
  "model": "sora-2",
  "size": "1280x720",
  "seconds": "10",
  "created_at": 1704067200,
  "url": null,
  "completed_at": null
}

​

Completed Response Example

{
  "id": "video_abc123def456",
  "status": "completed",
  "progress": 100,
  "prompt": "A cute golden retriever chasing a frisbee on a park lawn, sunny day, background with green trees and blue sky",
  "model": "sora-2",
  "size": "1280x720",
  "seconds": "10",
  "created_at": 1704067200,
  "url": "https://api.apiyi.com/v1/videos/video_abc123def456/content",
  "completed_at": 1704067500
}

​

Step 3: Download Generated Video

After video generation is complete (status is completed), you can download the video file.

​

Request Method

GET /v1/videos/{video_id}/content

​

Download Examples

cURL

curl -X GET "https://api.apiyi.com/v1/videos/video_abc123def456/content" \
  -H "Authorization: YOUR_API_KEY" \
  -o video.mp4

import requests

BASE_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"

def download_video(video_id, output_path='video.mp4'):
    headers = {'Authorization': API_KEY}
    content_url = f"{BASE_URL}/{video_id}/content"

    print(f"Starting video download...")
    response = requests.get(content_url, headers=headers, stream=True)

    if response.status_code == 200:
        # Get file size
        total_size = int(response.headers.get('content-length', 0))

        with open(output_path, 'wb') as f:
            if total_size == 0:
                f.write(response.content)
            else:
                downloaded = 0
                for chunk in response.iter_content(chunk_size=8192):
                    if chunk:
                        f.write(chunk)
                        downloaded += len(chunk)
                        percent = (downloaded / total_size) * 100
                        print(f"\rDownload progress: {percent:.1f}%", end='')

        print(f"\nVideo downloaded successfully! Saved to: {output_path}")
        print(f"File size: {total_size} bytes")
        return True
    else:
        print(f"Download failed: {response.status_code}")
        print(f"Response: {response.text}")
        return False

# Usage example
download_video("video_abc123def456", "my_video.mp4")

const axios = require('axios');
const fs = require('fs');

const BASE_URL = 'https://api.apiyi.com/v1/videos';
const API_KEY = 'YOUR_API_KEY';

async function downloadVideo(videoId, outputPath = 'video.mp4') {
    const contentUrl = `${BASE_URL}/${videoId}/content`;

    console.log('Starting video download...');

    const response = await axios.get(contentUrl, {
        headers: { 'Authorization': API_KEY },
        responseType: 'stream'
    });

    const writer = fs.createWriteStream(outputPath);
    response.data.pipe(writer);

    return new Promise((resolve, reject) => {
        writer.on('finish', () => {
            console.log(`Video downloaded successfully! Saved to: ${outputPath}`);
            resolve();
        });
        writer.on('error', reject);
    });
}

// Usage example
downloadVideo('video_abc123def456', 'my_video.mp4');

Video files may expire after a certain period. It’s recommended to download immediately after generation and save locally.

​

Best Practices

​

Prompt Writing Tips

A good prompt should include: scene description, subject action, camera style, artistic style.

Good Example:

A cute golden retriever chasing a red frisbee on green grass, sunny day,
background with blue sky, white clouds and green trees, smooth motion,
close-up camera following the dog's action, cinematic quality, warm tones

Poor Example:

Dog chasing frisbee

​

Reference Image Recommendations

• Resolution: Recommended 1280x720 or higher
• Format: PNG or JPG
• File Size: < 10MB
• Content: Clear, well-defined subject, good lighting
• Relevance: Image content should relate to prompt description

​

Polling Strategy Recommendations

Recommended Settings

• Polling interval: 30 seconds
• Maximum wait: 10 minutes (600 seconds)
• Typical duration: 3-5 minutes

Avoid Settings

• Polling interval: < 30 seconds (may trigger rate limiting)
• Maximum wait: < 5 minutes (may give up too early)

​

Error Retry Strategy

import time

def retry_with_backoff(func, max_retries=3):
    """Exponential backoff retry strategy"""
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise
            wait_time = 2 ** i  # 1s, 2s, 4s
            print(f"Retry {i+1}/{max_retries}, waiting {wait_time} seconds...")
            time.sleep(wait_time)

​

Quotas and Limits

Limit	Value	Description
Request Rate	10 requests/minute	Exceeding returns 429 error
Concurrent Tasks	5 tasks	Number of videos processed simultaneously
Video Duration	10 or 15 seconds	Other durations not supported
Image Size	< 10MB	Recommended < 5MB
Prompt Length	< 1000 characters	Recommended 100-300 characters

​

Error Handling

​

Common Error Codes

Status Code	Description	Solution
200	Success	-
400	Invalid request parameters	Check if all required parameters are complete
401	Authentication failed	Check if API Key is correct
403	Permission denied	Check if API Key is valid or balance sufficient
404	Resource not found	Check if video_id is correct
429	Too many requests	Increase polling interval
500	Server error	Retry later

​

FAQ

How long does video generation take?

Typically 3-5 minutes, depending on server load and video complexity. Recommended polling interval: 30 seconds, maximum wait time: 10 minutes.

What's the difference between Async API and Sync API?

• Async API: 3-step workflow (submit→poll→download), suitable for batch processing and background tasks, requires managing polling logic
• Sync API: Streaming output, real-time progress, suitable for scenarios needing immediate feedback

See: Synchronous Streaming API Documentation

Can I submit multiple video generation tasks simultaneously?

Yes, up to 5 concurrent tasks are supported. You can submit multiple requests simultaneously and poll their status separately. Be careful not to exceed the request rate limit (10 requests/minute).

How long are video files stored?

It’s recommended to download videos immediately after generation to avoid file expiration. Contact technical support for specific storage duration.

How to handle generation failures?

Check the error message in the response. Common causes:

• Content policy violation (modify prompt or change image)
• Insufficient quota (recharge or upgrade plan)
• Invalid parameters (check parameter format and values)
• Server overload (retry later)

How to control landscape vs portrait orientation?

Control via the size parameter:

• 1280x720: Landscape
• 720x1280: Portrait

​

Related Resources

Synchronous Streaming API

Real-time progress feedback for interactive applications

API Basics Manual

Learn about API authentication, request formats, etc.

FAQ

View more frequently asked questions