Get Video Details

Retrieve detailed status and metadata information for a Sora video generation task

Overview

The /v1/videos/{video_id} endpoint allows you to retrieve detailed status and metadata information for a Sora video generation task. This is the primary endpoint for tracking video generation progress and obtaining video details once processing is complete.

Use this endpoint to monitor video generation status, check progress, and retrieve metadata such as video dimensions, duration, creation time, and expiration time.

Before using this endpoint, you must first generate a video using the Create video endpoint to obtain a video ID.

Important Notes

Polling Strategy

Video generation is asynchronous and can take several minutes. Implement a polling mechanism to check status periodically (e.g., every 10-30 seconds) until the status is completed or failed.

Resource Expiration

Generated videos have an expiration time. Check the expires_at field and download videos promptly using the content endpoint once generation is complete.

---

Auto-Generated Documentation

The request parameters and response format are automatically generated from the OpenAPI specification. All parameters, their types, descriptions, defaults, and examples are pulled directly from openapi.json. Scroll down to see the interactive API reference.

---

Quick Start

Basic Example: Check Video Status

cURL

curl -X GET "https://api.wisgate.ai/v1/videos/video_68f88d1e44988190b2614f6604afd3b80fb3f07d5e600d05" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY"

Polling Example: Wait for Completion

Python

import requests
import time

def wait_for_video_completion(video_id, max_wait_time=600, poll_interval=10):
    """
    Poll video status until completion or timeout.
    
    Args:
        video_id: The video ID to check
        max_wait_time: Maximum time to wait in seconds (default: 10 minutes)
        poll_interval: Time between polls in seconds (default: 10 seconds)
    
    Returns:
        dict: Video details when completed, None if timeout
    """
    url = f"https://api.wisgate.ai/v1/videos/{video_id}"
    headers = {"Authorization": f"Bearer WISDOM_GATE_KEY"}
    
    start_time = time.time()
    
    while time.time() - start_time < max_wait_time:
        response = requests.get(url, headers=headers)
        result = response.json()
        
        status = result['status']
        progress = result.get('progress', 0)
        
        print(f"Status: {status}, Progress: {progress}%")
        
        if status == 'completed':
            return result
        elif status == 'failed':
            error = result.get('error', 'Unknown error')
            raise Exception(f"Video generation failed: {error}")
        
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Video generation did not complete within {max_wait_time} seconds")

# Usage
try:
    video_details = wait_for_video_completion("video_68f88d1e44988190b2614f6604afd3b80fb3f07d5e600d05")
    print("Video completed successfully!")
    print(f"Video ID: {video_details['id']}")
    print(f"Size: {video_details['size']}")
    print(f"Duration: {video_details['seconds']} seconds")
except TimeoutError as e:
    print(f"Timeout: {e}")
except Exception as e:
    print(f"Error: {e}")

Response Fields

Status Values

The status field indicates the current state of video generation:

Status	Description
queued	Video is queued and waiting to be processed
processing	Video is currently being generated
completed	Video generation has completed successfully
failed	Video generation failed (check error field)

Key Fields

• id: The unique identifier for the video
• status: Current generation status (queued, processing, completed, failed)
• progress: Generation progress percentage (0-100)
• created_at: Unix timestamp when the request was created
• completed_at: Unix timestamp when generation completed (null if not completed)
• error: Error information if generation failed (null if no error)
• model: Model used for generation (e.g., “sora-2”)
• meta_data: Metadata object containing the video download URL when completed
  • meta_data.url: The download URL for the generated video (available when status is completed)

FAQ

How often should I poll for status?

We recommend polling every 10-30 seconds. More frequent polling is unnecessary and may hit rate limits. Less frequent polling (60+ seconds) is acceptable but will delay your response to completion.

What should I do when status is “completed”?

Once the status is completed, you can:

1. Get the video download URL from meta_data.url in the response
2. Download the video using the URL
3. Store the video ID and metadata for your records

What should I do when status is “failed”?

When status is failed, check the error field for details:

• Review the error message
• Verify your request parameters were correct
• Check if the content violated OpenAI’s usage policies
• Retry with a modified prompt if appropriate

How long do videos stay available?

Check the expires_at field to know when the video will expire. Download videos promptly after completion to avoid expiration. Expired videos cannot be retrieved.

Can I check status for a remixed video?

Yes, remixed videos have the same status tracking. The remixed_from_video_id field will contain the ID of the original video if this video was created via remixing.

How to handle rate limits when polling?

Implement exponential backoff when encountering rate limits:

import requests
import time
import random

def poll_with_backoff(video_id, max_retries=5):
    url = f"https://api.wisgate.ai/v1/videos/{video_id}"
    headers = {"Authorization": f"Bearer WISDOM_GATE_KEY"}
    
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            if response.status_code == 429:  # Rate limit
                wait_time = (2 ** attempt) + random.random()
                time.sleep(wait_time)
                continue
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) + random.random()
                time.sleep(wait_time)
            else:
                raise

---