# Sora 2 API 文档

> 通过 AI Studio API 使用 Sora 2 模型生成视频。

## 概览

使用 AI Studio API 创建 Sora 2 生成任务并查询任务状态。接口采用异步流程：先创建任务拿到 `taskId`，再通过任务查询接口轮询结果。

## 认证方式

所有请求都需要在 `Authorization` 请求头中携带 API Key。

```http
Authorization: Bearer YOUR_API_KEY
```

## 可用模型

| modelId | 版本 | 服务商 | 运行模型 |
| --- | --- | --- | --- |
| `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. 创建生成任务

### 接口地址

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

### 请求示例

```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"
    }
  }
}
```

### 成功响应

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

## 2. 查询任务状态

### 接口

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

### 成功响应

```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
  }
}
```

## 请求字段

### Sora 2 Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | 否 | `["https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"]` | - | Provide external image URLs as references for video generation. |
| `prompt` | string | 否 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Optional field. |
| `duration` | enum | 否 | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | 否 | `["https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"]` | - | Provide external image URLs as references for video generation. |
| `prompt` | string | 否 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Optional field. |
| `duration` | enum | 否 | `"10"` | 10, 15 | The duration of the generated video in seconds. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Pro Storyboard

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `"25"` | 25 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Official

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"A cinematic shot with realistic motion, natural lighting, and smooth camera movement."` | - | Text prompt describing the desired video motion. Required field. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `"8"` | 4, 8, 12, 16, 20 | The duration of the generated video in seconds. |
| `nsfw_checker` | boolean | 否 | `false` | - | Defaults to false. You can set it to false based on your needs. |

### Sora 2 Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `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 | 否 | `"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 | 否 | `-` | - | 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 | 否 | `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 | 否 | `"16:9"` | 9:16, 16:9 | The aspect ratio of the generated video |
| `duration` | enum | 否 | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | string | 否 | `"720p"` | - | The resolution of the generated video |

#### input 字段

_该模型暂无字段配置。_

### Sora 2 Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `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 | 否 | `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 | 否 | `"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 | 否 | `-` | - | 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 | 否 | `"auto"` | auto, 9:16, 16:9 | The aspect ratio of the generated video |
| `image_url` | string | 是 | `"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 | 否 | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | 否 | `"auto"` | auto, 720p | The resolution of the generated video |

#### input 字段

_该模型暂无字段配置。_

### Sora 2 Pro Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `detect_and_block_ip` | boolean | 否 | `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 | 是 | `"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 | 否 | `"16:9"` | 9:16, 16:9 | The aspect ratio of the generated video |
| `duration` | enum | 否 | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | 否 | `"1080p"` | 720p, 1080p, true_1080p | The resolution of the generated video |
| `delete_video` | boolean | 否 | `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 | 否 | `-` | - | 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 字段

_该模型暂无字段配置。_

### Sora 2 Pro Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `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 | 否 | `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 | 否 | `-` | - | 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 | 否 | `"auto"` | auto, 9:16, 16:9 | The aspect ratio of the generated video |
| `image_url` | string | 是 | `"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 | 否 | `4` | 4, 8, 12, 16, 20 | Duration of the generated video in seconds |
| `resolution` | enum | 否 | `"auto"` | auto, 720p, 1080p, true_1080p | The resolution of the generated video |

#### input 字段

_该模型暂无字段配置。_

### Sora 2 Video Remix

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `video_id` | string | 是 | `"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 | 是 | `"Change the cat's fur color to purple."` | - | Updated text prompt that directs the remix generation |
| `delete_video` | boolean | 否 | `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 字段

_该模型暂无字段配置。_

## 价格

创建生成任务时会预扣积分。创建任务响应中的 `reservedCredits` 是本次请求最终预留的积分数量。

| 模型 | 类型 | 规格 | 价格 | 计费方式 |
| --- | --- | --- | --- | --- |
| Sora 2 Text to Video | 文生视频 | 10 | 3 积分/秒 | 输出秒数 × 3 |
| Sora 2 Text to Video | 文生视频 | 15 | 3 积分/秒 | 输出秒数 × 3 |
| Sora 2 Image to Video | 图生视频 | 10 | 3 积分/秒 | 输出秒数 × 3 |
| Sora 2 Image to Video | 图生视频 | 15 | 3 积分/秒 | 输出秒数 × 3 |
| Sora 2 Pro Text to Video | 文生视频 | 10 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Pro Text to Video | 文生视频 | 15 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Pro Image to Video | 图生视频 | 10 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Pro Image to Video | 图生视频 | 15 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Pro Storyboard | Storyboard | 16:9 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Pro Storyboard | Storyboard | 9:16 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Official | 文/图生视频 | 4 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Official | 文/图生视频 | 8 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Official | 文/图生视频 | 12 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Official | 文/图生视频 | 16 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Official | 文/图生视频 | 20 | 5 积分/秒 | 输出秒数 × 5 |
| Sora 2 Text to Video | 文生视频 | - | 20 积分/秒 | 输出秒数 × 20 |
| Sora 2 Image to Video | 图生视频 | - | 20 积分/秒 | 输出秒数 × 20 |
| Sora 2 Pro Text to Video | 文生视频 | 720p | 60 积分/秒 | 输出秒数 × 60 |
| Sora 2 Pro Text to Video | 文生视频 | 1080p | 100 积分/秒 | 输出秒数 × 100 |
| Sora 2 Pro Text to Video | 文生视频 | true_1080p | 140 积分/秒 | 输出秒数 × 140 |
| Sora 2 Pro Image to Video | 图生视频 | auto | 100 积分/秒 | 输出秒数 × 100 |
| Sora 2 Pro Image to Video | 图生视频 | 720p | 60 积分/秒 | 输出秒数 × 60 |
| Sora 2 Pro Image to Video | 图生视频 | 1080p | 100 积分/秒 | 输出秒数 × 100 |
| Sora 2 Pro Image to Video | 图生视频 | true_1080p | 140 积分/秒 | 输出秒数 × 140 |
| Sora 2 Video Remix | 文/图生视频 | - | 20 积分 | 单次生成固定价格 |

## 常见错误

| 状态 | 含义 |
| --- | --- |
| `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 |