# 動画生成のアクセスと使用
<a name="video-gen-access"></a>

Amazon Nova Reel を使用した動画の生成は非同期プロセスであり、通常は 6 秒間の動画の場合は約 90 秒かかり、2 分間の動画の場合は約 14 ～ 17 分かかります。動画の生成を開始したら、動画はアカウントの Amazon S3 バケットに書き込まれます。Amazon Bedrock はユーザーに代わって Amazon S3 バケットにファイルを書き込むため、適切な Amazon Bedrock、Amazon S3 のアクション、`s3:PutObject` アクションを許可するため、使用する AWS ロールにはアクセス許可を設定する必要があります。動画の生成に必要なアクションの最小限のアクセス許可は次のとおりです。
+ `bedrock:InvokeModel`
+ `s3:PutObject`

ただし、動画生成ジョブのステータスを追跡できるように、次の追加のアクションをお勧めします。
+ `bedrock:GetAsyncInvoke`
+ `bedrock:ListAsyncInvokes`

動画の生成が完了すると、動画およびその構成要素のショットは指定した Amazon S3 バケットに保存されます。Amazon Nova は、呼び出し ID ごとにフォルダを作成します。このフォルダには、動画生成リクエストによって作成された manifest.json、output.mp4、generation-status.json ファイルが含まれています。

