Query Video Task

Query Video Task

curl --request GET \
  --url https://api.gravitex.ai/v1/video/generations/{task_id} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.gravitex.ai/v1/video/generations/{task_id}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.gravitex.ai/v1/video/generations/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/video/generations/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/video/generations/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.gravitex.ai/v1/video/generations/{task_id}")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/video/generations/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

GET

video

generations

{task_id}

Query Video Task

curl --request GET \
  --url https://api.gravitex.ai/v1/video/generations/{task_id} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.gravitex.ai/v1/video/generations/{task_id}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.gravitex.ai/v1/video/generations/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/video/generations/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/video/generations/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.gravitex.ai/v1/video/generations/{task_id}")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/video/generations/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

string

required

Bearer Token, e.g. Bearer sk-xxxxxxxxxx

Path Parameters

string

required

Video generation task ID returned by the submit task API

Response Description

Task Status

Status	Description	Suggested Action
`queued`	Task queued, waiting for processing	Continue polling
`in_progress`	Task being processed	Continue polling
`succeeded`	Task completed successfully	Download video or get video URL
`failed`	Task failed	View 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));
  }
}

API documentation

Chat & text

Safety & audio

Image Series

Video Series

Completions & Embeddings

Interface module

Introduction

Authentication

Path Parameters

Response Description

Task Status

Response Example (Queued)

Response Example (In Progress)

Response Example (Completed)

Response Example (Failed)

Usage Example

Polling Examples

Python Example

JavaScript Example

Submit Video Task

Download Video

​Introduction

​Authentication

​Path Parameters

​Response Description

​Task Status

​Response Example (Queued)

​Response Example (In Progress)

​Response Example (Completed)

​Response Example (Failed)

​Usage Example

​Polling Examples

​Python Example

​JavaScript Example

​Related APIs

Submit Video Task

Download Video

Introduction

Authentication

Path Parameters

Response Description

Task Status

Response Example (Queued)

Response Example (In Progress)

Response Example (Completed)

Response Example (Failed)

Usage Example

Polling Examples

Python Example

JavaScript Example

Related APIs