# 视频生成访问和使用
<a name="video-gen-access"></a>

使用 Amazon Nova Reel 生成视频是一个异步过程，6 秒钟的视频通常需约 90 秒，2 分钟的视频通常需约 14-17 分钟。开始生成视频后，视频将写入您账户中的 Amazon S3 存储桶。由于 Amazon Bedrock 会代表您将文件写入 Amazon S3 存储桶，您使用的 AWS 角色需要配置权限，才能执行相应的 Amazon Bedrock 和 Amazon S3 操作以及 `s3:PutObject` 操作。生成视频所需的最低操作权限如下：
+ `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**（可选）– 用作输出视频起始关键帧的单张 JPEG 或 PNG 图像。此输入图像与文本提示一起用于生成视频。该图像必须格式化为 base64 字符串或存储在 Amazon S3 存储桶中。

  图像可以采用 PNG 或 JPEG 格式，但每个颜色通道必须为 8 位（RGB）。PNG 图像可以包含额外的 Alpha 通道，但该通道不得包含任何透明或半透明像素。目前，该模型仅接受 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` 任务，仅需一个文本提示，就能以六秒为增量生成长达两分钟的视频。您可以提供包含最多 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` 任务生成长达两分钟的视频，其中包含多个文本提示和多张输入图像。对于视频中每一个时长为六秒的镜头，您可以提供一个文本提示，并可选择附带一张输入图像。视频的时长根据指定的镜头数确定。

```
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 格式，但每个颜色通道必须为 8 位（RGB）。PNG 图像可以包含额外的 Alpha 通道，但该通道不得包含任何透明或半透明像素。目前，该模型仅接受 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\$1N.mp4** – 每个单独的镜头也会作为独立的视频提供。文件名采用“shot\$10001.mp4”“shot\$10002.mp4”等格式。只有整个作业成功了，才会写入这些文件。

## 检查视频生成作业的进度
<a name="video-gen-check-progress"></a>

有两种方法可以检查视频生成作业的进度。如果对启动调用时返回的调用 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}")
```

作业状态或为“已完成”“进行中”或“失败”。有关使用 `get_async_invoke()` 方法的更多详细信息，请参阅 Async Invoke API 文档。

如果没有对调用 ARN 的引用，或想同时检查多个作业的状态，则可以使用 `list_async_invokes()` 运行时的 Amazon Bedrock 方法。

```
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()` 方法的更多详细信息，请参阅 Async Invoke API 文档。

## 访问视频生成作业的结果
<a name="video-gen-read-results"></a>

视频生成作业成功或失败后，系统会向 Amazon S3 存储桶添加一个 JSON 文件。此文件包含有关为视频创建的镜头的元数据。此文件命名为 `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\$1SERVER\$1EXCEPTION –“Something went wrong on the server side.”
+ RAI\$1VIOLATION\$1OUTPUT\$1VIDEO\$1DEFLECTION –“The generated content has been blocked by our content filters.”
+ RATE\$1LIMIT\$1EXCEEDED –“Service capacity limit has been reached. Please try again later.”
+ ABORTED -“Request has been aborted.”