Create Video Generation

Create video generation tasks using OpenAI Sora models with text prompts and optional image references

Overview

videos is OpenAI Sora’s video generation interface that creates video generation tasks through text prompts or optional reference image inputs.

After creation, you need to use the query interface to get the generation status. Once the task is completed, you can proceed with subsequent operations such as remixing and downloading.

For more information about the Sora generation interface, please refer to OpenAI Official Documentation.

Supported Models

Currently supported model IDs:

• sora-2 (default)
• sora-2-pro
• veo-3.1
• doubao-seedance-2 (see Seedance 2.0 docs)

Important Notes

Asynchronous Processing

Video generation requires considerable time and uses asynchronous mode. After creating a task, a task ID is returned immediately. You need to use the query interface to get generation progress and results.

Content Policy

Generated video content must comply with OpenAI’s usage policies. Content that is illegal, violent, pornographic, or infringes on copyrights is prohibited.

Resource Management

Download generated videos promptly to avoid resource expiration. Check the expires_at field in the response to know when the video will expire.

---

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: Text-to-Video

cURL

curl -X POST "https://api.wisgate.ai/v1/videos" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY" \
  -F "prompt=A cat walking on the street" \
  -F "model=sora-2" \
  -F "seconds=4" \
  -F "size=720x1280"

Example with Image Reference

cURL

curl -X POST "https://api.wisgate.ai/v1/videos" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY" \
  -F "prompt=A serene landscape animation" \
  -F "model=sora-2" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "input_reference=@reference_image.jpg"

Best Practices

1. Prompt Optimization

Use specific, detailed descriptions including scene, action, lighting and other details:

Good prompt:

A cinematic shot of a red sports car driving through a winding mountain road at sunset, with dramatic lighting and misty atmosphere, shot with a professional camera, 4K quality

Poor prompt:

car driving

2. Duration Control

Choose appropriate duration based on content complexity; shorter durations typically yield better quality:

• Sora 2: Supports 10s, 15s
• Sora 2 Pro: Supports 10s, 15s, 25s
• Veo 3.1:
  • 4 seconds: Best for simple scenes, fastest generation
  • 8 seconds: Good for moderate complexity scenes
  • 12 seconds: For complex scenes, longer generation time

3. Resolution Selection

Choose appropriate resolution based on use case, balancing quality and generation time:

• 720x1280 (default): Vertical format, good for mobile/social media
• 1280x720: Horizontal format, standard widescreen
• 1024x1792: High vertical resolution
• 1792x1024: High horizontal resolution

4. Image Preprocessing

When using image guidance, ensure input images are:

• Clear and well-composed
• Reasonable file size (not too large)
• In supported formats (JPEG, PNG)

5. Error Handling

Implement comprehensive retry and error handling mechanisms:

Python

import requests
import time
import random

def create_video_with_retry(prompt, max_retries=3):
    url = "https://api.wisgate.ai/v1/videos"
    headers = {"Authorization": f"Bearer WISDOM_GATE_KEY"}
    data = {"prompt": prompt, "model": "sora-2"}
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, data=data)
            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

Storyboard Mode

The API supports Storyboard functionality for creating sequential multi-shot videos. When using storyboard mode, the prompt must strictly follow this format:

Shot 1:
duration: 7.5sec
Scene: The plane takes off.

Shot 2:
duration: 7.5sec
Scene: The plane lands.

Format Requirements

• Each shot starts with Shot N: (N is the shot number)
• Use duration: Xsec to specify shot duration
• Use Scene: to describe the shot content
• Separate shots with blank lines

Storyboard Example

cURL

curl -X POST "https://api.wisgate.ai/v1/videos" \
  -H "Authorization: Bearer $WISDOM_GATE_KEY" \
  -F "prompt=Shot 1:
duration: 7.5sec
Scene: The plane takes off.

Shot 2:
duration: 7.5sec
Scene: The plane lands." \
  -F "model=sora-2" \
  -F "size=1280x720"

FAQ

How long does video generation take?

Typically takes several minutes to over ten minutes, depending on video duration, resolution, and server load. If there’s no response for a long time or failure occurs, please contact customer service.

What resolutions are supported?

Default support for 720x1280. Supported resolutions:

• 720x1280 (default) - Vertical
• 1280x720 - Horizontal
• 1024x1792 - High vertical
• 1792x1024 - High horizontal

For specific supported resolutions, please refer to the model documentation.

How long can generated videos be?

Default is 4 seconds. Maximum duration depends on model limitations:

• sora-2: Supports 10, 15 seconds
• sora-2-pro: Supports 10, 15, 25 seconds
• veo-3.1: Supports 4, 8, 12 seconds

Please refer to official documentation for the latest duration limits.

How to improve generation quality?

1. Use detailed prompts: Include scene, action, lighting, camera angles, and style
2. Choose appropriate duration: Shorter durations (4-8 seconds) typically yield better quality
3. Provide high-quality reference images: Clear, well-composed images guide better results
4. Use Storyboard mode: For complex multi-shot videos, use the storyboard format

How to check video generation status?

After creating a video, use the returned id to query status:

video_id = result['id']
status_url = f"https://api.wisgate.ai/v1/videos/{video_id}"
response = requests.get(status_url, headers=headers)
status = response.json()
print(f"Status: {status['status']}, Progress: {status['progress']}%")

How to download the generated video?

Once the status is completed, get the download URL from meta_data.url in the status response:

status_url = f"https://api.wisgate.ai/v1/videos/{video_id}"
response = requests.get(status_url, headers=headers)
result = response.json()

if result['status'] == 'completed':
    video_url = result['meta_data']['url']
    video_response = requests.get(video_url, stream=True)
    with open("generated_video.mp4", "wb") as f:
        for chunk in video_response.iter_content(chunk_size=8192):
            f.write(chunk)

---