Skip to main content
This is legacy Sora2 route documentation and is now outdated. Use Sora Official API Forwarding for the currently available video route.
Async Endpoint: https://api2.laozhang.ai/v1/videosCall Method: Three steps (Create Task → Query Status → Get Video)Advantages: More Stable | Task Queue | Long-running Tasks Support
Important Difference - Image-to-Video Upload MethodAsync API differs significantly from Sync API for image-to-video:If you have an image URL: Download it locally first, then upload via Async API.Example Comparison:

Why Choose Async API?

Higher Stability

Task queue based, avoiding long connection timeout issues

No Charge on Failure ⭐

Key Advantage: No charges for failures of any kind
  • ✓ Content violation → No charge
  • ✓ Queue timeout → No charge
  • ✓ Generation failure → No charge
Sync API charges as long as request succeeds (HTTP 200), even if generation ultimately fails!

Flexible Polling

Query task status and progress anytime

Parameterized Control

Specify resolution and duration via parameters, more flexible

Sync vs Async Comparison

Recommended to use Async API, especially in production environments or when batch generating videos, for better stability.

Quick Start

Async calling consists of three steps:
1

Create Video Task

POST request to create task, get task ID
2

Query Task Status

Periodically poll to check generation progress
3

Download Video

Retrieve video file after task completes

Complete Example

API Endpoints

1. Create Video Task

POST https://api2.laozhang.ai/v1/videosCreate a new video generation task

Request Parameters

Model Selection
  • sora-2: Base model, 720P resolution, extremely high stability, $0.15/call
  • sora-2-pro: HD model, 1080P resolution, generation time ~10 minutes, $0.8/call

Response Fields

2. Query Task Status

GET https://api2.laozhang.ai/v1/videos/{video_id}Query current status and progress of video generation task

Path Parameters

Response Fields

Task Status

3. Get Video Content

GET https://api2.laozhang.ai/v1/videos/{video_id}/contentDownload completed video file

Path Parameters

Response

Returns binary stream of video file (MP4 format)
Important NoticeVideo files are stored for 24 hours only. Please download and save to local storage promptly!

Complete Code Examples

Python Example (with Polling Logic)

JavaScript/Node.js Example

Best Practices

Recommended polling interval: 3-5 seconds
Reasoning:
  • Video generation typically takes 2-5 minutes
  • 3-5 seconds provides timely progress feedback
  • Avoids excessive requests
Recommended timeout: 10 minutes (600 seconds)
Note:
  • Task timeout doesn’t auto-cancel
  • Can continue querying same video_id later
  • Task validity period is 24 hours
Suggested retry logic:
Retry scenarios:
  • ✓ Network errors → Retry
  • ✓ Service busy (503) → Retry
  • ✗ Content violation → Don’t retry, modify prompt
  • ✗ Insufficient balance → Don’t retry, confirm account credit first
Concurrency control recommendations:
Recommendations:
  • Creating tasks: High concurrency OK (10-30)
  • Querying status: Recommended concurrency ≤ 10
  • Downloading videos: Recommended concurrency ≤ 5

Pricing

Async API has exactly the same pricing as Sync API, billed per call.
Billing Rules:
  • ✓ Charges are based on console order status and the returned generation result
  • ✗ Failed, timeout, and cancelled tasks should be checked in console order status
  • ✗ Content safety issues should be checked in console order status (important difference from Sync API⭐)
  • ✗ Status query billing follows console records
Key Advantage of Async API: No charges for failures of any kind, including content safety review failures. Sync API charges as long as the request succeeds, even if generation ultimately fails.

FAQ

Task validity: 24 hours
  • After creating task, expires_at field shows expiration time
  • Can query task status anytime within 24 hours
  • After video generation completes, file is stored for 24 hours
  • After 24 hours, task and video will be automatically cleaned
Recommendations:
  • Download video immediately after completion
  • Don’t rely on server for long-term storage
Manual task cancellation not currently supported
  • Once created, task will auto-queue for execution
  • If no longer needed, simply ignore it
  • Incomplete tasks won’t be charged
Alternatives:
  • Wait for task to naturally complete or fail
  • Task auto-expires after 24 hours
Possible reasons:
  1. Incorrect video_id - Check if fully copied
  2. Task expired - Over 24 hours
  3. Network issues - Retry request
Solution:
Yes, they’re completely independentTwo API systems are completely independent:
  • Different endpoints
  • Different calling methods
  • Same pricing
  • Share same API Key and balance
Usage recommendations:
  • Quick testing → Use sync API
  • Production environment → Use async API (more stable)
  • Batch generation → Use async API
Possible reasons:
  1. Normal - Some processing stages update slowly
  2. Queue waiting - May be queued during peak hours
  3. Task stuck - Rare cases where task may get stuck
Handling:
  • Continue waiting 5-10 minutes
  • If no change after 10 minutes, contact support
  • Provide video_id for troubleshooting
No! Only local file upload is supported.Correct approach:
Not supported:
  • ✗ Image URLs
  • ✗ Base64 encoding
  • ✗ Online image links
Reason: Async API uses multipart/form-data format, supporting only local file streams.
Supported formats:
  • ✓ JPG / JPEG
  • ✓ PNG
  • ✓ WebP
Image requirements:
  • File size: < 5MB (recommended)
  • Resolution: Recommended 1280x720 or similar ratio
  • Source: Must be local file
Auto-detect MIME type:
Yes, prompt parameter is required!Even if you just want the image to “naturally animate”, you need to provide a description:Recommended simple prompts:
More specific prompts work better:
Exactly the same price!Billing notes:
  • Image-to-video and text-to-video cost the same
  • Only charged when successfully generated
  • No charge on failure (including format errors, content violations, etc.)
Almost no impact.Image-to-video and text-to-video take similar time:
  • Typical time: 2-5 minutes
  • Factors: Video length, queue size, complexity
Image size impact:
  • Recommended < 5MB: Fast upload, fast processing
  • Large images: Only affects upload time (seconds), no significant impact on generation time

Error Handling

Common Error Codes

Error Response Format

Technical Support

Need Help?

Contact us if you have any questions:

Next Steps

Sync API

Check out sync API approach

Examples

View more usage examples

Pricing

Learn about detailed pricing

FAQ

View more Q&A