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 SupportImportant 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:
| Feature | Sync API | Async API |
|---|---|---|
| Image Upload | Supports URL or Base64 | Local file only |
| Request Format | JSON | multipart/form-data |
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
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 |
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://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)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
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
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
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: [email protected]
- WeChat: laozhangdaichong
- Telegram: https://t.me/laozhang_cn
- Documentation: https://docs.laozhang.ai