Async Endpoint:
https://api.laozhang.ai/v1/videosCall Method: Three steps (Create Task → Query Status → Get Video)Advantages: More Stable | Task Queue | Long-running Tasks SupportWhy 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
Flexible Polling
Query task status and progress anytime
Parameterized Control
Specify resolution and duration via parameters, more flexible
Sync vs Async Comparison
| Feature | Sync API | Async API (Recommended) |
|---|---|---|
| Call Method | Single request, wait for completion | Create task then poll for results |
| Endpoint | /v1/chat/completions | /v1/videos |
| Resolution | Model name (sora_video2-landscape) | Parameter (size: "1280x720") |
| Duration | Model name (sora_video2-15s) | Parameter (seconds: "15") |
| Image-to-Video | Supports image URL | Local file upload only |
| Failed Billing | Charged even if generation fails | ⭐ No charge on failure |
| Stability | Depends on long connection | ⭐⭐⭐⭐⭐ More Stable |
| Progress | Stream output | Poll for progress percentage |
| Timeout | Needs long timeout setting | Task runs independently, no timeout limit |
| Use Cases | Quick testing, real-time feedback | Production environment, 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
| Parameter | Type | Required | Options | Description |
|---|---|---|---|---|
model | string | ✓ | "sora-2" | Model name (fixed value) |
prompt | string | ✓ | - | Video generation prompt |
size | string | ✓ | "1280x720", "720x1280" | Video resolution (landscape/portrait) |
seconds | string | ✓ | "10", "15" | Video duration (seconds) |
input_reference | file | Required for image-to-video | - | Local image file (local upload only) Supported formats: JPG, PNG, WebP Recommended size: 1280x720 Recommended file size: < 5MB |
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique task identifier for subsequent queries |
object | string | Fixed as "task" |
model | string | Model used |
status | string | Task status: "submitted" |
created_at | integer | Creation timestamp |
expires_at | integer | Expiration timestamp (24 hours later) |
2. Query Task Status
GET
https://api.laozhang.ai/v1/videos/{video_id}Query current status and progress of 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) |
progress | integer | Progress percentage (0-100) |
url | string | Video download path (completed status only) |
created_at | integer | Creation timestamp |
completed_at | integer | Completion timestamp (completed status only) |
error | object | Error information (failed status only) |
Task Status
| Status | Description | Progress |
|---|---|---|
submitted | Submitted, waiting for processing | 0% |
in_progress | Generating | 1-99% |
completed | Generation completed | 100% |
failed | Generation failed | - |
3. Get Video Content
GET
https://api.laozhang.ai/v1/videos/{video_id}/contentDownload completed video filePath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
video_id | string | ✓ | Task ID |
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, recharge 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.
| Parameter Combination | Price | $100 Top-up Rate |
|---|---|---|
| 10s video (landscape/portrait) | $0.15/call | ≈ ¥1.0/call |
| 15s video (landscape/portrait) | $0.15/call | ≈ ¥1.0/call |
- ✓ Charged only when video successfully generated (status = “completed”)
- ✗ Failed, timeout, cancelled not charged
- ✗ Content safety issues also not charged (important difference from Sync API⭐)
- ✗ Status queries not charged
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?
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
- 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?
Exactly the same price!
Billing notes:
| Video Length | Price |
|---|---|
| 10s (landscape/portrait) | $0.15/call ≈ ¥1.0/call |
| 15s (landscape/portrait) | $0.15/call ≈ ¥1.0/call |
- 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.)
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
| HTTP Status | Error Type | Description | Action |
|---|---|---|---|
| 400 | Bad Request | Invalid request parameters | Check parameter format and values |
| 401 | Unauthorized | Invalid API Key | Check Authorization header |
| 402 | Payment Required | Insufficient balance | Recharge and retry |
| 404 | Not Found | Task doesn’t exist | Check video_id or task expired |
| 429 | Too Many Requests | Requests 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?
Contact us if you have any questions:
- Email: threezhang.cn@gmail.com
- WeChat: laozhangdaichong
- Telegram: https://t.me/laozhang_cn
- Documentation: https://docs.laozhang.ai