Get Task Status

Query task execution status and retrieve generation results

GET /api/generate/status/{task_id}

Get task status

cURL

curl --request GET \
  --url https://api.vidgo.ai/api/generate/status/{task_id} \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}

Get Task Status

Query the execution status of image and video generation tasks and retrieve results when complete.

Endpoint

GET https://api.vidgo.ai/api/generate/status/{task_id}

Authentication

All requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Get API Key

Generate your API key from the console

Parameters

Path Parameters

Parameter	Type	Required	Description
task_id	string	Yes	Unique task identifier returned from the submit endpoint

Response

Success Response (200)

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}

Response Fields

Field	Type	Description
code	integer	HTTP status code (200 for success)
data.task_id	string	Unique task identifier
data.status	string	Task status: not_started, running, finished, failed
data.files	array	Generated media files (when status is finished)
data.files[].file_url	string	Direct URL to generated file
data.files[].file_type	string	Type of media file: image or video
data.created_time	string	ISO 8601 timestamp of task creation
data.progress	integer	Completion percentage (0-100)
data.error_message	string	Error description (when status is failed)

Status Values

Status	Description
not_started	Task is queued, waiting to be processed
running	Task is currently being generated
finished	Task completed successfully, results available in files
failed	Task failed, error details in error_message

Response Examples by Status

Not Started

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": null
  }
}

Running (Image)

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "running",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 45,
    "error_message": null
  }
}

Finished (Image)

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}

Finished (Video)

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video-xyz789.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}

Failed

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "failed",
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": "The prompt violates our content policy"
  }
}

Code Examples

cURL

curl -X GET https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

API_KEY = "your-api-key-here"
task_id = "task-unified-1757165031-uyujaw3d"

