Skip to main content
GET
/
v1
/
video
/
generations
/
{task_id}
Query Video Task
curl --request GET \
  --url https://api.gravitex.ai/v1/video/generations/{task_id} \
  --header 'Authorization: <authorization>'

Documentation Index

Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

The query video task API is used to query the status and results of a video generation task by task ID. After submitting a task, you need to periodically poll this API to check the task status until the task completes or fails. Important Note: It is recommended to poll the task status every 3-5 seconds until the task status becomes succeeded or failed.

​
Authentication

​
Authorization
string
required
Bearer Token, e.g. Bearer sk-xxxxxxxxxx

​
Path Parameters

​
task_id
string
required
Video generation task ID returned by the submit task API

​
Response Description

​
Task Status

StatusDescriptionSuggested Action
queuedTask queued, waiting for processingContinue polling
in_progressTask being processedContinue polling
succeededTask completed successfullyDownload video or get video URL
failedTask failedView error reason

​
Response Example (Queued)

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "queued",
  "format": "mp4"
}

​
Response Example (In Progress)

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "in_progress",
  "format": "mp4"
}

​
Response Example (Completed)

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://gravitex-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/video.mp4"
}
Note: For Veo and Ali Wanxiang, the video URL is directly included in the response when the task succeeds. For Sora 2, you need to use the download API to get the video.

​
Response Example (Failed)

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}

​
Usage Example

curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

​
Polling Examples

​
Python Example

import requests
import time

def poll_task_status(task_id, api_key, max_wait_time=300):
    """Poll task status until completion"""
    url = f"https://api.gravitex.ai/v1/video/generations/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    start_time = time.time()
    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")
        
        print(f"Current status: {status}")
        
        if status == "succeeded":
            video_url = data.get("url")
            print(f"✅ Task completed! Video URL: {video_url}")
            return video_url
        elif status == "failed":
            error_msg = data.get("error", {}).get("message", "Unknown error")
            print(f"❌ Task failed: {error_msg}")
            return None
        
        # Check timeout
        if time.time() - start_time > max_wait_time:
            print("⏰ Timeout")
            return None
        
        # Wait 5 seconds before querying again
        time.sleep(5)

​
JavaScript Example

async function pollTaskStatus(taskId, apiKey, maxWaitTime = 300000) {
  const url = `https://api.gravitex.ai/v1/video/generations/${taskId}`;
  const headers = { 'Authorization': `Bearer ${apiKey}` };
  
  const startTime = Date.now();
  
  while (true) {
    const response = await fetch(url, { headers });
    const data = await response.json();
    const status = data.status;
    
    console.log(`Current status: ${status}`);
    
    if (status === 'succeeded') {
      const videoUrl = data.url;
      console.log(`✅ Task completed! Video URL: ${videoUrl}`);
      return videoUrl;
    } else if (status === 'failed') {
      const errorMsg = data.error?.message || 'Unknown error';
      console.error(`❌ Task failed: ${errorMsg}`);
      throw new Error(errorMsg);
    }
    
    // Check timeout
    if (Date.now() - startTime > maxWaitTime) {
      throw new Error('Timeout');
    }
    
    // Wait 5 seconds before querying again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

Submit Video Task

Submit video generation task

Download Video

Download completed video files (Sora 2 only)