# Sora 2 API Documentation

> Generate videos with the Sora 2 model through the AI Studio API.

## Overview

Use the AI Studio API to create Sora 2 generation tasks and query their status. The flow is asynchronous: create a task first, then poll the task endpoint with the returned `taskId`.

## Authentication

All requests require an API key in the `Authorization` header.

```http
Authorization: Bearer YOUR_API_KEY
```

## Available models

| modelId | Version | Provider | Runtime model |
| --- | --- | --- | --- |
| `video:sora2-text-to-video-standard` | Sora 2 Text to Video | Sora 2 | sora-2-text-to-video |
| `video:sora2-image-to-video-standard` | Sora 2 Image to Video | Sora 2 | sora-2-image-to-video |
| `video:sora2-pro-text-to-video` | Sora 2 Pro Text to Video | Sora 2 Pro | sora-2-pro-text-to-video |
| `video:sora2-pro-image-to-video` | Sora 2 Pro Image to Video | Sora 2 Pro | sora-2-pro-image-to-video |
| `video:sora2-pro-storyboard` | Sora 2 Pro Storyboard | Sora 2 Pro | sora-2-pro-storyboard |
| `video:sora2-official` | Sora 2 Official | Sora 2 Official | sora-2-official |
| `video:fal-fal-ai-sora-2-text-to-video` | Sora 2 Text to Video | sora-2 | fal-ai/sora-2/text-to-video |
| `video:fal-fal-ai-sora-2-image-to-video` | Sora 2 Image to Video | sora-2 | fal-ai/sora-2/image-to-video |
| `video:fal-fal-ai-sora-2-text-to-video-pro` | Sora 2 Pro Text to Video | sora-2 | fal-ai/sora-2/text-to-video/pro |
| `video:fal-fal-ai-sora-2-image-to-video-pro` | Sora 2 Pro Image to Video | sora-2 | fal-ai/sora-2/image-to-video/pro |
| `video:fal-fal-ai-sora-2-video-to-video-remix` | Sora 2 Video Remix | sora-2 | fal-ai/sora-2/video-to-video/remix |

## 1. Create generation task

### Endpoint

```http
POST https://localhost:3000/api/ai-studio/execute
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

### Request example

```json
{
  "modelId": "video:sora2-text-to-video-standard",
  "isPublic": true,
  "payload": {
    "model": "sora-2-text-to-video",
    "input": {
      "prompt": "A cinematic shot with realistic motion, natural lighting, and smooth camera movement.",
      "aspect_ratio": "16:9",
      "duration": "10"
    }
  }
}
```

### Success response

```json
{
  "success": true,
  "data": {
    "modelId": "video:sora2-text-to-video-standard",
    "generationId": "generation-id",
    "reservedCredits": 20,
    "taskId": "provider-task-id",
    "state": "queued"
  }
}
```

## 2. Query task status

### Endpoint

```http
GET https://localhost:3000/api/ai-studio/tasks/{taskId}
Authorization: Bearer YOUR_API_KEY
```

### Success response

```json
{
  "success": true,
  "data": {
    "generationId": "generation-id",
    "taskId": "provider-task-id",
    "modelId": "video:sora2-text-to-video-standard",
    "state": "succeeded",
    "mediaUrls": [
      "https://example.com/result.mp4"
    ],
    "reservedCredits": 20,
    "refundedCredits": 0
  }
}
```

## Request fields

### Sora 2 Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-text-to-video"` | sora-2-text-to-video | The model name to use for generation. Required field. - Must be `sora-2-text-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `duration` | enum | No | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-image-to-video"` | sora-2-image-to-video | The model name to use for generation. Required field. - Must be `sora-2-image-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | No | `["https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"]` | - | Provide external image URLs as references for video generation. |
| `prompt` | string | No | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Optional field. |
| `duration` | enum | No | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-pro-text-to-video"` | sora-2-pro-text-to-video | The model name to use for generation. Required field. - Must be `sora-2-pro-text-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `duration` | enum | No | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-pro-image-to-video"` | sora-2-pro-image-to-video | The model name to use for generation. Required field. - Must be `sora-2-pro-image-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | No | `["https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"]` | - | Provide external image URLs as references for video generation. |
| `prompt` | string | No | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Optional field. |
| `duration` | enum | No | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Storyboard

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-pro-storyboard"` | sora-2-pro-storyboard | The model name to use for generation. Required field. - Must be `sora-2-pro-storyboard` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `duration` | enum | No | `"25"` | 25 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Official

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"sora-2-official"` | sora-2-official | The model name to use for generation. Required field. - Must be `sora-2-official` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Supported values: 16:9 and 9:16. |
| `duration` | enum | No | `"8"` | 4, 8, 12, 16, 20 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | No | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A dramatic Hollywood breakup scene at dusk on a quiet suburban street. A man and a woman in their 30s face each other, speaking softly but emotionally, lips syncing to breakup dialogue. Cinematic lighting, warm sunset tones, shallow depth of field, gentle breeze moving autumn leaves, realistic natural sound, no background music"` | - | The text prompt describing the video you want to generate |
| `delete_video` | boolean | No | `true` | - | Whether to delete the video after generation for privacy reasons. If True, the video cannot be used for remixing and will be permanently deleted. |
| `model` | enum | No | `"sora-2"` | sora-2, sora-2-2025-12-08, sora-2-2025-10-06 | The model to use for the generation. When the default model is selected, the latest snapshot of the model will be used - otherwise, select a specific snapshot of the model. |
| `character_ids` | object | No | `-` | - | Up to two character IDs (from create-character) to use in the video. Refer to characters by name in the prompt. When set, only the OpenAI provider is used. |
| `detect_and_block_ip` | boolean | No | `false` | - | If enabled, the prompt (and image for image-to-video) will be checked for known intellectual property references and the request will be blocked if any are detected. |
| `aspect_ratio` | enum | No | `"16:9"` | 9:16, 16:9 | The aspect ratio of the generated video |
| `duration` | enum | No | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | string | No | `"720p"` | - | The resolution of the generated video |