response = requests.get(
    f"https://api.vidgo.ai/api/generate/status/{task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

result = response.json()
data = result["data"]

print(f"Status: {data['status']}")
print(f"Progress: {data['progress']}%")

if data["status"] == "finished":
    for file in data["files"]:
        print(f"Generated file: {file['file_url']}")
elif data["status"] == "failed":
    print(f"Error: {data['error_message']}")

JavaScript / Node.js

const API_KEY = 'your-api-key-here';
const taskId = 'task-unified-1757165031-uyujaw3d';

const response = await fetch(
  `https://api.vidgo.ai/api/generate/status/${taskId}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const result = await response.json();
const data = result.data;

console.log(`Status: ${data.status}`);
console.log(`Progress: ${data.progress}%`);

if (data.status === 'finished') {
  data.files.forEach(file => {
    console.log(`Generated file: ${file.file_url}`);
  });
} else if (data.status === 'failed') {
  console.log(`Error: ${data.error_message}`);
}

Go

package main

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

const (
    APIKey = "your-api-key-here"
    BaseURL = "https://api.vidgo.ai"
)

type APIResponse struct {
    Code int      `json:"code"`
    Data TaskData `json:"data"`
}

type TaskData struct {
    TaskID       string      `json:"task_id"`
    Status       string      `json:"status"`
    Files        []MediaFile `json:"files"`
    CreatedTime  string      `json:"created_time"`
    Progress     int         `json:"progress"`
    ErrorMessage *string     `json:"error_message"`
}

type MediaFile struct {
    FileURL  string `json:"file_url"`
    FileType string `json:"file_type"`
}

func main() {
    taskID := "task-unified-1757165031-uyujaw3d"

    req, _ := http.NewRequest(
        "GET",
        fmt.Sprintf("%s/api/generate/status/%s", BaseURL, taskID),
        nil,
    )
    req.Header.Set("Authorization", "Bearer "+APIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var apiResp APIResponse
    json.Unmarshal(body, &apiResp)

    data := apiResp.Data
    fmt.Printf("Status: %s\n", data.Status)
    fmt.Printf("Progress: %d%%\n", data.Progress)

    if data.Status == "finished" {
        for _, file := range data.Files {
            fmt.Printf("Generated file: %s\n", file.FileURL)
        }
    } else if data.Status == "failed" {
        fmt.Printf("Error: %s\n", *data.ErrorMessage)
    }
}

Java

import java.net.http.*;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;

public class VidgoAPI {
    private static final String API_KEY = "your-api-key-here";
    private static final String BASE_URL = "https://api.vidgo.ai";

    public static void main(String[] args) throws Exception {
        String taskId = "task-unified-1757165031-uyujaw3d";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/generate/status/" + taskId))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        ObjectMapper mapper = new ObjectMapper();
        JsonNode root = mapper.readTree(response.body());
        JsonNode data = root.get("data");

        String status = data.get("status").asText();
        int progress = data.get("progress").asInt();

        System.out.println("Status: " + status);
        System.out.println("Progress: " + progress + "%");

        if ("finished".equals(status)) {
            JsonNode files = data.get("files");
            files.forEach(file -> {
                System.out.println("Generated file: " + file.get("file_url").asText());
            });
        } else if ("failed".equals(status)) {
            System.out.println("Error: " + data.get("error_message").asText());
        }
    }
}

PHP

<?php

$apiKey = 'your-api-key-here';
$taskId = 'task-unified-1757165031-uyujaw3d';
$baseUrl = 'https://api.vidgo.ai';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/api/generate/status/$taskId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey"
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
$data = $result['data'];

echo "Status: {$data['status']}\n";
echo "Progress: {$data['progress']}%\n";

if ($data['status'] === 'finished') {
    foreach ($data['files'] as $file) {
        echo "Generated file: {$file['file_url']}\n";
    }
} elseif ($data['status'] === 'failed') {
    echo "Error: {$data['error_message']}\n";
}

Ruby

require 'net/http'
require 'json'
require 'uri'

api_key = 'your-api-key-here'
task_id = 'task-unified-1757165031-uyujaw3d'
base_url = 'https://api.vidgo.ai'

uri = URI("#{base_url}/api/generate/status/#{task_id}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)
data = result['data']

puts "Status: #{data['status']}"
puts "Progress: #{data['progress']}%"

if data['status'] == 'finished'
  data['files'].each do |file|
    puts "Generated file: #{file['file_url']}"
  end
elsif data['status'] == 'failed'
  puts "Error: #{data['error_message']}"
end

Polling Best Practices

When polling for task completion, follow these recommendations:

Poll Interval: Check status every 2-5 seconds. Avoid polling more frequently to prevent rate limiting.

Timeout: Implement timeouts to avoid infinite loops. Typical generation times:

• Images: 15-60 seconds
• Videos: 90-300 seconds

Exponential Backoff: On rate limit (429) or server errors (5xx), implement exponential backoff (wait 1s, 2s, 4s, 8s…).

Complete Polling Example

import requests
import time

API_KEY = "your-api-key-here"
BASE_URL = "https://api.vidgo.ai"

def wait_for_completion(task_id, timeout=600, poll_interval=2):
    """
    Wait for task completion with timeout

    Args:
        task_id: Task identifier
        timeout: Maximum wait time in seconds
        poll_interval: Seconds between checks

    Returns:
        Task data when complete

    Raises:
        TimeoutError: If timeout exceeded
        RuntimeError: If task failed
    """
    start_time = time.time()
    headers = {"Authorization": f"Bearer {API_KEY}"}

    while True:
        # Check timeout
        if time.time() - start_time > timeout:
            raise TimeoutError(f"Task did not complete within {timeout}s")

        # Get status
        response = requests.get(
            f"{BASE_URL}/api/generate/status/{task_id}",
            headers=headers
        )

        if response.status_code == 429:
            # Rate limited - wait longer
            time.sleep(poll_interval * 2)
            continue

        response.raise_for_status()
        result = response.json()
        data = result["data"]

        # Log progress
        elapsed = int(time.time() - start_time)
        print(f"[{elapsed}s] Status: {data['status']}, Progress: {data['progress']}%")

        # Check completion
        if data["status"] == "finished":
            print(f"闁?Task completed successfully")
            return data
        elif data["status"] == "failed":
            raise RuntimeError(f"Task failed: {data['error_message']}")

        time.sleep(poll_interval)

# Usage
try:
    task_id = "task-unified-1757165031-uyujaw3d"
    result = wait_for_completion(task_id)

    for file in result["files"]:
        print(f"Download: {file['file_url']}")

except TimeoutError as e:
    print(f"Timeout: {e}")
except RuntimeError as e:
    print(f"Error: {e}")

Error Responses

HTTP Error Codes

Code	Description	Action
401	Unauthorized	Check your API key
403	Forbidden	Task belongs to another user
404	Not Found	Task ID does not exist
429	Too Many Requests	Reduce polling frequency, implement backoff
500	Server Error	Retry with exponential backoff
502	Bad Gateway	Service temporarily unavailable, retry

Error Response Format

{
  "detail": "Task not found"
}

Important Notes

Content Validity: Generated images and videos are accessible for 24 hours after creation. Download and save your content promptly.

Credits: Credits are only deducted when the task status becomes finished. Failed tasks do not consume credits.

Webhooks: Instead of polling, you can provide a callback_url when submitting tasks to receive automatic notifications. See the Quick Start guide.

Next Steps

Submit Task

Learn how to submit generation tasks

Image Generation

Generate images with GPT-4o

Video Generation

Create videos with Sora 2

Quick Start

Complete integration guide

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

task_id · string · required

Unique task identifier

Response

200

application/json

Task status retrieved successfully

code · integer · required

HTTP status code

Example:

200

data · object · required

Show child attributes