Async Endpoint:
https://api.laozhang.ai/v1/videosWorkflow: Three steps (Create Task → Query Status → Get Video)Advantages: More Stable | Task Queue | Long Tasks Support | No Charge on FailureWhy Choose Async API?
Higher Stability
Based on task queue, avoids long connection timeout issues
No Charge on Failure ⭐
Major Advantage: No charge for any failure
- ✓ Content violation → No charge
- ✓ Queue timeout → No charge
- ✓ Generation failed → No charge
Flexible Polling
Query task status and progress anytime
Batch Processing
Suitable for batch generation and background tasks
Sync vs Async Comparison
| Feature | Sync API | Async API (Recommended) |
|---|---|---|
| Workflow | Single request waits for completion | Create task then poll |
| Endpoint | /v1/chat/completions | /v1/videos |
| Model Selection | Via model parameter | Via model parameter |
| Image-to-Video | Supports URL and Base64 | Supports URL |
| Charge on Failure | Charges even if generation fails | ⭐ No charge on failure |
| Stability | Depends on long connections | ⭐⭐⭐⭐⭐ More stable |
| Progress View | Streaming output | Poll progress percentage |
| Timeout Handling | Needs long timeout | Tasks run independently |
| Use Cases | Quick testing, real-time feedback | Production, batch generation |
Quick Start
Async workflow consists of three steps:1
Create Video Task
POST request to create task, get task ID
2
Query Task Status
Periodically poll for generation progress
3
Download Video
Get 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
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | ✓ | Model name (see model list below) |
prompt | string | ✓ | Video generation prompt |
Available Models
| Model Name | Aspect | Speed | Image-to-Video | Price |
|---|---|---|---|---|
veo-3.1 | Portrait | Standard | ❌ | $0.25/request |
veo-3.1-fl | Portrait | Standard | ✅ | $0.25/request |
veo-3.1-fast | Portrait | Fast | ❌ | $0.15/request |
veo-3.1-fast-fl | Portrait | Fast | ✅ | $0.15/request |
veo-3.1-landscape | Landscape | Standard | ❌ | $0.25/request |
veo-3.1-landscape-fl | Landscape | Standard | ✅ | $0.25/request |
veo-3.1-landscape-fast | Landscape | Fast | ❌ | $0.15/request |
veo-3.1-landscape-fast-fl | Landscape | Fast | ✅ | $0.15/request |
Model Naming Convention:
landscape= Landscape (16:9)fast= Fast version (cheaper)fl= Supports frame-to-video (image-to-video)
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique task identifier for subsequent queries |
object | string | Fixed as "video" |
model | string | Model used |
status | string | Task status: "queued" |
created | integer | Creation timestamp |
2. Query Task Status
GET
https://api.laozhang.ai/v1/videos/{video_id}Query the current status of a video generation taskPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
video_id | string | ✓ | Task ID returned when creating task |
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Task ID |
object | string | Fixed as "video" |
model | string | Model used |
status | string | Task status (see below) |
prompt | string | Original prompt |
created | integer | Creation timestamp |
Task Status Description
| Status | Description | Next Action |
|---|---|---|
queued | Task queued | Continue polling |
processing | Generating | Continue polling |
completed | Generation complete | Call get content endpoint |
failed | Generation failed | Check error message |
3. Get Video Content
GET
https://api.laozhang.ai/v1/videos/{video_id}/contentGet the actual content of a completed videoPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
video_id | string | ✓ | Task ID |
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Task ID |
object | string | Fixed as "video" |
status | string | Task status |
model | string | Model used |
prompt | string | Original prompt |
url | string | Video download URL |
duration | integer | Video duration (seconds) |
resolution | string | Video resolution |
created | integer | Creation timestamp |
Complete Code Examples
Python Example (with Polling Logic)
JavaScript/Node.js Example
Best Practices
Polling Interval Settings
Polling Interval Settings
Recommended polling interval: 5-10 secondsReasons:
- Video generation typically takes 2-5 minutes
- 5-10 seconds provides timely feedback
- Avoids excessive requests
Timeout Handling
Timeout Handling
Recommended timeout: 10 minutes (600 seconds)Note:
- Task timeout doesn’t auto-cancel
- Can continue querying the same video_id later
- Tasks are valid for 24 hours
Error Retry Strategy
Error Retry Strategy
Recommended retry logic:Retry scenarios:
- ✓ Network error → Retry
- ✓ Service busy (503) → Retry
- ✗ Content violation → Don’t retry, modify prompt
- ✗ Insufficient balance → Don’t retry, top up first
Batch Generation Optimization
Batch Generation Optimization
Concurrency control suggestions:Suggestions:
- Task creation: Can be highly concurrent (10-30)
- Status query: Recommend concurrency ≤ 10
- Video download: Recommend concurrency ≤ 5
Pricing
Async API has same pricing as Sync API, charged per request.
| Model Type | Price | With $100 top-up |
|---|---|---|
| Standard (veo-3.1 etc.) | $0.25/request | ≈ ¥1.7/request |
| Fast (veo-3.1-fast etc.) | $0.15/request | ≈ ¥1.0/request |
- ✓ Only charge when video successfully generates (status = “completed”)
- ✗ Failure, timeout, cancellation no charge
- ✗ Content safety failure also no charge (major difference from sync API ⭐)
- ✗ Status queries are free
FAQ
How long are tasks valid?
How long are tasks valid?
Task validity: 24 hours
- Can query task status anytime within 24 hours after creation
- Video files are stored for 24 hours after generation completes
- Tasks and videos are automatically cleaned up after 24 hours
- Download immediately after video generation completes
- Don’t rely on server for long-term storage
Why am I getting 404 when querying?
Why am I getting 404 when querying?
Possible reasons:
- Incorrect video_id - Check if copied completely
- Task expired - Over 24 hours
- Network issue - Retry the request
Can I mix async and sync APIs?
Can I mix async and sync APIs?
Yes, they’re completely independentThe two API systems are completely separate:
- Different endpoints
- Different workflows
- Same pricing
- Share the same API Key and balance
- Quick testing → Use Sync API
- Production → Use Async API (more stable)
- Batch generation → Use Async API
How to choose the right model?
How to choose the right model?
Choose based on needs:
| Need | Recommended Model |
|---|---|
| Quick testing | veo-3.1-fast |
| Standard portrait video | veo-3.1 |
| Standard landscape video | veo-3.1-landscape |
| Image-to-video (portrait) | veo-3.1-fl |
| Image-to-video (landscape) | veo-3.1-landscape-fl |
| Batch generation (cost-saving) | veo-3.1-fast or veo-3.1-landscape-fast |
Error Handling
Common Error Codes
| HTTP Code | Error Type | Description | Solution |
|---|---|---|---|
| 400 | Bad Request | Request parameter error | Check parameter format and values |
| 401 | Unauthorized | Invalid API Key | Check Authorization header |
| 402 | Payment Required | Insufficient balance | Top up and retry |
| 404 | Not Found | Task doesn’t exist | Check video_id or task expired |
| 429 | Too Many Requests | Request too frequent | Reduce polling frequency |
| 500 | Internal Server Error | Server error | Retry later |
| 503 | Service Unavailable | Service temporarily unavailable | Wait and retry |
Error Response Format
Technical Support
Need Help?
If you have questions, feel free to contact us:
- Email: threezhang.cn@gmail.com
- WeChat: laozhangdaichong
- Telegram: https://t.me/laozhang_cn
- Docs: https://docs.laozhang.ai