Sora 2 Video Generation (Async) - API易文档中心

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.

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 -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"

Image-to-Video Examples

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

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"

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 -X GET "https://api.apiyi.com/v1/videos/video_abc123def456" \
  -H "Authorization: YOUR_API_KEY"

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 -X GET "https://api.apiyi.com/v1/videos/video_abc123def456/content" \
  -H "Authorization: YOUR_API_KEY" \
  -o 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

Synchronous Streaming API

Real-time progress feedback for interactive applications

Complete API Manual

View Feishu docs for more code examples

API Basics Manual

Learn about API authentication, request formats, etc.

FAQ

View more frequently asked questions

Basics

API Capabilities

​Overview

​Key Features

Independent Task Management

Flexible Polling Strategy

Reliable Video Download

Batch Processing Support

​Complete Workflow

​API Endpoint

​Step 1: Submit Video Generation Request

​Request Parameters

​Text-to-Video Examples

​Image-to-Video Examples

​Response Format

​Step 2: Poll Video Generation Status

​Request Method

​Query Examples

​Status Descriptions

​In-Progress Response Example

​Completed Response Example

​Step 3: Download Generated Video

​Request Method

​Download Examples

​Best Practices

​Prompt Writing Tips

​Reference Image Recommendations

​Polling Strategy Recommendations

Recommended Settings

Avoid Settings

​Error Retry Strategy

​Quotas and Limits

​Error Handling

​Common Error Codes

​FAQ

​Related Resources

Synchronous Streaming API

Complete API Manual

API Basics Manual

FAQ

Overview

Key Features

Complete Workflow

API Endpoint

Step 1: Submit Video Generation Request

Request Parameters

Text-to-Video Examples

Image-to-Video Examples

Response Format

Step 2: Poll Video Generation Status

Request Method

Query Examples

Status Descriptions

In-Progress Response Example

Completed Response Example

Step 3: Download Generated Video

Request Method

Download Examples

Best Practices

Prompt Writing Tips

Reference Image Recommendations

Polling Strategy Recommendations

Error Retry Strategy

Quotas and Limits

Error Handling

Common Error Codes

FAQ

Related Resources