https://api.laozhang.ai/v1/videos. A call took three steps: create a task, query its status, then download the video. The async flow ran on a task queue and supported long-running tasks.
Image-to-video upload method
Async 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:
Async API characteristics
- Task queue: Avoids long-connection timeout issues
- Failure billing: Billing for failed tasks (content violations, queue timeouts, generation failures) follows the console records; abnormal Sync API charges follow the console order status
- Flexible polling: Query task status and progress anytime
- Parameterized control: Resolution and duration are set through parameters
Sync vs Async Comparison
The legacy route recommended the Async API for production workloads and batch generation.
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://api.laozhang.ai/v1/videosCreate a new video generation taskRequest Parameters
Model Selection
sora-2: Base model, 720P resolution, $0.15/call (historical price)sora-2-pro: HD model, 1080P resolution, generation time ~10 minutes, $0.8/call (historical price)
Response Fields
2. Query Task Status
GET
https://api.laozhang.ai/v1/videos/{video_id}Query current status and progress of video generation taskPath Parameters
Response Fields
Task Status
3. Get Video Content
GET
https://api.laozhang.ai/v1/videos/{video_id}/contentDownload completed video filePath Parameters
Response
Returns binary stream of video file (MP4 format)Complete Code Examples
Python Example (with Polling Logic)
JavaScript/Node.js Example
Best Practices
Polling Interval
Polling Interval
Recommended polling interval: 3-5 secondsReasoning:
- Video generation typically takes 2-5 minutes
- 3-5 seconds provides timely progress feedback
- Avoids excessive requests
Timeout Handling
Timeout Handling
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
Retry Strategy
Retry Strategy
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
Batch Generation
Batch Generation
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 follow the console order status
- Failed, timed-out, cancelled, and content-safety-rejected tasks follow the console records
- Whether status queries are billed follows the console records
FAQ
How long is task validity?
How long is task validity?
Task validity: 24 hours
- After creating task,
expires_atfield 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
- Download video immediately after completion
- Don’t rely on server for long-term storage
How to cancel a running task?
How to cancel a running task?
The legacy route did not support manual task cancellation
- Once created, task will auto-queue for execution
- If no longer needed, simply ignore it
- Billing for unfinished tasks follows the console records
- Wait for task to naturally complete or fail
- Task auto-expires after 24 hours
Why do I get 404 when querying?
Why do I get 404 when querying?
Possible reasons:
- Incorrect video_id - Check if fully copied
- Task expired - Over 24 hours
- Network issues - Retry request
Can async and sync APIs be mixed?
Can async and sync APIs be mixed?
Yes, they’re completely independentTwo API systems are completely independent:
- Different endpoints
- Different calling methods
- Same pricing
- Share same API Key and balance
- Quick testing → Use sync API
- Production environment → Use async API (more stable)
- Batch generation → Use async API
Why isn't progress field updating?
Why isn't progress field updating?
Possible reasons:
- Normal - Some processing stages update slowly
- Queue waiting - May be queued during peak hours
- Task stuck - Rare cases where task may get stuck
- Continue waiting 5-10 minutes
- If no change after 10 minutes, contact support
- Provide video_id for troubleshooting
Does image-to-video support image URLs?
Does image-to-video support image URLs?
No! Only local file upload is supported.Correct approach:Not supported:
- ✗ Image URLs
- ✗ Base64 encoding
- ✗ Online image links
multipart/form-data format, supporting only local file streams.What image formats are supported?
What image formats are supported?
Supported formats:
- ✓ JPG / JPEG
- ✓ PNG
- ✓ WebP
- File size: < 5MB (recommended)
- Resolution: Recommended 1280x720 or similar ratio
- Source: Must be local file
Is prompt required for image-to-video?
Is prompt required for image-to-video?
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:
Is image-to-video more expensive?
Is image-to-video more expensive?
Same price.
Billing notes:
- Image-to-video and text-to-video cost the same
- Charges follow the console order status
- Billing for failed tasks (including format errors and content violations) follows the console records
Does image affect generation time?
Does image affect generation time?
Almost no impact.Image-to-video and text-to-video take similar time:
- Typical time: 2-5 minutes
- Factors: Video length, queue size, complexity
- 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
Contact us if you have any questions:- Email: hi@laozhang.ai
- Telegram: https://t.me/laozhang_cn
- Documentation: https://docs.laozhang.ai
Next Steps
Sync API
Check out sync API approach
Examples
View more usage examples
Pricing
Learn about detailed pricing
FAQ
View more Q&A