LivePortrait video generation API reference - Alibaba Cloud Model Studio

LivePortrait モデルは、LivePortrait-detect モデルで処理されたポートレート画像と、人間の声を含む音声ファイルから、軽量で動的なポートレート動画を迅速に生成します。このドキュメントでは、API を呼び出してこのモデルの動画生成機能を使用する方法について説明します。

重要

このドキュメントは、中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キーを使用する必要があります。

モデル概要

モデル	説明
liveportrait	liveportrait はポートレート動画生成モデルです。ポートレート画像と人間の声を含む音声ファイルに基づいて、軽量で動的なポートレート動画を迅速に生成できます。

HTTP API 呼び出し

機能説明

動的なポートレート動画を生成します。

前提条件

Alibaba Cloud Model Studio を有効化し、API キーを取得済みであること。詳細については、「API キーの作成と設定」をご参照ください。
入力画像が「LivePortrait 画像検出」によって処理済みであること。

入力制限

画像フォーマット：jpeg、jpg、png、bmp、または webp。
画像解像度：画像ファイルは 10 MB 未満である必要があります。アスペクト比は 2 以下、最大辺長は 4096 ピクセルを超えないようにしてください。
音声フォーマット：wav または mp3。
音声制限：ファイルは 15 MB 未満である必要があります。長さは 1 秒から 3 分の間でなければなりません。
音声コンテンツ：音声には、クリアで大きな人間の声が含まれている必要があります。環境ノイズ、背景音楽、その他の音の干渉は除去してください。
画像と音声ファイルのアップロードは HTTP URL のみをサポートしており、ローカルファイルパスはサポートされていません。

タスク送信 API

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/

説明

アルゴリズムの呼び出しには時間がかかるため、タスクは非同期呼び出しを使用して送信されます。
タスクを送信すると、システムはタスク ID を返します。その後、「タスクステータスのクエリと結果取得 API」を使用して、タスクのステータスと結果を取得できます。

リクエストパラメーター

フィールド	タイプ	パラメーターの引き渡し	必須	説明	例
Content-Type	String	Header	はい	リクエストタイプ：application/json。	application/json
Authorization	String	Header	はい	API キー。例：Bearer d1**2a。	Bearer d1**2a
X-DashScope-Async	String	Header	はい	値を enable に設定して、タスクを非同期で送信します。	enable
model	String	Body	はい	呼び出すモデル。値を liveportrait に設定します。	liveportrait
input.image_url	String	Body	はい	アップロードする画像の URL。画像は、まず「LivePortrait 画像検出 API」で処理する必要があります。画像ファイルは 10 MB 未満である必要があります。アスペクト比は 2 以下、最大辺長は 4096 を超えないようにしてください。サポートされているフォーマット：jpeg、jpg、png、bmp、webp。説明ファイルのアップロードは HTTP リンクのみをサポートしており、ローカルファイルパスはサポートされていません。	"image_url": "http://a/a.jpg"
input.audio_url	String	Body	はい	アップロードする音声ファイルの URL。音声ファイルは 15 MB 未満である必要があります。長さは 1 秒から 3 分の間でなければなりません。サポートされているフォーマット：wav、mp3。説明ファイルのアップロードは HTTP リンクのみをサポートしており、ローカルファイルパスはサポートされていません。	http://aaa/bbb.wav
parameters.template_id	String	Body	いいえ	テンプレートに基づいて、姿勢と頭の動きの範囲を制御します。サポートされているテンプレートは、normal、calm、active です。デフォルト値は normal です。	"normal"
parameters.eye_move_freq	Float	Body	いいえ	1 秒あたりのまばたきの回数。値は 0 から 1 の範囲で設定できます。値が大きいほど、まばたきの頻度が高くなります。デフォルト値は 0.5 です。	0.5
parameters.video_fps	Integer	Body	いいえ	出力動画のフレームレート。値は 15 から 30 の範囲で設定できます。デフォルト値は 24 です。	24
parameters.mouth_move_strength	Float	Body	いいえ	口の動きの大きさ。値は 0 から 1.5 の範囲で設定できます。値が大きいほど、口の形が大きくなります。このパラメーターを 0 に設定すると、口は動きません。デフォルト値は 1 です。	1
parameters.paste_back	Boolean	Body	いいえ	生成された顔を元の画像に貼り付けるかどうかを指定します。値は true または false に設定できます。このパラメーターを false に設定すると、生成された顔のみが出力され、体は無視されます。デフォルト値は true です。	true
parameters.head_move_strength	Float	Body	いいえ	頭の動きの大きさ。値は 0 から 1 の範囲で設定できます。値が大きいほど、頭の動きの範囲が広くなります。デフォルト値は 0.7 です。	0.7

レスポンスパラメーター

