# Sora 2 API ドキュメント

> AI Studio API で Sora 2 モデルを使用して動画を生成します。

## 概要

AI Studio API を使用して Sora 2 の生成タスクを作成し、タスク状態を確認します。処理は非同期です。まずタスクを作成して `taskId` を取得し、その後タスク API で結果を確認します。

## 認証

すべてのリクエストで `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 |