#### Input fields

_No fields are configured for this model._

### Sora 2 Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Front-facing 'invisible' action-cam on a skydiver in freefall above bright clouds; camera locked on his face. He speaks over the wind with clear lipsync: 'This is insanely fun! You've got to try it—book a tandem and go!' Natural wind roar, voice close-mic'd and slightly compressed so it's intelligible. Midday sun, goggles and jumpsuit flutter, altimeter visible, parachute rig on shoulders. Energetic but stable framing with subtle shake; brief horizon roll. End on first tug of canopy and wind noise dropping."` | - | The text prompt describing the video you want to generate |
| `delete_video` | boolean | No | `true` | - | Whether to delete the video after generation for privacy reasons. If True, the video cannot be used for remixing and will be permanently deleted. |
| `detect_and_block_ip` | boolean | No | `false` | - | If enabled, the prompt (and image for image-to-video) will be checked for known intellectual property references and the request will be blocked if any are detected. |
| `model` | enum | No | `"sora-2"` | sora-2, sora-2-2025-12-08, sora-2-2025-10-06 | The model to use for the generation. When the default model is selected, the latest snapshot of the model will be used - otherwise, select a specific snapshot of the model. |
| `character_ids` | object | No | `-` | - | Up to two character IDs (from create-character) to use in the video. Refer to characters by name in the prompt. When set, only the OpenAI provider is used. |
| `aspect_ratio` | enum | No | `"auto"` | auto, 9:16, 16:9 | The aspect ratio of the generated video |
| `image_url` | string | Yes | `"https://storage.googleapis.com/falserverless/example_inputs/sora-2-i2v-input.png"` | - | The URL of the image to use as the first frame |
| `duration` | enum | No | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | No | `"auto"` | auto, 720p | The resolution of the generated video |

#### Input fields

_No fields are configured for this model._

### Sora 2 Pro Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `detect_and_block_ip` | boolean | No | `false` | - | If enabled, the prompt (and image for image-to-video) will be checked for known intellectual property references and the request will be blocked if any are detected. |
| `prompt` | string | Yes | `"A dramatic Hollywood breakup scene at dusk on a quiet suburban street. A man and a woman in their 30s face each other, speaking softly but emotionally, lips syncing to breakup dialogue. Cinematic lighting, warm sunset tones, shallow depth of field, gentle breeze moving autumn leaves, realistic natural sound, no background music"` | - | The text prompt describing the video you want to generate |
| `aspect_ratio` | enum | No | `"16:9"` | 9:16, 16:9 | The aspect ratio of the generated video |
| `duration` | enum | No | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | No | `"1080p"` | 720p, 1080p, true_1080p | The resolution of the generated video |
| `delete_video` | boolean | No | `true` | - | Whether to delete the video after generation for privacy reasons. If True, the video cannot be used for remixing and will be permanently deleted. |
| `character_ids` | object | No | `-` | - | Up to two character IDs (from create-character) to use in the video. Refer to characters by name in the prompt. When set, only the OpenAI provider is used. |

#### Input fields

_No fields are configured for this model._