**Topics**
+ [動画生成ジョブの開始](#video-gen-start-a-job)
+ [動画生成の入力パラメータ](#video-gen-input-params)
+ [動画生成ジョブの進行状況の確認](#video-gen-check-progress)
+ [動画生成ジョブの結果へのアクセス](#video-gen-read-results)

## 動画生成ジョブの開始
<a name="video-gen-start-a-job"></a>

動画の生成を開始するには、`start_async_invoke()` を呼び出します。新しい呼び出しジョブが作成されます。ジョブが完了すると、Amazon Nova は指定した Amazon S3 バケットに生成された動画を自動的に保存します。

`start_async_invoke()` は次の引数を取ります。
+ **modelId** (必須) – 使用するモデル ID。Amazon Nova Reel の場合は「amazon.nova-reel-v1:1」です。
+ **modelInput** (必須) – Amazon Nova Reel モデル固有のすべての動画生成パラメータを定義します。詳細については、「[動画生成の入力パラメータ](#video-gen-input-params)」を参照してください。
+ **outputDataConfig** (必須) – 生成された動画を保存する場所を定義します。値には次の構造を持たせる必要があります。

  ```
  {
      "s3OutputDataConfig": {
          "s3Uri": {{string (S3 URL starting with "s3://")}}
      }
  }
  ```

## 動画生成の入力パラメータ
<a name="video-gen-input-params"></a>

Amazon Nova Reel を使用して動画を生成する方法については、次のパラメータの説明を参照してください。

------
#### [ Text-to-video generation ]

次の構造では、Amazon Nova Reel の動画生成ジョブが定義されます。

```
{
    "taskType": "TEXT_VIDEO",
    "textToVideoParams": {
        "text": {{string}},
        "images": {{ImageSource[] (list containing a single ImageSource)}}
    },
    "videoGenerationConfig": {
        "durationSeconds": {{int}},
        "fps": {{int}},
        "dimension": {{string}}, 
        "seed": {{int}}
    }
}
```

動画生成ジョブを作成するには、これらの入力パラメータが必要です。
+ **text** (必須) — 動画を生成するテキストプロンプト。1 ～ 512 文字の長さである必要があります。
+ **images** (オプション) – 出力動画の開始キーフレームとして使用される 1 つの JPEG または PNG 動画。この入力動画は、動画を生成するためにテキストプロンプトとともに使用されます。画像は base64 文字列としてフォーマットするか、Amazon S3 バケットに保存する必要があります。

  画像は PNG または JPEG の形式にすることができ、カラーチャネル (RGB) ごとに 8 ビットである必要があります。PNG 画像には追加のアルファチャネルを含めることができますが、そのチャネルに透明または半透明のピクセルを含めることはできません。現在、モデルは 1280 (幅) x 720 (高さ) の画像のみに対応します。

  Amazon S3 バケットを介して含まれる画像は 25 MB を超えることはできません。
+ **durationSeconds** (必須) – 出力動画の再生時間。現在サポートされている値は 6 のみです。
+ **fps** (必須) – 出力動画のフレームレート。現在サポートされている値は 24 のみです。
+ **dimension** (必須) – 出力動画の幅および高さ。現在サポートされている値は「1280 x 720」のみです。
+ **seed** (オプション) – 生成プロセスの初期ノイズ設定を指定します。他のすべてのパラメータを変えずにシード値を変更すると、プロンプト、ディメンション、その他の設定に準拠し続けるまったく新しい動画が生成されます。最適な画像を見つけるには、さまざまなシード値を試すことが一般的です。

  シード値は 0 ～ 2、147、483、646 の間である必要があり、デフォルト値は 42 です。

**imageSource スキーマ**  
画像を入力として使用する際、次の構造を使用してリクエストに画像を含めます。

```
{
    "format": "png" | "jpeg"
    "source": {
        "bytes": {{string (base64 encoded image)}}
    }
}
```
+ **format** (必須) – 入力画像の形式と一致する必要があります。「png」または「jpeg」のいずれか。
+ **source** (必須)
  + **bytes** (必須) – base64 文字列としてエンコードされた入力画像。画像の解像度は 1280 x 720 である必要があります。

------
#### [ Automated long video generation ]

`MULTI_SHOT_AUTOMATED` タスクを使用するテキストプロンプトだけで、6 秒単位で最大 2 分間の動画を生成できます。最大 4000 文字のテキストプロンプトを指定できますが、入力画像を指定することはできません。

```
{
    "taskType": "MULTI_SHOT_AUTOMATED",
    "multiShotAutomatedParams": {
        "text": {{string}},
    },
    "videoGenerationConfig": {
        "durationSeconds": {{int}},
        "fps": {{int}},
        "dimension": {{string}}, 
        "seed": {{int}}
    }
}
```

動画生成ジョブを作成するには、これらの入力パラメータが必要です。
+ **text** (必須) — 動画を生成するテキストプロンプト。1 ～ 4000 文字の長さである必要があります。
+ **durationSeconds** (必須) – 出力動画の再生時間。12 と 120 の間にある 6 の倍数であり、その範囲に限ります。
+ **fps** (必須) – 出力動画のフレームレート。現在サポートされている値は 24 のみです。
+ **dimension** (必須) – 出力動画の幅および高さ。現在サポートされている値は「1280 x 720」のみです。
+ **seed** (オプション) – 生成プロセスの初期ノイズ設定を指定します。他のすべてのパラメータを変更せずにシード値を変更すると、プロンプト、ディメンション、その他の設定に準拠し続けるまったく新しい画像が生成されます。最適な画像を見つけるには、さまざまなシード値を試すことが一般的です。

  シード値は 0 ～ 2、147、483、646 の間である必要があり、デフォルト値は 42 です。

------
#### [ Manual long video generation ]

`MULTI_SHOT_MANUAL` タスクを使用して、複数のテキストプロンプトおよび入力画像を含む最大 2 分間の動画を生成できます。動画の 6 秒のショットごとに、オプションの入力画像を含むテキストプロンプトを指定できます。動画の再生時間は、指定したショット数に基づいて決定されます。

```
model_input = {
  "taskType": "MULTI_SHOT_MANUAL",
  "multiShotManualParams": {
    "shots": [
      {
        "text": "{{Information for shot 1}}"
      },
      {
        "text": "{{Information for shot 2}}",
        "image": {
          "format": "png", # Must be "png" or "jpeg"
          "source": {
            "bytes": "<base64 image string>"
          },
        },
      },
      {
        "text": "{{Information for shot 3}}",
        "image": {
            "format": "png",  # Must be "png" or "jpeg"
            "source": {
                "s3Location": {
                    "uri": "<S3 URI string>",
                    "bucketOwner": "<S3 bucket owner string>" # Optional
                }
            }
        }
      },
    ]
  },
  "videoGenerationConfig": {
        "fps": {{int}},
        "dimension": {{string}}, 
        "seed": {{int}}
    }
}
```

動画生成ジョブを作成するには、これらの入力パラメータが必要です。
+ **shots** (必須) – 動画生成に使用されるテキストプロンプトおよび入力画像に関する情報が含まれます。
+ **text** (必須) — 動画を生成するテキストプロンプト。1 ～ 512 文字の長さである必要があります。
+ **image** (オプション) – このショットに使用される入力画像に関する情報が含まれます。画像は `bytes` フィールドで base64 文字列または `s3Location` フィールドで Amazon S3 URI のいずれかとして指定できます。

  画像は PNG または JPEG の形式にすることができ、カラーチャネル (RGB) ごとに 8 ビットである必要があります。PNG 画像には追加のアルファチャネルを含めることができますが、そのチャネルに透明または半透明のピクセルを含めることはできません。現在、モデルは 1280 (幅) x 720 (高さ) の画像のみに対応します。

  Amazon S3 バケットを介して含まれる画像は 25 MB を超えることはできません。
+ **fps** (必須) – 出力動画のフレームレート。現在サポートされている値は 24 のみです。
+ **dimension** (必須) – 出力動画の幅および高さ。現在サポートされている値は「1280 x 720」のみです。
+ **seed** (オプション) – 生成プロセスの初期ノイズ設定を指定します。他のすべてのパラメータを変更せずにシード値を変更すると、プロンプト、ディメンション、その他の設定に準拠し続けるまったく新しい画像が生成されます。最適な画像を見つけるには、さまざまなシード値を試すことが一般的です。

  シード値は 0 ～ 2、147、483、646 の間である必要があり、デフォルト値は 42 です。

------

動画生成プロセスでは、指定した Amazon S3 保存先に次のファイルが書き込まれます。
+ **manifest.json** – ジョブの開始時に書き込まれるファイルであり、リクエスト ID が含まれます。
+ **video-generation-status.json** – ジョブの成功または失敗とは関わらず、このファイルは書き込まれます。ジョブが失敗すると、失敗したジョブの部分に加え、エラーを修正するために実行するアクションを正確に説明する詳細な情報が含まれます。
+ **output.mp4** – マルチショット動画の全体。ジョブが成功した場合にのみ書き込まれます。
+ **shot\_N.mp4** – 個々のショットも独自の動画として提供されます。ファイル名は「shot\_0001.mp4」や「shot\_0002.mp4」などの形式に従います。これらのファイルは、ジョブ全体が成功した場合にのみ書き込まれます。

## 動画生成ジョブの進行状況の確認
<a name="video-gen-check-progress"></a>

動画生成ジョブの進行状況を確認する方法は 2 つあります。呼び出しの開始時に返された呼び出し ARN への参照がある場合、Amazon Bedrock ランタイムの `get_async_invoke()` 方法を使用できます。

```
response = bedrock_runtime.get_async_invoke(
    invocationArn="arn:AWS:bedrock:us-east-1:{{account-id}}:async-invoke/{{invocation-id}}"
)

status = response["status"]
print(f"Status: {status}")
```

ジョブのステータスは、「Completed」、「InProgress」、「Failed」になります。`get_async_invoke()` 方法の使用の詳細については、「非同期 Invoke API ドキュメント」を参照してください。

呼び出し ARN への参照がないか、複数ジョブのステータスを一度に確認する場合、Amazon Bedrock ランタイムの `list_async_invokes()` 方法を使用できます。

```
invocations_details = bedrock_runtime.list_async_invokes(
    maxResults=10,  # (Optional)
    statusEquals="InProgress",  # (Optional) Can be "Completed", "InProgress", or "Failed". Omit this argument to list all jobs, regardless of status.
    # Note: There are other supported arguments not demonstrated here.
)

print(json.dumps(invocations_details, indent=2, default=str))
```

`list_async_invokes()` 方法の使用の詳細については、「非同期 Invoke API ドキュメント」を参照してください。

## 動画生成ジョブの結果へのアクセス
<a name="video-gen-read-results"></a>

動画生成ジョブが成功または失敗したら、JSON ファイルが Amazon S3 バケットに追加されます。このファイルには、動画用に作成されたショットに関するメタデータが含まれています。ファイルの名前は `video-generation-status.json` です。

成功した動画生成リクエストの場合、ファイルには動画全体を構成する個々のショットのロケーションが含まれます。失敗したリクエストの場合、ファイルには失敗メッセージおよびショットが失敗した理由に関する追加の詳細が含まれます。

この JSON ファイルのスキーマは以下のとおりに示されます。

```
{
    "schemaVersion": string,
    "shots": [{
            "status": enum, // where success is generation + upload
            "location": string,
            "failureType": enum,
            "failureMessage": string,
        },
        ...
    ],
    "fullVideo": {
        "status": enum, // where success is generation + upload
        "location": string,
        "failureType": enum,
        "failureMessage": string,
    }
}
```
+ **SchemaVersion** – JSON スキーマのバージョン。
+ **shots** – 動画の各ショットに関する情報が提供されます。
  + **status** – ショットの完了状態 (成功または失敗)。
  + **location** – ショットが保存されているファイル名と Amazon S3 のロケーション。ロケーションは、すべてのショットが正常に生成され、完成した動画が Amazon S3 のロケーションにアップロードされた場合のみに利用できます。
  + **failureType** – 失敗の理由が示されます。
  + **failureMessage** – 失敗の理由に関する詳細な情報が示されます。
+ **fullVideo** – 動画全体に関する情報が示されます。
  + **status** – 動画全体の完了状態 (正常生成または失敗)。
  + **location** – 動画全体が保存されているファイル名および Amazon S3 のロケーション。
  + **failureType** – 失敗の理由が示されます。
  + **failureMessage** – 失敗の理由に関する詳細な情報が示されます。

考えられる失敗の理由およびメッセージは次のとおりです。
+ INTERNAL\_SERVER\_EXCEPTION – 「サーバー側で問題が発生しました」
+ RAI\_VIOLATION\_OUTPUT\_VIDEO\_DEFLECTION – 「生成されたコンテンツはコンテンツフィルターによってブロックされました」
+ RATE\_LIMIT\_EXCEEDED – 「サービス容量の制限に達しました。後でもう一度お試しください」
+ ABORTED – 「リクエストが中止されました」