建立一個角色演繹 World。使用自然語言 Prompt 和必填的首幀圖來建立 World，介面會立即返回加密 World ID（encryptedWorldId），World 在背景進行非同步建構，用戶端需輪詢建構進度直至完成。
適用範圍
建立一個 Acting World。呼叫前請確認下列事項：
HTTP 呼叫
新加坡
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds
呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。
美国（維吉尼亞）
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds
呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。
請求參數 | 首幀圖（非同步建立）curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"prompt": "金发双马尾少女，白色蝴蝶结，额前金色新月冠，白衬衫、深蓝水手领与蓝色大领结，蓝白菱格短裙。右手举起一张写着「晚安」的黄色便签。身后深红丝绒帘与花丛。面对镜头，二次元写实混搭，暖色室内光。",
"resolution": "480p",
"aspectRatio": "9:16",
"firstFrameImage": {
"url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc5.png",
"referenceType": "default"
}
}'
首幀圖 base64（非同步建立）curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"async": true,
"prompt": "客厅沙发上的轻松对谈，角色自然看向镜头",
"resolution": "480p",
"aspectRatio": "9:16",
"firstFrameImage": {
"base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
"referenceType": "default"
}
}'
|
Content-Typestring（必選） 請求內容類型。此參數必須設定為 application/json。 |
Authorization string （必選） API Key 驗證。僅支援 主 API Key，以 sk- 開頭，例如 sk-xxx。通常設定為環境變數 $DASHSCOPE_API_KEY。若使用臨時 API Key（以 st- 開頭）進行呼叫，將返回 403003。 |
請求主體（Request Body） |
async boolean（選用） 是否非同步建立。預設 true：
true：立即返回，World 在背景建構，用戶端輪詢 查詢 World 建構狀態。false：伺服器端每 3 秒輪詢一次，最長等待 120 秒，建構完成後返回；若逾時仍返回 generating，用戶端隨後改為自行輪詢。 |
creationModel string（選用） 建立子模式。預設為 simple，Acting 僅支援 simple。 |
prompt string （必選） 角色、場景和演繹目標的自然語言描述。不可為空，最長 2000 個字元。缺失、空白或超過限制時返回 400000。 |
uploadMode string（選用） 圖片上傳模式。預設為 first_frame，Acting 僅支援 first_frame。 |
resolution string（選用） 視訊解析度。預設 480p。可選值： |
aspectRatio string（選用） 推流畫幅，同時決定首幀圖方向，建議兩者保持一致。預設為 9:16。可選值：
9:16（豎屏）：建議配豎屏首幀16:9（橫屏）：建議配橫屏首幀 即直式推流（9:16）建議傳入直式首幀，橫式推流（16:9）建議傳入橫式首幀。預設為 9:16，需要橫式畫面時須明確傳入 aspectRatio=16:9。 |
refWorldId string（選用） 基於現有 Acting World 衍生建立。必須是目前主帳號名下的 Acting 加密 World ID；若為其他模型或其他主帳號的 World，則返回 403001。 |
firstFrameImage object （必選） 複用作為 World 首幀的圖片引用。url 與 base64 二擇一且互斥。圖片限制條件如下：
- 格式：JPG / JPEG / PNG / WebP
- 大小：單張嚴格小於 6 MB
- 寬高比：
aspectRatio=9:16 時寬 / 高為 0.5–0.667；aspectRatio=16:9 時為 1.5–2.0
- 內容安全：未通過內容安全或版權 / IP 驗證時返回
403004 / 403005
屬性 url string（條件必選） 首幀圖片 URL。與 base64 二擇一且互斥。限制條件：
- 必須是帶有 Host 的合法
http / https URL，並可由伺服器端存取
- 真實格式、大小和首幀寬高比在轉存後校驗
- 非同步請求可能先返回
generating，隨後 World 因圖片驗證失敗而進入 failed
base64 string（條件必選） 首幀圖片 base64。與 url 二擇一且互斥。限制條件：
- 建議使用完整的 data URI
data:image/<subtype>;base64,<payload>
- 在建立入口同步校驗格式、大小和首幀寬高比
referenceType string（選用） 首幀參考類型。預設為 default，目前依 default 使用。 |
回應參數 | 非同步建立{
"code": 0,
"message": null,
"data": {
"encryptedWorldId": "enc_a1b2****",
"status": "generating",
"firstFrame": null
}
}
請求失敗{
"code": 400000,
"message": "Invalid request parameters.",
"data": null
}
|
code integer 返回碼。0 表示成功，非 0 為錯誤碼。 |
message string 錯誤訊息。成功時為 null；失敗時為可讀的錯誤訊息。 |
data object 回應資料。失敗時為 null。 屬性 encryptedWorldId string 伺服器端產生的加密 World ID。同步和非同步模式均會返回，後續輪詢建構狀態、查詢詳情、換取體驗憑證時皆使用此值。 status string 目前建立狀態：
generating：建立中ready：就緒failed：建立失敗 firstFrame string World 首幀 URL；尚未生成時為 null。 |
錯誤碼
如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。
下一步
建立成功後可進行以下操作：