全部產品
Search
文件中心

Intelligent Media Services:SubmitAvatarVideoJob

更新時間:Oct 09, 2026

以人聲音訊或文字作為輸入,渲染虛擬人影片。

介面說明

  • 該介面為非同步介面,提交任務後返回任務 ID(此時任務尚未完成,任務將進入背景排隊非同步執行),最終結果將透過回呼通知,也可透過獲取智慧任務結果主動查詢任務狀態。

  • 目前僅支援輸入為文字或人聲音訊作為輸入,音訊僅支援 mp3 或 wav 格式。

  • 支援輸出 mp4 和 webm 格式。當輸出為 mp4 時,成片為帶綠幕背景的影片,同時輸出虛擬人的遮罩影片,供後續使用,推薦使用此方案。當輸出為 webm 時,成片為帶透明通道的 webm,可用於前端展示,由於 webm 編碼問題,合成會慢一些。

  • 輸出結果中包含人聲的句子時間戳記,供後續在剪輯中使用。

調試

您可以在OpenAPI Explorer中直接運行該介面,免去您計算簽名的困擾。運行成功後,OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊,可以在RAM權限原則語句的Action元素中使用,用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下:

  • 操作:是指具體的許可權點。

  • 存取層級:是指每個操作的存取層級,取值為寫入(Write)、讀取(Read)或列出(List)。

  • 資源類型:是指操作中支援授權的資源類型。具體說明如下:

    • 對於必選的資源類型,用前面加 * 表示。

    • 對於不支援資源級授權的操作,用全部資源表示。

  • 條件關鍵字:是指雲產品自身定義的條件關鍵字。

  • 關聯操作:是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權,操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ice:SubmitAvatarVideoJob

create

*全部資源。

*

無 無

請求參數

名稱

類型

必填

描述

樣本值

InputConfig

string

否

虛擬人任務輸入參數。支援以文字、音訊 OSS 檔案、媒資作為輸入。音訊僅支援 mp3 或 wav 格式。

重要 Text 的輸入內容長度不能少於 5 個字。

{"Text": "Do you not see the Yellow River's waters descending from heaven, rushing to the sea never to return.Do you not see in the bright mirror of the high hall, the sad sight of white hair,Hair turns from black to white in the course of a day."}

EditingConfig

string

否

虛擬人任務配置資訊,支援設定虛擬人 ID、人聲、語速等資訊。

{"AvatarId":"yunqiao"}

OutputConfig

string

否

任務輸出資訊,支援設定輸出地址。

{"MediaURL":"https://your-bucket.oss-cn-shanghai.aliyuncs.com/xxx.mp4"}

Title

string

否

任務標題,長度不超過 128 位元組。

Test Title

Description

string

否

任務描述,長度不超過 128 位元組。

Test Description

UserData

string

否

使用者自訂設定,可傳入客戶業務資訊,如業務方環境、任務資訊,JSON 字串格式。

{"user":"data","env":"prod"}

InputConfig 範例:

輸入為音訊地址:

{
  "InputFile": "https://your-bucket.oss-cn-shanghai.aliyuncs.com/xxx.mp3"
}

輸入為文字:

{
  "Text": "Do you not see the Yellow River's waters descending from heaven, rushing to the sea never to return.Do you not see in the bright mirror of the high hall, the sad sight of white hair,Hair turns from black to white in the course of a day."
}

輸入為 MediaId:

{
  "MediaId": "4aef0c80cc0071edbf92f6e7c44b6302"
}

EditingConfig 範例:

AvatarId:虛擬人形象 ID,必填,取值:數位人官方形象
Voice:發音人,僅輸入為 Text 有效,選填,取值:智慧語音效果範例
CustomizedVoice:個人化人聲。如果需要使用透過人聲複製生成的個人化人聲作為發音人,請使用此欄位,而不是 Voice 欄位
LoopMotion:是否首尾同影格,如果設定此值為 true,則生成的數位人影片影像的首影格與尾影格相同,循環播放影片時人物形象的動作和表情不會有「跳變」現象,取值範圍:{true, false},預設值:false
SpeechRate:語速,僅當輸入為文字類型有效,取值範圍:-500~500,預設值:0
PitchRate:音調,僅當輸入為文字類型有效,取值範圍:-500~500,預設值:0
Volume:音量,僅當輸入為文字類型有效,取值範圍:0~100,預設值:50
BackgroundUrl:背景圖,選填,不傳預設為黑色背景,僅支援 jpg、png 格式;解析度要求為 1080P,如果使用的是直式形象,則要求為 1080P 直式,如果使用的是橫式形象,則要求為 1080P 橫式。



















{
  "AvatarId": "xinxin-marketing_standing", 
  "BackgroundUrl": "https://your-bucket.oss-cn-shanghai.aliyuncs.com/xxx.jpg",
  "Voice" : "zhichu",
  "LoopMotion": true,
  "SpeechRate": 100,
  "PitchRate": 10, 
  "Volume": 10 
}

OutputConfig 範例:

{
  "MediaURL": "https://your-bucket.oss-cn-shanghai.aliyuncs.com/xxx.mp4
}

返回參數

名稱

類型

描述

樣本值

object

Schema of Response

RequestId

string

Id of the request

******11-DB8D-4A9A-875B-275798******

JobId

string

智慧任務 ID。

****20b48fb04483915d4f2cd8ac****

MediaId

string

成片媒資 ID。

******70dcc471edaf00e6f6f4******

可以透過獲取智慧任務結果介面查詢任務執行狀態和任務結果,任務執行成功時介面返回結果範例如下。

{
	"RequestId": "2014D1A8-4143-164F-94B4-32B8F39B706D",
	"JobId": "d9367da8c7184ec7a3f24de530ac5b9a",
	"State": "Finished",
	"SmartJobInfo": {
		"Title": "default_title_2023-03-28T13:37:47Z",
		"EditingConfig": "null",
		"JobType": "AvatarVideo",
		"CreateTime": "2023-03-28T13:37:47Z",
		"ModifiedTime": "2023-03-28T13:37:47Z",
		"UserId": 1833202230108227,
		"outputConfig": {
			"mediaUrl": "https://oushu-test-shanghai.oss-cn-shanghai.aliyuncs.com/avatar/222.mp4"
		}
	},
	"JobResult": {
		"MediaId": "4aef0c80cc0071edbf92f6e7c44b6302",
		"AiResult": "{\"outputVideoUrl\":\"https://oushu-test-shanghai.oss-cn-shanghai.aliyuncs.com/avatar/222.mp4\",\"subtitleClips\":\"[{\\\"from\\\":0.0,\\\"to\\\":4.692,\\\"content\\\":\\\"君不见黄河之水天上来,奔流到海不复回。\\\"},{\\\"from\\\":4.692,\\\"to\\\":9.061,\\\"content\\\":\\\"君不见高堂明镜悲白发,朝如青丝暮成雪。\\\"}]\"}"
	}
}

其中,AiResult 格式如下:
outputVideoUrl 為輸出成片地址,mp4 格式
subtitleClips 字幕句子時間戳記




{
	"outputVideoUrl": "https://oushu-test-shanghai.oss-cn-shanghai.aliyuncs.com/avatar/222.mp4",
	"subtitleClips": "[{\"from\":0.0,\"to\":4.692,\"content\":\"君不见黄河之水天上来,奔流到海不复回。\"},{\"from\":4.692,\"to\":9.061,\"content\":\"君不见高堂明镜悲白发,朝如青丝暮成雪。\"}]"
}

樣本

正常返回樣本

JSON格式

{
  "RequestId": "******11-DB8D-4A9A-875B-275798******\n",
  "JobId": "****20b48fb04483915d4f2cd8ac****\n",
  "MediaId": "******70dcc471edaf00e6f6f4******"
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊,參考變更詳情。