フィールド	タイプ	説明	例
output.task_id	String	送信された非同期タスクの ID。実際のタスク結果は、非同期タスククエリ API を使用して取得する必要があります。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	非同期タスクが送信された後のタスクのステータス。	"PENDING"
request_id	String	このリクエストの一意のシステムコード。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

利用可能なアクションテンプレート

template_id	効果の説明
normal	デフォルトのアクションテンプレート。頭の動きの範囲は中程度です。このテンプレートは、さまざまなシナリオに適しています。
calm	キャラクターは落ち着いて見え、頭の動きの範囲は小さいです。このテンプレートは、ブロードキャストなどのシナリオに推奨されます。
active	キャラクターは活発に見え、頭の動きの範囲は大きいです。このテンプレートは、歌唱などのシナリオに推奨されます。

リクエスト例

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "liveportrait",
    "input": {
        "image_url": "http://xxx/1.jpg",
        "audio_url": "http://xxx/1.wav"
    },
      "parameters": {
         "template_id": "normal",
         "eye_move_freq": 0.5,
         "video_fps":30,
         "mouth_move_strength":1,
         "paste_back": true,
         "head_move_strength":0.7
    }
  }'

レスポンス例

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

タスクステータスのクエリと結果取得 API

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

リクエストパラメーター

フィールド	タイプ	パラメーター渡し	必須	説明	例
Authorization	String	Header	はい	API キー。例：Bearer d1**2a。	Bearer d1**2a
task_id	String	Url Path	はい	クエリするタスクの ID。	a8532587-fa8c-4ef8-82be-0c46b17950d1

レスポンスパラメーター

フィールド	タイプ	説明	例
output.task_id	String	クエリされたタスクの ID。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	クエリされたタスクのステータス。	タスクステータス： PENDING：タスクはキューに入っています。 RUNNING：タスクは処理中です。 SUCCEEDED：タスクは成功しました。 FAILED：タスクは失敗しました。 UNKNOWN：タスクが存在しないか、ステータスが不明です。
output.results.video_url	String	タスクが成功した場合、このパラメーターにはモデルによって生成された結果オブジェクトが含まれます。各オブジェクトには、必要に応じて生成された結果の URL が含まれます。video_url は、タスク完了後 24 時間有効です。	https://xxx/1.mp4
usage.video_duration	Float	このリクエストで生成された動画の長さ (秒単位)。	10.23
usage.video_ratio	String	このリクエストで生成された動画のフレームタイプ。値は standard です。	"video_ratio": "standard"
request_id	String	このリクエストの一意のシステムコード。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

リクエスト例

curl -X GET \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>

レスポンス例 (成功)

{
    "request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output":{
        "task_id":"a8532587-fa8c-4ef8-82be-0c46b17950d1",
	"task_status":"SUCCEEDED",
        "results":{
            "video_url":"https://xxx/1.mp4"
        }
    },
    "usage":{
        "video_duration": 10.23,
        "video_ratio": "standard"
    }
}

レスポンス例 (失敗)

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "FAILED",
    	"code": "xxx", 
    	"message": "xxxxxx"
    }  
}

ステータスコードの説明

大規模モデルサービスプラットフォームの一般的なステータスコードについては、「エラーメッセージ」をご参照ください。

このモデルには、次の固有のエラーコードもあります：

HTTP リターンコード*	エラーコード (code)	エラーメッセージ (message)	説明
400	InvalidParameter.UnsupportedFileFormat	入力ファイルのフォーマットがサポートされていません。	音声または画像のフォーマットがサポートされていません。サポートされている音声フォーマット：mp3、wav、aac。サポートされている画像フォーマット：jpg、jpeg、png、bmp、webp。
400	InvalidParameter.InputDownloadFailed	入力ファイルのダウンロードに失敗しました。	入力ファイルのダウンロードに失敗しました。
400	InvalidImage.ImageSize	画像のサイズが制限を超えています。	画像のサイズが制限を超えています。画像のアスペクト比は 2 以下、最長辺は 4096 を超えないようにしてください。
400	InvalidFile.AudioLengthError	音声の長さは 1 秒から 180 秒の間でなければなりません。	音声の長さが無効です。範囲は [1, 180] 秒以内でなければなりません。
400	InvalidImage.NoHumanFace	人間の顔が検出されませんでした。	人間の顔が検出されません。このエラーは、非同期タスククエリ API によってのみ返されます。
400	InvalidParamter.OutOfDefinition	{parameter} のタイプまたは値が定義外です。	パラメーターのタイプまたは値が無効です。
500	InternalError.Algo	アルゴリズムの実行中に内部エラーが発生しました。	アルゴリズムの実行時にエラーが発生しました。
500	InternalError.Upload	結果のアップロードに失敗しました。	生成された結果のアップロードに失敗しました。