Get Video Details

Overview

The /v1/video/{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 StrategyVideo 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 ExpirationGenerated videos have an expiration time. Check the expires_at field and download videos promptly using the content endpoint once generation is complete.

Auto-Generated DocumentationThe 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 -X GET "https://wisdom-gate.juheapi.com/v1/video/video_68f88d1e44988190b2614f6604afd3b80fb3f07d5e600d05" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY"

Polling Example: Wait for Completion

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://wisdom-gate.juheapi.com/v1/video/{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)
expires_at: Unix timestamp when the video will expire (download promptly!)
error: Error information if generation failed (null if no error)
model: Model used for generation (e.g., “sora-2”)
seconds: Video duration in seconds
size: Video resolution (width x height, e.g., “720x1280”)
remixed_from_video_id: ID of the video this was remixed from (null if not a remix)

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:

Download the video using the content endpoint
Use the video ID for remixing if needed
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://wisdom-gate.juheapi.com/v1/video/{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

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API key in the Authorization header as 'Bearer YOUR_API_KEY'

Path Parameters

video_id

string

required

The unique identifier of the video generation request

Response

Video details retrieved successfully

Detailed status and metadata information for a Sora video generation task. Use this to monitor video generation progress and obtain video details once processing is complete.

string

required

The identifier of the video

Example:

"video_68f88d1e44988190b2614f6604afd3b80fb3f07d5e600d05"

object

string

required

Object type, always 'video'

Example:

"video"

status

enum<string>

required

Current status of the video generation. Use this to track progress.

Available options:

queued,

processing,

completed,

failed

Example:

"processing"

created_at

integer

required

Unix timestamp (in seconds) when the request was created

Example:

1759938772

completed_at

integer

required

Unix timestamp (in seconds) when the video generation completed. Null if not yet completed.

Example:

1759942372

expires_at

integer

required

Unix timestamp (in seconds) when the video will expire. Download promptly to avoid expiration.

Example:

1759945972

error

object

required

Error information if generation failed. Null if no error.

model

string

required

Model used for generation

progress

integer

required

Generation progress percentage (0-100)

Required range: 0 <= x <= 100

remixed_from_video_id

string

required

ID of the video this was remixed from, if applicable

seconds

string

required

Video duration in seconds

size

string

required

Video resolution (width x height)

Text Models

Image Models

Video Models

Error Handling

Overview

Important Notes

Quick Start

Basic Example: Check Video Status

Polling Example: Wait for Completion

Response Fields

Status Values

Key Fields

FAQ

How often should I poll for status?

What should I do when status is “completed”?

What should I do when status is “failed”?

How long do videos stay available?

Can I check status for a remixed video?

How to handle rate limits when polling?

Authorizations

Path Parameters

Response

Text Models

Image Models

Video Models

Error Handling

​Overview

​Important Notes

​Quick Start

​Basic Example: Check Video Status

​Polling Example: Wait for Completion

​Response Fields

​Status Values

​Key Fields

​FAQ

​How often should I poll for status?

​What should I do when status is “completed”?

​What should I do when status is “failed”?

​How long do videos stay available?

​Can I check status for a remixed video?

​How to handle rate limits when polling?

Authorizations

Path Parameters

Response

Overview

Important Notes

Quick Start

Basic Example: Check Video Status

Polling Example: Wait for Completion

Response Fields

Status Values

Key Fields

FAQ

How often should I poll for status?

What should I do when status is “completed”?

What should I do when status is “failed”?

How long do videos stay available?

Can I check status for a remixed video?

How to handle rate limits when polling?