Skip to main content
GET
/
v1
/
videos
/
generations
/
{task_id}
curl --request GET \
  --url 'https://toapis.com/v1/videos/generations/task_01K9S419324DREZFBWNSVXYR6H' \
  --header 'Authorization: Bearer <token>'

{
  "id": "video_7497f4d5-3a88-44c7-923a-967fa7d941a0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380222
}
  • Query async video generation task execution status and results
  • Real-time status updates and progress tracking
  • Get generated videos when task completes
  • Multi-language support (zh/en/ko/ja)
All video generation tasks are executed asynchronously. After submitting a task, you need to query the status and results via the query endpoint.

​
Authorizations

​
Authorization
string
required
All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
task_id
string
required
Task ID returned by the video generation API
curl --request GET \
  --url 'https://toapis.com/v1/videos/generations/task_01K9S419324DREZFBWNSVXYR6H' \
  --header 'Authorization: Bearer <token>'

{
  "id": "video_7497f4d5-3a88-44c7-923a-967fa7d941a0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380222
}

​
Response

​
id
string
Unique task identifier
​
object
string
Object type, always generation.task
​
status
string
Task status
  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
​
progress
integer
Task progress percentage (0-100)
​
model
string
Video generation model used
​
created_at
integer
Task creation time (Unix timestamp)
​
completed_at
integer
Task completion time (Unix timestamp, only returned when completed)
​
expires_at
integer
Video URL expiration time (Unix timestamp, only returned on completion)
​
result
object
Task result (only returned on success)
​
error
object
Error information (only returned on failure)

​
Task Status Reference

StatusDescriptionIs FinalRecommended Action
queuedTask submitted, waiting in queue❌Wait 5-10 seconds, then query again
in_progressTask is processing❌Wait 10-15 seconds, then query again
completedTask completed successfully✅Get video from result.data[0].url
failedTask processing failed✅Check error info

​
Polling Strategy

Initial wait: 5 seconds
Polling interval: 10 seconds
Max wait: 600 seconds (10 minutes)
Typical time: 1-5 minutes

​
Python Polling Example

import time
import requests

def poll_video_task(task_id, api_key, max_wait=600):
    """Poll video generation task until completion or timeout"""
    start_time = time.time()
    interval = 10  # 10 second interval
    
    # Initial 5 second wait
    time.sleep(5)
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f'https://toapis.com/v1/videos/generations/{task_id}',
            headers={'Authorization': f'Bearer {api_key}'}
        )
        data = response.json()
        
        print(f"Status: {data['status']}, Progress: {data.get('progress', 0)}%")
        
        if data['status'] == 'completed':
            return {
                'url': data['result']['data'][0]['url'],
                'format': data['result']['data'][0].get('format'),
                'expires_at': data.get('expires_at')
            }
        elif data['status'] == 'failed':
            raise Exception(f"Generation failed: {data['error']['message']}")
        
        time.sleep(interval)
    
    raise TimeoutError("Task timeout")

​
Resource Expiration

Generated video URLs are valid for 24 hours
  • Please download and save videos within the validity period
  • expires_at field indicates video expiration time (Unix timestamp)
  • Expired videos cannot be accessed; to regenerate, submit a new task
  • Thumbnails expire simultaneously with videos

​
Error Codes

HTTP CodeError TypeDescription
400invalid_requestInvalid request parameters
401unauthorizedAuthentication failed, check API Key
402insufficient_quotaInsufficient balance
404task_not_foundTask not found
422content_policy_violationContent policy violation
429rate_limit_exceededRate limit exceeded
500internal_errorInternal server error

​
Performance Tips

Video generation takes longer, recommendations:
  1. Use Webhook Callbacks: If supported, configure callback URL to avoid frequent polling
  2. Set Reasonable Polling Interval: Recommended 10 seconds, too frequent wastes request quota
  3. Set Timeout: Long videos may take 5-10 minutes, set reasonable timeout
  4. Download Promptly: Videos expire after 24 hours, save to your storage immediately