> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Video Task

> Query the status and results of a video generation task

## Introduction

The query video task endpoint is used to check the status and results of a video generation task by task ID. After submitting a task, you need to periodically poll this endpoint to check the task status until the task is completed or failed.

<Tip>
  We recommend polling the task status every 3-5 seconds until the status becomes `succeeded` or `failed`.
</Tip>

## Authentication

Bearer Token, e.g., `Bearer sk-xxxxxxxxxx`

## Path Parameters

<ParamField path="task_id" type="string" required>
  Video generation task ID, returned by the submit task endpoint
</ParamField>

## Task Status

| Status        | Description                             | Recommended Action              |
| ------------- | --------------------------------------- | ------------------------------- |
| `queued`      | Task is queued, waiting to be processed | Continue polling                |
| `in_progress` | Task is being processed                 | Continue polling                |
| `succeeded`   | Task completed successfully             | Download video or get video URL |
| `failed`      | Task failed                             | Check error details             |

## cURL Example

```bash theme={null}
curl -X GET "https://api.mixroute.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## Polling Examples

### Python Example

```python theme={null}
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.mixroute.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 next query
        time.sleep(5)
```

### JavaScript Example

```javascript theme={null}
async function pollTaskStatus(taskId, apiKey, maxWaitTime = 300000) {
  const url = `https://api.mixroute.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 next query
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}
```

## Response Examples

### Task Queued

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "queued",
  "format": "mp4"
}
```

### Task In Progress

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "in_progress",
  "format": "mp4"
}
```

### Task Succeeded (Veo/Doubao Seedance)

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://nebula-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/video.mp4"
}
```

<Note>
  Veo include the video URL directly in the response when the task succeeds.
</Note>

### Task Succeeded (Sora 2)

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4"
}
```

<Warning>
  Sora 2 model does not return a video URL directly. You need to call the download video endpoint to retrieve the video data.
</Warning>

### Task Failed

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}
```

## Response Fields

| Field     | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `task_id` | string | Task ID                                           |
| `status`  | string | Task status                                       |
| `format`  | string | Video format                                      |
| `url`     | string | Video download URL (for models other than Sora 2) |
| `error`   | object | Error information (returned on failure)           |

## Model Differences

| Model           | Returns URL | Notes                      |
| --------------- | ----------- | -------------------------- |
| Sora 2          | ❌           | Requires download endpoint |
| Veo             | ✅           | Returns video URL directly |
| Doubao Seedance | ✅           | Returns video URL directly |

## Notes

* Response fields may vary slightly between different models
* Implement exponential backoff strategy to avoid excessive requests
* Video generation typically takes 30 seconds to several minutes, please be patient

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.mixroute.ai/v1/video/generations/video_xxx \
    --header 'Authorization: Bearer sk-xxxxxxxxxx'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.mixroute.ai/v1/video/generations/video_xxx"
  headers = {"Authorization": "Bearer sk-xxxxxxxxxx"}

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mixroute.ai/v1/video/generations/video_xxx', {
    headers: {
      'Authorization': 'Bearer sk-xxxxxxxxxx'
    }
  });
  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->get('https://api.mixroute.ai/v1/video/generations/video_xxx', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx'
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://api.mixroute.ai/v1/video/generations/video_xxx", nil)
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/video/generations/video_xxx"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .GET()
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/video/generations/video_xxx')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "task_id": "video_xxx",
    "status": "succeeded",
    "format": "mp4",
    "url": "https://example.com/video.mp4"
  }
  ```
</ResponseExample>