### Sora 2 Pro Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Front-facing 'invisible' action-cam on a skydiver in freefall above bright clouds; camera locked on his face. He speaks over the wind with clear lipsync: 'This is insanely fun! You've got to try it—book a tandem and go!' Natural wind roar, voice close-mic'd and slightly compressed so it's intelligible. Midday sun, goggles and jumpsuit flutter, altimeter visible, parachute rig on shoulders. Energetic but stable framing with subtle shake; brief horizon roll. End on first tug of canopy and wind noise dropping."` | - | The text prompt describing the video you want to generate |
| `delete_video` | boolean | No | `true` | - | Whether to delete the video after generation for privacy reasons. If True, the video cannot be used for remixing and will be permanently deleted. |
| `detect_and_block_ip` | boolean | No | `false` | - | If enabled, the prompt (and image for image-to-video) will be checked for known intellectual property references and the request will be blocked if any are detected. |
| `character_ids` | object | No | `-` | - | Up to two character IDs (from create-character) to use in the video. Refer to characters by name in the prompt. When set, only the OpenAI provider is used. |
| `aspect_ratio` | enum | No | `"auto"` | auto, 9:16, 16:9 | The aspect ratio of the generated video |
| `image_url` | string | Yes | `"https://storage.googleapis.com/falserverless/example_inputs/sora-2-i2v-input.png"` | - | The URL of the image to use as the first frame |
| `duration` | enum | No | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | No | `"auto"` | auto, 720p, 1080p, true_1080p | The resolution of the generated video |

#### Input fields

_No fields are configured for this model._

### Sora 2 Video Remix

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `video_id` | string | Yes | `"video_123"` | - | The video_id from a previous Sora 2 generation. Note: You can only remix videos that were generated by Sora (via text-to-video or image-to-video endpoints), not arbitrary uploaded videos. |
| `prompt` | string | Yes | `"Change the cat's fur color to purple."` | - | Updated text prompt that directs the remix generation |
| `delete_video` | boolean | No | `true` | - | Whether to delete the video after generation for privacy reasons. If True, the video cannot be used for remixing and will be permanently deleted. |

#### Input fields

_No fields are configured for this model._

## Pricing

Credits are reserved when a generation task is created. The `reservedCredits` value in the create-task response is the final amount reserved for that request.

| Model | Type | Spec | Price | Billing |
| --- | --- | --- | --- | --- |
| Sora 2 Text to Video | Text to Video | 10 | 3 credits/s | Output seconds × 3 |
| Sora 2 Text to Video | Text to Video | 15 | 3 credits/s | Output seconds × 3 |
| Sora 2 Image to Video | Image to Video | 10 | 3 credits/s | Output seconds × 3 |
| Sora 2 Image to Video | Image to Video | 15 | 3 credits/s | Output seconds × 3 |
| Sora 2 Pro Text to Video | Text to Video | 10 | 5 credits/s | Output seconds × 5 |
| Sora 2 Pro Text to Video | Text to Video | 15 | 5 credits/s | Output seconds × 5 |
| Sora 2 Pro Image to Video | Image to Video | 10 | 5 credits/s | Output seconds × 5 |
| Sora 2 Pro Image to Video | Image to Video | 15 | 5 credits/s | Output seconds × 5 |
| Sora 2 Pro Storyboard | Storyboard | 16:9 | 5 credits/s | Output seconds × 5 |
| Sora 2 Pro Storyboard | Storyboard | 9:16 | 5 credits/s | Output seconds × 5 |
| Sora 2 Official | Text/Image to Video | 4 | 5 credits/s | Output seconds × 5 |
| Sora 2 Official | Text/Image to Video | 8 | 5 credits/s | Output seconds × 5 |
| Sora 2 Official | Text/Image to Video | 12 | 5 credits/s | Output seconds × 5 |
| Sora 2 Official | Text/Image to Video | 16 | 5 credits/s | Output seconds × 5 |
| Sora 2 Official | Text/Image to Video | 20 | 5 credits/s | Output seconds × 5 |
| Sora 2 Text to Video | Text to Video | - | 20 credits/s | Output seconds × 20 |
| Sora 2 Image to Video | Image to Video | - | 20 credits/s | Output seconds × 20 |
| Sora 2 Pro Text to Video | Text to Video | 720p | 60 credits/s | Output seconds × 60 |
| Sora 2 Pro Text to Video | Text to Video | 1080p | 100 credits/s | Output seconds × 100 |
| Sora 2 Pro Text to Video | Text to Video | true_1080p | 140 credits/s | Output seconds × 140 |
| Sora 2 Pro Image to Video | Image to Video | auto | 100 credits/s | Output seconds × 100 |
| Sora 2 Pro Image to Video | Image to Video | 720p | 60 credits/s | Output seconds × 60 |
| Sora 2 Pro Image to Video | Image to Video | 1080p | 100 credits/s | Output seconds × 100 |
| Sora 2 Pro Image to Video | Image to Video | true_1080p | 140 credits/s | Output seconds × 140 |
| Sora 2 Video Remix | Text/Image to Video | - | 20 credits | Fixed per generation |

## Common errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request payload |
| `401` | Missing or invalid API key |
| `402` | Insufficient credits or plan limit |
| `404` | Model or task not found |
| `429` | Rate limit exceeded |
| `500` | Server error |