Skip to main content

​
Overview

The /v1/videos/{video_id}/content endpoint allows you to retrieve the actual video file content for a completed Sora video generation task. This endpoint provides direct access to the generated video binary data.
Before using this endpoint, you must first:
  1. Generate a video using the Create video endpoint
  2. Retrieve the video_id from the successful response
  3. Check the video status using the Retrieve video endpoint
  4. Ensure the status is completed before attempting to download

​
Important Notes

Video Must Be CompletedOnly videos with status completed can be retrieved. If you attempt to retrieve content for a video that is still queued or processing, you will receive an error response. Always check the video status first.
Resource ExpirationGenerated videos have an expiration time. Download videos promptly after generation completes to avoid expiration. Once expired, videos cannot be retrieved.
Content-Type HandlingWhen successful, this endpoint returns video binary data with Content-Type: video/* (typically video/mp4). Handle the response as binary data, not JSON.
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: Download Video

# First, check video status
curl -X GET "https://wisdom-gate.juheapi.com/v1/videos/video_68e688d4950481918ec389280c2f78140fcb904657674466" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY"

# Once status is "completed", download the video
curl -X GET "https://wisdom-gate.juheapi.com/v1/videos/video_68e688d4950481918ec389280c2f78140fcb904657674466/content" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY" \
  --output video.mp4

​
Complete Example: Wait and Download

import requests
import time

def download_video_when_ready(video_id, output_filename="video.mp4", max_wait_time=600):
    """
    Wait for video to complete and then download it.
    
    Args:
        video_id: The video ID to download
        output_filename: Output filename for the video
        max_wait_time: Maximum time to wait in seconds
    
    Returns:
        bool: True if download successful, False otherwise
    """
    status_url = f"https://wisdom-gate.juheapi.com/v1/videos/{video_id}"
    content_url = f"https://wisdom-gate.juheapi.com/v1/videos/{video_id}/content"
    headers = {"Authorization": f"Bearer WISDOM_GATE_KEY"}
    
    start_time = time.time()
    
    # Poll for completion
    while time.time() - start_time < max_wait_time:
        status_response = requests.get(status_url, headers=headers)
        status_data = status_response.json()
        
        status = status_data['status']
        progress = status_data.get('progress', 0)
        
        print(f"Status: {status}, Progress: {progress}%")
        
        if status == 'completed':
            # Download video
            print("Video completed! Downloading...")
            content_response = requests.get(content_url, headers=headers, stream=True)
            
            if content_response.status_code == 200:
                content_type = content_response.headers.get('Content-Type', '')
                if 'video' in content_type:
                    with open(output_filename, 'wb') as f:
                        for chunk in content_response.iter_content(chunk_size=8192):
                            f.write(chunk)
                    print(f"Video downloaded to {output_filename}")
                    return True
                else:
                    error_data = content_response.json()
                    print(f"Error downloading video: {error_data}")
                    return False
            else:
                print(f"Failed to download: HTTP {content_response.status_code}")
                return False
        elif status == 'failed':
            error = status_data.get('error', 'Unknown error')
            print(f"Video generation failed: {error}")
            return False
        
        time.sleep(10)  # Poll every 10 seconds
    
    print(f"Timeout: Video did not complete within {max_wait_time} seconds")
    return False

# Usage
success = download_video_when_ready(
    "video_68e688d4950481918ec389280c2f78140fcb904657674466",
    "my_video.mp4"
)

​
Response Handling

​
Success Response (200)

When the video is ready and successfully retrieved:
  • Content-Type: video/* (typically video/mp4)
  • Body: Binary video file data
  • Save the response directly as a video file

​
Error Response (200 with JSON)

When the video is not ready or an error occurs, the API may return JSON instead of video data:
  • Content-Type: application/json
  • Body: JSON object with error information
Example error response: 
{
  "message": "Video generation still in progress",
  "data": {
    "error": {
      "message": "Video generation is still in progress. Please check the status endpoint.",
      "type": "video_not_ready",
      "code": "video_processing",
      "param": null
    }
  }
}

​
Other Status Codes

  • 202: Video generation still in progress (alternative response format)
  • 404: Video not found
  • 401: Unauthorized - Invalid or missing API key

​
FAQ

​
How do I know if the response is video or JSON?

Check the Content-Type header:
  • If it contains video, the response is binary video data
  • If it’s application/json, parse it as JSON error information

​
What video format is returned?

Videos are returned in MP4 format (video/mp4).

​
How to handle large video files?

For large video files, use streaming download: 
response = requests.get(url, headers=headers, stream=True)
with open('video.mp4', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

​
What if the video has expired?

If a video has expired (past expires_at), you will receive a 404 or error response. Videos cannot be retrieved after expiration. Always download videos promptly after generation completes.

​
Can I get a download URL instead of binary data?

The endpoint returns binary video data directly. If you need a URL, you would need to store the video yourself or use a different service. The endpoint does not provide pre-signed URLs.

​
How to verify video download was successful?

Check the file size and verify it’s a valid video file: 
import os

# Check file exists and has content
if os.path.exists('video.mp4') and os.path.getsize('video.mp4') > 0:
    print("Video file downloaded successfully")
    # Optionally verify with a video library
    # from moviepy.editor import VideoFileClip
    # clip = VideoFileClip('video.mp4')
    # print(f"Duration: {clip.duration}s")
else:
    print("Download failed or file is empty")