API Documentation

Learn how to integrate Sora2 API to generate stunning videos programmatically

Quick Start
Get started with Sora2 API in just 3 steps

💡 Copy and paste to ChatGPT, Claude or other AI assistants to implement

1. Get Your API Key

Create an account and generate your API key from the dashboard

Get API Key

2. Make Your First Request

Use your API key to authenticate and start generating videos

// Make your first video generation request
async function generateVideo() {
  const response = await fetch('https://sora2api.org/api/generate-video', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'A beautiful sunset over the ocean with gentle waves',
      aspectRatio: '16:9',
      duration: 10,
      type: 'text2video'
    })
  });
  
  const result = await response.json();
  console.log('Task ID:', result.data.taskId);
  console.log('Credits used:', result.data.creditsUsed);
  
  return result.data.taskId; // Save this for status checking
}

generateVideo();

3. Poll for Results

Check the status of your video generation task and retrieve the video URL

// Complete example: Generate and poll for video
async function generateAndWaitForVideo() {
  // Step 1: Start video generation
  const generateResponse = await fetch('https://sora2api.org/api/generate-video', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'A beautiful sunset over the ocean with gentle waves',
      aspectRatio: '16:9',
      duration: 10,
      type: 'text2video'
    })
  });
  
  const generateResult = await generateResponse.json();
  const taskId = generateResult.data.taskId;
  console.log('Video generation started, Task ID:', taskId);
  
  // Step 2: Poll for completion
  return new Promise((resolve, reject) => {
    const checkStatus = async () => {
      const statusResponse = await fetch('https://sora2api.org/api/check-video-status', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ taskId })
      });
      
      const statusResult = await statusResponse.json();
      const { status, progress, videoUrl } = statusResult.data;
      
      console.log(`Status: ${status}, Progress: ${progress}%`);
      
      if (status === 'succeeded') {
        console.log('Video ready! URL:', videoUrl);
        resolve(videoUrl);
      } else if (status === 'failed') {
        reject(new Error('Video generation failed'));
      } else {
        // Still processing, check again in 5 seconds
        setTimeout(checkStatus, 5000);
      }
    };
    
    checkStatus();
  });
}

// Usage
generateAndWaitForVideo()
  .then(videoUrl => console.log('Final video URL:', videoUrl))
  .catch(error => console.error('Error:', error));
Authentication
All API requests must include your API key in the Authorization header

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Authentication Example

curl -X POST https://sora2api.org/api/generate-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat playing", "aspectRatio": "16:9", "duration": 10, "type": "text2video"}'
API Endpoints
POST/api/generate-video

Initiates a video generation task and returns a task ID

Parameters

promptrequired

The text description or action prompt for the video (string, required)

aspectRatiorequired

Video aspect ratio: "16:9" (landscape) or "9:16" (portrait) (string, required)

durationoptional

Video duration in seconds: 10 or 15 (number, optional, default: 10). Cost depends on resolution: 480p 10s = 95 credits, 480p 15s = 143 credits, 720p 10s = 205 credits, 720p 15s = 308 credits

imageUrloptional

Public URL of the uploaded image (string, optional, required for image2video)

Request Example

{
  "prompt": "A beautiful sunset over the ocean",
  "aspectRatio": "16:9",
  "resolution": "480p",
  "duration": 10, // optional, default 10, can be 10 or 15 seconds
  "type": "text2video",
  "imageUrl": "https://yourdomain.com/image.jpg" // optional, for image2video
}

Response Example

{
  "code": 0,
  "data": {
    "success": true,
    "taskId": "xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx",
    "creditsUsed": 95,
    "message": "Video generation started"
  }
}
POST/api/check-video-status

Check the status and progress of a video generation task

Parameters

taskIdrequired

The task ID returned from the generate-video endpoint (string, required)

Request Example

{
  "taskId": "xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx"
}

Response Example

{
  "code": 0,
  "data": {
    "status": "succeeded",
    "progress": 100,
    "videoUrl": "https://example.com/video.mp4",
    "id": "xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx"
  },
  "msg": "success"
}

Status Codes

runningVideo generation in progress
succeededVideo generation completed successfully
failedVideo generation failed (credits will be refunded)
Code Examples
Complete examples for text-to-video and image-to-video generation

Generate a video from text description only:

async function generateTextToVideo() {
  // Step 1: Generate video
  const generateResponse = await fetch('https://sora2api.org/api/generate-video', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'A serene mountain landscape at sunrise',
      aspectRatio: '16:9',
      resolution: '480p', // optional: 480p or 720p, default 480p
      duration: 10, // optional: 10 or 15 seconds
      type: 'text2video'
    })
  });
  
  const { data } = await generateResponse.json();
  const taskId = data.taskId;
  
  // Step 2: Poll for status
  const pollStatus = async () => {
    const statusResponse = await fetch('https://sora2api.org/api/check-video-status', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ taskId })
    });
    
    const statusData = await statusResponse.json();
    
    if (statusData.data.status === 'succeeded') {
      console.log('Video URL:', statusData.data.videoUrl);
      return statusData.data.videoUrl;
    } else if (statusData.data.status === 'running') {
      // Poll again after 3 seconds
      setTimeout(pollStatus, 3000);
    } else {
      console.error('Generation failed');
    }
  };
  
  pollStatus();
}
Error Handling
Common errors you might encounter and how to handle them

Common Error Codes

401 Unauthorized

Invalid or missing API key. Check your Authorization header.

402 Payment Required

Insufficient credits. Please purchase more credits to continue.

400 Bad Request

Invalid request parameters. Check your request body.

Limits & Pricing

Cost per Video

95-308 Credits

480p: 95 credits for 10s, 143 credits for 15s. 720p: 205 credits for 10s, 308 credits for 15s

Video Duration

10s / 15s

Choose between 10s or 15s

Max Image Size

5MB

For image-to-video generation

Video URL Validity

2 Hours

Download within this period