本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 影片產生的存取和使用
<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** (必填) - 輸出影片的寬度和高度。「1280x720」是目前唯一支援的值。
+ **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** (必填) - 輸出影片的寬度和高度。「1280x720」是目前唯一支援的值。
+ **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** (必填) - 輸出影片的寬度和高度。「1280x720」是目前唯一支援的值。
+ **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>

有兩種方式可以檢查影片產生任務的進度。如果您有開始調用時傳回之調用 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()` 方法的詳細資訊，請參閱「非同步 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** - 鏡頭的完成狀態 (SUCCESS 或 FAILURE)。
  + **location** - 鏡頭的檔案名稱和存放該鏡頭的 Amazon S3 位置。只有在成功產生所有鏡頭，並將完整的影片上傳到其 Amazon S3 位置時，才能使用該位置。
  + **failureType** - 提供失敗的原因。
  + **failureMessage** - 提供有關失敗原因的詳細資訊。
+ **fullVideo** - 提供完整影片的相關資訊。
  + **status** - 完整影片的完成狀態 (SUCCESS 或 FAILURE)。
  + **location** - 完整影片的檔案名稱和存放該影片的 Amazon S3 位置。
  + **failureType** - 提供失敗的原因。
  + **failureMessage** - 提供有關失敗原因的詳細資訊。

可能的失敗原因和訊息包括
+ INTERNAL\_SERVER\_EXCEPTION -「伺服器端發生錯誤。」
+ RAI\_VIOLATION\_OUTPUT\_VIDEO\_DEFLECTION -「我們的內容過濾器已封鎖產生的內容。」
+ RATE\_LIMIT\_EXCEEDED -「已達到服務容量限制。請稍後再試。」
+ ABORTED -「請求已中止。」